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

# Module utm

Universal Transverse Mercator (UTM) classes Utm and UTMError and functions parseUTM5, toUtm8 and utmZoneBand5.

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 another way to identify 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 module includes some of Charles Karney's 'Transverse Mercator with an accuracy of a few nanometers', 2011 (building on Krüger's 'Konforme Abbildung des Erdellipsoids in der Ebene', 1912) and C++ class TransverseMercator.

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

Version: 19.04.22

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=`'````'`) DEPRECATED, use function parseUTM5. |
parseUTM5(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[band] hemisphere easting northing". |
toUtm(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, name=`'````'`, cmoff=True) DEPRECATED, use function toUtm8. |
toUtm8(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, cmoff=True, name=`'````'`, zone=None) Convert a lat-/longitude point to a UTM coordinate. |
utmZoneBand2(lat, lon) DEPRECATED, use function utmZoneBand5. |
utmZoneBand5(lat, lon, cmoff=False) Return the UTM zone number, Band letter, hemisphere and clipped lat- and longitude for a given location. |

Variables
| __all__ = `_ALL_LAZY.utm`

Function Details

### parseUTM(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, name=`'````'`) |
DEPRECATED, use function parseUTM5. Returns: The UTM coordinate (Utm) or 4-tuple (`zone, hemisphere, easting, northing`) if Utm is `None`.

### parseUTM5(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[band] hemisphere easting northing". Parameters: `strUTM` - A UTM coordinate (`str`). `datum` - Optional datum to use (Datum). `Utm` - Optional (sub-)class to return the UTM coordinate (Utm) or `None`. `name` - Optional Utm name (`str`). Returns: The UTM coordinate (Utm) or 5-tuple (`zone, hemisphere, easting, northing, band`) 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) |
DEPRECATED, use function toUtm8. Returns: The UTM coordinate (Utm) or a 6-tuple (zone, easting, northing, band, convergence, scale) if Utm is `None` or cmoff is `False`.

### toUtm8(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, cmoff=True, name=`'````'`, zone=None) |
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 return the UTM coordinate (Utm) or `None`. `cmoff` - Offset longitude from zone's central meridian, apply false easting and false northing (`bool`). `name` - Optional Utm name (`str`). `zone` - Optional zone to enforce (`int` or `str`). Returns: The UTM coordinate (Utm) or a 8-tuple (`zone, hemisphere, easting, northing, band, datum, convergence, scale`) if Utm is `None` or cmoff is `False`. Raises: `TypeError` - If latlon is not ellipsoidal. `RangeError` - If lat outside the valid UTM bands or if lat or lon outside the valid range and rangerrrors set to `True`. `UTMError` - Invlid zone. `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

### utmZoneBand5(lat, lon, cmoff=False) |
Return the UTM zone number, Band letter, hemisphere and clipped lat- and longitude for a given location. Parameters: `lat` - Latitude in degrees (`scalar` or `str`). `lon` - Longitude in degrees (`scalar` or `str`). `cmoff` - Offset longitude from zone's central meridian (`bool`). Returns: 5-Tuple (`zone, Band, hemisphere, lat, lon`) as (`int, str, 'N'|'S', degrees90, degrees180`) where `zone` is `1..60` and `Band` is `'C'|'D'..'W'|'X'` for UTM. Raises: `RangeError` - If lat outside the valid UTM bands or if lat or lon outside the valid range and rangerrrors set to `True`. `ValueError` - Invalid lat or lon.