pygeodesy 24.7.24__py2.py3-none-any.whl → 24.8.24__py2.py3-none-any.whl

pygeodesy/wgrs.py

@@ -1,25 +1,26 @@
 
 # -*- coding: utf-8 -*-
 
-u'''World Geographic Reference System (WGRS) en-/decoding.
+u'''World Geographic Reference System (WGRS) en-/decoding, aka GEOREF.
 
-Classes L{Georef} and L{WGRSError} and several functions to encode,
-decode and inspect WGRS references.
+Class L{Georef} and several functions to encode, decode and inspect WGRS
+(or GEOREF) references.
 
 Transcoded from I{Charles Karney}'s C++ class U{Georef
 <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1Georef.html>},
-but with modified C{precision} and extended with C{height} and C{radius}.  See
-also U{World Geographic Reference System
-<https://WikiPedia.org/wiki/World_Geographic_Reference_System>}.
+but with modified C{precision} and extended with C{height} and C{radius}.
+
+@see: U{World Geographic Reference System
+      <https://WikiPedia.org/wiki/World_Geographic_Reference_System>}.
 '''
 # from pygeodesy.basics import isstr  # from .named
 from pygeodesy.constants import INT0, _float, _off90, _0_001, \
                                _0_5, _1_0, _2_0, _60_0, _1000_0
-from pygeodesy.dms import parse3llh  # parseDMS2
+from pygeodesy.dms import parse3llh
 from pygeodesy.errors import _ValueError, _xattr, _xStrError
 from pygeodesy.interns import NN, _0to9_, _AtoZnoIO_, _COMMA_, \
-                             _height_, _radius_, _SPACE_
-from pygeodesy.lazily import _ALL_LAZY, _ALL_OTHER
+                             _height_, _INV_, _radius_, _SPACE_
+from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY
 from pygeodesy.named import _name2__, nameof,  isstr, Property_RO
 from pygeodesy.namedTuples import LatLon2Tuple, LatLonPrec3Tuple
 # from pygeodesy.props import Property_RO  # from .named
@@ -31,21 +32,18 @@ from pygeodesy.utily import ft2m, m2ft, m2NM
 from math import floor
 
 __all__ = _ALL_LAZY.wgrs
-__version__ = '24.06.15'
+__version__ = '24.08.15'
 
 _Base    =  10
 _BaseLen =  4
 _DegChar = _AtoZnoIO_.tillQ
 _Digits  = _0to9_
-_Height_ =  Height.__name__
-_INV_    = 'INV'  # INValid
 _LatOrig = -90
 _LatTile = _AtoZnoIO_.tillM
 _LonOrig = -180
 _LonTile = _AtoZnoIO_
 _60B     =  60000000000  # == 60_000_000_000 == 60e9
 _MaxPrec =  11
-_Radius_ =  Radius.__name__
 _Tile    =  15  # tile size in degrees
 
 _MaxLen  = _BaseLen + 2 * _MaxPrec
@@ -68,31 +66,30 @@ def _divmod3(x, _Orig_60B):
     return xt, xd, x
 
 
-def _fllh3(lat, lon, height=None):
-    '''(INTERNAL) Convert lat, lon, height.
+def _2fll(lat, lon):
+    '''(INTERNAL) Convert lat, lon.
     '''
     # lat, lon = parseDMS2(lat, lon)
     return (Lat(lat, Error=WGRSError),
-            Lon(lon, Error=WGRSError), height)
+            Lon(lon, Error=WGRSError))
 
 
-def _geostr2(georef):
+def _2geostr2(georef):
     '''(INTERNAL) Check a georef string.
     '''
     try:
-        n, geostr = len(georef), georef.upper()
+        n, g = len(georef), georef.upper()
         p, o = divmod(n, 2)
         if o or n < _MinLen or n > _MaxLen \
-             or geostr[:3] == _INV_ \
-             or not geostr.isalnum():
-            raise ValueError
-        return geostr, _Precision(p - 1)
+             or g.startswith(_INV_) or not g.isalnum():
+            raise ValueError()
+        return g, _2Precision(p - 1)
 
     except (AttributeError, TypeError, ValueError) as x:
         raise WGRSError(Georef.__name__, georef, cause=x)
 
 
-def _Precision(precision):
+def _2Precision(precision):
     '''(INTERNAL) Return a L{Precision_} instance.
     '''
     return Precision_(precision, Error=WGRSError, low=0, high=_MaxPrec)
@@ -108,48 +105,51 @@ class Georef(Str):
     '''Georef class, a named C{str}.
     '''
     # no str.__init__ in Python 3
-    def __new__(cls, cll, precision=3, name=NN):
+    def __new__(cls, lat_gll, lon=None, height=None, precision=3, name=NN):
         '''New L{Georef} from an other L{Georef} instance or georef
            C{str} or from a C{LatLon} instance or lat-/longitude C{str}.
 
-           @arg cll: Cell or location (L{Georef} or C{str}, C{LatLon}
-                     or C{str}).
-           @kwarg precision: Optional, the desired georef resolution
-                             and length (C{int} 0..11), see function
-                             L{wgrs.encode} for more details.
+           @arg lat_gll: Latitude (C{degrees90}), a georef (L{Georef},
+                         C{str}) or a location (C{LatLon}, C{LatLon*Tuple}).
+           @kwarg lon: Logitude (C{degrees180)}, required if B{C{lat_gll}}
+                       is C{degrees90}, ignored otherwise.
+           @kwarg height: Optional height in C{meter}, used if B{C{lat_gll}}
+                          is a location.
+           @kwarg precision: The desired georef resolution and length (C{int}
+                             0..11), see L{encode<pygeodesy.wgrs.encode>}.
            @kwarg name: Optional name (C{str}).
 
            @return: New L{Georef}.
 
-           @raise RangeError: Invalid B{C{cll}} lat- or longitude.
+           @raise RangeError: Invalid B{C{lat_gll}} or B{C{lon}}.
 
-           @raise TypeError: Invalid B{C{cll}}.
+           @raise TypeError: Invalid B{C{lat_gll}} or B{C{lon}}.
 
-           @raise WGRSError: INValid or non-alphanumeric B{C{cll}}.
+           @raise WGRSError: INValid B{C{lat_gll}}.
         '''
-        ll = p = None
-
-        if isinstance(cll, Georef):
-            g, p = _geostr2(str(cll))
-
-        elif isstr(cll):
-            if _COMMA_ in cll:
-                lat, lon, h = _fllh3(*parse3llh(cll, height=None))
-                g  = encode(lat, lon, precision=precision, height=h)  # PYCHOK false
-                ll = lat, lon  # original lat, lon
-            else:
-                g = cll.upper()
-
-        else:  # assume LatLon
-            try:
-                lat, lon, h = _fllh3(cll.lat, cll.lon)
-            except AttributeError:
-                raise _xStrError(Georef, cll=cll)  # Error=WGRSError
-            h  = _xattr(cll, height=h)
-            g  =  encode(lat, lon, precision=precision, height=h)  # PYCHOK false
-            ll =  lat, lon  # original lat, lon
-
-        self = Str.__new__(cls, g, name=name or nameof(cll))
+        if lon is None:
+            if isinstance(lat_gll, Georef):
+                g, ll, p = str(lat_gll), lat_gll.latlon, lat_gll.precision
+            elif isstr(lat_gll):
+                if _COMMA_ in lat_gll or _SPACE_ in lat_gll:
+                    lat, lon, h = parse3llh(lat_gll, height=height)
+                    g, ll, p = _encode3(lat, lon, precision, h=h)
+                else:
+                    g, ll = lat_gll.upper(), None
+                    try:
+                        _, p = _2geostr2(g)  # validate
+                    except WGRSError:  # R00H00?
+                        p = None  # = decode5(g).precision?
+            else:  # assume LatLon
+                try:
+                    g, ll, p = _encode3(lat_gll.lat, lat_gll.lon, precision,
+                                        h=_xattr(lat_gll, height=height))
+                except AttributeError:
+                    raise _xStrError(Georef, gll=lat_gll)  # Error=WGRSError
+        else:
+            g, ll, p = _encode3(lat_gll, lon, precision, h=height)
+
+        self = Str.__new__(cls, g, name=name or nameof(lat_gll))
         self._latlon    = ll
         self._precision = p
         return self
@@ -232,8 +232,8 @@ def decode3(georef, center=True):
     '''Decode a C{georef} to lat-, longitude and precision.
 
        @arg georef: To be decoded (L{Georef} or C{str}).
-       @kwarg center: If C{True} the center, otherwise the south-west,
-                      lower-left corner (C{bool}).
+       @kwarg center: If C{True}, use the georef's center, otherwise
+                      the south-west, lower-left corner (C{bool}).
 
        @return: A L{LatLonPrec3Tuple}C{(lat, lon, precision)}.
 
@@ -255,7 +255,7 @@ def decode3(georef, center=True):
             raise _Error(i)
         return k
 
-    g, precision = _geostr2(georef)
+    g, precision = _2geostr2(georef)
     lon = _index(_LonTile, g, 0) + _LonOrig_Tile
     lat = _index(_LatTile, g, 1) + _LatOrig_Tile
 
@@ -285,33 +285,32 @@ def decode5(georef, center=True):
     '''Decode a C{georef} to lat-, longitude, precision, height and radius.
 
        @arg georef: To be decoded (L{Georef} or C{str}).
-       @kwarg center: If C{True} the center, otherwise the south-west,
-                      lower-left corner (C{bool}).
+       @kwarg center: If C{True}, use the georef's center, otherwise the
+                      south-west, lower-left corner (C{bool}).
 
-       @return: A L{LatLonPrec5Tuple}C{(lat, lon,
-                precision, height, radius)} where C{height} and/or
-                C{radius} are C{None} if missing.
+       @return: A L{LatLonPrec5Tuple}C{(lat, lon, precision, height, radius)}
+                where C{height} and/or C{radius} are C{None} if missing.
 
-       @raise WGRSError: Invalid B{C{georef}}, INValid, non-alphanumeric
-                         or odd length B{C{georef}}.
+       @raise WGRSError: Invalid B{C{georef}}.
     '''
-    def _h2m(kft, name):
-        return Height(ft2m(kft * _1000_0), name=name, Error=WGRSError)
+    def _h2m(kft, g_n):
+        return Height(ft2m(kft * _1000_0), name=g_n, Error=WGRSError)
 
-    def _r2m(NM, name):
-        return Radius(NM / m2NM(1), name=name, Error=WGRSError)
+    def _r2m(NM, g_n):
+        return Radius(NM / m2NM(1), name=g_n, Error=WGRSError)
 
-    def _split2(g, name, _2m):
-        i = max(g.find(name[0]), g.rfind(name[0]))
+    def _split2(g, Unit, _2m):
+        n = Unit.__name__
+        i = max(g.find(n[0]), g.rfind(n[0]))
         if i > _BaseLen:
-            return g[:i], _2m(int(g[i+1:]), _SPACE_(georef, name))
+            return g[:i], _2m(int(g[i+1:]), _SPACE_(georef, n))
         else:
             return g, None
 
     g = Str(georef, Error=WGRSError)
 
-    g, h = _split2(g, _Height_, _h2m)  # H is last
-    g, r = _split2(g, _Radius_, _r2m)  # R before H
+    g, h = _split2(g, Height, _h2m)  # H is last
+    g, r = _split2(g, Radius, _r2m)  # R before H
 
     return decode3(g, center=center).to5Tuple(h, r)
 
@@ -334,41 +333,49 @@ def encode(lat, lon, precision=3, height=None, radius=None):  # MCCABE 14
 
        @raise WGRSError: Invalid B{C{precision}}, B{C{height}} or B{C{radius}}.
 
-       @note: The B{C{precision}} value differs from U{Georef<https://
+       @note: The B{C{precision}} value differs from I{Karney}'s U{Georef<https://
               GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1Georef.html>}.
-              The C{georef} length is M{2 * (precision + 1)} and the
-              C{georef} resolution is I{15°} for B{C{precision}} 0, I{1°}
-              for 1, I{1′} for 2, I{0.1′} for 3, I{0.01′} for 4, ...
-              M{10**(2 - precision)}.
+              The C{georef} length is M{2 * (precision + 1)} and the C{georef}
+              resolution is I{15°} for B{C{precision}} 0:, I{1°} for 1, I{1′} for 2,
+              I{0.1′} for 3, I{0.01′} for 4, ... up to I{10**(2 - precision)′}.
     '''
     def _option(name, m, m2_, K):
         f = Scalar_(m, name=name, Error=WGRSError)
         return NN(name[0].upper(), int(m2_(f * K) + _0_5))
 
-    p = _Precision(precision)
+    g, _, _ = _encode3(lat, lon, precision)
+    if radius is not None:  # R before H
+        g += _option(_radius_, radius, m2NM, _1_0)
+    if height is not None:  # H is last
+        g += _option(_height_, height, m2ft, _0_001)
+    return g
+
 
-    lat, lon, _ = _fllh3(lat, lon)
-    lat = _off90(lat)
+def _encode3(lat, lon, precision, h=None):
+    '''Return 3-tuple C{(georef, (lat, lon), p)}.
+    '''
+    p = _2Precision(precision)
 
-    xt, xd, x = _divmod3(lon, _LonOrig_60B)
-    yt, yd, y = _divmod3(lat, _LatOrig_60B)
+    lat, lon = _2fll(lat, lon)
 
-    g = _LonTile[xt], _LatTile[yt]
-    if p > 0:
-        g += _DegChar[xd], _DegChar[yd]
-        p -= 1
-        if p > 0:
-            d =  pow(_Base, _MaxPrec - p)
-            x = _0wd(p, x // d)
-            y = _0wd(p, y // d)
-            g += x, y
+    if h is None:
+        xt, xd, x = _divmod3(       lon,  _LonOrig_60B)
+        yt, yd, y = _divmod3(_off90(lat), _LatOrig_60B)
 
-    if radius is not None:  # R before H
-        g += _option(_radius_, radius, m2NM, _1_0),
-    if height is not None:  # H is last
-        g += _option(_height_, height, m2ft, _0_001),
+        g = _LonTile[xt], _LatTile[yt]
+        if p > 0:
+            g += _DegChar[xd], _DegChar[yd]
+            p -= 1
+            if p > 0:
+                d =  pow(_Base, _MaxPrec - p)
+                x = _0wd(p, x // d)
+                y = _0wd(p, y // d)
+                g += x, y
+        g = NN.join(g)
+    else:
+        g = encode(lat, lon, precision=p, height=h)
 
-    return NN.join(g)  # XXX Georef(''.join(g))
+    return g, (lat, lon), p  # XXX Georef(''.join(g))
 
 
 def precision(res):
@@ -403,7 +410,8 @@ def resolution(prec):
     '''
     p = Int(prec=prec, Error=WGRSError)
     if p > 1:
-        r = _1_0 / (_60_0 * pow(_Base, min(p, _MaxPrec) - 1))
+        p =  min(p, _MaxPrec) - 1
+        r = _1_0 / (pow(_Base, p) * _60_0)
     elif p < 1:
         r = _float_Tile
     else:
@@ -411,8 +419,8 @@ def resolution(prec):
     return r
 
 
-__all__ += _ALL_OTHER(decode3, decode5,  # functions
-                      encode, precision, resolution)
+__all__ += _ALL_DOCS(decode3, decode5,  # functions
+                     encode, precision, resolution)
 
 # **) MIT License
 #