Coverage for pygeodesy/utmups.py : 98%

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 -*-
Functions L{parseUTMUPS5}, L{toUtmUps8}, L{UtmUps} and L{utmupsZoneBand5} to handle both I{Universal Transverse Mercator} (U{UTM <https://WikiPedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>}) and I{Universal Polar Stereographic} (U{UPS <https://WikiPedia.org/wiki/Universal_polar_stereographic_coordinate_system>}) coordinates.
A pure Python implementation, partially transcoded from C++ class U{UTMUPS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1UTMUPS.html>} by I{Charles Karney}. '''
# from pygeodesy.basics import map1 # from .utmupsBase # from pygeodesy.datums import _WGS84 # from .utmupsBase _outside_, _range_, _SPACE_, _UPS_, _UTM_ # from pygeodesy.streprs import Fmt # from .utmupsBase _UPS_ZONE, _UPS_ZONE_STR, \ _UTMUPS_ZONE_MIN, _UTMUPS_ZONE_MAX, _WGS84
# UPS ranges for North, South pole
# UTM ranges for Northern, Southern hemisphere
'''Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) parse, validate or other issue. '''
'''Parse a string representing a UTM or UPS coordinate, consisting of C{"zone[band] hemisphere/pole easting northing"}.
@arg strUTMUPS: A UTM or UPS coordinate (C{str}). @kwarg datum: Optional datum to use (L{Datum}). @kwarg Utm: Optional class to return the UTM coordinate (L{Utm}) or C{None}. @kwarg Ups: Optional class to return the UPS coordinate (L{Ups}) or C{None}. @kwarg name: Optional instance name (C{str}).
@return: The UTM or UPS instance (B{C{Utm}} or B{C{Ups}}) or a L{UtmUps5Tuple}C{(zone, hemipole, easting, northing, band)} if B{C{Utm}} respectively B{C{Ups}} or both are C{None}. The C{hemipole} is C{'N'|'S'}, the UTM hemisphere or UPS pole, the UPS projection top/center.
@raise UTMUPSError: Invalid B{C{strUTMUPS}}.
@see: Functions L{pygeodesy.parseUTM5} and L{pygeodesy.parseUPS5}. ''' except UTMError: u = parseUPS5(strUTMUPS, datum=datum, Ups=Ups, name=name)
except (UTMError, UPSError) as x: raise UTMUPSError(strUTMUPS=strUTMUPS, txt=str(x))
pole=NN, name=NN, **cmoff): '''Convert a lat-/longitude point to a UTM or UPS coordinate.
@arg latlon: Latitude (C{degrees}) or an (ellipsoidal) geodetic C{LatLon} point. @kwarg lon: Optional longitude (C{degrees}) or C{None}. @kwarg datum: Optional datum to use this UTM coordinate, overriding B{C{latlon}}'s datum (C{Datum}). @kwarg falsed: False both easting and northing (C{bool}). @kwarg Utm: Optional class to return the UTM coordinate (L{Utm}) or C{None}. @kwarg Ups: Optional class to return the UPS coordinate (L{Ups}) or C{None}. @kwarg pole: Optional top/center of UPS (stereographic) projection (C{str}, C{'N[orth]'} or C{'S[outh]'}). @kwarg name: Optional name (C{str}). @kwarg cmoff: DEPRECATED, use B{C{falsed}}. Offset longitude from zone's central meridian, for UTM only (C{bool}).
@return: The UTM or UPS coordinate (B{C{Utm}} respectively B{C{Ups}}) or a L{UtmUps8Tuple}C{(zone, hemipole, easting, northing, band, datum, convergence, scale)} if B{C{Utm}} respectively B{C{Ups}} is C{None} or B{C{cmoff}} is C{False}.
@raise RangeError: If B{C{lat}} outside the valid UTM or UPS bands or if B{C{lat}} or B{C{lon}} outside the valid range and L{pygeodesy.rangerrors} set to C{True}.
@raise TypeError: If B{C{latlon}} is not ellipsoidal or B{C{lon}} value is missing of B{C{datum}} is invalid.
@raise UTMUPSError: UTM or UPS validation failed.
@raise ValueError: Invalid B{C{lat}} or B{C{lon}}.
@see: Functions L{pygeodesy.toUtm8} and L{pygeodesy.toUps8}. '''
else:
falsed=True, name=NN): '''Class-like function to create a UTM/UPS coordinate.
@kwarg zone: The UTM zone with/-out I{longitudinal} Band or UPS zone C{0} or C{"00"} with/-out I{polar} Band (C{str} or C{int}). @kwarg hemipole: UTM hemisphere or UPS top/center of 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, UTM I{latitudinal} C{'C'|'D'|..|'W'|'X'} or UPS I{polar} Band letter C{'A'|'B'|'Y'|'Z'} Band letter (C{str}). @kwarg datum: Optional, the coordinate's datum (L{Datum}). @kwarg falsed: Both B{C{easting}} and B{C{northing}} are falsed (C{bool}). @kwarg name: Optional name (C{str}).
@return: New UTM or UPS instance (L{Utm} or L{Ups}).
@raise TypeError: Invalid B{C{datum}}.
@raise UTMUPSError: UTM or UPS validation failed.
@see: Classes L{Utm} and L{Ups} and I{Karney}'s U{UTMUPS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1UTMUPS.html>}. ''' falsed=falsed, name=name)
'''Check a UTM or UPS coordinate.
@arg coord: The UTM or UPS coordinate (L{Utm}, L{Ups} or C{5+Tuple}). @kwarg falsed: C{5+Tuple} easting and northing are falsed (C{bool}). @kwarg MGRS: Increase easting and northing ranges (C{bool}). @kwarg Error: Optional error to raise, overriding the default (L{UTMUPSError}).
@return: C{None} if validation passed.
@raise Error: Validation failed.
@see: Function L{utmupsValidateOK}. '''
except (TypeError, ValueError): pass raise Error(ename, en, txt=t)
else: raise _IsnotError(Error=Error, coord=coord, *map1(modulename, Utm, Ups, UtmUps5Tuple, UtmUps8Tuple))
else: # UTM
U, s = _MGRS_, _MGRS_TILE else:
or z > _UTMUPS_ZONE_MAX \ or B not in u._Bands: t = Fmt.PAREN(U, repr(_SPACE_(NN(Fmt.zone(z), B), h))) raise Error(coord=t, zone=zone, band=band, hemisphere=hemi)
'''Check a UTM or UPS coordinate.
@arg coord: The UTM or UPS coordinate (L{Utm}, L{Ups} or C{5+Tuple}). @kwarg falsed: C{5+Tuple} easting and northing are falsed (C{bool}). @kwarg ok: Result to return if validation passed (B{C{ok}}).
@return: B{C{ok}} if validation passed, the L{UTMUPSError} otherwise.
@see: Function L{utmupsValidate}. ''' except UTMUPSError as x: return x
'''Return the UTM/UPS zone number, Band letter, hemisphere/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 cmoff: Offset longitude from the zone's central meridian, for UTM only (C{bool}). @kwarg name: Optional name (C{str}).
@return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole, lat, lon)} where C{hemipole} is C{'N'|'S'}, the UTM hemisphere or UPS pole, the UPS projection top/center.
@raise RangeError: If B{C{lat}} outside the valid UTM or UPS bands or if B{C{lat}} or B{C{lon}} outside the valid range and L{pygeodesy.rangerrors} set to C{True}.
@raise ValueError: Invalid B{C{lat}} or B{C{lon}}.
@see: Functions L{pygeodesy.utmZoneBand5} and L{pygeodesy.upsZoneBand5}. ''' except RangeError: return upsZoneBand5(lat, lon, name=name)
# **) MIT License # # Copyright (C) 2016-2022 -- 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. |