pygeodesy 24.5.24__py2.py3-none-any.whl → 24.6.1__py2.py3-none-any.whl

pygeodesy/utmupsBase.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 u'''(INTERNAL) Private class C{UtmUpsBase}, functions and constants
-for L{epsg}, L{etm}, L{mgrs}, L{ups} and L{utm}.
+for modules L{epsg}, L{etm}, L{mgrs}, L{ups} and L{utm}.
 '''
 
 from pygeodesy.basics import isint, isscalar, isstr, neg_, \
@@ -11,12 +11,12 @@ from pygeodesy.constants import _float, _0_0, _0_5, _N_90_0, _180_0
 from pygeodesy.datums import _ellipsoidal_datum, _WGS84
 from pygeodesy.dms import degDMS, parseDMS2
 from pygeodesy.ellipsoidalBase import LatLonEllipsoidalBase as _LLEB
-from pygeodesy.errors import _or, ParseError, _parseX, _UnexpectedError, \
-                             _ValueError, _xkwds, _xkwds_not, _xkwds_pop2
+from pygeodesy.errors import _or, ParseError, _parseX, _ValueError, \
+                             _xkwds, _xkwds_not
 # from pygeodesy.internals import _name__, _under  # from .named
 from pygeodesy.interns import NN, _A_, _B_, _COMMA_, _Error_, \
                              _gamma_, _n_a_, _not_, _N_, _NS_, _PLUS_, \
-                             _scale_, _SPACE_, _Y_, _Z_
+                             _S_, _scale_, _SPACE_, _Y_, _Z_
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS
 from pygeodesy.named import _NamedBase, _xnamed,  _name__, _under
 from pygeodesy.namedTuples import EasNor2Tuple, LatLonDatum5Tuple
@@ -27,7 +27,7 @@ from pygeodesy.units import Band, Easting, Northing, Scalar, Zone
 from pygeodesy.utily import _Wrap, wrap360
 
 __all__ = _ALL_LAZY.utmupsBase
-__version__ = '24.05.19'
+__version__ = '24.05.30'
 
 _UPS_BANDS = _A_, _B_, _Y_, _Z_  # UPS polar bands SE, SW, NE, NW
 # _UTM_BANDS = _MODS.utm._Bands
@@ -59,94 +59,6 @@ _UTMUPS_ZONE_MIN     = _UPS_ZONE      # PYCHOK for export too, by .units.py
 # _UTM                  = -2
 
 
