Coverage for pygeodesy/gars.py : 97%

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{Garef} and L{GARSError} and several functions to encode, decode and inspect I{Global Area Reference System} (GARS) references.
Transcoded 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>}. '''
_floatuple, _0to9_, _0_5, _90_0 Str, _xStrError
'''(INTERNAL) Convert lat, lon. ''' # lat, lon = parseDMS2(lat, lon) Lon(lon, Error=GARSError))
# def _2Garef(garef): # '''(INTERNAL) Check or create a L{Garef} instance. # ''' # if not isinstance(garef, Garef): # try: # garef = Garef(garef) # except (TypeError, ValueError): # raise _xStrError(Garef, Str, garef=garef) # return garef
'''(INTERNAL) Check a garef string. ''' or garstr[:3] == 'INV' \ or not garstr.isalnum(): raise ValueError
except (AttributeError, TypeError, ValueError) as x: raise GARSError(Garef.__name__, garef, txt=str(x))
'''(INTERNAL) Return a L{Precision_} instance. '''
'''Global Area Reference System (GARS) encode, decode or other L{Garef} issue. '''
'''Garef class, a named C{str}. ''' # 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}.
@arg cll: Cell or location (L{Garef} or C{str}, C{LatLon} or C{str}). @kwarg precision: Optional, the desired garef resolution and length (C{int} 0..2), see function L{gars.encode} for more details. @kwarg 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:
else: # assume LatLon except AttributeError: raise _xStrError(Garef, cll=cll) # Error=GARSError
'''Get this garef's attributes (L{LatLonPrec3Tuple}). ''' lat, lon = self.latlon return LatLonPrec3Tuple(lat, lon, self.precision, name=self.name)
'''(INTERNAL) Initial L{LatLonPrec5Tuple}. '''
'''Get this garef's (center) lat- and longitude (L{LatLon2Tuple}). '''
'''Get this garef's precision (C{int}). '''
'''Return (the center of) this garef cell as an instance of the supplied C{LatLon} class.
@arg LatLon: Class to use (C{LatLon}). @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword arguments.
@return: This garef location (B{C{LatLon}}).
@raise GARSError: Invalid B{C{LatLon}}. ''' kwds = _xkwds(LatLon_kwds, LatLon=None, name=self.name) raise GARSError(**kwds)
'''Decode a C{garef} to lat-, longitude and precision.
@arg garef: To be decoded (L{Garef} or C{str}). @kwarg 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(garef=Fmt.SQUARE(repr(garef), i))
raise _Error(i) raise _Error(j)
raise _Error(i)
Lon(lon * r, Error=GARSError), precision, name=nameof(garef))
'''Encode a lat-/longitude as a C{garef} of the given precision.
@arg lat: Latitude (C{degrees}). @arg lon: Longitude (C{degrees}). @kwarg 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. '''
lat *= EPS1_2
'''Determine the L{Garef} precision to meet a required (geographic) resolution.
@arg res: The required resolution (C{degrees}).
@return: The L{Garef} precision (C{int} 0..2).
@raise ValueError: Invalid B{C{res}}.
@see: Function L{gars.encode} for more C{precision} details. '''
'''Determine the (geographic) resolution of a given L{Garef} precision.
@arg prec: The given precision (C{int}).
@return: The (geographic) resolution (C{degrees}).
@raise GARSError: Invalid B{C{prec}}.
@see: Function L{gars.encode} for more C{precision} details. '''
encode, precision, resolution)
# **) 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. |