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

pygeodesy/utm.py

@@ -44,8 +44,7 @@ from pygeodesy.fmath import fdot3, hypot, hypot1,  _operator
 from pygeodesy.interns import MISSING, NN, _by_, _COMMASPACE_, _N_, \
                              _NS_, _outside_, _range_, _S_, _scale0_, \
                              _SPACE_, _UTM_, _V_, _X_, _zone_
-# from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS  # from .named
-from pygeodesy.named import _name__, _name2__,  _ALL_LAZY, _MODS
+from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS
 from pygeodesy.namedTuples import EasNor2Tuple, UtmUps5Tuple, \
                                   UtmUps8Tuple, UtmUpsLatLon5Tuple
 from pygeodesy.props import deprecated_method, property_doc_, \
@@ -64,7 +63,7 @@ from math import asinh, atanh, atan2, cos, cosh, degrees, fabs, \
 # import operator as _operator  # from .fmath
 
 __all__ = _ALL_LAZY.utm
-__version__ = '24.05.21'
+__version__ = '24.05.31'
 
 _Bands = 'CDEFGHJKLMNPQRSTUVWXX'  # UTM latitude bands C..X (no
 # I|O) 8° each, covering 80°S to 84°N and X repeated for 80-84°N
@@ -134,121 +133,6 @@ class _Kseries(object):
         return fdot3(self._pq, self._sy, self._shx, start=q0)
 
 
