=head1 Backround and extended 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 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 Dec 2010) and available at
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 Coordinates and ellipsoid models

This section explains the fundamental problems of mapping a
spherical earth onto a flat piece of paper (or computer screen).  A
basic understanding of this material will help you use these
routines more effectively.  It will also provide you with a good
store of ammunition if you ever get into an argument with someone
from the Flat Earth Society.

It is a direct consequence of Newton's law of universal gravitation
(and in particular the bit that states that the gravitational
attraction between two objects varies inversely as the square of the
distance between them) that all planets are roughly spherical.  (If
they were any other shape gravity would tend to pull them into a
sphere).  On the other hand, most useful surfaces for displaying
large scale maps (such as pieces of paper or screens) are flat.
There is therefore a fundamental problem in making any maps of the
earth that its curved surface being mapped must be distorted at
least slightly in order to get it to fit onto the flat map.

This module sets out to solve the corresponding problem of
converting latitude and longitude coordinates (designed for a
spherical surface) to and from a rectangular grid (for a flat
surface).  A spherical projection is a fairly simple but tedious bit
of trigonometry, but the problem is complicated by the fact that the
earth is not quite a sphere.  Because our planet spins about a
vertical axis, it tends to bulge out slightly in the middle, so it
is more of an oblate spheroid (or ellipsoid) than a sphere.  This
makes the arithmetic even more tedious, but the real problem is that
the earth is not a regular ellipsoid either, but an irregular lump
that closely resembles an ellipsoid and which is constantly (if
slowly) being rearranged by plate tectonics.  So the best we can do
is to pick an imaginary regular ellipsoid that provides a good fit
for the region of the earth that we are interested in mapping.

An ellipsoid model is defined by a series of numbers:  the major and
minor semiaxes of the solid, and a ratio between them called the
flattening. There are three ellipsoid models that are relevant to the UK:

=over 4

=item OSGB36

The OSGB's own ellipsoid is a revision of work begun by George Airy
the Astronomer Royal in 1830, when the OS first undertook to make a
series of maps that covered the entire country.  It provides a
good fit for most of the British Isles. 

=item EDM50

The European standard ellipsoid is a compromise to get a good fit
for most of Western Europe. 

=item WGS84

As part of the development of the GPS network by the American
military in the 1980s a new world-wide ellipsoid was defined. This
fits most populated regions of the world reasonably well.

=back

The latitude and longitude marked on OS maps are in the OSGB36 model.
The latitude and longitude you read from your GPS device, or from
Wikipedia, or Google Earth are in the WGS84 model.  So the point
with latitude 51.4778 and longitude 0 in the OSGB36 model is on the prime
meridian line in the courtyard of the Royal Observatory in
Greenwich, but the point with the same coordinates in the WGS84
model is about 100 yards away to the east, in the park.

There is no intrinsic merit to using one model or another, but
there's an obvious need to be consistent about which one you choose,
and with the growing ubiquity of GPS systems, it makes sense to
standardize of WGS84.  It is perhaps possible that future editions
of OS maps will show WGS84 latitude and longitude along the edges 
rather than OSGB36.

In these modules the shape used for the projection of latitude and
longitude onto the grid is WGS84 unless you specifically set it to
use OSGB36. 

=head2 The British National Grid and OSTN02

A Mercator grid projection like the British National Grid is defined
by the five parameters defined as constants at the top of the
module.

=over 4

=item True point of origin Latitude and Longitude = 49N 2W

=item False origin easting and northing = 400000 -100000

=item Convergence factor = 0.9996012717

=back 

One consequence of the True Point of Origin of the British Grid
being set to C<+4900-00200/> is that all the vertical grid lines are
parallel to the 2W meridian; you can see this on the appropriate OS
maps (for example Landranger sheet 184), or on the C<plotmaps.pdf>
picture supplied with this package.  The effect of moving the False
Point of Origin to the far south west is that all grid references
always positive.

