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

pygeodesy/utmups.py

@@ -16,7 +16,7 @@ by I{Charles Karney}.
 '''
 # from pygeodesy.basics import map1  # from .namedTuples
 # from pygeodesy.datums import _WGS84  # from .utmupsBase
-from pygeodesy.errors import _IsnotError, RangeError, _ValueError, _xkwds_get
+from pygeodesy.errors import _IsnotError, RangeError, _ValueError, _xkwds_pop2
 from pygeodesy.interns import NN, _easting_, _MGRS_, _northing_, _NS_, \
                              _outside_, _range_, _SPACE_, _UPS_, _UTM_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS
@@ -31,7 +31,7 @@ from pygeodesy.utmupsBase import Fmt, _to4lldn, _to3zBhp, _UPS_ZONE, \
                                 _UTMUPS_ZONE_MAX, _WGS84
 
 __all__ = _ALL_LAZY.utmups
-__version__ = '23.05.03'
+__version__ = '24.05.30'
 
 _MGRS_TILE = _100km  # in .mgrs.Mgrs.tile
 
@@ -73,7 +73,7 @@ class UTMUPSError(_ValueError):  # XXX (UTMError, UPSError)
     pass
 
 
-def parseUTMUPS5(strUTMUPS, datum=_WGS84, Utm=Utm, Ups=Ups, name=NN):
+def parseUTMUPS5(strUTMUPS, datum=_WGS84, Utm=Utm, Ups=Ups, **name):
     '''Parse a string representing a UTM or UPS coordinate, consisting
        of C{"zone[band] hemisphere/pole easting northing"}.
 
@@ -83,13 +83,13 @@ def parseUTMUPS5(strUTMUPS, datum=_WGS84, Utm=Utm, Ups=Ups, name=NN):
                    or C{None}.
        @kwarg Ups: Optional class to return the UPS coordinate (L{Ups})
                    or C{None}.
-       @kwarg name: Optional instance name (C{str}).
+       @kwarg name: Optional B{C{Utm}} or B{C{Ups}} C{B{name}=NN} (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.
+       @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}}.
 
@@ -100,14 +100,13 @@ def parseUTMUPS5(strUTMUPS, datum=_WGS84, Utm=Utm, Ups=Ups, name=NN):
             u = parseUTM5(strUTMUPS, datum=datum, Utm=Utm, name=name)
         except UTMError:
             u = parseUPS5(strUTMUPS, datum=datum, Ups=Ups, name=name)
-        return u
-
     except (UTMError, UPSError) as x:
         raise UTMUPSError(strUTMUPS=strUTMUPS, cause=x)
+    return u
 
 
 def toUtmUps8(latlon, lon=None, datum=None, falsed=True, Utm=Utm, Ups=Ups,
-                                            pole=NN, name=NN, **cmoff):
+                                              pole=NN, **name_cmoff):
     '''Convert a lat-/longitude point to a UTM or UPS coordinate.
 
        @arg latlon: Latitude (C{degrees}) or an (ellipsoidal)
@@ -122,9 +121,10 @@ def toUtmUps8(latlon, lon=None, datum=None, falsed=True, Utm=Utm, Ups=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}).
+       @kwarg name_cmoff: Optional B{C{Utm}} or B{C{Ups}} C{B{name}=NN}
+                   (C{str}) and DEPRECATED keyword argument C{B{cmoff}=True}
+                   to offset the longitude from the zone's central meridian
+                   (C{bool}), use B{C{falsed}} instead and I{for UTM only}.
 
        @return: The UTM or UPS coordinate (B{C{Utm}} respectively B{C{Ups}})
                 or a L{UtmUps8Tuple}C{(zone, hemipole, easting, northing,
@@ -144,19 +144,18 @@ def toUtmUps8(latlon, lon=None, datum=None, falsed=True, Utm=Utm, Ups=Ups,
 
        @see: Functions L{pygeodesy.toUtm8} and L{pygeodesy.toUps8}.
     '''
