Debian Codegraph @

lib/Geo/Coordinates/OSGB/Background.pod

raw
1 =pod
2
3 =head1 NAME
4
5 Geo::Coordinates::OSGB::Background - Background and extended description
6
7 =head1 VERSION
8
9 2.20
10
11 =head1 DESCRIPTION
12
13 These notes are part of Geo::Coordinates::OSGB, a Perl implementation of
14 latitude and longitude co-ordinate conversion for England, Wales, and
15 Scotland based on formulae and data published by the Ordnance Survey of
16 Great Britain.
17
18 These modules will convert accurately between an OSGB national grid
19 reference, and coordinates given in latitude and longitude using the
20 WGS84 model. This means that you can take latitude and longitude
21 readings from your GPS receiver, (or read them from Wikipedia, or Google
22 Earth, or your car's sat-nav), and use this module to convert them to an
23 accurate British National grid reference for use with one of the
24 Ordnance Survey's paper maps. And I<vice versa>, of course.
25
26 These notes explain some of the background and implementation details
27 that might help you get the most out of them.
28
29 The algorithms and theory for these conversion routines are all from I<A Guide
30 to Coordinate Systems in Great Britain> published by the OSGB, April 1999
31 (Revised December 2010) and available from L<the Ordnance Survey
32 website|http://www.ordnancesurvey.co.uk/>. You may also like to read some of
33 the other introductory material there. Should you be hoping to adapt this code
34 to your own custom Mercator projection, you will find the paper called
35 I<Surveying with the National GPS Network>, especially useful.
36
37 =head2 Upgrading from V2.09 or earlier
38
39 These modules suffered a major overhaul in V2.10 which changed the
40 semantics and interface. The motivation for the change was to simplify
41 the interface, to make WGS84 the default model for latitude and
42 longitude, and to speed up conversions. This section explains what you
43 might have to change to get your old code to work with V2.10 and above.
44
45 =over 4
46
47 =item *
48
49 The module structure changed from V2.09 to V2.10 so it would probably be
50 a good idea to clean up any old installation you have and re-install a
51 new version so that none of the old files hangs about. The simplest way
52 to do this is to use the C<cpanm> application.
53
54 =item *
55
56 The parsing and formatting routines have been split into a separate
57 module, so before V2.10 you could do this:
58
59 use Geo::Coordinates::OSGB ':all'; # Don't do this any more
60
61 now you need to do this:
62
63 use Geo::Coordinates::OSGB qw(grid_to_ll ll_to_grid);
64 use Geo::Coordinates::OSGB::Grid qw(parse_grid format_grid);
65
66 =item *
67
68 The old C<OSTN02.pm> module has been removed. The data and the
69 functions it provided are now integrated into C<OSGB.pm>. The
70 old C<OSGB36_to_ETRS89> and C<ETRS89_to_OSGB36> functions are
71 now built into C<ll_to_grid> and C<grid_to_ll>; the OSTN data
72 is now used automatically when needed.
73
74 =item *
75
76 The main conversion routines now assume the WGS84 model for lat/lon
77 coordinates. If you still want to work with the OSGB36 model for
78 lat/lon, then you need to add the C<< { shape => 'OSGB36' } >> option
79 when converting. In other words if you did this before:
80
81 my ($e, $n) = ll_to_grid(52.5, -2);
82
83 then to get exactly the same results, you now need to do this
84
85 my ($e, $n) = ll_to_grid(52.5, -2, { shape => 'OSGB36' } );
86
87 On the other hand, if you are working with the WGS84 model, then before
88 V2.10 you had to do this:
89
90 # Old and exact
91 my ($e, $n) = ETRS89_to_OSGB36(ll_to_grid(52.5, -2));
92
93 or this:
94
95 # Old and approximate
96 my ($e, $n) = ll_to_grid(shift_ll_from_WGS84(52.5, -2));
97
98 now you can just do:
99
100 my ($e, $n) = ll_to_grid(52.5, -2);
101
102 This means that the most likely use case is the default. In other words
103 you can take lat/lon from your GPS and get correct grid references by
104 default
105
106 =item *
107
108 The functions C<shift_ll_into_WGS84> and C<shift_ll_from_WGS84> are
109 no longer provided. They were not very accurate, and they were
110 confusing. C<ll_to_grid> and C<grid_to_ll> now do the necessary
111 adjustments for you automatically.
112
113 =item *
114
115 The functions to parse and format grid references are moved to
116 C<OSGB/Grid.pm>. They have also been radically simplified, so that
117 there are now only two functions: C<parse_grid> and C<format_grid>.
118 The old names like C<parse_GPS_grid> and C<format_grid_trad> are
119 retained with their former meanings, but they are just synonyms
120 for the two core functions.
121
122 =item *
123
124 The functions to parse and format lat/lon have been removed. They
125 were not really a core function of this module. There are other modules
126 on CPAN to deal with latitude and longitude. I also give an example of
127 how to format decimal degrees as degrees, minutes, and seconds in
128 C<examples/bngl.pl>.
129
130 =back
131
132 =head2 Coordinates and ellipsoid models
133
134 This section explains the fundamental problems of mapping a spherical
135 earth onto a flat piece of paper (or computer screen). A basic
136 understanding of this material will help you use these routines more
137 effectively. It will also provide you with a good store of ammunition
138 if you ever get into an argument with someone from the Flat Earth
139 Society.
140
141 It is a direct consequence of Newton's law of universal gravitation (and
142 in particular the bit that states that the gravitational attraction
143 between two objects varies inversely as the square of the distance
144 between them) that all planets are roughly spherical; if they were any
145 other shape gravity would tend to pull them into a sphere. On the other
146 hand, most useful surfaces for displaying large scale maps (such as
147 pieces of paper or screens) are flat. Therefore the fundamental problem
148 in making a map of the earth is that the curved surface being mapped
149 must be distorted at least slightly in order to get it to fit onto a
150 flat map.
151
152 This module sets out to solve the corresponding problem of converting
153 latitude and longitude coordinates (designed for a spherical surface) to
154 and from a rectangular grid (for a flat surface). A spherical
155 projection is a fairly simple but tedious bit of trigonometry, but the
156 problem is complicated by the fact that the earth is not quite a sphere.
157 Because our planet spins about a vertical axis, it tends to bulge out
158 slightly in the middle, so it is more of an oblate spheroid (or
159 ellipsoid) than a sphere. This makes the arithmetic even more tedious,
160 but the real problem is that the earth is not a regular ellipsoid
161 either; it is an irregular lump that closely resembles an ellipsoid and
162 which is constantly (if slowly) being rearranged by plate tectonics. So
163 the best we can do is to pick an imaginary regular ellipsoid that
164 provides a good fit for the region of the earth that we are interested
165 in mapping.
166
167 An ellipsoid model is defined by a series of numbers: the major and
168 minor semi-axes of the solid, and a ratio between them called the
169 flattening. There are four ellipsoid models that are relevant to the UK:
170
171 =over 4
172
173 =item OSGB36
174
175 The OSGB36 ellipsoid is a revision of work begun by George Airy the
176 Astronomer Royal in 1830, when the OS first undertook to make a series
177 of maps that covered the entire country. It provides a good fit for
178 most of the British Isles.
179
180 =item EDM50
181
182 The European standard ellipsoid is a compromise to get a good fit for
183 most of Western Europe. This is not used by these modules.
184
185 =item WGS84
186
187 As part of the development of the GPS network by the American military
188 in the 1980s a new world-wide ellipsoid called WGS84 was defined. This fits most
189 populated regions of the world reasonably well. (Technically the ellipsoid is
190 called GRS80, and WGS84 refers to the whole World Geodetic System that is based on it, plus
191 some very nerdy modifications, but for the purposes of this module it's just a label).
192
193 =item ETRS89
194
195 The European Terrestrial Reference System is also based on GRS80, and for our
196 purposes is identical to WGS84. The technical difference is that in the ETRS89
197 system assumes that the Eurasian tectonic plate is the reference, whereas
198 WGS84 assumes that the American plate is the reference. But this makes no
199 practical difference whatsoever for the use of these modules.
200
201 =back
202
203 The latitude and longitude marked on OS maps printed before 2015 are given in
204 the OSGB36 model. The latitude and longitude you read from your GPS device, or
205 from Wikipedia, or Google Earth are in the WGS84 model. So the point with
206 latitude 51.4778 and longitude 0 in the OSGB36 model is on the prime meridian
207 line in the courtyard of the Royal Observatory in Greenwich, but the point with
208 the same coordinates in the WGS84 model is about 120 metres away to the
209 south-east, in the park.
210
211 In these modules the shape used for the projection of latitude and
212 longitude onto the grid is WGS84 unless you specifically set it to use
213 OSGB36.
214
215 =head2 The British National Grid and OSTN02 / OSTN15
216
217 A Mercator grid projection like the British National Grid is defined by
218 the five parameters defined as constants at the top of the module.
219
220 =over 4
221
222 =item *
223
224 True point of origin Latitude and Longitude = 49N, 2W
225
226 =item *
227
228 False origin easting and northing = 400000, -100000
229
230 =item *
231
232 Convergence factor = 0.9996012717
233
234 =back
235
236 One consequence of the True Point of Origin of the British Grid being
237 set to 49N, 2W is that all the vertical grid lines are parallel
238 to the 2W meridian; you can see this on the appropriate OS maps (for
239 example Landranger sheet 184), or on the PDF picture supplied with this
240 package in the C<examples> folder. The effect of moving the False Point
241 of Origin to the far south west is to make all grid references positive.
242
243 Strictly speaking, grid references are given as the distance in metres
244 from the False Point of Origin, with the easting always given before the
245 northing. For everyday use however, the OSGB suggest that grid
246 references need only to be given within the local 100km square as this
247 makes the numbers smaller. For this purpose they divide Britain into a
248 series of 100km squares, each identified by a pair of letters: TQ, SU,
249 ND, etc. The grid of the big squares actually used is something like
250 this:
251
252 HP
253 HU
254 HY
255 NA NB NC ND
256 NF NG NH NJ NK
257 NL NM NN NO NP
258 NR NS NT NU
259 NW NX NY NZ OV
260 SC SD SE TA
261 SH SJ SK TF TG
262 SM SN SO SP TL TM
263 SR SS ST SU TQ TR
264 SV SW SX SY SZ TV
265
266 SW covers most of Cornwall, TQ London, HU the Shetlands, and there is one
267 tiny corner of a beach in Yorkshire that is in OV. The system has the
268 neat feature that N and S are directly above each other, so that most Sx
269 squares are in the south and most Nx squares are in the north. The
270 system logically extends far out in all directions; so square XA lies
271 south of SV and ME to the west of NA and so on. But it becomes less
272 useful the further you go from the central meridian of 2W.
273
274 Within each of the large squares, we only need five-digit coordinates --- from
275 (0,0) to (99999,99999) --- to refer to a given square metre. But general use
276 rarely demands such precision, so the OSGB recommendation is to use units of
277 100m (hectometres) so that we only need three digits for each easting and
278 northing --- (000,000) to (999,999). If we combine the easting and northing we
279 get the familiar traditional six figure grid reference. Each of these grid
280 references is repeated in each of the large 100km squares but this does not
281 usually matter for local use with a particular map. Where it does matter, the
282 OS suggest that the six figure reference is prefixed with the identifier of the
283 large grid square to give a `full national grid reference', such as TQ330800.
284 This system is described in the notes in the corner of every Landranger
285 1:50,000 scale map.
286
287 This system was originally devised for use on top of the OSGB36 model of
288 latitude and longitude, so the prime meridian used and the coordinates
289 of the true point of origin are all defined in that system. However as
290 part of standardizing on an international GPS system, the OS have
291 redefined the grid as a rubber sheet transformation from WGS84.
292 There is no intrinsic merit to using one model or another, but there's
293 an obvious need to be consistent about which one you choose, and with
294 the growing ubiquity of GPS systems, it makes sense to standardize on
295 WGS84.
296
297 The grid remains the primary reference system for use with maps, but
298 the OS has always also printed a latitude and longitude `graticule' around the
299 edges of the large scale sheets. Traditionally these coordinates have been
300 given in the OSGB36 model, but since 2015 the OS has been printing revised
301 editions of Explorer and Landranger sheets with WGS84 coordinates instead.
302 The legend of my recently purchased copy of Explorer 311 has this paragraph under the
303 heading `The National Grid Reference System':
304
305 =over 4
306
307 =item * Base map constructed on Transverse Mercator Projection, Airy Ellipsoid, OSGB (1936) Datum.
308 Vertical datum mean sea level. The latitude, longitude graticule overlay is on the ETRS89 datum
309 and is compatible with the WGS84 datum used by satellite navigation devices.
310
311 =back
312
313 If your map does not have the last sentence you can assume that it shows OSGB36
314 latitude and longitude. Of course, this change makes no difference to the grid
315 itself.
316
317 The differences between the OSGB36 and WGS84 models are only important if you
318 are working at a fairly small scale. The average differences on the ground
319 vary from about -67 metres to + 124 meters depending on where you are in the
320 country.
321
322 Square Easting difference Northing difference
323 -------------------- ------------------------- ------------------
324 HP 109 66
325 HT HU 100 106 59 62
326 HW HX HY 73 83 93 51 48 47
327 NA NB NC ND 61 65 81 89 40 39 38 40
328 NF NG NH NJ NK 57 68 79 92 99 30 29 28 26 26
329 NL NM NN NO 56 66 79 91 18 17 15 15
330 NR NS NT NU 66 77 92 100 3 2 1 0
331 NW NX NY NZ 70 77 92 103 -9 -8 -10 -13
332 SC SD SE TA 77 93 104 112 -19 -22 -23 -24
333 SH SJ SK TF TG 79 91 103 114 124 -35 -34 -35 -38 -40
334 SM SN SO SP TL TM 72 80 90 101 113 122 -49 -47 -46 -46 -46 -47
335 SS ST SU TQ TR 80 90 101 113 121 -57 -56 -57 -57 -59
336 SW SX SY SZ TV 71 79 90 100 113 -67 -64 -62 -62 -62
337
338
339 The chart above shows the mean difference in each grid square. A
340 positive easting difference means the WGS84 Lat/Lon is to the east of
341 OSGB36; a positive northing difference means it is to the north of
342 OSGB36. At a scale of 1:50,000, 124 meters is 2.48 mm, and at 1:25,000
343 it is 4.96 mm, so the difference is readily visible if you compare new
344 and old editions of the same map sheet.
345
346 The transformation from WGS84 to OSGB36 published in 2002 was called OSTN02 and
347 consisted of a large data set that defined a three dimensional shift for each
348 square kilometre of the country. This dataset was revised (apparently to give
349 a better fit) in 2015 and the revised dataset is called OSTN15.
350
351 To get from WGS84 latitude and longitude to the grid, you project from the
352 WGS84 ellipsoid to a pseudo-grid and then look up the relevant shifts from
353 OSTN15 and adjust the easting and northing accordingly to get coordinates in
354 the OSGB grid. Going the other way is slightly more complicated as you have to
355 use an iterative approach to find the latitude and longitude that would give
356 you your grid coordinates.
357
358 It is also possible to use a three-dimensional shift and rotation called
359 a Helmert transformation to get an approximate conversion. This
360 approach is used automatically by these modules for locations that are
361 undefined in OSTN15, and, if you want to, you can explicitly use it
362 anywhere in the UK by using the C<grid_to_ll_helmert> and
363 C<ll_to_grid_helmert> routines.
364
365 Modern GPS receivers can all display coordinates in the OS grid system.
366 You just need to set the display units to be `British National Grid' or
367 whatever similar name is used on your unit. Most units display the
368 coordinates as two groups of five digits and a grid square identifier.
369 The units are metres within the grid square. However you should note
370 that your consumer GPS unit will B<not> have a copy of the whole of
371 OSTN15 in it. To show you an OSGB grid reference, your GPS will be
372 using either a Helmert transformation, or an even more approximate
373 Molodenksy transformation to translate from the WGS84 coordinates it is
374 getting from the satellites.
375
376 Note that the OSGB (and therefore this module) does not cover the whole
377 of the British Isles, nor even the whole of the UK, in particular it
378 covers neither the Channel Islands nor Northern Ireland. The coverage
379 that is included is essentially the same as the coverage provided by the
380 OSGB "Landranger" 1:50000 series maps. The coverage of the OSTN02 data
381 set was slightly smaller, as the OS did not originally define the model for any
382 points more than about 2km off shore. The main difference in OSTN15 is that
383 coverage is extended to the whole rectangle from grid point (0,0) to (700000,1250000),
384 although the accuracy far off shore should not be relied on more than about +/- 5m.
385
386 =head2 Implementation of OSTN shift data
387
388 The OSTN15 is the definitive transformation from WGS84 coordinates to
389 the British National Grid. It is published as a large text file giving
390 a set of corrections for each square kilometre of the country. The OS
391 also publish an algorithm to use it which is described on their website.
392 Essentially you take WGS84 latitude and longitude coordinates and
393 project them into an (easting, northing) pair of coordinates for the
394 flat surface of your grid. You then look up the corrections for the four
395 corners of the relevant kilometre square and interpolate the exact
396 corrections needed for your spot in the square. Adding these exact
397 corrections gives you an (easting, northing) pair in the British grid.
398
399 The distributed data also includes a vertical height correction as part
400 of the OSGM15 geoid module, but this is not used in this module, so it
401 is omitted from the module in order to save space.
402
403 The table of data supplied by the Ordnance Survey contains 876951 rows with
404 entries for each km intersection between (0,0) and (700000, 1250000). In
405 OSTN02, 567472 of these entries referred to square kms that are more than 10 km
406 away from the British mainland (either in the sea or in Eire) and these were
407 set to zero, indicating that OSTN02 is not defined at these places. In order
408 to save more space, these were omitted from the beginning and end of each row
409 in the data as stored in my original implementation. The last 21 rows (north of
410 Shetland) were all zeroes, so these were omitted as well.
411
412 My implementation of the OSTN02 data was included in the C<OSGB.pm> module after
413 the C<__DATA__> line, and was read using the magic C<< <DATA> >> file handle.
414 In tests this proved to be the fastest way to load all that data, by a long
415 way.
416
417 There were 1229 rows of data, and each row contained up to 701 pairs of shift
418 data encoded as pairs of integers representing the shift in mm. Leading and
419 trailing zeros were omitted, and the number of leading zeros omitted was stored
420 in the first three characters of each row. The integer pairs were all coded in
421 a home-grown version of base32 using the character set C<<
422 0123456789:;<=>?@ABDEFGHIJKLMNO >>. This allowed integers up to 32767 to be
423 stored in three bytes of printable ASCII. that could be stored inside
424 C<OSGB.pm>. Decoding them was very slightly slower than decoding hex strings,
425 but using 3 bytes integer instead of 4 reduced the memory and loading time by
426 25%.
427
428 When the OSGB revised OSTN02 to OSTN15, they filled in all the zeros, so
429 this complicated approach was no longer justified. In version 2.20 and above
430 of this module, the shift data sets are included in the module's `share` directory
431 and loaded at run time. This turns out to be faster and simpler.
432
433 =head2 Accuracy, uncertainty, and speed
434
435 This section explores the limits of accuracy and precision you can
436 expect from this software.
437
438 =head3 Accuracy of readings from GPS devices
439
440 If you are converting readings taken from your own handheld GPS device, the
441 readings themselves will not be very accurate. To convince yourself of this,
442 try taking your GPS on the same walk on different days and comparing the track:
443 you will see that the tracks do not coincide. If you have two units take them
444 both and compare the tracks: you will see that they do not coincide.
445
446 The accuracy of the readings you get will be affected by cloud cover,
447 tree cover, the exact positions of the satellites relative to you (which
448 are constantly changing as the earth rotates), how close you are to
449 sources of interference, like buildings or electricity installations,
450 not to mention the ambient temperature and the state of your
451 rechargeable batteries.
452
453 To get really accurate readings you have to invest in some serious
454 professional or military grade surveying equipment.
455
456 =head3 How big is 0.000001 of a degree?
457
458 In the British Isles the distance along a meridian between two points
459 that are one degree of latitude apart is about 110 km or just under 70
460 miles. This is the distance as the crow flies from, say, Swindon to
461 Walsall. So a tenth of a degree is about 11 km or 7 miles, a hundredth
462 is just over 1km, 0.001 is about 110m, 0.0001 about 11m and 0.00001 just
463 over 1 m. If you think in minutes, and seconds, then one minute is
464 about 1840 m (and it's no coincidence that this happens to be
465 approximately the same as 1 nautical mile). One second is a bit over
466 30m, 0.1 seconds is about 3 m, and 0.0001 second is about 3mm.
467
468 Degrees Minutes Seconds * LATITUDE *
469 1 = 110 km 1 = 1.8 km 1 = 30 m
470 0.1 = 11 km 0.1 = 180 m 0.1 = 3 m
471 0.01 = 1.1 km 0.01 = 18 m 0.01 = 30 cm
472 0.001 = 110 m 0.001 = 2 m 0.001 = 3 cm
473 0.0001 = 11 m 0.0001 = 20 cm 0.0001 = 3 mm
474 0.00001 = 1.1 m 0.00001 = 2 cm
475 0.000001 = 11 cm 0.000001 = 2 mm
476 0.0000001 = 1 cm
477
478 Degrees of latitude get very slightly longer as you go further north but
479 not by much. In contrast degrees of longitude, which represent the same
480 length on the ground as latitude at the equator, get significantly
481 smaller in northern latitudes. In southern England one degree of
482 longitude represents about 70 km or 44 miles, in northern Scotland it's
483 less than 60 km or about 35 miles. Scaling everything down means that
484 the fifth decimal place of a degree of longitude represents about
485 60-70cm on the ground.
486
487 Degrees Minutes Seconds * LONGITUDE *
488 1 = 60-70 km 1 = 1.0-1.2 km 1 = 17-20 m
489 0.1 = 6-7 km 0.1 = 100-120 m 0.1 = 2 m
490 0.01 = 600-700 m 0.01 = 10-12 m 0.01 = 20 cm
491 0.001 = 60-70 m 0.001 = 1 m 0.001 = 2 cm
492 0.0001 = 6-7 m 0.0001 = 10 cm 0.0001 = 2 mm
493 0.00001 = 60-70 cm 0.00001 = 1 cm
494 0.000001 = 6-7 cm
495
496 =head3 How accurate are the conversions?
497
498 The OS supply test data with OSTN15 that comes from various fixed
499 stations around the country and that form part of the definition of the
500 transformation. If you look in the test files C<06-osgb-*.t> you can see
501 how it is used for testing these modules.
502
503 In all cases translating from the WGS84 coordinates to the national grid
504 and vice versa
505 is accurate to the millimetre, so these modules are at least as accurate
506 as the OSGB software that produced the test data.
507
508 The main difference between the OSTN02 transformation and OSTN15
509 is that the model fits the whole grid area better. With OSTN02 the
510 conversions were (very slightly) less accurate for places west of 7W.
511 Translating from the given grid coordinates to WGS84 latitude and
512 longitude coordinates was accurate to 1mm for all of
513 England, Wales, Scotland and the Isle of Man, but
514 `round trip' testing (by generating random grid
515 references, converting them to WGS84 latitude and longitude and then converting
516 them back to grid easting and northing), showed
517 that beyond of 6W (that is in the Scilly Isles and the Hebrides), the
518 error creeps up to about 4mm if you go as far as St Kilda (at about 8.57W).
519 The new OSTN15 numbers are all very slightly different, so that converting any given latitude
520 and longitude in WGS84 gives a grid reference that may be a few mm different. But OSTN15
521 no longer shows greater round trip errors in the far west. The accuracy of round trip conversions
522 is less than 1mm for all of the OSGB test points in both directions.
523
524 Outside the rectangle covered by OSTN15, this module uses the small Helmert
525 transformation recommended by the OS. The OS state that, with the parameters
526 they provide, this transformation will be accurate up to about +/-5 metres, in
527 the vicinity of the British Isles.
528
529 You can also use this transformation within the OSTN15 rectangle by calling the
530 C<grid_to_ll_helmert> and C<ll_to_grid_helmert> routines. If you compare the
531 output from these routines to the output from the more accurate routines that
532 use OSTN15 you will find that the differences are between about -3.6 metres and
533 +5.1 metres depending on where you are in the country. In the South East both
534 easting and northing are underestimated, in northern Scotland they tend to be
535 overestimated.
536
537 =head3 How fast are the conversions?
538
539 In general the answer to this question is "probably faster than you need", but if
540 you have read this far you might be interested in the results of my benchmarking.
541 The slowest part of these routines used to be the loading of the OSTN15 data set but I have
542 put considerable effort into making this faster since about version 2.08 of this module, so that
543 now the accurate routines the use the OSTN15 data are pretty much the same as the approximate
544 routines (C<ll_to_grid> is slightly faster, C<grid_to_ll> is slightly slower).
545
546 The tests used to be a bit generous to my code because of the caching
547 effect. In order to speed up the OSTN data lookups, the routines used to keep a
548 cache of the data fetched, so that if you convert a sequence of coordinates in
549 the same square km, the second and subsequent lookups will get the data from a
550 local hash instead of having to read the table. The benchmark test (using the
551 standard Benchmark.pm approach) consists of getting Perl to run as many
552 conversions as possible for about 5 CPU seconds, and as a result the cache hit
553 ratio was probably rather exaggerated. Nevertheless this might still be
554 reasonably representative if you are converting, say, the steps in a GPX track,
555 where successive steps are highly likely to be the same square km as the one
556 before. Moreover, since converting to OSTN15, I have removed the cache look ups
557 so I'm no longer getting any such boost.
558
559 Last year (2016) with version 2.16 of this module, a typical bench mark run on
560 my development machine (a Mac Mini server from 2011) using the Apple-supplied
561 Perl 5.16 gave:
562
563 Subroutine calls per sec ms per call
564 ----------------------------------------------
565 ll_to_grid 41677 0.024
566 ll_to_grid_helmert 42145 0.024
567
568 grid_to_ll 18131 0.055
569 grid_to_ll_helmert 35793 0.028
570
571 On my newer work machine (a MBP from 2015) using the newer Perl 5.18 supplied
572 with macOS Sierra, I got slightly better numbers with V2.16
573
574 Subroutine calls per sec ms per call
575 ----------------------------------------------
576 ll_to_grid 50980 0.020
577 ll_to_grid_helmert 68267 0.015
578
579 grid_to_ll 25831 0.039
580 grid_to_ll_helmert 54371 0.018
581
582 But after a bit more work to simplify the way that the cache is implemented
583 I get this on the same MBP with the version 2.19:
584
585 Subroutine calls per sec ms per call
586 ----------------------------------------------
587 ll_to_grid 69099 0.0145
588 ll_to_grid_helmert 66158 0.0151
589
590 grid_to_ll 29114 0.0343
591 grid_to_ll_helmert 53969 0.0185
592
593 Now, on the same MBP, but with the new OSTN15 data set and the simpler data look up I get:
594
595 Subroutine calls per sec ms per call
596 ----------------------------------------------
597 ll_to_grid 70730 0.0141
598 ll_to_grid_helmert 63308 0.0158
599
600 grid_to_ll 32238 0.0310
601 grid_to_ll_helmert 55286 0.0181
602
603 In my opinion, this justifies my decision to make the accurate OSTN conversion
604 the default. The approximate Helmert-based routine is no quicker for ll to
605 grid conversions.
606
607 It is always going to be slightly slower converting from grid to ll, due to the
608 iterative nature of the algorithm that is built into OSTN15. So the
609 approximate routine is likely to remain slightly faster. Having said that
610 none of the routines is really slow, since even C<grid_to_ll> averages under 60
611 microseconds per call on the older machine. `Your mileage may vary', of
612 course.
613
614 The routines have been tested with various versions of Perl, including recent
615 versions with the C<uselongdouble> option enabled. Using a locally compiled
616 version of Perl 5.22 with ordinary doubles, I saw a small improvement on the
617 Helmert routines, but the default routines are about the same. On the same
618 system, long doubles slowed everything down by about 10%, and made no
619 difference to the round trip precision of the routines. Since the formulae were
620 specifically designed for ordinary double precision arithmetic, Perl's default
621 arithmetic is more than adequate.
622
623 =head2 Maps
624
625 Since Version 2.09 these modules have included a set of map sheet
626 definitions so that you can find which paper maps your coordinates are
627 on.
628
629 See L<Geo::Coordinates::OSGB::Maps> for details of the series included.
630 The first three series are OS maps:
631
632 A - OS Landranger maps at 1:50000 scale;
633 B - OS Explorer maps at 1:25000;
634 C - the old OS One-Inch maps at 1:63360.
635
636 Landranger sheet 47 appears in the list of keys as C<A:47>, Explorer
637 sheet 161 as C<B:161>, and so on. As of 2015, the Explorer series of
638 incorporates the Outdoor Leisure maps, so (for example) the two sheets
639 that make up the map `Outdoor Leisure 1' appear as C<B:OL1E> and
640 C<B:OL1W>.
641
642 Thanks to the marketing department at the OS and their ongoing
643 re-branding exercise several Explorer sheets have been promoted to
644 Outdoor Leisure status. So (for example) Explorer sheet 364 has
645 recently become `Explorer sheet Outdoor Leisure 39'. Maps like this are
646 listed with a combined name, thus: C<B:395/OL54>.
647
648 Many of the Explorer sheets are printed on both sides. In these cases
649 each side is treated as a separate sheet and distinguished with
650 suffixes. The pair of suffixes used for a map will either be N and S,
651 or E and W. So for example there is no Explorer sheet C<B:271>, but you
652 will find sheets C<B:271N> and C<B:271S>. The suffixes are determined
653 automatically from the layout of the sides, so in a very few cases it
654 might not match what is printed on the sheet but it should still be
655 obvious which side is which. Where the map has a combined name the
656 suffix only appears at the end. For example: C<B:386/OL49E> and
657 C<B:386/OL49W>.
658
659 Several sheets also have insets, for islands, like Lundy or The Scilly
660 Isles, or for promontories like Selsey Bill or Spurn Head. Like the
661 sides, these insets are also treated as additional sheets (albeit rather
662 smaller). They are named with an alphabetic suffix so Spurn Head is on
663 an inset on Explorer sheet 292 and this is labelled C<B:292.a>. Where
664 there is more than one inset on a sheet, they are sorted in descending
665 order of size and labelled C<.a>, C<.b> etc. On some sheets the insets
666 overlap the area of the main sheet, but they are still treated as
667 separate map sheets.
668
669 Some maps have marginal extensions to include local features - these are
670 simply included in the definition of the main sheets. There are,
671 therefore, many sheets that are not regular rectangles. Nevertheless,
672 the module is able to work out when a point is covered by one of these
673 extensions.
674
675 In the examples folder there is an extended example showing how to work
676 with the map data as supplied through the C<Maps.pm> interface.
677
678 The source files for the map data are in the C<maps> directory. The script that
679 builds C<Maps.pm> from the source files is C<build/make_maps_code>.
680
681 It's probably fair to say that currently (in early 2016) everything about the
682 maps is still experimental and may change in the future.
683
684 For each series there are two files:
685
686 =over 4
687
688 =item *
689
690 C<catalogue> which defines:
691 an index number for each map (unique to this project);
692 the sheet number for the map - not necessarily an integer;
693 the sheet title as a UTF8 string;
694 the current ISBN number for maps that have them.
695
696 =item *
697
698 C<polygons> which has:
699 index numbers that match the corresponding C<catalogue>;
700 sheet numbers that match the corresponding C<catalogue>;
701 a flag - an integer to show the status of the entry (no formal meaning);
702 followed by a MULTIPOLYGON in WKT format.
703
704 =back
705
706 There is one line in each of the files for each map in the series. The data
707 format for the sheet polygons is Well Known Text (as defined in Wikipedia).
708 The set of polygons for each map is defined as a MULTIPOLYGON; a list of
709 POLYGONS. There are no holes in any of the polygons. A missing polygon list
710 is recorded as "EMPTY" (this is part of WKT).
711
712 The units are metres from the false point of origin (which is some miles west
713 of the Scilly Isles). So the south west corner of Landranger sheet 204, which has
714 traditional grid reference SW 720 140 is defined in this data as "172000
715 14000". This is essentially what "parse_grid" returns. No leading zeros
716 needed.
717
718 The polygon starts at the south west corner of the sheet and is recorded
719 anticlockwise. WKT insists that the first pair is repeated at the end to close
720 the polygon. So a simple 40km square Landranger sheet with no insets or
721 extensions, such as Sheet 152, whose SW corner is at SP 530 300 is recorded as
722
723 (((453000 230000, 493000 230000, 493000 270000, 453000 270000, 453000 230000)))
724
725 If the sheet boundary is more complicated than a square, the polygon consists of a coordinate
726 pair for each corner. Extensions - where the coloured printing spills
727 over the neat edge - are included as part of the main polygon in the appropriate place,
728 always moving anticlockwise. Extensions don't have to be rectilinear but they
729 are made up of straight lines. Extensions consisting of administrative boundaries
730 and labels are ignored. If in doubt, use common sense.
731
732 If an inset is drawn on the map sheet with its own grid margin then it is recorded
733 as a separate polygon following the WKT format, even if it overlaps the main sheet.
734
735 On OS Landranger maps, the first (and last) pair should always be the SW
736 corner, if an extension affects the SW corner, start and end with the regular
737 corner pair even if they are technically redundant. This allows me to find the
738 SW corners currently defined for the Landranger maps easily. In other series,
739 start somewhere near the SW and go anticlockwise.
740
741 =cut
742