libubdadl Documentation

Introduction

libubdadl is a library written in Python designed to allow you to convert a grid reference in the Adelaide UBD street directory into Geographic ("GPS") co-ordinates. The library is designed to be modifiable to suit other Australian street directories for other capital cities.

The library will not convert a Geographic co-ordinate into a street directory reference. It is assumed you have some other mapping software to allow that conversion. However, it may become a feature in future versions.

This software is a library. You are supposed to use it to develop your own applications. However using the interactive Python interpreter, you can use the library to perform calculations.

Requirements

Python 2.3 or later. This script was tested on Python 2.3 and 2.4. However, it may work on older versions.
A recent copy of the UBD Adelaide Street Directory. I used the 36th edition (1998), however it is recommened you use the most up to date version.

Explanation of Concepts

The library needs three pieces of data in order to calculate the co-ordinates:

A UBD map number
A grid reference
A "subgrid" reference

The first two pieces of data I assume you understand, else why would you download mapping-related software if you do not know how to use a map?! The subgrid reference is an idea of my own in order to enhance the accuracy of the data given without compensating with reduced usability or need for higher resolution maps.

Figure 1: Diagram of how subgrids are positioned.

NW is at the upper left corner of the cell.
N is at the upper centre edge of the cell.
NE is at the upper right corner of the cell.
W is at the centre left edge of the cell.
C is in the centre area of the cell.
E is at the center right edge of the cell.
SW is at the lower left corner of the cell.
S is at the lower centre edge of the cell.
SE is at the lower right corner of the cell.

Figure 2: Example use of subgrid.

Point A (corner of Sixth Avenue and Hooking Terrace) can be described as:

Map 105, Grid B1, Subgrid SE
Map 105, Grid B2, Subgrid NE
Map 105, Grid C1, Subgrid SW
Map 105, Grid C2, Subgrid NW

Which one of these you use doesn't matter, as they all mean the same thing to the library.

Point B (public telephone box on Seventh Avenue) can only be described as Map 105, Grid D1, Subgrid C.

"Public" Functions of libubdadl

While Python makes no distinction between public and private functions, I'll only document here the "public" functions, the ones that I feel are actually useful.

mapToAMG(mapid, grid, subgrid)

Converts a mapid, grid and subgrid reference into an AMG reference. The reference is returned in a tuple with the format (easting, northing, mapnumber).

Example:

>>> import libubdadl
>>> libubdadl.mapToAMG(105, 'C1', 'NW')
(276000, 6139000, 54)

mapToGeo(mapid, grid, subgrid)

Converts a mapid, grid and subgrid reference into a geographic co-ordinate (latitude and longnitude). The co-ordinate is returned in a tuple with the format (latitude, longnitude). The format is decimal. Positive latitude is north, positive longnitude is east.

>>> import libubdadl
>>> libubdadl.mapToGeo(105, 'C1', 'NW')
(-34.866577964459474, 138.54949128721805)

libamgtogeo

Included is a library called libamgtogeo. It converts an AMG reference into a geographic co-ordinate. Please see the source code for more info, it is fairly well documented.

Website

You can find the current version and my contact information at the "official" website.

Acknowledgements

Thanks to Neil Freeman for providing his script, "amg2geo_ascii_agd66.pl", which was the basis for libamgtogeo. I would be lost without it. There is a web based version of his script.

Adelaide UBD (36th edition, 1998) is Copyright 1998 Universal Press Pty. Ltd. The portion of map used, to the documentation author's knowledge, in accordance with the Australian Copyright Act's fair use provisions.

Changelog

Version 1.0 (2005.03.02), Initial Release: First release!

The End

And they live happily ever after. The end. :-)