-    lat, lon, d, name = _to4lldn(latlon, lon, datum, name)
-    z, B, p, lat, lon = utmupsZoneBand5(lat, lon)
-
-    f = falsed and _xkwds_get(cmoff, cmoff=True)
+    f, name = _xkwds_pop2(name_cmoff, cmoff=falsed)
+    lat, lon, d, n = _to4lldn(latlon, lon, datum, name)
+    z, _, p, lat, lon = utmupsZoneBand5(lat, lon)
     if z == _UPS_ZONE:
-        u = toUps8(lat, lon, datum=d, falsed=f, Ups=Ups, name=name, pole=pole or p)
+        u = toUps8(lat, lon, datum=d, falsed=f, Ups=Ups, name=n, pole=pole or p)
     else:
-        u = toUtm8(lat, lon, datum=d, falsed=f, Utm=Utm, name=name)
+        u = toUtm8(lat, lon, datum=d, falsed=f, Utm=Utm, name=n)
     return u
 
 
 def UtmUps(zone, hemipole, easting, northing, band=NN, datum=_WGS84,
-                                              falsed=True, name=NN):
+                                              falsed=True, **name):
     '''Class-like function to create a UTM/UPS coordinate.
 
        @kwarg zone: The UTM zone with/-out I{longitudinal} Band or UPS zone C{0}
@@ -167,9 +166,10 @@ def UtmUps(zone, hemipole, easting, northing, band=NN, datum=_WGS84,
        @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}).
+       @kwarg datum: The coordinate's datum (L{Datum}).
+       @kwarg falsed: If C{True}, both B{C{easting}} and B{C{northing}} are
+                      falsed (C{bool}).
+       @kwarg name: Optional L{Utm} or L{Ups} C{B{name}=NN} (C{str}).
 
        @return: New UTM or UPS instance (L{Utm} or L{Ups}).
 
@@ -183,7 +183,7 @@ def UtmUps(zone, hemipole, easting, northing, band=NN, datum=_WGS84,
     z, B, hp = _to3zBhp(zone, band, hemipole=hemipole)
     U = Ups if z in (_UPS_ZONE, _UPS_ZONE_STR) else Utm
     return U(z, hp, easting, northing, band=B, datum=datum,
-                                       falsed=falsed, name=name)
+                                       falsed=falsed, **name)
 
 
 def utmupsValidate(coord, falsed=False, MGRS=False, Error=UTMUPSError):
@@ -253,10 +253,11 @@ def utmupsValidateOK(coord, falsed=False, ok=True):
     '''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 falsed: Use C{B{falsed}=True} if the 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.
+       @return: B{C{ok}} if validation passed, otherwise the L{UTMUPSError}.
 
        @see: Function L{utmupsValidate}.
     '''
@@ -267,20 +268,19 @@ def utmupsValidateOK(coord, falsed=False, ok=True):
         return x
 
 
-def utmupsZoneBand5(lat, lon, cmoff=False, name=NN):
+def utmupsZoneBand5(lat, lon, cmoff=False, **name):
     '''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}).
