Package pygeodesy :: Module osgr |
[frames] | no frames]

# Module osgr

Ordnance Survey Grid References (OSGR) references on the UK National Grid.

Classes Osgr and OSGRError and functions parseOSGR and toOsgr.

A pure Python implementation, transcoded from Chris Veness' JavaScript originals OS National Grid and Module osgridref and Charles Karney's C++ class OSGB.

OSGR provides geocoordinate references for UK mapping purposes, converted in 2015 to work with the `WGS84` or the original `OSGB36` datum. In addition, this implementation includes both the OS recommended and the Krüger-based method to convert between OSGR and geodetic coordinates (with keyword argument `kTM` of function toOsgr, method Osgr.toLatLon and method `toOsgr` of any ellipsoidal `LatLon` class).

See Transverse Mercator: Redfearn series, Karney's "Transverse Mercator with an accuracy of a few nanometers", 2011 (building on "Konforme Abbildung des Erdellipsoids in der Ebene", 1912, "Die Mathematik der Gauß-Krueger-Abbildung", 2006, A Guide and Ordnance Survey National Grid.

Version: 22.09.24

Classes
| OSGRError Error raised for a parseOSGR, Osgr or other OSGR issue.
| Osgr Ordnance Survey Grid References (OSGR) coordinates on the National Grid.

Functions
parseOSGR(strOSGR, Osgr=<class 'pygeodesy.osgr.Osgr'>, name='', **Osgr_kwds) Parse a string representing an OS Grid Reference, consisting of `"[GD] easting northing"`. |
toOsgr(latlon, lon=None, kTM=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Osgr=<class 'pygeodesy.osgr.Osgr'>, name='', **prec_Osgr_kwds) Convert a lat-/longitude point to an OSGR coordinate. |

Variables
| __all__ = `_ALL_LAZY.osgr`

Function Details

### parseOSGR (strOSGR, Osgr=<class 'pygeodesy.osgr.Osgr'>, name='', **Osgr_kwds) |
Parse a string representing an OS Grid Reference, consisting of `"[GD] easting northing"`. Accepts standard OS Grid References like "SU 387 148", with or without whitespace separators, from 2- up to 22-digit references, or all-numeric, comma-separated references in meters, for example "438700,114800". Arguments: `strOSGR` - An OSGR coordinate (`str`). `Osgr` - Optional class to return the OSGR coordinate (Osgr) or `None`. `name` - Optional `Osgr` name (`str`). `Osgr_kwds` - Optional, additional `Osgr` keyword arguments, ignored if `Osgr is None`. Returns: An (`Osgr`) instance or if `Osgr` is `None` an EasNor2Tuple`(easting, northing)`. Raises: `OSGRError` - Invalid `strOSGR`. Example:
    >>> r = parseOSGR('TG5140913177')
    >>> str(r)  # 'TG 51409 13177'
    >>> r = parseOSGR('TG 51409 13177')
    >>> r.toStr()  # 'TG5140913177'
    >>> r = parseOSGR('651409,313177')
    >>> r.toStr(sep=' ')  # 'TG 51409 13177'
    >>> r.toStr(GD=False)  # '651409,313177'

### toOsgr (latlon, lon=None, kTM=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Osgr=<class 'pygeodesy.osgr.Osgr'>, name='', **prec_Osgr_kwds) |
Convert a lat-/longitude point to an OSGR coordinate. Arguments: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude in degrees (scalar or `None`). `kTM` - If `True` use Karney's Krüger method from module ktm, otherwise use the Ordnance Survey formulation (`bool`). `datum` - Optional datum to convert `lat, lon` from (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple). `Osgr` - Optional class to return the OSGR coordinate (Osgr) or `None`. `name` - Optional `Osgr` name (`str`). `prec_Osgr_kwds` - Optional truncate precision `prec=ndigits` and/or additional `Osgr` keyword arguments, ignored if `Osgr is None`. Returns: An (`Osgr`) instance or if `Osgr` is `None` an EasNor2Tuple`(easting, northing)`. Raises: `OSGRError` - Invalid `latlon` or `lon`. `TypeError` - Non-ellipsoidal `latlon` or invalid `datum`, `Osgr`, `Osgr_kwds` or conversion to `Datums.OSGB36` failed. Note: If isint`(prec)` both easting and northing are truncated to the given number of digits. Example:
    >>> p = LatLon(52.65798, 1.71605)
    >>> r = toOsgr(p)  # [G:TG, E:51409, N:13177]
    >>> # for conversion of (historical) OSGB36 lat-/longitude:
    >>> r = toOsgr(52.65757, 1.71791, datum=Datums.OSGB36)
    >>> # alternatively and using Krüger
    >>> r = p.toOsgr(kTM=True)  # [G:TG, E:51409, N:13177]