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:

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]