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

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.

    @arg latlon: Latitude (C{degrees}) or an (ellipsoidal) geodetic
                 C{LatLon} point.
    @kwarg lon: Optional longitude in degrees (scalar or C{None}).
    @kwarg kTM: If C{True} use I{Karney}'s Krüger method from
                module L{ktm}, otherwise use the Ordnance
                Survey formulation (C{bool}).
    @kwarg datum: Optional datum to convert B{C{lat, lon}} from
                  (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} or
                  L{a_f2Tuple}).
    @kwarg Osgr: Optional class to return the OSGR coordinate
                 (L{Osgr}) or C{None}.
    @kwarg name: Optional B{C{Osgr}} name (C{str}).
    @kwarg prec_Osgr_kwds: Optional L{truncate} precision
                           C{B{prec}=ndigits} and/or additional
                           B{C{Osgr}} keyword arguments, ignored
                           if C{B{Osgr} is None}.

    @return: An (B{C{Osgr}}) instance or if B{C{Osgr}} is C{None}
             an L{EasNor2Tuple}C{(easting, northing)}.

    @note: If L{isint{C{(B{prec})} both easting and northing are
           L{truncate}d to the given number of digits.

    @raise OSGRError: Invalid B{C{latlon}} or B{C{lon}}.

    @raise TypeError: Non-ellipsoidal B{C{latlon}} or invalid
                      B{C{datum}}, B{C{Osgr}}, B{C{Osgr_kwds}}
                      or conversion to C{Datums.OSGB36} failed.

    @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]