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

# Module ups

Karney's Universal Polar Stereographic (UPS) projection.

Classes Ups and UPSError and functions parseUPS5, toUps8 and upsZoneBand5.

A pure Python implementation, partially transcoded from Karney's C++ class PolarStereographic.

The UPS system is used in conjuction with UTM for locations on the polar regions of the earth. UPS covers areas south of 79.5°S and north of 83.5°N, slightly overlapping the UTM range from 80°S to 84°N by 30' at each end.

Env variable `PYGEODESY_UPS_POLES` determines the UPS zones at latitude 90°S and 90°N. By default, the encoding follows Karney's and Appendix B-3 of DMA TM8358.1, using only zones `'B'` respectively `'Z'` and digraph `'AN'`. If `PYGEODESY_UPS_POLES` is set to anything other than `"std"`, zones `'A'` and `'Y'` are used for negative, west longitudes at latitude 90°S respectively 90°N (for backward compatibility).

Version: 23.09.29

Classes
| UPSError Universal Polar Stereographic (UPS) parse or other Ups issue.
| Ups Universal Polar Stereographic (UPS) coordinate.

Functions
parseUPS5(strUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Ups=<class 'pygeodesy.ups.Ups'>, falsed=True, name='') Parse a string representing a UPS coordinate, consisting of `"[zone][band] pole easting northing"` where `zone` is pseudo zone `"00"|"0"|""` and `band` is `'A'|'B'|'Y'|'Z'|''`. |
toUps8(latlon, lon=None, datum=None, Ups=<class 'pygeodesy.ups.Ups'>, pole='', falsed=True, strict=True, name='') Convert a lat-/longitude point to a UPS coordinate. |
upsZoneBand5(lat, lon, strict=True, name='') Return the UTM/UPS zone number, polar Band letter, pole and clipped lat- and longitude for a given location. |

Variables
| __all__ = `_ALL_LAZY.ups`

Function Details

### parseUPS5 (strUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Ups=<class 'pygeodesy.ups.Ups'>, falsed=True, name='') |
Parse a string representing a UPS coordinate, consisting of `"[zone][band] pole easting northing"` where `zone` is pseudo zone `"00"|"0"|""` and `band` is `'A'|'B'|'Y'|'Z'|''`. Arguments: `strUPS` - A UPS coordinate (`str`). `datum` - Optional datum to use (Datum). `Ups` - Optional class to return the UPS coordinate (Ups) or `None`. `falsed` - Both `easting` and `northing` are falsed (`bool`). `name` - Optional `Ups` name (`str`). Returns: The UPS coordinate (`Ups`) or a UtmUps5Tuple`(zone, hemipole, easting, northing, band)` if `Ups` is `None`. The `hemipole` is the `'N'|'S'` pole, the UPS projection top/center. Raises: `UPSError` - Invalid `strUPS`.

### toUps8 (latlon, lon=None, datum=None, Ups=<class 'pygeodesy.ups.Ups'>, pole='', falsed=True, strict=True, name='') |
Convert a lat-/longitude point to a UPS coordinate. Arguments: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude (`degrees`) or `None` if `latlon` is a `LatLon`. `datum` - Optional datum for this UPS coordinate, overriding `latlon`'s datum (`Datum`, Ellipsoid, Ellipsoid2 or a_f2Tuple). `Ups` - Optional class to return the UPS coordinate (Ups) or `None`. `pole` - Optional top/center of (stereographic) projection (`str`, `'N[orth]'` or `'S[outh]'`). `falsed` - False both easting and northing (`bool`). `strict` - Restrict `lat` to UPS ranges (`bool`). `name` - Optional `Ups` name (`str`). Returns: The UPS coordinate (`Ups`) or a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, gamma, scale)` if `Ups` is `None`. The `hemipole` is the `'N'|'S'` pole, the UPS projection top/center. Raises: `RangeError` - If `strict` and `lat` outside the valid UPS bands or if `lat` or `lon` outside the valid range and pygeodesy.rangerrors set to `True`. `TypeError` - If `latlon` is not ellipsoidal or `datum` invalid. `ValueError` - If `lon` value is missing or if `latlon` is invalid. See Also: Karney's C++ class UPS.

### upsZoneBand5 (lat, lon, strict=True, name='') |
Return the UTM/UPS zone number, polar Band letter, 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`). `strict` - Restrict `lat` to UPS ranges (`bool`). `name` - Optional name (`str`). Returns: A UtmUpsLatLon5Tuple`(zone, band, hemipole, lat, lon)` where `hemipole` is the `'N'|'S'` pole, the UPS projection top/center and `lon` [-180..180). Raises: `RangeError` - If `strict` and `lat` in the UTM and not the UPS range or if `lat` or `lon` outside the valid range and pygeodesy.rangerrors set to `True`. `ValueError` - Invalid `lat` or `lon`. Note: The `lon` is set to `0` if `lat` is `-90` or `90`, see env variable `PYGEODESY_UPS_POLES` in module pygeodesy.ups.