-def _hemi(lat, N=0):  # imported by .ups, .utm
-    '''Return the hemisphere letter.
-
-       @arg lat: Latitude (C{degrees} or C{radians}).
-       @kwarg N: Minimal North latitude, C{0} or C{_N_}.
-
-       @return: C{'N'|'S'} for north-/southern hemisphere.
-    '''
-    return _NS_[int(lat < N)]
-
-
-def _to4lldn(latlon, lon, datum, name, wrap=False):
-    '''(INTERNAL) Return 4-tuple (C{lat, lon, datum, name}).
-    '''
-    try:
-        # if lon is not None:
-        #     raise AttributeError
-        lat, lon = float(latlon.lat), float(latlon.lon)
-        _xinstanceof(_LLEB, LatLonDatum5Tuple, latlon=latlon)
-        if wrap:
-            _Wrap.latlon(lat, lon)
-        d = datum or latlon.datum
-    except AttributeError:
-        lat, lon = _Wrap.latlonDMS2(latlon, lon) if wrap else \
-                          parseDMS2(latlon, lon)  # clipped
-        d = datum or _WGS84
-    return lat, lon, d, _name__(name, _or_nameof=latlon)
-
-
-def _to3zBhp(zone, band, hemipole=NN, Error=_ValueError):  # imported by .epsg, .ups, .utm, .utmups
-    '''Parse UTM/UPS zone, Band letter and hemisphere/pole letter.
-
-       @arg zone: Zone with/-out Band (C{scalar} or C{str}).
-       @kwarg band: Optional I{longitudinal/polar} Band letter (C{str}).
-       @kwarg hemipole: Optional hemisphere/pole letter (C{str}).
-       @kwarg Error: Optional error to raise, overriding the default
-                     C{ValueError}.
-
-       @return: 3-Tuple (C{zone, Band, hemisphere/pole}) as (C{int, str,
-                'N'|'S'}) where C{zone} is C{0} for UPS or C{1..60} for
-                UTM and C{Band} is C{'A'..'Z'} I{NOT} checked for valid
-                UTM/UPS bands.
-
-       @raise ValueError: Invalid B{C{zone}}, B{C{band}} or B{C{hemipole}}.
-    '''
-    try:
-        B, z = band, _UTMUPS_ZONE_INVALID
-        if isscalar(zone):
-            z = int(zone)
-        elif zone and isstr(zone):
-            if zone.isdigit():
-                z = int(zone)
-            elif len(zone) > 1:
-                B = zone[-1:]
-                z = int(zone[:-1])
-            elif zone.upper() in _UPS_BANDS:  # single letter
-                B =  zone
-                z = _UPS_ZONE
-
-        if _UTMUPS_ZONE_MIN <= z <= _UTMUPS_ZONE_MAX:
-            hp = hemipole[:1].upper()
-            if hp in _NS_ or not hp:
-                z = Zone(z)
-                B = Band(B.upper())
-                if B.isalpha():
-                    return z, B, (hp or _hemi(B, _N_))
-                elif not B:
-                    return z, B, hp
-
-        raise ValueError  # _invalid_
-    except (AttributeError, IndexError, TypeError, ValueError) as x:
-        raise Error(zone=zone, band=B, hemipole=hemipole, cause=x)
-
-
-def _to3zll(lat, lon):  # imported by .ups, .utm
-    '''Wrap lat- and longitude and determine UTM zone.
-
-       @arg lat: Latitude (C{degrees}).
-       @arg lon: Longitude (C{degrees}).
-
-       @return: 3-Tuple (C{zone, lat, lon}) as (C{int}, C{degrees90},
-                C{degrees180}) where C{zone} is C{1..60} for UTM.
-    '''
-    x = wrap360(lon + _180_0)  # use wrap360 to get ...
-    z = int(x) // 6 + 1  # ... longitudinal UTM zone [1, 60] and ...
-    return Zone(z), lat, (x - _180_0)  # ... -180 <= lon < 180
-
-
 class UtmUpsBase(_NamedBase):
     '''(INTERNAL) Base class for L{Utm} and L{Ups} coordinates.
     '''
@@ -166,7 +78,7 @@ class UtmUpsBase(_NamedBase):
     _utm        =  None   # cached toUtm (L{Utm})
 
     def __init__(self, easting, northing, band=NN, datum=None, falsed=True,
-                                          gamma=None, scale=None, **convergence):
+                                                   gamma=None, scale=None):
         '''(INTERNAL) New L{UtmUpsBase}.
         '''
         E = self._Error
@@ -185,10 +97,6 @@ class UtmUpsBase(_NamedBase):
         if not falsed:
             self._falsed = False
 
-        if convergence:  # for backward compatibility
-            gamma, kwds = _xkwds_pop2(convergence, convergence=gamma)
-            if kwds:
-                raise _UnexpectedError(**kwds)
         if gamma is not self._gamma:
             self._gamma = Scalar(gamma=gamma, Error=E)
         if scale is not self._scale:
@@ -272,7 +180,7 @@ class UtmUpsBase(_NamedBase):
 
     @Property_RO
     def falsed(self):
