noble (3) Geo::Coordinates::OSGB.3pm.gz

Provided by: libgeo-coordinates-osgb-perl_2.20-2_all bug

NAME

       Geo::Coordinates::OSGB - Convert coordinates between Lat/Lon and the British National Grid

       An implementation of co-ordinate conversion for England, Wales, and Scotland based on formulae and data
       published by the Ordnance Survey of Great Britain.

VERSION

       2.20

SYNOPSIS

         use Geo::Coordinates::OSGB qw(ll_to_grid grid_to_ll);

         ($easting,$northing) = ll_to_grid($lat,$lon);
         ($lat,$lon) = grid_to_ll($easting,$northing);

DESCRIPTION

       These modules convert accurately between OSGB national grid references and coordinates given in latitude
       and longitude.

       The default "ellipsoid model" used for the conversions is the de facto international standard WGS84.
       This means that you can take latitude and longitude readings from your GPS receiver, or read them from
       Wikipedia, or Google Earth, or your car's sat-nav, and use this module to convert them to accurate
       British National grid references for use with one of the Ordnance Survey's paper maps.  And vice versa,
       of course.

       The module is implemented purely in Perl, and should run on any platform with Perl version 5.8 or better.

       In this description, the abbreviations `OS' and `OSGB' mean `the Ordnance Survey of Great Britain': the
       British government agency that produces the standard maps of England, Wales, and Scotland.  Any mention
       of `sheets' or `maps' refers to one or more of the map sheets defined in the accompanying maps module.

       This code is written for the British national grid system.  It is of no use outside Britain.  In fact
       it's only really useful in the areas covered by the OS's main series of maps, which exclude the Channel
       Islands and Northern Ireland.

