view release on metacpan or  search on metacpan

lib/Geo/Coordinates/OSGB/Background.pod  view on Meta::CPAN

=pod

=head1 NAME

Geo::Coordinates::OSGB::Background - Background and extended description 

=head1 VERSION

2.20

=head1 DESCRIPTION

These notes are part of Geo::Coordinates::OSGB, a Perl implementation of
latitude and longitude co-ordinate conversion for England, Wales, and
Scotland based on formulae and data published by the Ordnance Survey of
Great Britain.

These modules will convert accurately between an OSGB national grid
reference, and coordinates given in latitude and longitude using the
WGS84 model.  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 an
accurate British National grid reference for use with one of the
Ordnance Survey's paper maps.  And I<vice versa>, of course.

These notes explain some of the background and implementation details
that might help you get the most out of them.

The algorithms and theory for these conversion routines are all from I<A Guide
to Coordinate Systems in Great Britain> published by the OSGB, April 1999
(Revised December 2010) and available from L<the Ordnance Survey
website|http://www.ordnancesurvey.co.uk/>.  You may also like to read some of
the other introductory material there.  Should you be hoping to adapt this code
to your own custom Mercator projection, you will find the paper called
I<Surveying with the National GPS Network>, especially useful.

=head2 Upgrading from V2.09 or earlier

These modules suffered a major overhaul in V2.10 which changed the
semantics and interface.  The motivation for the change was to simplify
the interface, to make WGS84 the default model for latitude and
longitude, and to speed up conversions.  This section explains what you
might have to change to get your old code to work with V2.10 and above.

=over 4

=item * 

The module structure changed from V2.09 to V2.10 so it would probably be
a good idea to clean up any old installation you have and re-install a
new version so that none of the old files hangs about.  The simplest way 
to do this is to use the C<cpanm> application.

=item *

The parsing and formatting routines have been split into a separate
module, so before V2.10 you could do this:

   use Geo::Coordinates::OSGB ':all'; # Don't do this any more

now you need to do this:

   use Geo::Coordinates::OSGB       qw(grid_to_ll ll_to_grid);
   use Geo::Coordinates::OSGB::Grid qw(parse_grid format_grid);

=item *

The old C<OSTN02.pm> module has been removed.  The data and the
functions it provided are now integrated into C<OSGB.pm>.  The 
old C<OSGB36_to_ETRS89> and C<ETRS89_to_OSGB36> functions are
now built into C<ll_to_grid> and C<grid_to_ll>; the OSTN data 
is now used automatically when needed.

=item * 

lib/Geo/Coordinates/OSGB/Background.pod  view on Meta::CPAN

Last year (2016) with version 2.16 of this module, a typical bench mark run on
my development machine (a Mac Mini server from 2011) using the Apple-supplied
Perl 5.16 gave:

    Subroutine          calls per sec  ms per call 
    ----------------------------------------------
    ll_to_grid                  41677        0.024 
    ll_to_grid_helmert          42145        0.024 
    
    grid_to_ll                  18131        0.055 
    grid_to_ll_helmert          35793        0.028 

On my newer work machine (a MBP from 2015) using the newer Perl 5.18 supplied
with macOS Sierra, I got slightly better numbers with V2.16

    Subroutine          calls per sec  ms per call
    ----------------------------------------------
    ll_to_grid                  50980        0.020
    ll_to_grid_helmert          68267        0.015
    
    grid_to_ll                  25831        0.039
    grid_to_ll_helmert          54371        0.018

But after a bit more work to simplify the way that the cache is implemented 
I get this on the same MBP with the version 2.19:

    Subroutine          calls per sec  ms per call
    ----------------------------------------------
    ll_to_grid                  69099       0.0145
    ll_to_grid_helmert          66158       0.0151

    grid_to_ll                  29114       0.0343
    grid_to_ll_helmert          53969       0.0185