-        '''Get easting and northing falsed (C{bool}).
+        '''Are easting and northing falsed (C{bool})?
         '''
         return self._falsed
 
@@ -310,9 +218,11 @@ class UtmUpsBase(_NamedBase):
                                ll, _under(_gamma_), _under(_scale_))
         return _xnamed(r, ll.name)
 
-    def _latlon5args(self, ll, _toBand, unfalse, *other):
+    def _latlon5args(self, ll, g, k, _toBand, unfalse, *other):
         '''(INTERNAL) See C{._toLLEB} methods, functions C{ups.toUps8} and C{utm._toXtm8}
         '''
+        ll._gamma = g
+        ll._scale = k
         ll._toLLEB_args = (unfalse,) + other
         if unfalse:
             if not self._band:
@@ -418,17 +328,26 @@ class UtmUpsBase(_NamedBase):
         return t if sep is None else sep.join(t)
 
 
-def _lowerleft(utmups, center):  # by .ellipsoidalBase._lowerleft
+def _hemi(lat, N=0):  # in .ups, .utm
+    '''Return the hemisphere letter.
+
+       @arg lat: Latitude (C{degrees} or C{radians}).
+       @kwarg N: Minimal North latitude, C{0} or C{_N_}.
+
+       @return: C{'N'|'S'} for north-/southern hemisphere.
+    '''
+    return _S_ if lat < N else _N_
+
+
+def _lowerleft(utmups, center):  # in .ellipsoidalBase._lowerleft
     '''(INTERNAL) I{Un}-center a B{C{utmups}} to its C{lowerleft} by
        C{B{center} meter} or by a I{guess} if B{C{center}} is C{0}.
     '''
     if center:
         e = n = -center
     else:
-        c = 5  # center
-        for _ in range(3):
-            c *= 10  # 50, 500, 5000
-            t  = c * 2
+        for c in (50, 500, 5000):
+            t = c * 2
             e = int(utmups.easting  % t)
             n = int(utmups.northing % t)
             if (e == c and n in (c, c - 1)) or \
@@ -439,7 +358,7 @@ def _lowerleft(utmups, center):  # by .ellipsoidalBase._lowerleft
 
     r = _xkwds_not(None, datum=utmups.datum,
                          gamma=utmups.gamma,
-                         scale=utmups.scale)
+                         scale=utmups.scale, name=utmups.name)
     return utmups.classof(utmups.zone, utmups.hemisphere,
                           utmups.easting - e, utmups.northing - n,
                           band=utmups.band, falsed=utmups.falsed, **r)
@@ -489,12 +408,89 @@ def _parseUTMUPS5(strUTMUPS, UPS, Error=ParseError, band=NN, sep=_COMMA_):
                              strUTMUPS=strUTMUPS, Error=Error)
 
 
+def _to4lldn(latlon, lon, datum, name, wrap=False):
+    '''(INTERNAL) Return 4-tuple (C{lat, lon, datum, name}).
+    '''
+    try:
+        # if lon is not None:
+        #     raise AttributeError
+        lat, lon = float(latlon.lat), float(latlon.lon)
+        _xinstanceof(_LLEB, LatLonDatum5Tuple, latlon=latlon)
+        if wrap:
+            _Wrap.latlon(lat, lon)
+        d = datum or latlon.datum
+    except AttributeError:  # TypeError
+        lat, lon = _Wrap.latlonDMS2(latlon, lon) if wrap else \
+                          parseDMS2(latlon, lon)  # clipped
+        d = datum or _WGS84
+    return lat, lon, d, _name__(name, _or_nameof=latlon)
+
+
 def _toMgrs(utmups):
     '''(INTERNAL) Convert a L{Utm} or L{Ups} to an L{Mgrs} instance.
     '''
     return _MODS.mgrs.toMgrs(utmups, datum=utmups.datum, name=utmups.name)
 
 
+def _to3zBhp(zone, band, hemipole=NN, Error=_ValueError):  # in .epsg, .ups, .utm, .utmups
+    '''Parse UTM/UPS zone, Band letter and hemisphere/pole letter.
+
+       @arg zone: Zone with/-out Band (C{scalar} or C{str}).
+       @kwarg band: Optional I{longitudinal/polar} Band letter (C{str}).
+       @kwarg hemipole: Optional hemisphere/pole letter (C{str}).
+       @kwarg Error: Optional error to raise, overriding the default
+                     C{ValueError}.
+
+       @return: 3-Tuple (C{zone, Band, hemisphere/pole}) as (C{int, str,
+                'N'|'S'}) where C{zone} is C{0} for UPS or C{1..60} for
+                UTM and C{Band} is C{'A'..'Z'} I{NOT} checked for valid
+                UTM/UPS bands.
+
+       @raise ValueError: Invalid B{C{zone}}, B{C{band}} or B{C{hemipole}}.
+    '''
+    try:
+        B, z = band, _UTMUPS_ZONE_INVALID
+        if isscalar(zone):
+            z = int(zone)
+        elif zone and isstr(zone):
+            if zone.isdigit():
+                z = int(zone)
+            elif len(zone) > 1:
+                B = zone[-1:]
+                z = int(zone[:-1])
+            elif zone.upper() in _UPS_BANDS:  # single letter
+                B =  zone
+                z = _UPS_ZONE
+
+        if _UTMUPS_ZONE_MIN <= z <= _UTMUPS_ZONE_MAX:
+            hp = hemipole[:1].upper()
+            if hp in _NS_ or not hp:
+                z = Zone(z)
+                B = Band(B.upper())
+                if B.isalpha():
+                    return z, B, (hp or _hemi(B, _N_))
+                elif not B:
+                    return z, B, hp
+
+        raise ValueError  # _invalid_
+    except (AttributeError, IndexError, TypeError, ValueError) as x:
+        raise Error(zone=zone, band=B, hemipole=hemipole, cause=x)
+
+
+def _to3zll(lat, lon):  # in .ups, .utm
+    '''Wrap lat- and longitude and determine UTM zone.
+
+       @arg lat: Latitude (C{degrees}).
+       @arg lon: Longitude (C{degrees}).
+
+       @return: 3-Tuple (C{zone, lat, lon}) as (C{int}, C{degrees90},
+                C{degrees180}) where C{zone} is C{1..60} for UTM.
+    '''
+    x = wrap360(lon + _180_0)  # use wrap360 to get ...
+    z = int(x) // 6 + 1  # ... longitudinal UTM zone [1, 60] and ...
+    return Zone(z), lat, (x - _180_0)  # ... -180 <= lon < 180
+
+
 __all__ += _ALL_DOCS(UtmUpsBase)
 
 # **) MIT License

pygeodesy/webmercator.py

@@ -22,11 +22,11 @@ from pygeodesy.basics import _splituple, _xinstanceof
 from pygeodesy.constants import PI_2, R_MA, _2_0
 from pygeodesy.datums import Datum, _spherical_datum
 from pygeodesy.dms import clipDegrees, parseDMS2
-from pygeodesy.errors import _parseX, _ValueError, _xattr, _xkwds
+from pygeodesy.errors import _parseX, _ValueError, _xattr, _xkwds, _xkwds_pop2
 from pygeodesy.interns import NN, _COMMASPACE_, _datum_, _earth_, _easting_, \
                              _northing_, _radius_, _SPACE_, _x_, _y_
 # from pygeodesy.lazily import _ALL_LAZY  from .named
-from pygeodesy.named import _NamedBase, _NamedTuple,  _ALL_LAZY
+from pygeodesy.named import _name2__, _NamedBase, _NamedTuple,  _ALL_LAZY
 from pygeodesy.namedTuples import LatLon2Tuple, LatLonDatum3Tuple, PhiLam2Tuple
 from pygeodesy.props import deprecated_method, Property_RO
 from pygeodesy.streprs import Fmt, strs, _xzipairs
@@ -36,7 +36,7 @@ from pygeodesy.utily import degrees90, degrees180
 from math import atan, atanh, exp, radians, sin, tanh
 
 __all__ = _ALL_LAZY.webmercator
-__version__ = '24.02.04'
+__version__ = '24.05.31'
 
 # _FalseEasting  = 0   # false Easting (C{meter})
 # _FalseNorthing = 0   # false Northing (C{meter})
@@ -66,32 +66,30 @@ class Wm(_NamedBase):
     _x      = 0     # Easting (C{meter})
     _y      = 0     # Northing (C{meter})
 
-    def __init__(self, x, y, earth=R_MA, name=NN, **radius):
+    def __init__(self, x, y, earth=R_MA, **name_radius):
         '''New L{Wm} Web Mercator (WM) coordinate.
 
            @arg x: Easting from central meridian (C{meter}).
            @arg y: Northing from equator (C{meter}).