SUBROUTINES/METHODS

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

           grid_to_ll
           ll_to_grid

       Neither of these is exported by default.

   Main subroutines
       "ll_to_grid(lat, lon)"

       "ll_to_grid" translates a latitude and longitude pair into a grid easting and northing pair.

       When called in a list context, "ll_to_grid" returns the easting and northing as a list of two.  When
       called in a scalar context, it returns a single string with the numbers separated by a space.

       The arguments should be supplied as real numbers representing decimal degrees, like this:

           my ($e,$n) = ll_to_grid(51.5, -2.1); # (393154.801, 177900.605)

       Following the normal mathematical convention, positive arguments mean North or East, negative South or
       West.

       If you have data with degrees, minutes, and seconds, you can convert them to decimals like this:

           my ($e,$n) = ll_to_grid(51+25/60, 0-5/60-2/3600);

       If you have trouble remembering the order of the arguments, or the returned values, note that latitude
       comes before longitude in the alphabet too, as easting comes before northing.  However, since reasonable
       latitudes for the OSGB are in the range 49 to 61, and reasonable longitudes in the range -9 to +2,
       "ll_to_grid" accepts the arguments in either order; if your longitude is larger than your latitude, then
       the values of the arguments will be silently swapped.

       You can also supply the arguments as named keywords (but be sure to use the curly braces so that you pass
       them as a reference):

           my ($e,$n) = ll_to_grid( { lat => 51.5, lon => -2.1 } );

       The easting and northing will be returned as the orthogonal distances in metres from the `false point of
       origin' of the British Grid (which is a point some way to the south-west of the Scilly Isles).  The
       returned pair refers to a point on the usual OSGB grid, which extends from the Scilly Isles in the south
       west to the Shetlands in the north.

           my ($e,$n) = ll_to_grid(51.5, -2.1); # (393154.807, 177900.595)
           my $s      = ll_to_grid(51.5, -2.1); # "393154.807 177900.595"

       If the coordinates you supply are in the area covered by the OSTN transformation data, then the results
       will be rounded to 3 decimal places, which corresponds to the nearest millimetre.  If they are outside
       the coverage then the conversion is automagically done using a Helmert transformation instead of the OSTN
       data.  The results will be rounded to the nearest metre in this case, although you probably should not
       rely on the results being more accurate than about 5m.

       With the older OSTN02 dataset, coverage extended only to about 3km offshore, but the current OSTN15
       dataset extends coverage to the whole grid area from (0,0) to (700000, 1250000), so you have be really
       far away to get whole metres.  Even points well away from land, like this one:

          # A point in the sea, to the north-west of Coll
          my $s = ll_to_grid(56.75,-7);

       will get an accurate conversion.  With OSTN02 that returned "94471 773206" but with OSTN15 you get
       "94469.597 773209.464".  For your sake, I hope you are never in a situation at sea off Coll where the 3
       metres difference is important.

       The numbers returned may be negative if your latitude and longitude are far enough south and west, but
       beware that the transformation is less and less accurate or useful the further you get from the British
       Isles.

       If you want the result presented in a more traditional grid reference format you should pass the results
       to one of the grid formatting routines from Grid.pm.  Like this.

           my $s = ll_to_grid(51.5, -2.1);              # "393154.807 177900.595"
           $s = format_grid(ll_to_grid(51.5,-2.1));     # "ST 931 779"
           $s = format_grid_GPS(ll_to_grid(51.5,-2.1)); # "ST 93154 77900"
           $s = format_grid_map(ll_to_grid(51.5,-2.1)); # "ST 931 779 on A:173, B:156, C:157"

       "ll_to_grid()" also takes an optional argument that sets the ellipsoid model to use.  This defaults to
       `WGS84', the name of the normal model for working with normal GPS coordinates, but if you want to work
       with the traditional latitude and longitude values printed around the edges of OS maps before 2015 then
       you should add an optional shape parameter like this:

           my ($e, $n) = ll_to_grid(49,-2, {shape => 'OSGB36'});

       Incidentally, if you make this call above you will get back "(400000, -100000)" which are the coordinates
       of the `true point of origin' of the British grid.  You should get back an easting of 400000 for any
       point with longitude 2W since this is the central meridian used for the OSGB projection.  However you
       will get a slightly different value unless you specify "{shape => 'OSGB36'}" because the WGS84 meridians
       are not quite the same as OSGB36.

       "grid_to_ll(e,n)"

       The routine "grid_to_ll()" takes an easting and northing pair representing the distance in metres from
       the `false point of origin' of the OSGB grid and returns a pair of real numbers representing the
       equivalent longitude and latitude coordinates in the WGS84 model.

       Following convention, positive results are North of the equator and East of the prime meridian, negative
       numbers are South and West.  The fractional parts of the results represent decimal fractions of degrees.

       No special processing is done in scalar context because there is no obvious assumption about how to round
       the results.  You will just get the length of the list returned, which is 2.

       The arguments must be an (easting, northing) pair representing the absolute grid reference in metres from
       the point of origin.  You can get these from a traditional grid reference string by calling
       "parse_grid()" first.

           my ($lat, $lon) = grid_to_ll(parse_grid('SM 349 231'))

       An optional last argument defines the ellipsoid model to use just as it does for "ll_to_grid()".  This is
       only necessary is you are working with an ellipsoid model other than WGS84.  Pass the argument as a hash
       ref with a `shape' key.

           my ($lat, $lon) = grid_to_ll(400000, 300000, {shape => 'OSGB36'});

       If you like named arguments then you can use a single hash ref for all of them (this is strictly
       optional):

           my ($lat, $lon) = grid_to_ll({ e => 400000, n => 300000, shape => 'OSGB36'});

       The results returned will be floating point numbers with the default Perl precision.  Unless you are
       running with long double precision floats you will get 13 decimal places for latitude and 14 places for
       longitude;  but this does not mean that the calculations are accurate to that many places.  The OS online
       conversion tools return decimal degrees to only 6 places.  A difference of 1 in the sixth decimal place
       represents a distance on the ground of about 10 cm.  This is probably a good rule of thumb for the
       reliability of these calculations, but all the available decimal places are returned so that you can
       choose the rounding that is appropriate for your application.  Here's one way to do that:

           my ($lat, $lon) = map { sprintf "%.6f", $_ } grid_to_ll(431234, 312653);

   Additional subroutines
       "set_default_shape(shape)"

       The default ellipsoid shape used for conversion to and from latitude and longitude is `WGS84' as used in
       the international GPS system.  This default is set every time that  you load the module.  If you want to
       process or produce a large number latitude and longitude coordinates in the British Ordnance Survey
       system (as printed round the edges of OS Landranger and Explorer maps before 2015) you can use
       "set_default_shape('OSGB36');" to set the default shape to OSGB36.  This saves you having to add "{ shape
       => 'OSGB36' }" to every call of "ll_to_grid" or "grid_to_ll".

       You can use "set_default_shape('WGS84');" to set the default shape back to WGS84 again when finished with
       OSGB36 coordinates.

       "ll_to_grid_helmert(lat, lon)"

       You can use this function to do a conversion from WGS84 lat/lon to the OS grid without using the whole
       OSTN data set.  The algorithm used is known as a Helmert transformation.  This is the usual coordinate
       conversion algorithm implemented in most consumer-level GPS devices, which generally do not have enough
       memory space for the whole of OSTN.  It is based on parameters supplied by the OS; they suggest that in
       most of the UK this conversion is accurate to within about 5m.

           my ($e, $n) = ll_to_grid_helmert(51.477811, -0.001475);  # RO Greenwich

       The input must be decimal degrees in the WGS84 model, with latitude first and longitude second.  The
       results are rounded to the nearest whole metre.  They can be used with "format_grid" in the same way as
       the results from "ll_to_grid".

       This function is called automatically by "ll_to_grid" if your coordinates are WGS84 and lie outside the
       OSTN polygon.

       "grid_to_ll_helmert(e,n)"

       You can use this function to do a slightly quicker conversion from OS grid references to WGS84 latitude
       and longitude coordinates without using the whole OSTN data set.  The algorithm used is known as a
       Helmert transformation.  This is the usual coordinate conversion algorithm implemented in most consumer-
       level GPS devices.  It is based on parameters supplied by the OS; they suggest that in most of the UK
       this conversion is accurate to within about 5m.

           my ($lat, $lon) = grid_to_ll_helmert(538885, 177322);

       The input must be in metres from false point of origin (as produced by "parse_grid") and the results are
       in decimal degrees using the WGS84 model.

       The results are returned with the full Perl precision in the same way as "grid_to_ll" so that you can
       choose an appropriate rounding for your needs.  Four or five decimal places is probably appropriate in
       most cases.  This represents somewhere between 1 and 10 m on the ground.

       This function is called automatically by "grid_to_ll" if the grid reference you supply lies outside the
       OSTN polygon.  (All such spots are far out to sea).  The results are only useful close to mainland
       Britain.

       Importing all the functions

       You can import all the functions defined in "OSGB.pm" with an ":all" tag.

           use Geo::Coordinates::OSGB ':all';

