Ubuntu Manpage: Geo::Coordinates::OSTN02 - An implementation of the OSGB's OSTN02 transformation

Provided by: libgeo-coordinates-osgb-perl_2.06-1_all

NAME

       Geo::Coordinates::OSTN02 - An implementation of the OSGB's OSTN02 transformation

SYNOPSIS

         use Geo::Coordinates::OSTN02 qw/OSGB36_to_ETRS89 ETRS89_to_OSGB36/;

         ($x, $y, $z) = OSGB36_to_ETRS89($e, $n, $h);
         ($e, $n, $h) = ETRS89_to_OSGB36($x, $y, $z);

DESCRIPTION

       The purpose and use of these modules is described briefly in the companion Geo::Coordinates::OSGB
       modules.  In essence they implement in Perl the Ordnance Survey's OSTN02 transformation which is part of
       the current definition of the British National Grid.  You are strongly recommended to read the official
       public guides and other introductory documents that are published by the Ordnance Survey of Great Britain
       with a wealth of other technical information about the OSTN02 transformation.

FUNCTIONS

       The following functions can be exported from the "Geo::Coordinates::OSTN02" module:

           OSGB36_to_ETRS89
           ETRS89_to_OSGB36

       None is exported by default.

       OSGB36_to_ETRS89(easting, northing, [elevation])
           Transforms from normal OSGB36 grid references to a pseudo-grid based on the WGS84/ETRS89 geoid model,
           which can then be translated to lat/long coordinates using "grid_to_ll()" with the 'WGS84' parameter.

              my $elevation = '100'; # in metres
              my ($e, $n) = parse_grid_trad('TQ304293');
              my ($x, $y, $z) = OSGB36_to_ETRS89($e, $n, $elevation);
              my ($lat, $lon) = grid_to_ll($x, $y, 'ETRS89'); # or 'WGS84'

           Elevation will default to 0 metres if you omit it.

       ETRS89_to_OSGB36(x, y, [z])
           Transforms WGS84/ETRS89 pseudo-grid coordinates into OSGB36 grid references.

             my ($lat, $lon, $height) = (51.5, -1, 10); # Somewhere in London
             my ($x, $y) = ll_to_grid($lat, $lon, 'ETRS89'); # or 'WGS84'
             my ($e, $n, $elevation) = ETRS89_to_OSGB36($x, $y, $height);

IMPLEMENTATION NOTES

Since 2002 the British Ordnance Survey have defined the UK national grid not as a projection from their
own model of the earth (the Airy 1830 geoid, revised 1936, known as OSGB36), but as a simple table of
calculated differences from a projection based on the European standard geoid ETRS89 (which is for Europe
a functional equivalent of the international WGS84 geoid). This revision is known as OSGM02 and the
transformation is called OSTN02.

The idea is that you project your WGS84 latitude and longitude coordinates into WGS84 (or ETRS89) pseudo-
grid references, and then look up the appropriate three dimensional correction in the OS table, and add
the results to your grid reference to give you a standard British National Grid reference that you can
use with British OS maps. Going back the other way is slightly more complicated, as you have to work
backwards, but a simple iteration will do the job. This package implements these lookups and
adjustments. You give it a three dimensional grid reference (easting, northing, and altitude, all in
metres) and the package returns it corrected from one system to the other.

The problem in the implementation is that the table is huge, and most of it is empty as the OS have
chosen to leave the transformation undefined for areas that are off shore. So this package only works
properly for grid references that are actually on one or more OS maps. The complete table (including all
the 0 lines) contains nearly 1 million lines with six data points and a key. In text form as supplied by
the OS that is about 36M bytes of table. By leaving out the lines where the transformation is undefined,
omitting a couple of redundant fields, and storing everything as hex strings, this module brings the
amount of data down to just over 6M bytes, which loads in about 1 second on my test system. It would be
possible to compress the data down to 3M bytes by storing it as packed decimals, but then it would be
difficult to include inline in this module, as it would break every time I edited it.

The data is stored below, after the __DATA__ line. Each line is 18 bytes long and represents the
transformation parameters for an individual grid square of 1km by 1km. Each line contains five fields
all expressed as hexadecimal integers.

Start Length Meaning
0 3 The northing of the square in km
3 3 The easting of the square in km
6 4 The x-offset in mm (easting)
10 4 The y-offset in mm (northing)
14 4 The z-offset in mm (elevation)

To keep the numbers small and positive the values given for the offsets are actually the amount that they
exceed the respective smallest values in the data set. Currently these minima are x: 86275mm, y:
-81603mm, and z: 43982mm. So when we read a line from the data we have to add these minima to the
values, convert to decimal, and multiply by 1000 to get back to metres.

When you load the OSTN02 module, the first thing it does is to load all 309,798 lines into an array
called @ostn_data by simply doing this.

our @ostn_data = <DATA>;

This is why it takes a few microseconds to load the module, but once loaded it's all very fast.

When we need to find the data values for a given grid reference, we work out the appropriate grid square
by truncating the easting and northing to the next lowest whole kilometer, and pass these as the argument
to the "_get_ostn_ref" subroutine. This is the only subroutine that actually touches the data.

The core of the subroutine is a binary search. We work out the key by converting the northing and
easting to hexadecimal and concatenating them. We add leading zeros so that each value is exactly three
bytes long and the combined key is exactly six bytes long. The maximum value for easting in the OSGB
grid is 700km and for northing 1250km, which are 2BC and 4E2, so each fits into three bytes. (And by the
time this is called we have already checked that the values don't exceed the maxima).

This works pretty quickly, the only slow bit is loading the array at the beginning, but it is much faster
and needs *much* less memory than loading all the data into the hash. (This would be simpler, and is what
the original version did, but it was too slow to be usable and meant that the tests failed on many
smaller systems as part of CPAN testing). We do still use a hash, but only to cache lines that we've
already found. Read the code for details. This only gives a tiny speed up in general, so I might remove
it in future versions.

Back in 2008, loading the array took about 1.2 seconds on my Windows machine (a 2.8G Hz Intel Pentium M
processor with 2G byte of memory) and just under 0.5 seconds on my Linux system (a 2.8G Hz Intel Pentium
4 processor with 512M bytes of memory). I think that probably said more about speed of the disks I had
(and probably the efficiency of Perl under Linux) back then. Today on my newish Mac Mini there is only a
very slightly noticeable delay. Once the data is loaded, calling the routines is reasonably quick.

BUGS

       Please report any to toby@cpan.org

EXAMPLES

       See the test routines included in the distribution.

AUTHOR

       Toby Thurston -- 04 Oct 2013

       toby@cpan.org