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

# Module utm

Veness' Universal Transverse Mercator (UTM) projection.

Classes Utm and UTMError and functions parseUTM5, toUtm8 and utmZoneBand5.

Pure Python implementation of UTM / WGS-84 conversion functions using an ellipsoidal earth model, transcoded 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 `easting`s and `northing`s, 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: 22.08.23

Classes
| UTMError Universal Transverse Mercator (UTM parse or other Utm issue.
| Utm Universal Transverse Mercator (UTM) coordinate.

Functions
parseUTM5(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name='') Parse a string representing a UTM coordinate, consisting of `"zone[band] hemisphere easting northing"`. |
toUtm8(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name='', strict=True, zone=None, **cmoff) Convert a lat-/longitude point to a UTM coordinate. |
utmZoneBand5(lat, lon, cmoff=False, name='') Return the UTM zone number, Band letter, hemisphere and (clipped) lat- and longitude for a given location. |

Variables
| __all__ = `_ALL_LAZY.utm`

Function Details

### parseUTM5 (strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name='') |
Parse a string representing a UTM coordinate, consisting of `"zone[band] hemisphere easting northing"`. Arguments: `strUTM` - A UTM coordinate (`str`). `datum` - Optional datum to use (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple). `Utm` - Optional class to return the UTM coordinate (Utm) or `None`. `falsed` - Both easting and northing are falsed (`bool`). `name` - Optional `Utm` name (`str`). Returns: The UTM coordinate (`Utm`) or if `Utm` is `None`, a UtmUps5Tuple`(zone, hemipole, easting, northing, band)`. The `hemipole` is the `'N'|'S'` hemisphere. Raises: `UTMError` - Invalid `strUTM`. `TypeError` - Invalid `datum`. Example:
    >>> u = parseUTM5('31 N 448251 5411932')
    >>> u.toRepr()  # [Z:31, H:N, E:448251, N:5411932]
    >>> u = parseUTM5('31 N 448251.8 5411932.7')
    >>> u.toStr()  # 31 N 448252 5411933

### toUtm8 (latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name='', strict=True, zone=None, **cmoff) |
Convert a lat-/longitude point to a UTM coordinate. Arguments: `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, Ellipsoid, Ellipsoid2 or a_f2Tuple). `Utm` - Optional class to return the UTM coordinate (Utm) or `None`. `falsed` - False both easting and northing (`bool`). `name` - Optional `Utm` name (`str`). `strict` - Restrict `lat` to UTM ranges (`bool`). `zone` - Optional UTM zone to enforce (`int` or `str`). `cmoff` - DEPRECATED, use `falsed`. Offset longitude from the zone's central meridian (`bool`). Returns: The UTM coordinate (`Utm`) or if `Utm` is `None` or not `falsed`, a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, convergence, scale)`. The `hemipole` is the `'N'|'S'` hemisphere. Raises: `RangeError` - If `lat` outside the valid UTM bands or if `lat` or `lon` outside the valid range and pygeodesy.rangerrors set to `True`. `TypeError` - Invalid `datum` or `latlon` not ellipsoidal. `UTMError` - Invalid `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, name='') |
Return the UTM zone number, Band letter, hemisphere and (clipped) lat- and longitude for a given location. Arguments: `lat` - Latitude in degrees (`scalar` or `str`). `lon` - Longitude in degrees (`scalar` or `str`). `cmoff` - Offset longitude from the zone's central meridian (`bool`). `name` - Optional name (`str`). Returns: A UtmUpsLatLon5Tuple`(zone, band, hemipole, lat, lon)` where `hemipole` is the `'N'|'S'` UTM hemisphere. Raises: `RangeError` - If `lat` outside the valid UTM bands or if `lat` or `lon` outside the valid range and pygeodesy.rangerrors set to `True`. `ValueError` - Invalid `lat` or `lon`.