pygeodesy.utmups

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 transcoded from C++ class UTMUPS by Charles Karney.

Version: 25.04.14

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 `Utm` or `Ups` `name=NN` (`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 pygeodesy.parseUTM5 and pygeodesy.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` - Longitude (`degrees`), required if `latlon` is `degrees`, ignored otherwise. `datum` - Optional datum to use this UTM coordinate, overriding the `latlon`'s datum (`Datum`). `falsed` - If `True`, 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_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 and for UTM only. Returns: The UTM or UPS coordinate (`Utm` respectively `Ups`) or a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, gamma, scale)` if `Utm` respectively `Ups is None` or if `falsed is False`. Raises: `RangeError` - If `lat` outside the valid UTM or UPS bands or if `lat` or `lon` outside the valid range and rangerrors is `True`. `TypeError` - If `latlon` is not ellipsoidal or `lon` is missing or `datum` is invalid. `UTMUPSError` - UTM or UPS validation failed. `ValueError` - Invalid `lat` or `lon`. See Also: Functions pygeodesy.toUtm8 and pygeodesy.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 zone with/-out longitudinal Band or UPS zone `0` or `"00"` with/-out polar Band (`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 `'C'|'D'|..|'W'|'X'` or UPS polar Band letter `'A'|'B'|'Y'|'Z'` Band letter (`str`). `datum` - The coordinate's datum (Datum). `falsed` - If `True`, both `easting` and `northing` are falsed (`bool`). `name` - Optional Utm or Ups `name=NN` (`str`). Returns: New UTM or UPS instance (Utm or Ups). Raises: `TypeError` - Invalid `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, Etm, Ups or `5+Tuple`). `falsed` - If `True`, easting and northing are falsed in the `coord 5+Tuple` (`bool`), ignored otherwise. `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` - If `True`, easting and northing are falsed in the `coord 5+Tuple` (`bool`), ignored otherwise. `ok` - Result to return if validation passed (`ok`). Returns: `ok` if validation passed, otherwise the UTMUPSError. 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` - If `True`, offset longitude from the zone's central meridian, for UTM only (`bool`). `name` - Optional `name=NN` (`str`). Returns: A UtmUpsLatLon5Tuple`(zone, band, hemipole, lat, lon)` where `hemipole` is `'N'|'S'`, the UTM hemisphere or UPS pole, 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 is `True`. `ValueError` - Invalid `lat` or `lon`. See Also: Functions pygeodesy.utmZoneBand5 and pygeodesy.upsZoneBand5.