-           @kwarg earth: Earth radius (C{meter}), datum or
-                         ellipsoid (L{Datum}, L{a_f2Tuple},
-                         L{Ellipsoid} or L{Ellipsoid2}).
-           @kwarg name: Optional name (C{str}).
-           @kwarg radius: DEPRECATED, use keyword argument B{C{earth}}.
+           @kwarg earth: Earth radius (C{meter}), datum or ellipsoid (L{Datum},
+                         L{a_f2Tuple}, L{Ellipsoid} or L{Ellipsoid2}).
+           @kwarg name_radius: Optional C{B{name}=NN} (C{str}) and DEPRECATED
+                       keyword argument C{B{radius}=earth}, use B{C{earth}}.
 
-           @note: WM is strictly defined for spherical and WGS84
-                  ellipsoidal earth models only.
+           @note: WM is strictly defined for spherical and WGS84 ellipsoidal
+                  earth models only.
 
            @raise WebMercatorError: Invalid B{C{x}}, B{C{y}} or B{C{radius}}.
         '''
         self._x = Easting( x=x, Error=WebMercatorError)
         self._y = Northing(y=y, Error=WebMercatorError)
 
-        R = radius.get(_radius_, earth)
-        if R not in Wm._earths:
-            self._datum = _datum(R, _radius_ if radius else _earth_)
-            self._radius = self.datum.ellipsoid.a
-
+        R, name = _xkwds_pop2(name_radius, radius=earth)
         if name:
             self.name = name
+        if R not in Wm._earths:
+            self._datum = _datum(R, _radius_ if _radius_ in name_radius else _earth_)
+            self._radius = self.datum.ellipsoid.a
 
     @Property_RO
     def datum(self):
@@ -143,20 +141,18 @@ class Wm(_NamedBase):
 
         return LatLon2Tuple(degrees90(y), degrees180(x), name=self.name)
 
-    def parse(self, strWM, name=NN):
+    def parse(self, strWM, **name):
         '''Parse a string to a similar L{Wm} instance.
 