Strictly grid references are given as whole numbers of metres from
this point, with the easting always given before the northing.  For
everyday use however, the OSGB suggest that grid references need
only to be given within the local 100km square as this makes the
numbers smaller.  For this purpose they divide Britain into a series
of 100km squares identified in pair of letters:  TQ, SU, ND, etc.
The grid of the big squares actually used is something like this:

                                HP 
                                HU 
                             HY 
                    NA NB NC ND 
                    NF NG NH NJ NK
                    NL NM NN NO NP 
                       NR NS NT NU 
                       NW NX NY NZ OV
                          SC SD SE TA 
                          SH SJ SK TF TG 
                       SM SN SO SP TL TM 
                       SR SS ST SU TQ TR 
                    SV SW SX SY SZ TV

SW covers most of Cornwall, TQ London, HU the Shetlands, and there's
one tiny corner of a beach in Yorkshire that is in OV.  Note that it
has the neat feature that N and S are directly above each other, so
that most Sx squares are in the south and most Nx squares are in the
north.  The system logically extends far out in all directions; so 
square XA lies south of SV and ME to the west of NA and so on.  But
it becomes less useful the further you go from the central meridian
of 2W.

Within each of the large squares, we only need five digit
coordinates --- from (0,0) to (99999,99999) --- to refer to a given
square metre.  For daily use however we don't generally need such
precision, so the normal recommended usage is to use units of 100m
(hectometres) so that we only need three digits for each easting and
northing --- 000,000 to 999,999.  If we combine the easting and
northing we get the familiar traditional six figure grid reference.
Each of these grid references is repeated in each of the large 100km
squares but for local use with a particular map, this does not
usually matter.  Where it does matter, the OS suggest that the six
figure reference is prefixed with the identifier of the large grid
square to give a `full national grid reference', such as TQ330800.
This system is described in the notes in the corner of every
Landranger 1:50,000 scale map.

This system was originally devised for use on top of the OSGB36
model of latitude and longitude, so the prime meridian used and the
coordinates of the true point of origin are all defined in that
system.  However as part of standardizing on an international GPS
system, the OS have redefined the grid as a rubber sheet
transformation from WGS84.  This transformation of called OSTN02 and
consists of a large dataset that defines a three dimensional shift
for each square kilometre of the country.  To get from WGS84
latitude and longitude to the grid, you project from the WGS84
ellipsoid to a pseudo-grid and then look up the relevant shifts from
OSTN02 and adjust the easting and northing accordingly to get
coordinates in the OSGB grid.  Going the other way is slightly more
complicated as you have to use an iterative approach to find the
latitude and longitude that would give you your grid coordinates.

It is also possible to use a three-dimensional shift and rotation
called a Helmert transformation to get an approximate conversion. 
This approach is used automatically by these modules for locations 
that are undefined in OSTN02.

Modern GPS receivers can all display coordinates in the OS grid
system.  You just need to set the display units to be `British
National Grid' or whatever similar name is used on your unit.  Most
units display the coordinates as two groups of five digits and a
grid square identifier.  The units are metres within the grid
square.  However you should note that your consumer GPS unit will
B<not> have a copy of the whole of OSTN02 in it.  It will be using
either a Helmert transformation, or an even more approximate
Molodenksy transformation to translate from the WGS84 coordinates it
is getting from the satellite to find the OSGB grid figures.

Note that the OSGB (and therefore this module) does not cover the
whole of the British Isles, nor even the whole of the UK, in
particular it covers neither the Channel Islands nor Northern
Ireland.  The coverage that is included is essentially the same as
the coverage provided by the OSGB "Landranger" 1:50000 series maps.
The coverage of the OSTN02 data set is slightly smaller, as the OS
do not define the model for any points more than about 2km off
shore.

=head2 Accuracy and precision


This section explores the limits of accuracy and precision you can expect
from this software.  Almost certainly it provides more accuracy than
you need.  

In particular if you are converting readings taken from your own
handheld GPS device, the readings themselves will not be very
accurate. To convince yourself of this, try taking your GPS on the
same walk on different days and comparing the track: you will see
that the tracks do not coincide.  If you have two units take them
both and compare the tracks:  you will see that they do not
coincide.

The accuracy of the readings you get will be affected by cloud
cover, tree cover, the exact positions of the satellites relative to
you (which are constantly changing as the earth rotates), how close
you are to sources of interference, like buildings or electricity
installation, not to mention the ambient temperature and the state
of your rechargeable battery. 