-def _cmlon(zone):
-    '''(INTERNAL) Central meridian longitude (C{degrees180}).
-    '''
-    return (zone * 6) - 183
-
-
-def _false2(e, n, h):
-    '''(INTERNAL) False easting and northing.
-    '''
-    # Karney, "Test data for the transverse Mercator projection (2009)"
-    # <https://GeographicLib.SourceForge.io/C++/doc/transversemercator.html>
-    # and <https://Zenodo.org/record/32470#.W4LEJS2ZON8>
-    e += _FalseEasting  # make e relative to central meridian
-    if h == _S_:
-        n += _FalseNorthing  # make n relative to equator
-    return e, n
-
-
-def _toBand(lat, *unused, **strict_Error):  # see ups._toBand
-    '''(INTERNAL) Get the I{latitudinal} Band (row) letter.
-    '''
-    if _UTM_LAT_MIN <= lat < _UTM_LAT_MAX:  # [-80, 84) like Veness
-        return _Bands[int(lat - _UTM_LAT_MIN) >> 3]
-    elif _xkwds_get(strict_Error, strict=True):
-        r = _range_(_UTM_LAT_MIN, _UTM_LAT_MAX, ropen=True)
-        t = _SPACE_(_outside_, _UTM_, _range_, r)
-        E = _xkwds_get(strict_Error, Error=RangeError)
-        raise E(lat=degDMS(lat), txt=t)
-    else:
-        return NN  # None
-
-
-def _to3zBlat(zone, band, Error=UTMError):  # in .mgrs
-    '''(INTERNAL) Check and return zone, Band and band latitude.
-
-       @arg zone: Zone number or string.
-       @arg band: Band letter.
-       @arg Error: Exception to raise (L{UTMError}).
-
-       @return: 3-Tuple (zone, Band, latitude).
-    '''
-    z, B, _ = _to3zBhp(zone, band, Error=Error)
-    if not (_UTM_ZONE_MIN <= z <= _UTM_ZONE_MAX or
-           (_UPS_ZONE == z and Error is MGRSError)):
-        raise Error(zone=zone)
-
-    b = None
-    if B:
-        if z == _UPS_ZONE:  # polar
-            try:
-                b = Lat(_UPS_LATS[B], name=_bandLat_)
-            except KeyError:
-                raise Error(band=band or B, zone=z)
-        else:  # UTM
-            b = _Bands.find(B)
-            if b < 0:
-                raise Error(band=band or B, zone=z)
-            b = Int((b << 3) - 80, name=_bandLat_)
-        B = Band(B)
-    elif Error is not UTMError:
-        raise Error(band=band, txt=MISSING)
-
-    return Zone(z), B, b
-
-
-def _to4zBll(lat, lon, cmoff=True, strict=True, Error=RangeError):
-    '''(INTERNAL) Return zone, Band and lat- and (central) longitude in degrees.
-
-       @arg lat: Latitude (C{degrees}).
-       @arg lon: Longitude (C{degrees}).
-       @kwarg cmoff: Offset B{C{lon}} from zone's central meridian.
-       @kwarg strict: Restrict B{C{lat}} to UTM ranges (C{bool}).
-       @kwarg Error: Error for out of UTM range B{C{lat}}s.
-
-       @return: 4-Tuple (zone, Band, lat, lon).
-    '''
-    z, lat, lon = _to3zll(lat, lon)  # in .utmupsBase
-
-    x = lon - _cmlon(z)  # z before Norway/Svalbard
-    if fabs(x) > _UTM_ZONE_OFF_MAX:
-        t = _SPACE_(_outside_, _UTM_, _zone_, str(z), _by_, degDMS(x, prec=6))
-        raise Error(lon=degDMS(lon), txt=t)
-
-    B = _toBand(lat, strict=strict, Error=Error)
-    if B == _X_:  # and 0 <= lon < 42: z = int(lon + 183) // 6 + 1
-        x = _SvalbardXzone.get(z, None)
-        if x:  # Svalbard/Spitsbergen archipelago
-            z += 1 if lon >= x else -1
-    elif B == _V_ and z == 31 and lon >= 3:
-        z += 1  # SouthWestern Norway
-
-    if cmoff:  # lon off central meridian
-        lon -= _cmlon(z)  # z after Norway/Svalbard
-    return Zone(z), (Band(B) if B else None), Lat(lat), Lon(lon)
-
-
-def _to7zBlldfn(latlon, lon, datum, falsed, zone, strict, Error, **name_cmoff):
-    '''(INTERNAL) Determine 7-tuple (zone, band, lat, lon, datum,
-        falsed, name) for methods L{toEtm8} and L{toUtm8}.
-    '''
-    f, n = _xkwds_pop2(name_cmoff, cmoff=falsed)  # DEPRECATED
-    n    = _name__(**n)  # _UnexpectedError
-    lat, lon, d, n = _to4lldn(latlon, lon, datum, n)
-    z, B, lat, lon = _to4zBll(lat, lon, cmoff=f, strict=strict)
-    if zone:  # re-zone for ETM/UTM
-        r, _, _ = _to3zBhp(zone, B)
-        if r != z:
-            if not _UTM_ZONE_MIN <= r <= _UTM_ZONE_MAX:
-                raise Error(zone=zone)
-            if f:  # re-offset from central meridian
-                lon += _cmlon(z) - _cmlon(r)
-            z = r
-    return z, B, lat, lon, d, f, n
-
-
 class Utm(UtmUpsBase):
     '''Universal Transverse Mercator (UTM) coordinate.
     '''
@@ -276,10 +160,10 @@ class Utm(UtmUpsBase):
            @kwarg falsed: If C{True}, both B{C{easting}} and B{C{northing}} are
                           falsed (C{bool}).
            @kwarg gamma: Optional meridian convergence, bearing off grid North,
-                         clockwise from true North (C{degrees}) or C{None}.
-           @kwarg scale: Optional grid scale factor (C{scalar}) or C{None}.
+                         clockwise from true North to save (C{degrees}) or C{None}.
+           @kwarg scale: Optional grid scale factor to save (C{scalar}) or C{None}.
            @kwarg name_convergence: Optional C{B{name}=NN} (C{str}) and DEPRECATED
