Coverage for pygeodesy/ups.py : 96%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# -*- coding: utf-8 -*-
Classes L{Ups} and L{UPSError} and functions L{parseUPS5}, L{toUps8} and L{upsZoneBand5}.
A pure Python implementation, partially transcoded from C++ class U{PolarStereographic <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1PolarStereographic.html>} by I{Charles Karney}.
The U{UPS<https://WikiPedia.org/wiki/Universal_polar_stereographic_coordinate_system>} system is used in conjuction with U{UTM <https://WikiPedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>} 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). '''
_EPS__2, _EPSmin as _Tol90, _inside_, \ _pole_, _range_, _S_, _SPACE_, _to_, \ _UTM_, _0_0, _0_5, _1_0, _2_0, _90_0 UtmUps8Tuple, UtmUpsLatLon5Tuple _to4lldn, _to3zBhp, _to3zll, \ _UPS_LAT_MAX, _UPS_LAT_MIN, _UPS_ZONE, \ _UPS_ZONE_STR, UtmUpsBase
# determine the polar band letter
# compute the point scale factor, ala Karney
'''Universal Polar Stereographic (UPS) parse or other L{Ups} issue. '''
'''Universal Polar Stereographic (UPS) coordinate. ''' # _band = NN # polar band ('A', 'B', 'Y' or 'Z') # _scale = None # point scale factor (C{scalar})
datum=_WGS84, falsed=True, convergence=None, scale=None, name=NN): '''New L{Ups} UPS coordinate.
@arg zone: UPS zone (C{int}, zero) or zone with/-out Band letter (C{str}, '00', '00A', '00B', '00Y' or '00Z'). @arg pole: Top/center of (stereographic) projection (C{str}, C{'N[orth]'} or C{'S[outh]'}). @arg easting: Easting, see B{C{falsed}} (C{meter}). @arg northing: Northing, see B{C{falsed}} (C{meter}). @kwarg band: Optional, polar Band (C{str}, 'A'|'B'|'Y'|'Z'). @kwarg datum: Optional, this coordinate's datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}). @kwarg falsed: Both B{C{easting}} and B{C{northing}} are falsed (C{bool}). @kwarg convergence: Optional, meridian convergence gamma to save (C{degrees}). @kwarg scale: Optional, computed scale factor k to save (C{scalar}). @kwarg name: Optional name (C{str}).
@raise TypeError: Invalid B{C{datum}}.
@raise UPSError: Invalid B{C{zone}}, B{C{pole}}, B{C{easting}}, B{C{northing}}, B{C{band}}, B{C{convergence}} or B{C{scale}}. ''' self.name = name
raise ValueError except (TypeError, ValueError) as x: raise UPSError(zone=zone, pole=pole, band=band, txt=str(x)) convergence=convergence, scale=scale)
return isinstance(other, Ups) and other.zone == self.zone \ and other.pole == self.pole \ and other.easting == self.easting \ and other.northing == self.northing \ and other.band == self.band \ and other.datum == self.datum
'''Get the polar band letter (C{'A'|'B'|'Y'|'Z'}). '''
'''Get the easting and northing falsing (L{EasNor2Tuple}C{(easting, northing)}). '''
'''Get the hemisphere (C{'N'|'S'}). '''
'''(INTERNAL) Cache for L{toMgrs}. '''
'''Parse a string to a similar L{Ups} instance.
@arg strUPS: The UPS coordinate (C{str}), see function L{parseUPS5}. @kwarg name: Optional instance name (C{str}), overriding this name.
@return: The similar instance (L{Ups}).
@raise UTMError: Invalid B{C{strUPS}}.
@see: Function L{parseUTM5} and L{parseUTMUPS5}. ''' return parseUPS5(strUPS, datum=self.datum, Ups=self.classof, name=name or self.name)
def parseUPS(self, strUPS): # PYCHOK no cover '''DEPRECATED, use method L{parse}.''' return self.parse(strUPS)
'''Get the top/center of (stereographic) projection (C{'N'|'S'} or C{""}). '''
'''Set the central scale factor for this UPS projection.
@arg lat: Northern latitude (C{degrees}). @arg scale0: UPS k0 scale at B{C{lat}} latitude (C{scalar}).
@raise RangeError: If B{C{lat}} outside the valid range and L{rangerrors} set to C{True}.
@raise UPSError: Invalid B{C{scale}}. '''
'''Convert this UPS coordinate to an (ellipsoidal) geodetic point.
@kwarg LatLon: Optional, ellipsoidal class to return the geodetic point (C{LatLon}) or C{None}. @kwarg unfalse: Unfalse B{C{easting}} and B{C{northing}} if falsed (C{bool}). @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword arguments, ignored if C{B{LatLon}=None}.
@return: This UPS coordinate (B{C{LatLon}}) or if B{C{LatLon}} is C{None}, a L{LatLonDatum5Tuple}C{(lat, lon, datum, convergence, scale)}.
@raise TypeError: If B{C{LatLon}} is not ellipsoidal.
@raise UPSError: Invalid meridional radius or H-value. '''
else:
'''(INTERNAL) See method C{.toLatLon}, function C{toUps8}. '''
'''Convert this UPS coordinate to an MGRS grid reference.
@return: The MGRS grid reference (L{Mgrs}).
@see: Methods L{Ups.toUtm} and L{Utm.toMgrs}. '''
'''Return a string representation of this UPS coordinate.
Note that UPS coordinates are rounded, not truncated (unlike MGRS grid references).
@kwarg prec: Optional number of decimals, unstripped (C{int}). @kwarg fmt: Optional, enclosing backets format (C{str}). @kwarg sep: Optional separator between name:value pairs (C{str}). @kwarg B: Optionally, include polar band letter (C{bool}). @kwarg cs: Optionally, include gamma meridian convergence and point scale factor (C{bool} or non-zero C{int} to specify the precison like B{C{prec}}).
@return: This UPS as a string with C{00[Band] pole, easting, northing, [convergence, scale]} as C{"[Z:00[Band], P:N|S, E:meter, N:meter]"} plus C{", C:DMS, S:float"} if B{C{cs}} is C{True}, where C{[Band]} is present and C{'A'|'B'|'Y'|'Z'} only if B{C{B}} is C{True} and convergence C{DMS} is in I{either} degrees, minutes I{or} seconds (C{str}).
@note: Pseudo zone zero (C{"00"}) for UPS follows I{Karney}'s U{zone UPS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1UTMUPS.html>}. '''
'''Return a string representation of this UPS coordinate.
Note that UPS coordinates are rounded, not truncated (unlike MGRS grid references).
@kwarg prec: Optional number of decimals, unstripped (C{int}). @kwarg sep: Optional separator to join (C{str}) or C{None} to return an unjoined C{tuple} of C{str}s. @kwarg B: Optionally, include and polar band letter (C{bool}). @kwarg cs: Optionally, include gamma meridian convergence and point scale factor (C{bool} or non-zero C{int} to specify the precison like B{C{prec}}).
@return: This UPS as a string with C{00[Band] pole, easting, northing, [convergence, scale]} as C{"00[B] N|S meter meter"} plus C{" DMS float"} if B{C{cs}} is C{True}, where C{[Band]} is present and C{'A'|'B'|'Y'|'Z'} only if B{C{B}} is C{True} and convergence C{DMS} is in I{either} degrees, minutes I{or} seconds (C{str}).
@note: Zone zero (C{"00"}) for UPS follows I{Karney}'s U{zone UPS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1UTMUPS.html>}. '''
'''Duplicate this UPS coordinate.
@kwarg pole: Optional top/center of the UPS projection, (C{str}, 'N[orth]'|'S[outh]').
@return: A copy of this UPS coordinate (L{Ups}).
@raise UPSError: Invalid B{C{pole}} or attempt to transfer the projection top/center. ''' t = _SPACE_(_pole_, repr(self.pole), _to_, repr(pole)) raise UPSError('no transfer', txt=t)
'''Convert this UPS coordinate to a UTM coordinate.
@arg zone: The UTM zone (C{int}). @kwarg falsed: False both easting and northing (C{bool}).
@return: The UTM coordinate (L{Utm}). '''
'''Get the polar pseudo zone (C{0}), like I{Karney}'s U{zone UPS<https:// GeographicLib.SourceForge.io/html/classGeographicLib_1_1UTMUPS.html>}. '''
'''(INTERNAL) For method L{Ups.rescale0}. '''
'''Parse a string representing a UPS coordinate, consisting of C{"[zone][band] pole easting northing"} where B{C{zone}} is pseudo zone C{"00"|"0"|""} and C{band} is C{'A'|'B'|'Y'|'Z'|''}.
@arg strUPS: A UPS coordinate (C{str}). @kwarg datum: Optional datum to use (L{Datum}). @kwarg Ups: Optional class to return the UPS coordinate (L{Ups}) or C{None}. @kwarg falsed: Both B{C{easting}} and B{C{northing}} are falsed (C{bool}). @kwarg name: Optional B{C{Ups}} name (C{str}).
@return: The UPS coordinate (B{C{Ups}}) or a L{UtmUps5Tuple}C{(zone, hemipole, easting, northing, band)} if B{C{Ups}} is C{None}. The C{hemipole} is the C{'N'|'S'} pole, the UPS projection top/center.
@raise UPSError: Invalid B{C{strUPS}}. ''' raise UPSError(strUPS=strUPS, zone=z, band=B)
else:
falsed=True, strict=True, name=NN): '''Convert a lat-/longitude point to a UPS coordinate.
@arg latlon: Latitude (C{degrees}) or an (ellipsoidal) geodetic C{LatLon} point. @kwarg lon: Optional longitude (C{degrees}) or C{None} if B{C{latlon}} is a C{LatLon}. @kwarg datum: Optional datum for this UPS coordinate, overriding B{C{latlon}}'s datum (C{Datum}, L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}). @kwarg Ups: Optional class to return the UPS coordinate (L{Ups}) or C{None}. @kwarg pole: Optional top/center of (stereographic) projection (C{str}, C{'N[orth]'} or C{'S[outh]'}). @kwarg falsed: False both easting and northing (C{bool}). @kwarg strict: Restrict B{C{lat}} to UPS ranges (C{bool}). @kwarg name: Optional B{C{Ups}} name (C{str}).
@return: The UPS coordinate (B{C{Ups}}) or a L{UtmUps8Tuple}C{(zone, hemipole, easting, northing, band, datum, convergence, scale)} if B{C{Ups}} is C{None}. The C{hemipole} is the C{'N'|'S'} pole, the UPS projection top/center.
@raise RangeError: If B{C{strict}} and B{C{lat}} outside the valid UPS bands or if B{C{lat}} or B{C{lon}} outside the valid range and L{rangerrors} set to C{True}.
@raise TypeError: If B{C{latlon}} is not ellipsoidal or B{C{datum}} invalid.
@raise ValueError: If B{C{lon}} value is missing or if B{C{latlon}} is invalid.
@see: I{Karney}'s C++ class U{UPS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1UPS.html>}. '''
else:
else: convergence=c, scale=k), n)
'''Return the UTM/UPS zone number, (polar) Band letter, pole and clipped lat- and longitude for a given location.
@arg lat: Latitude in degrees (C{scalar} or C{str}). @arg lon: Longitude in degrees (C{scalar} or C{str}). @kwarg strict: Restrict B{C{lat}} to UPS ranges (C{bool}). @kwarg name: Optional name (C{str}).
@return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole, lat, lon)} where C{hemipole} is the C{'N'|'S'} pole, the UPS projection top/center.
@raise RangeError: If B{C{strict}} and B{C{lat}} in the UTM and not the UPS range or if B{C{lat}} or B{C{lon}} outside the valid range and L{rangerrors} set to C{True}.
@raise ValueError: Invalid B{C{lat}} or B{C{lon}}. '''
r = _range_(_UPS_LAT_MIN, _UPS_LAT_MAX) t = _SPACE_(_inside_, _UTM_, _range_, r) raise RangeError(lat=degDMS(lat), txt=t)
else:
# **) MIT License # # Copyright (C) 2016-2021 -- mrJean1 at Gmail -- All Rights Reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included # in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR # OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. |