Coverage for pygeodesy/ups.py : 89%

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 -*-
and functions L{parseUPS5}, L{toUps8} and L{upsZoneBand5}.
A pure Python implementation, partially transcribed 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>} to location 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).
@newfield example: Example, Examples '''
UtmUpsLatLon5Tuple, _xnamed _UPS_LAT_MAX, _UPS_LAT_MIN, _UPS_ZONE, \ _UPS_ZONE_STR, UtmUpsBase
# all public contants, classes and functions
'''Universal Polar Stereographic (UPS) parse or other L{Ups} issue. '''
# determine the polar band letter
# compute the point scale factor, ala Karney
'''Universal Polar Stereographic (UPS) coordinate. '''
datum=Datums.WGS84, falsed=True, convergence=None, scale=None, name=''): '''New L{Ups} UPS coordinate.
@param zone: UPS zone (C{int}, zero) or zone with/-out Band letter (C{str}, '00', '00A', '00B', '00Y' or '00Z'). @param pole: Top/center of (stereographic) projection (C{str}, C{'N[orth]'} or C{'S[outh]'}). @param easting: Easting, see B{C{falsed}} (C{meter}). @param northing: Northing, see B{C{falsed}} (C{meter}). @keyword band: Optional, polar Band (C{str}, 'A'|'B'|'Y'|'Z'). @keyword datum: Optional, this coordinate's datum (L{Datum}). @keyword falsed: Both B{C{easting}} and B{C{northing}} are falsed (C{bool}). @keyword convergence: Optionally, save gamma meridian convergence (C{degrees}). @keyword scale: Optionally, save computed k scale (C{scalar}). @keyword name: Optional name (C{str}).
@raise UPSError: Invalid B{C{zone}}, B{C{pole}} or B{C{band}}. ''' self.name = name
raise ValueError except ValueError: raise UPSError('%s, %s or %s invalid: %r' % ('zone', 'pole', 'band', (zone, pole, band)))
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
def band(self): '''Get the polar band letter ('A', 'B', 'Y' or 'Z'). '''
def falsed2(self): '''Get the easting and northing falsing (L{EasNor2Tuple}C{(easting, northing)}). '''
def hemisphere(self): '''Get the hemisphere (C{str}, 'N'|'S'). '''
'''Parse a string to a UPS coordinate.
@return: The coordinate (L{Ups}).
@see: Function L{parseUPS5} in this module L{ups}. ''' return parseUPS5(strUPS, datum=self.datum, Ups=self.classof)
def pole(self): '''Get the top/center of (stereographic) projection (C{'N'|'S'} or C{""}). '''
'''Set the central scale factor for this UPS projection.
@param lat: Northern latitude (C{degrees}). @param 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 ValueError: Invalid B{C{scale}}. ''' try: s0 = float(scale0) if not 0 < s0: # <= 1.003 or 1.0016? raise ValueError except (TypeError, ValueError): raise ValueError('%s invalid: %r' % ('scale', scale0))
lat = clipDMS(lat, 90) # clip and force N u = toUps8(abs(lat), 0, datum=self.datum, Ups=_UpsK1) k = s0 / u.scale if self.scale0 != k: self._band = '' # force re-compute self._latlon = self._epsg = self._mgrs = self._utm = None self._scale0 = k
'''Convert this UPS coordinate to an (ellipsoidal) geodetic point.
@keyword LatLon: Optional, ellipsoidal (sub-)class to return the point (C{LatLon}) or C{None}. @keyword unfalse: Unfalse B{C{easting}} and B{C{northing}} if falsed (C{bool}).
@return: This UPS coordinate as (B{C{LatLon}}) or A L{LatLonDatum5Tuple}C{(lat, lon, datum, convergence, scale)} if B{C{LatLon}} is C{None}.
@raise TypeError: If B{C{LatLon}} is not ellipsoidal.
@raise UPSError: Invalid meridional radius or H-value. '''
else:
'''(INTERNAL) See C{.toLatLon}, 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).
@keyword prec: Optional number of decimals, unstripped (C{int}). @keyword sep: Optional separator to join (C{str}). @keyword B: Optionally, include and polar band letter (C{bool}). @keyword cs: Optionally, include gamma meridian convergence and point scale factor (C{bool}).
@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 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).
@keyword prec: Optional number of decimals, unstripped (C{int}). @keyword fmt: Optional, enclosing backets format (C{str}). @keyword sep: Optional separator between name:value pairs (C{str}). @keyword B: Optionally, include polar band letter (C{bool}). @keyword cs: Optionally, include gamma meridian convergence and point scale factor (C{bool}).
@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 Karney's U{zone UPS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1UTMUPS.html>}. '''
'''Duplicate this UPS coordinate.
@keyword pole: Optional top/center of the UPS projection, (C{str}, 'N[orth]'|'S[outh]').
@return: A copt of this UPS coordinate (L{Ups}).
@raise UPSError: Invalid B{C{pole}} or attempt to transfer the projection top/center. ''' raise UPSError('%s transfer invalid: %r to %r' % ('pole', self.pole, pole)) # PYCHOK pole
'''Convert this UPS coordinate to a UTM coordinate.
@param zone: The UTM zone (C{int}). @keyword falsed: False both easting and northing (C{bool}).
@return: The UTM coordinate (L{Utm}). '''
def zone(self): '''Get the polar pseudo zone (C{0}), like Karney's U{zone UPS<https:// GeographicLib.SourceForge.io/html/classGeographicLib_1_1UTMUPS.html>}. '''
'''(INTERNAL) For method L{Ups.rescale}. '''
'''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'|''}.
@param strUPS: A UPS coordinate (C{str}). @keyword datum: Optional datum to use (L{Datum}). @keyword Ups: Optional (sub-)class to return the UPS coordinate (L{Ups}) or C{None}. @keyword falsed: Both B{C{easting}} and B{C{northing}} are falsed (C{bool}). @keyword 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 ValueError
raise ValueError except (AttributeError, TypeError, ValueError): raise UPSError('%s invalid: %r' % ('strUPS', strUPS))
r = UtmUps5Tuple(z, p, e, n, B) else:
falsed=True, strict=True, name=''): '''Convert a lat-/longitude point to a UPS coordinate.
@param latlon: Latitude (C{degrees}) or an (ellipsoidal) geodetic C{LatLon} point. @keyword lon: Optional longitude (C{degrees}) or C{None} if B{C{latlon}} is a C{LatLon}. @keyword datum: Optional datum for this UPS coordinate, overriding B{C{latlon}}'s datum (C{Datum}). @keyword Ups: Optional (sub-)class to return the UPS coordinate (L{Ups}) or C{None}. @keyword pole: Optional top/center of (stereographic) projection (C{str}, C{'N[orth]'} or C{'S[outh]'}). @keyword falsed: False both easting and northing (C{bool}). @keyword strict: Restrict B{C{lat}} to UPS ranges (C{bool}). @keyword 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.
@raise ValueError: If B{C{lon}} value is missing or if B{C{latlon}} is invalid.
@see: Karney's C++ class U{UPS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1UPS.html>}. '''
else:
r = UtmUps8Tuple(z, p, x, y, B, d, c, k) else: convergence=c, scale=k)
'''Return the UTM/UPS zone number, (polar) Band letter, pole and clipped lat- and longitude for a given location.
@param lat: Latitude in degrees (C{scalar} or C{str}). @param lon: Longitude in degrees (C{scalar} or C{str}). @keyword strict: Restrict B{C{lat}} to UPS ranges (C{bool}).
@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}}. '''
x = '%s [%s, %s]' % ('range', _UPS_LAT_MIN, _UPS_LAT_MAX) raise RangeError('%s inside UTM %s: %s' % ('lat', x, degDMS(lat)))
else:
# **) MIT License # # Copyright (C) 2016-2020 -- 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. |