-           @arg strWM: The WM coordinate (C{str}), see
-                       function L{parseWM}.
-           @kwarg name: Optional instance name (C{str}),
-                        overriding this name.
+           @arg strWM: The WM coordinate (C{str}), see function L{parseWM}.
+           @kwarg name: Optional C{B{name}=NN} (C{str}), overriding this name.
 
            @return: The similar instance (L{Wm}).
 
            @raise WebMercatorError: Invalid B{C{strWM}}.
         '''
         return parseWM(strWM, radius=self.radius, Wm=self.classof,
-                              name=name or self.name)
+                                name=self._name__(name))
 
     @deprecated_method
     def parseWM(self, strWM, name=NN):  # PYCHOK no cover
@@ -189,16 +185,14 @@ class Wm(_NamedBase):
            @kwarg LatLon: Ellipsoidal or sphperical C{LatLon} class to
                           return the geodetic point (C{LatLon}) or C{None}.
            @kwarg datum: Optional, datum (C{Datum}) overriding this WM's.
-           @kwarg LatLon_kwds: Optional, additional B{C{LatLon}}
-                               keyword arguments, ignored if
-                               C{B{LatLon} is None}.
+           @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword
+                               arguments, ignored if C{B{LatLon} is None}.
 
-           @return: This WM coordinate as B{C{LatLon}} or if
-                    C{B{LatLon} is None} a L{LatLonDatum3Tuple}.
+           @return: This WM coordinate as B{C{LatLon}} or if C{B{LatLon}
+                    is None} a L{LatLonDatum3Tuple}.
 
-           @raise TypeError: If B{C{LatLon}} and B{C{datum}} are
-                             incompatible or if B{C{datum}} is
-                             invalid.
+           @raise TypeError: If B{C{datum}} is invalid or if B{C{LatLon}}
+                             and B{C{datum}} are incompatible.
         '''
         d = datum or self.datum
         _xinstanceof(Datum, datum=d)
@@ -278,7 +272,7 @@ def _datum(earth, name=_datum_):
         raise WebMercatorError(name, earth, cause=x)
 
 
-def parseWM(strWM, radius=R_MA, Wm=Wm, name=NN):
+def parseWM(strWM, radius=R_MA, Wm=Wm, **name):
     '''Parse a string C{"e n [r]"} representing a WM coordinate,
        consisting of easting, northing and an optional radius.
 
@@ -287,11 +281,10 @@ def parseWM(strWM, radius=R_MA, Wm=Wm, name=NN):
                       case B{C{strWM}} doesn't include C{r}.
        @kwarg Wm: Optional class to return the WM coordinate (L{Wm})
                   or C{None}.
-       @kwarg name: Optional name (C{str}).
+       @kwarg name: Optional C{B{name}=NN} (C{str}).
 
-       @return: The WM coordinate (B{C{Wm}}) or an
-                L{EasNorRadius3Tuple}C{(easting, northing, radius)}
-                if B{C{Wm}} is C{None}.
+       @return: The WM coordinate (B{C{Wm}}) or if B{C{Wm}} is C{None}
+                an L{EasNorRadius3Tuple}C{(easting, northing, radius)}.
 
        @raise WebMercatorError: Invalid B{C{strWM}}.
     '''
