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

# Module utmups

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: 19.04.26

Classes
| UTMUPSError UTM/UPS parse, validate or other error.

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, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, pole=`'````'`, name=`'````'`) 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) Check a UTM or UPS coordinate. |
utmupsValidateOK(coord, falsed=False, ok=`'``OK``'`) Check a UTM or UPS coordinate. |
utmupsZoneBand5(lat, lon, cmoff=False) 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". Parameters: `strUTMUPS` - A UTM or UPS coordinate (`str`). `datum` - Optional datum to use (Datum). `Utm` - Optional (sub-)class to return the UTM coordinate (Utm) or `None`. `Ups` - Optional (sub-)class to return the UPS coordinate (Ups) or `None`. `name` - Optional name (`str`). Returns: The UTM or UPS coordinate (Utm or Ups) or 5-tuple (`zone, hemisphere/pole, easting, northing, Band`) if Utm respectively Ups or both are `None` as (`int, 'N'|'S', meter, meter, str`) where `zone` is `1..60` for UTM or `0` for UPS and `Band` is `""` or `'C'|'D'..'W'|'X'` for UTM or `'A'|'B'|'Y'|'Z'` for UPS. Raises: `UTMUPSError` - Invalid strUTMUPS. See Also: Functions parseUTM5 and parseUPS5.

### toUtmUps8(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, pole=`'````'`, name=`'````'`) |
Convert a lat-/longitude point to a UTM or UPS coordinate. Parameters: `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`). `Utm` - Optional (sub-)class to return the UTM coordinate (Utm) or `None`. `Ups` - Optional (sub-)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`). Returns: The UTM or UPS coordinate (Utm respectively Ups) or an 8-tuple (`zone, hemisphere/pole, easting, northing, Band, datum, convergence, scale`) if Utm respectively Ups is `None` or cmoff is `False` as (`int, 'N'|'S', meter, meter, str, degrees, scalar`) where `zone` is `1..60` for UTM or `0` for UPS and `Band` is `""` or `'C'|'D'..'W'|'X'` for UTM or `'A'|'B'|'Y'|'Z'` for UPS. Raises: `RangeError` - If lat outside the valid UTM or UPS bands or if lat or lon outside the valid range and rangerrrors set to `True`. `TypeError` - If latlon is not ellipsoidal or lon value is missing. `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. Parameters: `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: `UTMUPSError` - UTM or UPS validation failed. See Also: Classes Utm and Ups and Karney's UTMUPS.

### utmupsValidate(coord, falsed=False, MGRS=False) |
Check a UTM or UPS coordinate. Parameters: `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`). Returns: `None` if validation passed. Raises: `UTMUPSError` - Validation failed. See Also: Function utmupsValidateOK.

### utmupsValidateOK(coord, falsed=False, ok=`'``OK``'`) |
Check a UTM or UPS coordinate. Parameters: `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) |
Return the UTM/UPS zone number, Band letter, hemisphere/pole 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 the zone's central meridian, for UTM only (`bool`). Returns: 5-Tuple (`zone, Band, hemisphere/pole, lat, lon`) as (`int, str, 'N'|'S', degrees90, degrees180`) where `zone` is `1..60` for UTM or `0` for UPS and `Band` is `""` or `'C'|'D'..'W'|'X'` for UTM or `'A'|'B'|'Y'|'Z'` for UPS. Raises: `RangeError` - If lat outside the valid UTM or UPS bands or if lat or lon outside the valid range and rangerrrors set to `True`. `ValueError` - Invalid lat or lon. See Also: Functions utmZoneBand5 and upsZoneBand5.