-                       C{B{convergence}=None}, instead use C{B{gamma}=None}.
+                       keyword argument C{B{convergence}=None}, use B{C{gamma}}.
 
            @raise TypeError: Invalid or near-spherical B{C{datum}}.
 
@@ -287,17 +171,17 @@ class Utm(UtmUpsBase):
                             B{C{northing}}, B{C{band}}, B{C{convergence}} or
                             B{C{scale}}.
         '''
-        c = name_convergence
-        if c:
-            n, c = _name2__(**c)
-            if n:
-                self.name = n
+        if name_convergence:
+            gamma, name = _xkwds_pop2(name_convergence, convergence=gamma)
+            if name:
+                self.name = name
 
         self._zone, B, _ = _to3zBlat(zone, band)
 
         h = str(hemisphere)[:1].upper()
         if h not in _NS_:
             raise self._Error(hemisphere=hemisphere)
+        self._hemisphere = h
 
         e, n = easting, northing  # Easting(easting), ...
 #       if not falsed:
@@ -311,9 +195,8 @@ class Utm(UtmUpsBase):
 #       if 0 > n or n > _FalseNorthing:
 #           raise RangeError(northing=northing)
 
-        self._hemisphere = h
         UtmUpsBase.__init__(self, e, n, band=B, datum=datum, falsed=falsed,
-                                        gamma=gamma, scale=scale, **c)
+                                                gamma=gamma, scale=scale)
 
     def __eq__(self, other):
         return isinstance(other, Utm) and other.zone       == self.zone \
@@ -378,10 +261,8 @@ class Utm(UtmUpsBase):
     def parse(self, strUTM, **name):
         '''Parse a string to a similar L{Utm} instance.
 
-           @arg strUTM: The UTM coordinate (C{str}),
-                        see function L{parseUTM5}.
-           @kwarg name: Optional instance name (C{str}),
-                        overriding this name.
+           @arg strUTM: The UTM coordinate (C{str}), see function L{parseUTM5}.
+           @kwarg name: Optional instance name (C{str}), overriding this name.
 
            @return: The similar instance (L{Utm}).
 
@@ -483,11 +364,12 @@ class Utm(UtmUpsBase):
         # gamma and scale: Karney 2011 Eq 26, 27 and 28
         p = neg(K.ps(-1))
         q =     K.qs(0)
-        s = hypot(p, q) * E.a / A0
-        ll._gamma = degrees(atan1(tan(y) * tanh(x)) + atan2(q, p))
-        ll._scale = (E.e2s(sin(a)) * hypot1(T) * H / s) if s else s  # INF?
+        g = degrees(atan1(tan(y) * tanh(x)) + atan2(q, p))
+        k = hypot(p, q) * E.a / A0
+        if k:
+            k = E.e2s(sin(a)) * hypot1(T) * H / k  # INF?
         ll._iteration = i
-        self._latlon5args(ll, _toBand, unfalse, eps)
+        self._latlon5args(ll, g, k, _toBand, unfalse, eps)
 
     def toRepr(self, prec=0, fmt=Fmt.SQUARE, sep=_COMMASPACE_, B=False, cs=False, **unused):  # PYCHOK expected
         '''Return a string representation of this UTM coordinate.
@@ -540,12 +422,13 @@ class Utm(UtmUpsBase):
                         (C{str}, 'N[orth]'|'S[outh]').
            @kwarg eps: Optional convergence limit, L{EPS} or above
                        (C{float}), see method L{Utm.toLatLon}.
-           @kwarg falsed: False both easting and northing (C{bool}).
+           @kwarg falsed: If C{True}, false both easting and northing
+                          (C{bool}).
 
            @return: The UPS coordinate (L{Ups}).
         '''
         u = self._ups