Now, on the same MBP, but with the new OSTN15 data set and the simpler data look up I get:

    Subroutine          calls per sec  ms per call
    ----------------------------------------------
    ll_to_grid                  70730       0.0141
    ll_to_grid_helmert          63308       0.0158
    
    grid_to_ll                  32238       0.0310
    grid_to_ll_helmert          55286       0.0181

In my opinion, this justifies my decision to make the accurate OSTN conversion
the default.  The approximate Helmert-based routine is no quicker for ll to
grid conversions.  

It is always going to be slightly slower converting from grid to ll, due to the
iterative nature of the algorithm that is built into OSTN15.  So the
approximate routine is likely to remain slightly faster.  Having said that
none of the routines is really slow, since even C<grid_to_ll> averages under 60
microseconds per call on the older machine.  `Your mileage may vary', of
course.

The routines have been tested with various versions of Perl, including recent
versions with the C<uselongdouble> option enabled.  Using a locally compiled
version of Perl 5.22 with ordinary doubles, I saw a small improvement on the
Helmert routines, but the default routines are about the same.  On the same
system, long doubles slowed everything down by about 10%, and made no
difference to the round trip precision of the routines. Since the formulae were
specifically designed for ordinary double precision arithmetic, Perl's default
arithmetic is more than adequate.  

=head2 Maps 

Since Version 2.09 these modules have included a set of map sheet
definitions so that you can find which paper maps your coordinates are
on.

See L<Geo::Coordinates::OSGB::Maps> for details of the series included.
The first three series are OS maps:

  A - OS Landranger maps at 1:50000 scale; 
  B - OS Explorer maps at 1:25000; 
  C - the old OS One-Inch maps at 1:63360.  

Landranger sheet 47 appears in the list of keys as C<A:47>, Explorer
sheet 161 as C<B:161>, and so on.  As of 2015, the Explorer series of
incorporates the Outdoor Leisure maps, so (for example) the two sheets
that make up the map `Outdoor Leisure 1' appear as C<B:OL1E> and
C<B:OL1W>.

Thanks to the marketing department at the OS and their ongoing
re-branding exercise several Explorer sheets have been promoted to
Outdoor Leisure status.  So (for example) Explorer sheet 364 has
recently become `Explorer sheet Outdoor Leisure 39'.  Maps like this are
listed with a combined name, thus: C<B:395/OL54>.

Many of the Explorer sheets are printed on both sides.  In these cases
each side is treated as a separate sheet and distinguished with
suffixes.  The pair of suffixes used for a map will either be N and S,
or E and W.  So for example there is no Explorer sheet C<B:271>, but you
will find sheets C<B:271N> and C<B:271S>.  The suffixes are determined
automatically from the layout of the sides, so in a very few cases it
might not match what is printed on the sheet but it should still be
obvious which side is which.  Where the map has a combined name the
suffix only appears at the end. For example: C<B:386/OL49E> and
C<B:386/OL49W>.

Several sheets also have insets, for islands, like Lundy or The Scilly
Isles, or for promontories like Selsey Bill or Spurn Head.  Like the
sides, these insets are also treated as additional sheets (albeit rather
smaller).  They are named with an alphabetic suffix so Spurn Head is on
an inset on Explorer sheet 292 and this is labelled C<B:292.a>.  Where
there is more than one inset on a sheet, they are sorted in descending
order of size and labelled C<.a>, C<.b> etc.  On some sheets the insets
overlap the area of the main sheet, but they are still treated as
separate map sheets.  

Some maps have marginal extensions to include local features - these are
simply included in the definition of the main sheets.  There are,
therefore, many sheets that are not regular rectangles.  Nevertheless,
the module is able to work out when a point is covered by one of these
extensions.

In the examples folder there is an extended example showing how to work
with the map data as supplied through the C<Maps.pm> interface.

The source files for the map data are in the C<maps> directory.  The script that
builds C<Maps.pm> from the source files is C<build/make_maps_code>.