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-2024 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: 24.11.26

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, strict=True, zone=None, **name_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` - Use `falsed=False` if both easting and northing are not falsed (`bool`). `name` - Optional `name=NN` (`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`.

### toUtm8 (latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, strict=True, zone=None, **name_cmoff) |
Convert a lat-/longitude point to a UTM coordinate. Arguments: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Longitude (`degrees`), required if `latlon` is `degrees`, ignored otherwise. `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` - If `True`, false both easting and northing (`bool`). `strict` - If `True`, restrict `lat` to UTM ranges (`bool`). `zone` - Optional UTM zone to enforce (`int` or `str`). `name_cmoff` - Optional `name=NN` (`str`) and DEPRECATED keyword argument `cmoff=True` to offset the longitude from the zone's central meridian (`bool`), use `falsed` instead. Returns: The UTM coordinate (`Utm`) or if `Utm is None` or `falsed is False`, a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, gamma, scale)` where `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 rangerrors is `True`. `TypeError` - Invalid `datum` or `latlon` not ellipsoidal. `UTMError` - Invalid `zone`. `ValueError` - If `lon` is missing or `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 3,900 Km from the central meridian.

### 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` - If `True`, offset longitude from the zone's central meridian (`bool`). `name` - Optional `name=NN` (`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 rangerrors is `True`. `ValueError` - Invalid `lat` or `lon`.