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

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 (string). `datum` - Optional datum to use (Datum). `Utm` - Optional Utm class to use for the UTM coordinate (Utm) or None. `name` - Optional Utm name (string). Returns: The UTM coordinate (Utm) or 4-tuple (zone, hemisphere, easting, northing) if Utm is None. Raises: `UTMError` - Invalid strUTM. 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 Utm class to usefor the UTM coordinate (Utm) or None. `name` - Optional Utm name (string). `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 not scalar. 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.