+       @kwarg cmoff: If C{True}, offset longitude from the zone's central
+                     meridian, I{for UTM only} (C{bool}).
+       @kwarg name: Optional C{B{name}=NN} (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.
+       @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
@@ -291,9 +291,9 @@ def utmupsZoneBand5(lat, lon, cmoff=False, name=NN):
        @see: Functions L{pygeodesy.utmZoneBand5} and L{pygeodesy.upsZoneBand5}.
     '''
     try:
-        return utmZoneBand5(lat, lon, cmoff=cmoff, name=name)
+        return utmZoneBand5(lat, lon, cmoff=cmoff, **name)
     except RangeError:
-        return upsZoneBand5(lat, lon, name=name)
+        return upsZoneBand5(lat, lon, **name)
 
 # **) MIT License
 #

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_, \
@@ -12,13 +12,13 @@ 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, _ValueError, \
-                             _xkwds, _xkwds_get, _xkwds_not
-# from pygeodesy.internals import _under  # from .named
+                             _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, nameof, _xnamed,  _under
+from pygeodesy.named import _NamedBase, _xnamed,  _name__, _under
 from pygeodesy.namedTuples import EasNor2Tuple, LatLonDatum5Tuple
 from pygeodesy.props import deprecated_method, property_doc_, _update_all, \
                             deprecated_property_RO, Property_RO, property_RO
@@ -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.13'
+__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 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,8 +97,6 @@ class UtmUpsBase(_NamedBase):
         if not falsed:
             self._falsed = False
 
-        if convergence:  # for backward compatibility
-            gamma = _xkwds_get(convergence, convergence=gamma)
         if gamma is not self._gamma:
             self._gamma = Scalar(gamma=gamma, Error=E)
         if scale is not self._scale:
@@ -207,7 +117,7 @@ class UtmUpsBase(_NamedBase):
 #               self._notOverloaded(callername=_under('Bands'))
             if band not in self._Bands:
                 t = _or(*sorted(set(map(repr, self._Bands))))
-                raise self._Error(band=band, txt=_not_(t))
+                raise self._Error(band=band, txt_not_=t)
             self._band = band
         elif self._band:  # reset
             self._band = NN
@@ -270,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
 
@@ -308,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:
@@ -416,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 \
@@ -437,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)
@@ -487,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/vector2d.py

@@ -30,7 +30,7 @@ from contextlib import contextmanager
 # from math import fabs, sqrt  # from .fmath
 
 __all__ = _ALL_LAZY.vector2d
-__version__ = '24.05.04'
+__version__ = '24.05.17'
 
 _cA_        = 'cA'
 _cB_        = 'cB'
@@ -282,11 +282,10 @@ def circum4_(*points, **useZ_Vector_and_kwds):
         C = map2(float, C)
         R = map2(float, R)  # empty if rk < 4 or n <= 4
 
-    n = circum4_.__name__
-    c = Vector3d(*C[:3], name=n)
-    r = Radius(sqrt(fsumf_(C[3], *c.x2y2z2)), name=n)
+    c = Vector3d(*C[:3], name__=circum4_)  # .__name__
+    r = Radius(sqrt(fsumf_(C[3], *c.x2y2z2)), name=c.name)
 
-    c = _nVc(c, **_xkwds(kwds, clas=ps[0].classof, name=n))
+    c = _nVc(c, **_xkwds(kwds, clas=ps[0].classof, name=c.name))
     return Circum4Tuple(r, c, rk, R)
 
 
@@ -416,8 +415,8 @@ class _numpy(object):  # see also .formy._idllmn6, .geodesicw._wargs, .latlonBas
                  <https://StackOverflow.com/questions/2992947>} and U{here
                  <https://StackOverflow.com/questions/5889142>}.
         '''
-        def _Error(txt=self.null_space2.__name__, **kwds):
-            return _AssertionError(txt=txt, **kwds)
+        def _Error(**kwds):
+            return _AssertionError(txt__=self.null_space2, **kwds)
 
         np = self.np
         A  = np.array(A)

pygeodesy/vector3d.py

@@ -14,11 +14,11 @@ from pygeodesy.errors import IntersectionError, _ValueError, VectorError, \
 from pygeodesy.fmath import euclid, fabs, fdot, hypot, sqrt,  fsum1_
 # from pygeodesy.fsums import fsum1_  # from .fmath
 # from pygeodesy.formy import _radical2  # in _intersects2 below
-from pygeodesy.interns import NN, _COMMA_, _concentric_, _intersection_, \
-                             _near_, _negative_, _no_, _too_
+from pygeodesy.interns import _COMMA_, _concentric_, _intersection_, \
+                              _near_, _negative_, _no_, _too_
 from pygeodesy.iters import PointsIter,  Fmt
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS
-from pygeodesy.named import _xnamed, _xotherError
+from pygeodesy.named import _name__, _name2__, _xnamed, _xotherError
 from pygeodesy.namedTuples import Intersection3Tuple, NearestOn2Tuple, \
                                   NearestOn6Tuple, Vector3Tuple  # Vector4Tuple
 # from pygeodesy.nvectorBase import _nsumOf  # _MODS
@@ -31,7 +31,7 @@ from pygeodesy.vector3dBase import Vector3dBase
 # from math import fabs, sqrt  # from .fmath
 
 __all__ = _ALL_LAZY.vector3d
-__version__ = '24.02.20'
+__version__ = '24.05.21'
 
 
 class Vector3d(Vector3dBase):
@@ -236,18 +236,18 @@ class Vector3d(Vector3dBase):
         '''
         return nearestOn6(self, points, closed=closed, useZ=useZ)  # Vector=self.classof
 
-    def parse(self, str3d, sep=_COMMA_, name=NN):
+    def parse(self, str3d, sep=_COMMA_, **name):
         '''Parse an C{"x, y, z"} string to a L{Vector3d} instance.
 
            @arg str3d: X, y and z string (C{str}), see function L{parse3d}.
            @kwarg sep: Optional separator (C{str}).
-           @kwarg name: Optional instance name (C{str}), overriding this name.
+           @kwarg name: Optional instance C{B{name}=NN} (C{str}), overriding this name.
 
            @return: The instance (L{Vector3d}).
 
            @raise VectorError: Invalid B{C{str3d}}.
         '''
-        return parse3d(str3d, sep=sep, Vector=self.classof, name=name or self.name)
+        return parse3d(str3d, sep=sep, Vector=self.classof, name=self._name__(name))
 
     def radii11(self, point2, point3):
         '''Return the radii of the C{Circum-}, C{In-}, I{Soddy} and C{Tangent}
@@ -677,16 +677,15 @@ def nearestOn(point, point1, point2, within=True, useZ=True, Vector=None, **Vect
     p1 = _otherV3d(useZ=useZ, point1=point1)
     p2 = _otherV3d(useZ=useZ, point2=point2)
 
-    n    =  nearestOn.__name__
     p, _ = _nearestOn2(p0, p1, p2, within=within)
     if Vector is not None:
-        p = Vector(p.x, p.y, **_xkwds(Vector_kwds, z=p.z, name=n))
+        p = Vector(p.x, p.y, **_xkwds(Vector_kwds, z=p.z, name__=nearestOn))
     elif p is p1:
         p = point1
     elif p is p2:
         p = point2
     else:  # ignore Vector_kwds
-        p = point.classof(p.x, p.y, _xkwds_get(Vector_kwds, z=p.z), name=n)
+        p = point.classof(p.x, p.y, _xkwds_get(Vector_kwds, z=p.z), name__=nearestOn)
     return p
 
 
@@ -765,8 +764,9 @@ def nearestOn6(point, points, closed=False, useZ=True, **Vector_and_kwds):  # ep
     return NearestOn6Tuple(v, sqrt(c2), f, j, s, e)
 
 
-def _nVc(v, clas=None, name=NN, Vector=None, **Vector_kwds):  # in .vector2d
+def _nVc(v, clas=None, Vector=None, **Vector_kwds_name):  # in .vector2d
     # return a named C{Vector} or C{clas} instance
+    name, Vector_kwds = _name2__(**Vector_kwds_name)
     if Vector is not None:
         v = Vector(v.x, v.y, v.z, **Vector_kwds)
     elif clas is not None:
@@ -810,7 +810,7 @@ def parse3d(str3d, sep=_COMMA_, Vector=Vector3d, **Vector_kwds):
     except (TypeError, ValueError) as x:
         raise VectorError(str3d=str3d, cause=x)
     return _xnamed((Vector3Tuple(v) if Vector is None else  # *v
-                    Vector(*v, **Vector_kwds)), parse3d.__name__)
+                    Vector(*v, **Vector_kwds)), name__=parse3d)  # .__name__
 
 
 def sumOf(vectors, Vector=Vector3d, **Vector_kwds):
