Coverage for pygeodesy/gars.py : 91%

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 -*-
decode and inspect I{Global Area Reference System (GARS)} references.
Transcribed from C++ class U{GARS <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1GARS.html>} by I{Charles Karney}. See also U{Global Area Reference System <https://WikiPedia.org/wiki/Global_Area_Reference_System>} and U{NGA (GARS) <https://Earth-Info.NGA.mil/GandG/coordsys/grids/gars.html>}.
@newfield example: Example, Examples '''
_NamedStr, nameof, _xnamed
# all public contants, classes and functions 'encode', 'precision', 'resolution')
i -= 1
'''(INTERNAL) Convert lat, lon. '''
# def _2Garef(garef): # '''(INTERNAL) Check or create a L{Garef} instance. # ''' # if not isinstance(garef, Garef): # try: # garef = Garef(garef) # except (TypeError, ValueError): # raise _IsNotError(Garef.__name__, str.__name__, 'LatLon', garef=garef) # return garef
'''(INTERNAL) Check a garef string. ''' or garstr[:3] == 'INV' \ or not garstr.isalnum(): raise ValueError except (AttributeError, TypeError, ValueError): raise GARSError('%s: %r[%s]' % (Garef.__name__, garef, len(garef)))
'''Global Area Reference System (GARS) encode, decode or other L{Garef} issue. '''
'''Garef class, a C{_NamedStr}. '''
# no str.__init__ in Python 3 '''New L{Garef} from an other L{Garef} instance or garef C{str} or from a C{LatLon} instance or lat-/longitude C{str}.
@param cll: Cell or location (L{Garef} or C{str}, C{LatLon} or C{str}). @keyword precision: Optional, the desired garef resolution and length (C{int} 0..2), see function L{gars.encode} for more details. @keyword name: Optional name (C{str}).
@return: New L{Garef}.
@raise RangeError: Invalid B{C{cll}} lat- or longitude.
@raise TypeError: Invalid B{C{cll}}.
@raise GARSError: INValid or non-alphanumeric B{C{cll}}. '''
else: self = str.__new__(cls, cll.upper()) self._decode()
else: # assume LatLon except AttributeError: raise TypeError('%s: %r' % (Garef.__name__, cll))
# cache all decoded attrs lat, lon, p = decode3(self) if self._latlon is None: self._latlon = LatLon2Tuple(lat, lon) if self._precision is None: self._precision = p
def latlon(self): '''Get this garef's (center) lat- and longitude (L{LatLon2Tuple}). ''' self._decode()
def precision(self): '''Get this garef's precision (C{int}). ''' self._decode()
'''Return (the center of) this garef cell as an instance of the supplied C{LatLon} class.
@param LatLon: Class to use (C{LatLon}). @keyword kwds: Optional keyword arguments for B{C{LatLon}}.
@return: This garef location (B{C{LatLon}}).
@raise GARSError: Invalid B{C{LatLon}}. ''' raise GARSError('%s invalid: %r' % ('LatLon', LatLon))
'''Decode a C{garef} to lat-, longitude and precision.
@param garef: To be decoded (L{Garef} or C{str}). @keyword center: If C{True} the center, otherwise the south-west, lower-left corner (C{bool}).
@return: A L{LatLonPrec3Tuple}C{(lat, lon, precision)}.
@raise GARSError: Invalid B{C{garef}}, INValid, non-alphanumeric or bad length B{C{garef}}. ''' return GARSError('%s invalid: %r[%s]' % ('garef', garef, i))
raise _Error(i) raise _Error(j)
raise _Error(i)
'''Encode a lat-/longitude as a C{garef} of the given precision.
@param lat: Latitude (C{degrees}). @param lon: Longitude (C{degrees}). @keyword precision: Optional, the desired C{garef} resolution and length (C{int} 0..2).
@return: The C{garef} (C{str}).
@raise RangeError: Invalid B{C{lat}} or B{C{lon}}.
@raise GARSError: Invalid B{C{precision}}.
@note: The C{garef} length is M{precision + 5} and the C{garef} resolution is B{30′} for B{C{precision}} 0, B{15′} for 1 and B{5′} for 2, respectively. '''
raise ValueError except (TypeError, ValueError): raise GARSError('%s invalid: %r' % ('precision', precision))
lat *= EPS1_2
'''Determine the L{Garef} precision to meet a required (geographic) resolution.
@param res: The required resolution (C{degrees}).
@return: The L{Garef} precision (C{int} 0..2).
@see: Function L{gars.encode} for more C{precision} details. '''
'''Determine the (geographic) resolution of a given L{Garef} precision.
@param prec: The given precision (C{int}).
@return: The (geographic) resolution (C{degrees}).
@see: Function L{gars.encode} for more C{precision} details. '''
# **) 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. |