@@ -304,14 +297,14 @@ def parseWM(strWM, radius=R_MA, Wm=Wm, name=NN):
             raise ValueError
         x, y, R = map(float, w)
 
-        return EasNorRadius3Tuple(x, y, R, name=name) if Wm is None else \
-                               Wm(x, y, earth=R, name=name)
+        return EasNorRadius3Tuple(x, y, R, **name) if Wm is None else \
+                               Wm(x, y, earth=R, **name)
 
     return _parseX(_WM, strWM, radius, Wm, name,
                         strWM=strWM, Error=WebMercatorError)
 
 
-def toWm(latlon, lon=None, earth=R_MA, Wm=Wm, name=NN, **Wm_kwds):
+def toWm(latlon, lon=None, earth=R_MA, Wm=Wm, **name_Wm_kwds_radius):
     '''Convert a lat-/longitude point to a WM coordinate.
 
        @arg latlon: Latitude (C{degrees}) or an (ellipsoidal or
@@ -323,31 +316,30 @@ def toWm(latlon, lon=None, earth=R_MA, Wm=Wm, name=NN, **Wm_kwds):
                      datum if present.
        @kwarg Wm: Optional class to return the WM coordinate (L{Wm})
                   or C{None}.
-       @kwarg name: Optional name (C{str}).
-       @kwarg Wm_kwds: Optional, additional B{C{Wm}} keyword arguments,
-                       ignored if C{B{Wm} is None}.
+       @kwarg name_Wm_kwds_radius: Optional C{B{name}=NN} (C{str}),
+                   optional, additional B{C{Wm}} keyword arguments,
+                   ignored if C{B{Wm} is None} and DEPRECATED keyword
+                   argument C{B{radius}=earth}, use B{C{earth}}.
 
-       @return: The WM coordinate (B{C{Wm}}) or if B{C{Wm}} is C{None}
-                an L{EasNorRadius3Tuple}C{(easting, northing, radius)}.
+       @return: The WM coordinate (B{C{Wm}}) or if B{C{Wm}} is C{None} an
+                L{EasNorRadius3Tuple}C{(easting, northing, radius)}.
 
        @raise ValueError: If B{C{lon}} value is missing, if B{C{latlon}} is not
                           scalar, if B{C{latlon}} is beyond the valid WM range
                           and L{pygeodesy.rangerrors} is set to C{True} or if
                           B{C{earth}} is invalid.
     '''
-    if _radius_ in Wm_kwds:  # remove DEPRECATED, radius
-        d = _datum(Wm_kwds.pop(_radius_), _radius_)
-    else:
-        d = _datum(earth, _earth_)
+    name, kwds = _name2__(name_Wm_kwds_radius)
+    R, kwds = _xkwds_pop2(kwds, radius=earth)
+    d = _datum(R, _radius_ if _radius_ in name_Wm_kwds_radius else _earth_)
     try:
         y, x = latlon.lat, latlon.lon
         y =  clipDegrees(y, _LatLimit)
         d = _xattr(latlon, datum=d)
-        n =  name or _xattr(latlon, name=NN)
+        n =  latlon._name__(name)
     except AttributeError:
         y, x = parseDMS2(latlon, lon, clipLat=_LatLimit)
-        n = name
-
+        n =  name
     E = d.ellipsoid
     R = E.a
     s = sin(radians(y))
@@ -357,7 +349,7 @@ def toWm(latlon, lon=None, earth=R_MA, Wm=Wm, name=NN, **Wm_kwds):
     y *= R
     x  = R * radians(x)
     r  = EasNorRadius3Tuple(x, y, R, name=n) if Wm is None else \
-                         Wm(x, y, **_xkwds(Wm_kwds, earth=d, name=n))
+                         Wm(x, y, **_xkwds(kwds, earth=d, name=n))
     return r
 
 # **) MIT License