@@ -831,9 +831,8 @@ def sumOf(vectors, Vector=Vector3d, **Vector_kwds):
     except (TypeError, ValueError) as x:
         raise VectorError(vectors=vectors, Vector=Vector, cause=x)
     x, y, z = t[:3]
-    n = sumOf.__name__
-    return Vector3Tuple(x, y, z, name=n) if Vector is None else \
-           Vector(x, y, z, **_xkwds(Vector_kwds, name=n))
+    return Vector3Tuple(x, y, z, name__=sumOf) if Vector is None else \
+           Vector(x, y, z, **_xkwds(Vector_kwds, name__=sumOf))  # .__name__
 
 
 def trilaterate2d2(x1, y1, radius1, x2, y2, radius2, x3, y3, radius3,
@@ -930,7 +929,7 @@ def trilaterate3d2(center1, radius1, center2, radius2, center3, radius3,
                          center3=center3, radius3=radius3)
 
 
-def _xyzhdn3(xyz, height, datum, ll):  # in .cartesianBase, .nvectorBase
+def _xyzhdn3(xyz, height, datum, ll, **name):  # in .cartesianBase, .nvectorBase
     '''(INTERNAL) Get a C{(h, d, name)} 3-tuple.
     '''
     h = height or _xattr(xyz, height=None) \
@@ -940,7 +939,7 @@ def _xyzhdn3(xyz, height, datum, ll):  # in .cartesianBase, .nvectorBase
     d = datum or _xattr(xyz, datum=None) \
               or _xattr(ll,  datum=None)
 
-    return h, d, _xattr(xyz, name=NN)
+    return h, d, _name__(name, _or_nameof=xyz)
 
 
 __all__ += _ALL_DOCS(intersections2, sumOf, Vector3dBase)

pygeodesy/vector3dBase.py

@@ -15,8 +15,7 @@ from pygeodesy.constants import EPS, EPS0, INT0, PI, PI2, _copysignINF, \
                                _pos_self, _0_0, _1_0
 from pygeodesy.errors import CrossError, VectorError, _xcallable, _xError
 from pygeodesy.fmath import euclid_, fdot, hypot_, hypot2_
-from pygeodesy.interns import NN, _coincident_, _colinear_, \
-                             _COMMASPACE_, _xyz_
+from pygeodesy.interns import _coincident_, _colinear_, _COMMASPACE_, _xyz_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_DOCS, _ALL_MODS as _MODS, \
                              _sys_version_info2
 from pygeodesy.named import _NamedBase, _NotImplemented, _xother3
@@ -31,7 +30,7 @@ from pygeodesy.units import Float, Scalar
 from math import atan2, ceil, fabs, floor, trunc
 
 __all__ = _ALL_LAZY.vector3dBase
-__version__ = '24.05.10'
+__version__ = '24.05.19'
 
 
 class Vector3dBase(_NamedBase):  # sync __methods__ with .fsums.Fsum
@@ -44,7 +43,7 @@ class Vector3dBase(_NamedBase):  # sync __methods__ with .fsums.Fsum
 #   _y  = INT0  # Y component
 #   _z  = INT0  # Z component
 
-    def __init__(self, x_xyz, y=INT0, z=INT0, ll=None, name=NN):
+    def __init__(self, x_xyz, y=INT0, z=INT0, ll=None, **name):
         '''New L{Vector3d} or C{Vector3dBase} instance.
 
            The vector may be normalised or use x, y, z for position and
@@ -60,7 +59,7 @@ class Vector3dBase(_NamedBase):  # sync __methods__ with .fsums.Fsum
            @kwarg z: Z component of vector (C{scalar}), ignored if B{C{x_xyz}}
                      is not C{scalar}, otherwise same units as B{C{x_xyz}}.
            @kwarg ll: Optional latlon reference (C{LatLon}).
-           @kwarg name: Optional name (C{str}).
+           @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @raise VectorError: Invalid B{C{x_xyz}}.
         '''