Provided by: libgeo-coordinates-osgb-perl_2.15-1_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

       Examine $Geo::Coordinates::OSGB::VERSION for details.

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 an OSGB national grid reference and coordinates
       given in latitude and longitude.

       In Version 2.10 and above, the default ellipsoid model used 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 fine tuned to 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 excludes 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 spaces.

       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 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 argument 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 distance 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).

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

       If the coordinates you supply are in the area covered by the OSTN02 transformation data,
       then the results will be rounded to 3 decimal places, which corresponds to the nearest
       millimetre.  If they are outside the coverage (which normally means more than a few km off
       shore) then the conversion is automagically done using a Helmert transformation instead of
       the OSTN02 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.

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

       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.

           $gridref = format_grid(ll_to_grid(51.5,-0.0833));
           $gridref = format_grid_GPS(ll_to_grid(51.5,-0.0833));
           $gridref = format_grid_map(ll_to_grid(51.5,-0.0833));

       "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 on OS
       maps 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'}" since 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 it 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 maps).  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 quicker conversion from WGS84 lat/lon to the OS grid
       without using the whole OSTN02 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 ($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 OSTN02 polygon.

       "grid_to_ll_helmert(e,n)"

       You can use this function to do a quicker conversion from OS grid references to WGS84
       latitude and longitude coordinates without using the whole OSTN02 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 OSTN02 polygon.  (Generally such spots are in the sea).  The results are
       only reliable close to mainland Britain.

       "is_grid_in_ostn02(e,n)"

       This function can be used to check whether a grid point is covered by the OSTN02 data set.
       The input is an easting, northing pair as usual, and the output will be either true or
       false.  If you get a true value you can expect an accurate result from "grid_to_ll", if
       false then it's likely that "grid_to_ll" will fall back on using the approximate Helmert
       transformation.  This function is used by "random_grid" from
       Geo::Coordinates::OSGB::Grid.pm.

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 OSTN02, 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.08 or better.

INCOMPATIBILITIES

       None known.

LICENSE AND COPYRIGHT

       Copyright (C) 2002-2016 Toby Thurston

       OSTN02 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 -- 05 Feb 2016

       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).