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

Module utm

Universal Transverse Mercator (UTM) class Utm and functions parseUTM and toUtm.

Pure Python implementation of UTM / WGS-84 conversion functions using an ellipsoidal earth model, transcribed from JavaScript originals by (C) Chris Veness 2011-2016 published under the same MIT Licence**, see UTM and Module utm.

The UTM system is a 2-dimensional cartesian coordinate system providing locations on the surface of the earth.

UTM is a set of 60 transverse Mercator projections, normally based on the WGS-84 ellipsoid. Within each zone, coordinates are represented as eastings and northings, measured in metres.

This method based on Karney 'Transverse Mercator with an accuracy of a few nanometers', 2011 (building on Krüger 'Konforme Abbildung des Erdellipsoids in der Ebene', 1912).

Other references Seidel 'Die Mathematik der Gauß-Krueger-Abbildung', 2006, Transverse Mercator Projection, and Universal Transverse Mercator coordinate system.


Version: 18.10.12

Classes
  UTMError
UTM parse or other error.
  Utm
Universal Transverse Mercator (UTM) coordinate.
Functions
 
parseUTM(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Utm=<class 'pygeodesy.utm.Utm'>, name='')
Parse a string representing a UTM coordinate, consisting of zone, hemisphere, easting and northing.
 
toUtm(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, name='', cmoff=True)
Convert a lat-/longitude point to a UTM coordinate.
 
utmZoneBand2(lat, lon)
Return the UTM zone number and UTM Band letter for a location.
Function Details

parseUTM(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Utm=<class 'pygeodesy.utm.Utm'>, name='')

 

Parse a string representing a UTM coordinate, consisting of zone, hemisphere, easting and northing.

Parameters:
  • strUTM - A UTM coordinate (str).
  • datum - Optional datum to use (Datum).
  • Utm - Optional (sub-)class to use for the UTM coordinate (Utm) or None.
  • name - Optional Utm name (str).
Returns:
The UTM coordinate (Utm) or 4-tuple (zone, hemisphere, easting, northing) if Utm is None.
Raises:

Example:

>>> u = parseUTM('31 N 448251 5411932')
>>> u.toStr2()  # [Z:31, H:N, E:448251, N:5411932]
>>> u = parseUTM('31 N 448251.8 5411932.7')
>>> u.toStr()  # 31 N 448252 5411933

toUtm(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, name='', cmoff=True)

 

Convert a lat-/longitude point to a UTM coordinate.

Parameters:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon point.
  • lon - Optional longitude (degrees or None).
  • datum - Optional datum for this UTM coordinate, overriding latlon's datum (Datum).
  • Utm - Optional (sub-)class to use for the UTM coordinate (Utm) or None.
  • name - Optional Utm name (str).
  • cmoff - Offset longitude from zone's central meridian, apply false easting and false northing (bool).
Returns:
The UTM coordinate (Utm) or a 6-tuple (zone, easting, northing, band, convergence, scale) if Utm is None or cmoff is False.
Raises:
  • TypeError - If latlon is not ellipsoidal.
  • RangeError - If lat is outside the valid UTM bands or if lat or lon outside the valid range and rangerrrors set to True.
  • ValueError - If lon value is missing or if latlon is invalid.

Note: Implements Karney’s method, using 8-th order Krüger series, giving results accurate to 5 nm (or better) for distances up to 3900 km from the central meridian.

Example:

>>> p = LatLon(48.8582, 2.2945)  # 31 N 448251.8 5411932.7
>>> u = toUtm(p)  # 31 N 448252 5411933
>>> p = LatLon(13.4125, 103.8667) # 48 N 377302.4 1483034.8
>>> u = toUtm(p)  # 48 N 377302 1483035

utmZoneBand2(lat, lon)

 

Return the UTM zone number and UTM Band letter for a location.

Parameters:
  • lat - Latitude (degrees) or string.
  • lon - Longitude (degrees) or string.
Returns:
2-Tuple (zone, Band) as (int, string).
Raises:
  • RangeError - If lat is outside the valid UTM bands or if lat or lon outside the valid range and rangerrrors set to True.
  • ValueError - Invalid lat or lon.