-        if u is None or u.pole != (pole or u.pole) or falsed != bool(u.falsed):
+        if u is None or u.pole != (pole or u.pole) or bool(falsed) != u.falsed:
             ll  =  self.toLatLon(LatLon=_LLEB, eps=eps, unfalse=True)
             ups = _MODS.ups
             self._ups = u = ups.toUps8(ll, Ups=ups.Ups, falsed=falsed,
@@ -558,7 +441,8 @@ class Utm(UtmUpsBase):
            @arg zone: New UTM zone (C{int}).
            @kwarg eps: Optional convergence limit, L{EPS} or above
                        (C{float}), see method L{Utm.toLatLon}.
-           @kwarg falsed: False both easting and northing (C{bool}).
+           @kwarg falsed: If C{True}, fFalse both easting and northing
+                          (C{bool}).
 
            @return: The UTM coordinate (L{Utm}).
         '''
@@ -566,7 +450,7 @@ class Utm(UtmUpsBase):
             return self.copy()
         elif zone:
             u = self._utm
-            if u is None or u.zone != zone or falsed != u.falsed:
+            if u is None or u.zone != zone or bool(falsed) != u.falsed:
                 ll = self.toLatLon(LatLon=_LLEB, eps=eps, unfalse=True)
                 self._utm = u = toUtm8(ll, Utm=self.classof, falsed=falsed,
                                            name=self.name, zone=zone)
@@ -580,6 +464,24 @@ class Utm(UtmUpsBase):
         return self._zone
 
 
+def _cmlon(zone):
+    '''(INTERNAL) Central meridian longitude (C{degrees180}).
+    '''
+    return (zone * 6) - 183
+
+
+def _false2(e, n, h):
+    '''(INTERNAL) False easting and northing.
+    '''
+    # Karney, "Test data for the transverse Mercator projection (2009)"
+    # <https://GeographicLib.SourceForge.io/C++/doc/transversemercator.html>
+    # and <https://Zenodo.org/record/32470#.W4LEJS2ZON8>
+    e += _FalseEasting  # make e relative to central meridian
+    if h == _S_:
+        n += _FalseNorthing  # make n relative to equator
+    return e, n
+
+
 def _parseUTM5(strUTM, datum, Xtm, falsed, Error=UTMError, **name):  # imported by .etm
     '''(INTERNAL) Parse a string representing a UTM coordinate,
        consisting of C{"zone[band] hemisphere easting northing"},
@@ -590,7 +492,7 @@ def _parseUTM5(strUTM, datum, Xtm, falsed, Error=UTMError, **name):  # imported
         raise Error(strUTM=strUTM, zone=z, band=B)
 
     return UtmUps5Tuple(z, h, e, n, B, Error=Error, **name) if Xtm is None else \
-                    Xtm(z, h, e, n, band=B, datum=datum, falsed=falsed, **name)
+                    Xtm(z, h, e, n, band=B, datum=datum, falsed=bool(falsed), **name)
 
 
 def parseUTM5(strUTM, datum=_WGS84, Utm=Utm, falsed=True, **name):
@@ -602,8 +504,9 @@ def parseUTM5(strUTM, datum=_WGS84, Utm=Utm, falsed=True, **name):
                      L{Ellipsoid2} or L{a_f2Tuple}).
        @kwarg Utm: Optional class to return the UTM coordinate
                    (L{Utm}) or C{None}.