Having said that it's worthwhile considering what errors this
software might introduce.

First some sizes.  In the British Isles the distance along a
meridian between two points that are one degree of latitude apart is
about 110 km or just under 70 miles. This is the distance as the
crow flies from, say, Swindon to Walsall.  So a tenth of a degree is
about 11 km or 7 miles, a hundredth is just over 1km, 0.001 is about
110m, 0.0001 about 11m and 0.00001 just over 1 m.  If you think in
minutes, and seconds, then one minute is about 1840 m (and it's no
coincidence that this happens to be approximately the same as 1
nautical mile).  One second is a bit over 30m, 0.1 seconds is about
3 m, and 0.0001 second is about 3mm.

         Degrees              Minutes             Seconds  * LATITUDE *           
               1 = 110 km         1 = 1.8 km        1 = 30 m  
             0.1 =  11 km       0.1 = 180 m       0.1 =  3 m   
            0.01 = 1.1 km      0.01 =  18 m      0.01 = 30 cm 
           0.001 = 110 m      0.001 =   2 m     0.001 =  3 cm  
          0.0001 =  11 m     0.0001 = 20 cm    0.0001 =  3 mm  
         0.00001 = 1.1 m    0.00001 =  2 cm         
        0.000001 = 11 cm   0.000001 =  2 mm         
       0.0000001 =  1 cm               

Degrees of latitude get very slightly longer as you go further north
but not by much.  In contrast degrees of longitude, which represent
the same length on the ground as latitude at the equator, get
significantly smaller in northern latitudes.  In southern England
one degree of latitude represents about 70 km or 44 miles, in
northern Scotland it's less than 60 km or about 35 miles.  Scaling
everything down means that the fifth decimal place of a degree of
longitude represents about 60-70cm on the ground.

       Degrees                Minutes            Seconds * LONGITUDE * 
             1 = 60-70 km         1 = 1.0-1.2 km      1 = 17-20 m 
           0.1 = 6-7 km         0.1 = 100-120 m     0.1 = 2 m     
          0.01 = 600-700 m     0.01 = 10-12 m      0.01 = 20 cm   
         0.001 = 60-70 m      0.001 = 1 m         0.001 = 2 cm    
        0.0001 = 6-7 m       0.0001 = 10 cm      0.0001 = 2 mm      
       0.00001 = 60-70 cm   0.00001 = 1 cm             

The OS supply test data with OSTN02 that comes from various fixed
stations around the country and that form part of the definition of
the transformation.  If you look in the test file C<06osdata.t> you 
can see how it it used for testing these modules.

In all cases translating from the WGS84 coordinates to the national
grid is accurate to the millimetre, so these modules are at least as
accurate as the OSGB's own software that produced the test data.

Translating from the given grid coordinates to WGS84 latitude and
longitude coordinates is less accurate. This appears to be related
to the iterative approch required but there is no obvious reason.
Moreover there is a pattern to the errors.  In all of England and
Wales, this software produces WGS lat/lon coordinates from the given
grid references that are within a few mm of the OSGB data.  However
in Scotland, and especially for those stations that are further
north and west the latitude coordinates produced are upto 12cm out, 
while the longitude coordinates are about 1cm out.  This may be
because the OS test data has some bias, or it may be a feature of
the mathematics.  Either way that's what's achievable with the OS
test data, and your results are likely to be similar, provided you have
access to such accurate data readings in the first place.

Outside the area covered by OSTN02 this module uses the small
Helmert transformation recommended by the OS.  The OS state, that
with the parameters they provide, this transformation will be
accurate upto about 5m within the immediate vicinity of the British
Isles.  The accuracy will diminish the further away you are.

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

The series of maps currently defined include: 

 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 as "A:47" and Explorer sheet 161 as
"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 "B:OL1E" and "B:0L1W".

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: '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
'B:271', but you will find sheets 'B:271N' and '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: "B:386/OL49E" and "B:386/OL49W".

Several sheets also have insets, for islands, like Lundy or The
Scillies, or for promontaries 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 "B:292.a".  Where there is more than one inset on a sheet,
they are sorted in descending order of size and labelled ".a", ".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.

=cut