EXAMPLES

         use Geo::Coordinates::OSGB qw/ll_to_grid grid_to_ll/;

         # Latitude and longitude according to the WGS84 model
         ($lat, $lon) = grid_to_ll($e, $n);

         # and to go the other way
         ($e, $n) = ll_to_grid($lat,$lon);

       See the test files for more examples of usage.

BUGS AND LIMITATIONS

       The formulae supplied by the OS and used for the conversion routines are specifically designed to be
       close floating-point approximations rather than exact mathematical equivalences.  So after round-trips
       like these:

         ($lat1,$lon1) = grid_to_ll(ll_to_grid($lat0,$lon0));
         ($e1,$n1)     = ll_to_grid(grid_to_ll($e0,$n0));

       neither "$lat1 == $lat0" nor "$lon1 == $lon0" nor "$e1 == $e0" nor "$n1 == $n0" exactly.  However the
       differences should be very small.

       The OS formulae were designed to give an accuracy of about 1 mm of error.  This means that you can rely
       on the third decimal place for grid references and about the seventh or eighth for latitude and longitude
       (although the OS themselves only provide six decimal places in their results).

       For all of England, Wales, Scotland, and the Isle of Man the error will be tiny.  All other areas, like
       Northern Ireland, the Channel Islands or Rockall, and any areas of sea more than a few miles off shore,
       are outside the coverage of OSTN, so the simpler, less accurate transformation is used.  The OS state
       that this is accurate to about 5m but that the parameters used are only valid in the reasonably close
       vicinity of the British Isles.

       Not enough testing has been done.  I am always grateful for the feedback I get from users, but especially
       for problem reports that help me to make this a better module.

DIAGNOSTICS

       The only error message you will get from this module is about the ellipsoid shape used for the
       transformation.  If you try to set "{shape => 'blah'}" the module will croak with a message saying
       "Unknown shape: blah".  The shape should be one of the shapes defined: WGS84 or OSGB36.

       Should this software not do what you expect, then please first read this documentation, secondly verify
       that you have installed it correctly and that it passes all the installation tests on your set up,
       thirdly study the source code to see what it's supposed to be doing, fourthly get in touch to ask me
       about it.

CONFIGURATION AND ENVIRONMENT

       There is no configuration required either of these modules or your environment.  It should work on any
       recent version of Perl, on any platform.

DEPENDENCIES

       Perl 5.10 or better.

INCOMPATIBILITIES

       None known.

       Copyright (C) 2002-2017 Toby Thurston

       OSTN transformation data included in this module is freely available from the Ordnance Survey but remains
       Crown Copyright (C) 2002

       This program is free software; you can redistribute it and/or modify it under the terms of the GNU
       General Public License as published by the Free Software Foundation; either version 2 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
       License for more details.

       You should have received a copy of the GNU General Public License along with this program; if not, write
       to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

AUTHOR

       Toby Thurston -- 29 Oct 2017

       toby@cpan.org

SEE ALSO

       See Geo::Coordinates::OSGB::Grid for routines to format grid references.

       The UK Ordnance Survey's explanations on their web pages.

       See Geo::Coordinates::Convert for a general approach (not based on the OSGB).