-       @kwarg falsed: Both easting and northing are falsed (C{bool}).
-       @kwarg name: Optional B{C{Utm}} name (C{str}).
+       @kwarg falsed: Use C{B{falsed}=True} if both easting and
+                      northing are falsed (C{bool}).
+       @kwarg name: Optional B{C{Utm}} C{B{name}=NN} (C{str}).
 
        @return: The UTM coordinate (B{C{Utm}}) or if B{C{Utm}}
                 is C{None}, a L{UtmUps5Tuple}C{(zone, hemipole,
@@ -633,10 +536,10 @@ def toUtm8(latlon, lon=None, datum=None, Utm=Utm, falsed=True,
        @kwarg falsed: False both easting and northing (C{bool}).
        @kwarg strict: Restrict B{C{lat}} to UTM ranges (C{bool}).
        @kwarg zone: Optional UTM zone to enforce (C{int} or C{str}).
-       @kwarg name_cmoff: Optional B{C{Utm}} C{B{name}=NN} (C{str})
-                   and DEPRECATED C{B{cmoff}=True} to offset longitude
-                   from the zone's central meridian (C{bool}), instead
-                   use C{B{falsed}=True}.
+       @kwarg name_cmoff: Optional B{C{Utm}} C{B{name}=NN} (C{str}) and
+                   DEPRECATED C{B{cmoff}=True} to offset the longitude
+                   from the zone's central meridian (C{bool}), use
+                   C{B{falsed}} instead.
 
        @return: The UTM coordinate (B{C{Utm}}) or if B{C{Utm}} is
                 C{None} or not B{C{falsed}}, a L{UtmUps8Tuple}C{(zone,
@@ -695,8 +598,22 @@ def toUtm8(latlon, lon=None, datum=None, Utm=Utm, falsed=True,
                         B, d, g, k, f, n, latlon, EPS)
 
 
+def _toBand(lat, *unused, **strict_Error):  # see ups._toBand
+    '''(INTERNAL) Get the I{latitudinal} Band (row) letter.
+    '''
+    if _UTM_LAT_MIN <= lat < _UTM_LAT_MAX:  # [-80, 84) like Veness
+        return _Bands[int(lat - _UTM_LAT_MIN) >> 3]
+    elif _xkwds_get(strict_Error, strict=True):
+        r = _range_(_UTM_LAT_MIN, _UTM_LAT_MAX, ropen=True)
+        t = _SPACE_(_outside_, _UTM_, _range_, r)
+        E = _xkwds_get(strict_Error, Error=RangeError)
+        raise E(lat=degDMS(lat), txt=t)
+    else:
+        return NN  # None
+
+
 def _toXtm8(Xtm, z, lat, x, y, B, d, g, k, f,  # PYCHOK 13+ args
-                 n, latlon, eps, Error=UTMError):
+                 n, latlon, eps_other, Error=UTMError):
     '''(INTERNAL) Helper for methods L{toEtm8} and L{toUtm8}.
     '''
     h = _hemi(lat)
@@ -708,27 +625,106 @@ def _toXtm8(Xtm, z, lat, x, y, B, d, g, k, f,  # PYCHOK 13+ args
         r = Xtm(z, h, x, y, band=B, datum=d, falsed=f,
                                     gamma=g, scale=k, name=n)
         if isinstance(latlon, _LLEB) and d is latlon.datum:  # see ups.toUtm8
-            r._latlon5args(latlon, _toBand, f, eps)  # XXX weakref(latlon)?
-            latlon._gamma = g
-            latlon._scale = k
+            r._latlon5args(latlon, g, k, _toBand, f, eps_other)  # XXX weakref(latlon)?
         elif not r._band:
             r._band = _toBand(lat)
     return r
 
 
+def _to3zBlat(zone, band, Error=UTMError):  # in .mgrs
+    '''(INTERNAL) Check and return zone, Band and band latitude.
+
+       @arg zone: Zone number or string.
+       @arg band: Band letter.
+       @arg Error: Exception to raise (L{UTMError}).
+
+       @return: 3-Tuple (zone, Band, latitude).
+    '''
+    z, B, _ = _to3zBhp(zone, band, Error=Error)
+    if not (_UTM_ZONE_MIN <= z <= _UTM_ZONE_MAX or
+           (_UPS_ZONE == z and Error is MGRSError)):
+        raise Error(zone=zone)
+
+    b = None
+    if B:
+        if z == _UPS_ZONE:  # polar
+            try:
+                b = Lat(_UPS_LATS[B], name=_bandLat_)
+            except KeyError:
+                raise Error(band=band or B, zone=z)
+        else:  # UTM
+            b = _Bands.find(B)
+            if b < 0:
+                raise Error(band=band or B, zone=z)
+            b = Int((b << 3) - 80, name=_bandLat_)
+        B = Band(B)
+    elif Error is not UTMError:
+        raise Error(band=band, txt=MISSING)
+
+    return Zone(z), B, b
+
+
+def _to4zBll(lat, lon, cmoff=True, strict=True, Error=RangeError):
+    '''(INTERNAL) Return zone, Band and lat- and (central) longitude in degrees.
+
+       @arg lat: Latitude (C{degrees}).
+       @arg lon: Longitude (C{degrees}).
+       @kwarg cmoff: If C{True}, offset B{C{lon}} from the zone's central meridian.
+       @kwarg strict: Restrict B{C{lat}} to the UTM ranges (C{bool}).
+       @kwarg Error: Error for out of UTM range B{C{lat}}s.
+
+       @return: 4-Tuple (zone, Band, lat, lon).
+    '''
+    z, lat, lon = _to3zll(lat, lon)  # in .utmupsBase
+
+    x = lon - _cmlon(z)  # z before Norway/Svalbard
+    if fabs(x) > _UTM_ZONE_OFF_MAX:
+        t = _SPACE_(_outside_, _UTM_, _zone_, str(z), _by_, degDMS(x, prec=6))
+        raise Error(lon=degDMS(lon), txt=t)
+
+    B = _toBand(lat, strict=strict, Error=Error)
+    if B == _X_:  # and 0 <= lon < 42: z = int(lon + 183) // 6 + 1
+        x = _SvalbardXzone.get(z, None)
+        if x:  # Svalbard/Spitsbergen archipelago
+            z += 1 if lon >= x else -1
+    elif B == _V_ and z == 31 and lon >= 3:
+        z += 1  # SouthWestern Norway
+
+    if cmoff:  # lon off central meridian
+        lon -= _cmlon(z)  # z I{after} Norway/Svalbard
+    return Zone(z), (Band(B) if B else None), Lat(lat), Lon(lon)
+
+
+def _to7zBlldfn(latlon, lon, datum, falsed, zone, strict, Error, **name_cmoff):
+    '''(INTERNAL) Determine 7-tuple (zone, band, lat, lon, datum,
+        falsed, name) for methods L{toEtm8} and L{toUtm8}.
+    '''
+    f, name = _xkwds_pop2(name_cmoff, cmoff=falsed)  # DEPRECATED
+    lat, lon, d, n = _to4lldn(latlon, lon, datum, name)
+    z, B, lat, lon = _to4zBll(lat, lon, cmoff=f, strict=strict)
+    if zone:  # re-zone for ETM/UTM
+        r, _, _ = _to3zBhp(zone, B)
+        if r != z:
+            if not _UTM_ZONE_MIN <= r <= _UTM_ZONE_MAX:
+                raise Error(zone=zone)
+            if f:  # re-offset from central meridian
+                lon += _cmlon(z) - _cmlon(r)
+            z = r
+    return z, B, lat, lon, d, f, n
+
+
 def utmZoneBand5(lat, lon, cmoff=False, **name):
     '''Return the UTM zone number, Band letter, hemisphere 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
+       @kwarg cmoff: If C{True}, offset longitude from the zone's central
                      meridian (C{bool}).
-       @kwarg name: Optional name (C{str}).
+       @kwarg name: Optional C{B{name}=NN} (C{str}).
 
-       @return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole,
-                lat, lon)} where C{hemipole} is the C{'N'|'S'}
-                UTM hemisphere.
+       @return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole, lat, lon)}
+                where C{hemipole} is the C{'N'|'S'} UTM hemisphere.
 
        @raise RangeError: If B{C{lat}} outside the valid UTM bands or if
                           B{C{lat}} or B{C{lon}} outside the valid range

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
 #