Python routines for working with grid references as defined by the Ordnance Survey of Great Britain (OSGB).
Toby Thurston -- April 2018
The functions in this module convert from OSGB grid references to and from GPS Latitude and Longitude, using OSGB formulae and the OSTN15 data set. Conversions are accurate to approximately +/- 1mm. The scope of OSGB is limited to the same coverage as the Ordnance Survey maps: England, Wales, Scotland, and the Isle of Man, but not Northern Ireland, nor the Channel Islands.
This implementation supersedes the osgb module written by Paul Agapow; existing code should work unmodified, but the exported functions have been re-implemented, so the results will be more accurate.
The implementation uses the Ordnance Survey's high-precision dataset called OSTN15. This dataset is freely available for public use, but remains (c) Crown copyright, Ordnance Survey and the Ministry of Defence (MOD) 2016. All rights reserved.
The modules are designed to work with Python 2.7 or better and with Python 3.4 or better. With Python 2.7, they are very slightly faster than with Python 3.6, but the functions are, and the results should be, identical. If you are using Python 3, then use python3 (or whatever you call it) instead of python below.
python setup.py install
import osgb (lat, lon) = osgb.grid_to_ll(324231, 432525) (easting, northing) = osgb.ll_to_grid(52.132341, -2.43256) grid_ref = osgb.format_grid(324231, 231423) (easting, northing) = osgb.parse_grid("TQ213455")
Each of the modules contains detailed documentation and examples in "doctest" format:
pydoc osgb/convert.py pydoc osgb/gridder.py
The scripts directory contains a handy command line conversion tool. Try
bngl TQ 109 324 bngl --show 51.48 0 bngl --help
And a feature called plotmaps.py - if you have a current TeX distribution with "mpost" installed, this will produce a PDF of the National Grid, optionally with the outlines of all the OS maps.
python scripts/plot_maps.py --series A
The two PDF files included are examples of the output.
The original osgb functions are also still provided for compatibility with old code, so that code like this, should still work:
from osgb import osgb_to_lonlat, lonlat_to_osgb (lon, lat) = osgb_to_lonlat("SD 30271 33770") grid_ref = lonlat_to_osgb(-3.058695, 53.795346, digits=5)
Note that the older "osgb_to_lonlat" returns latitude and longitude in the opposite order to the newer "grid_to_ll". If in doubt, note that for valid OSGB grid references latitude will always be greater than longitude.
Note also that the older "lonlat_to_osgb" expects the arguments to have longitude first and latitude second. However the re-implemented version will determine the correct sequence automatically, so the calling order does not actually matter.
The re-implementation also adds an optional "model=" parameter to each of these functions, so you can use them with WGS84 coordinates. Model defaults to "OSGB36", so if you leave it out you will get the old functionality.
(lon, lat) = osgb_to_lonlat("SD 30271 33770", model="WGS84") grid_ref = lonlat_to_osgb(-3.058695, 53.795346, digits=5, model="WGS84")
You can run "python -m doctest" against the main modules, and on "test/grid_test_known_points"
You can also run the "test/ostn_standard_points.." routines to check that there are no error converting the forty standard points given by the OSGB.
python -m doctest osgb/convert.py python -m doctest osgb/gridder.py python -m doctest osgb/mapping.py python -m doctest test/grid_test_known_points.txt python test/ostn_standard_points_to_grid.py python test/ostn_standard_points_to_ll.py
You can also run "test/bench_mark.py" to see how fast you can go on your system.
This should produce something like:
Grid banger bench mark running under CPython 3.6.4 on Darwin-17.4.0-x86_64-i386-64bit ll_to_grid: 84231/s 0.0119 ms per call grid_to_ll: 22564/s 0.0443 ms per call
LICENCE.txt README.rst setup.py osgb/convert.py osgb/gridder.py osgb/mapping.py osgb/legacy_interface.py osgb/ostn_east_shift_82140 osgb/ostn_north_shift_-84180 osgb/gb_coastline.shapes scripts/bngl scripts/make_map_locker scripts/plot_maps.py scripts/whatmaps.py test/bench_mark.py test/grid_test_known_points.txt test/ostn_standard_points_to_grid.py test/ostn_standard_points_to_ll.py test/OSTN15_OSGM15_TestFiles_README.txt test/OSTN15_OSGM15_TestInput_ETRStoOSGB.txt test/OSTN15_OSGM15_TestInput_OSGBtoETRS.txt test/OSTN15_OSGM15_TestOutput_ETRStoOSGB.txt test/OSTN15_OSGM15_TestOutput_OSGBtoETRS.txt Index_for_map_series_A.pdf Index_for_map_series_B.pdf