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

# Module utmups

Karney's UTM and UPS utilities.

Functions parseUTMUPS5, toUtmUps8, UtmUps and utmupsZoneBand5 to handle both Universal Transverse Mercator (UTM) and Universal Polar Stereographic (UPS) coordinates.

A pure Python implementation, partially transcribed from C++ class UTMUPS by Charles Karney.

Version: 21.04.22

Classes
| UTMUPSError Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) parse, validate or other issue.

Functions
parseUTMUPS5(strUTMUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, name='') Parse a string representing a UTM or UPS coordinate, consisting of `"zone[band] hemisphere/pole easting northing"`. |
toUtmUps8(latlon, lon=None, datum=None, falsed=True, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, pole='', name='', **cmoff) Convert a lat-/longitude point to a UTM or UPS coordinate. |
UtmUps(zone, hemipole, easting, northing, band='', datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, falsed=True, name='') Class-like function to create a UTM/UPS coordinate. |
utmupsValidate(coord, falsed=False, MGRS=False, Error=<class 'pygeodesy.utmups.UTMUPSError'>) Check a UTM or UPS coordinate. |
utmupsValidateOK(coord, falsed=False, ok=True) Check a UTM or UPS coordinate. |
utmupsZoneBand5(lat, lon, cmoff=False, name='') Return the UTM/UPS zone number, Band letter, hemisphere/pole and clipped lat- and longitude for a given location. |

Variables
| __all__ = `_ALL_LAZY.utmups`

Function Details

### parseUTMUPS5 (strUTMUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, name='') |
Parse a string representing a UTM or UPS coordinate, consisting of `"zone[band] hemisphere/pole easting northing"`. Arguments: `strUTMUPS` - A UTM or UPS coordinate (`str`). `datum` - Optional datum to use (Datum). `Utm` - Optional class to return the UTM coordinate (Utm) or `None`. `Ups` - Optional class to return the UPS coordinate (Ups) or `None`. `name` - Optional instance name (`str`). Returns: The UTM or UPS instance (`Utm` or `Ups`) or a UtmUps5Tuple`(zone, hemipole, easting, northing, band)` if `Utm` respectively `Ups` or both are `None`. The `hemipole` is `'N'|'S'`, the UTM hemisphere or UPS pole, the UPS projection top/center. Raises: `UTMUPSError` - Invalid `strUTMUPS`. See Also: Functions parseUTM5 and parseUPS5.

### toUtmUps8 (latlon, lon=None, datum=None, falsed=True, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, pole='', name='', **cmoff) |
Convert a lat-/longitude point to a UTM or UPS coordinate. Arguments: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude (`degrees`) or `None`. `datum` - Optional datum to use this UTM coordinate, overriding `latlon`'s datum (`Datum`). `falsed` - False both easting and northing (`bool`). `Utm` - Optional class to return the UTM coordinate (Utm) or `None`. `Ups` - Optional class to return the UPS coordinate (Ups) or `None`. `pole` - Optional top/center of UPS (stereographic) projection (`str`, `'N[orth]'` or `'S[outh]'`). `name` - Optional name (`str`). `cmoff` - DEPRECATED, use `falsed`. Offset longitude from zone's central meridian, for UTM only (`bool`). Returns: The UTM or UPS coordinate (`Utm` respectively `Ups`) or a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, convergence, scale)` if `Utm` respectively `Ups` is `None` or `cmoff` is `False`. Raises: `RangeError` - If `lat` outside the valid UTM or UPS bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `TypeError` - If `latlon` is not ellipsoidal or `lon` value is missing of `datum` is invalid. `UTMUPSError` - UTM or UPS validation failed. `ValueError` - Invalid `lat` or `lon`. See Also: Functions toUtm8 and toUps8.

### UtmUps (zone, hemipole, easting, northing, band='', datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, falsed=True, name='') |
Class-like function to create a UTM/UPS coordinate. Arguments: `zone` - The UTM (longitudinal) zone with/-out Band letter for UTM or for UPS zone `"00"` or `0` (`str` or `int`). `hemipole` - UTM hemisphere or UPS top/center of projection (`str`, `'N[orth]'` or `'S[outh]'`). `easting` - Easting, see `falsed` (`meter`). `northing` - Northing, see `falsed` (`meter`). `band` - Optional, UTM (latitudinal) Band letter `'C'|'D'..'W'|'X'` or UPS (polar) Band letter `'A'|'B'|'Y'|'Z'` (`str`). `datum` - Optional, the coordinate's datum (Datum). `falsed` - Both `easting` and `northing` are falsed (`bool`). `name` - Optional name (`str`). Returns: New UTM or UPS instance (Utm or Ups). Raises: `TypeError` - Invalid B({`datum`}. `UTMUPSError` - UTM or UPS validation failed. See Also: Classes Utm and Ups and Karney's UTMUPS.

### utmupsValidate (coord, falsed=False, MGRS=False, Error=<class 'pygeodesy.utmups.UTMUPSError'>) |
Check a UTM or UPS coordinate. Arguments: `coord` - The UTM or UPS coordinate (Utm, Ups or `5+Tuple`). `falsed` - `5+Tuple` easting and northing are falsed (`bool`). `MGRS` - Increase easting and northing ranges (`bool`). `Error` - Optional error to raise, overriding the default (UTMUPSError). Returns: `None` if validation passed. Raises: `Error` - Validation failed. See Also: Function utmupsValidateOK.

### utmupsValidateOK (coord, falsed=False, ok=True) |
Check a UTM or UPS coordinate. Arguments: `coord` - The UTM or UPS coordinate (Utm, Ups or `5+Tuple`). `falsed` - `5+Tuple` easting and northing are falsed (`bool`). `ok` - Result to return if validation passed (`ok`). Returns: `ok` if validation passed, the UTMUPSError otherwise. See Also: Function utmupsValidate.

### utmupsZoneBand5 (lat, lon, cmoff=False, name='') |
Return the UTM/UPS zone number, Band letter, hemisphere/pole 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, for UTM only (`bool`). `name` - Optional name (`str`). Returns: A UtmUpsLatLon5Tuple`(zone, band, hemipole, lat, lon)` where `hemipole` is `'N'|'S'`, the UTM hemisphere or UPS pole, the UPS projection top/center. Raises: `RangeError` - If `lat` outside the valid UTM or UPS bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `ValueError` - Invalid `lat` or `lon`. See Also: Functions utmZoneBand5 and upsZoneBand5.