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.22

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 or ''.
Raises:

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 or ''.
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:

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:

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.