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

pygeodesy/sphericalBase.py

@@ -21,18 +21,18 @@ from pygeodesy.datums import Datums, _earth_ellipsoid, _spherical_datum
 from pygeodesy.errors import IntersectionError, _ValueError, \
                             _xattr, _xError
 from pygeodesy.fmath import favg, fdot, hypot, sqrt_a
-from pygeodesy.interns import NN, _COMMA_, _concentric_, _datum_, \
-                             _distant_, _exceed_PI_radians_, _name_, \
-                             _near_, _radius_, _too_
+from pygeodesy.interns import _COMMA_, _concentric_, _datum_, _distant_, \
+                              _exceed_PI_radians_, _name_, _near_, \
+                              _radius_, _too_
 from pygeodesy.latlonBase import LatLonBase,  _trilaterate5  # PYCHOK passed
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS
 # from pygeodesy.namedTuples import Bearing2Tuple  # from .cartesianBase
 from pygeodesy.nvectorBase import NvectorBase,  Fmt, _xattrs
-from pygeodesy.props import deprecated_method, property_doc_, \
-                            property_RO, _update_all
+from pygeodesy.props import deprecated_method, property_doc_, property_RO, \
+                           _update_all
 # from pygeodesy.streprs import Fmt, _xattrs  # from .nvectorBase
-from pygeodesy.units import _isRadius, Bearing, Bearing_, Radians_, \
-                             Radius, Radius_, Scalar_, _100km
+from pygeodesy.units import Bearing, Bearing_, _isRadius, Radians_, Radius, \
+                            Radius_, Scalar_, _100km
 from pygeodesy.utily import acos1, asin1, atan2b, atan2d, degrees90, \
                             degrees180, sincos2, sincos2d, _unrollon, \
                             tanPI_2_2, wrapPI
@@ -40,7 +40,7 @@ from pygeodesy.utily import acos1, asin1, atan2b, atan2d, degrees90, \
 from math import cos, fabs, log, sin, sqrt
 
 __all__ = _ALL_LAZY.sphericalBase
-__version__ = '23.12.18'
+__version__ = '24.05.31'
 
 
 class CartesianSphericalBase(CartesianBase):
@@ -117,7 +117,7 @@ class LatLonSphericalBase(LatLonBase):
     _datum       =  Datums.Sphere  # spherical L{Datum}
     _napieradius = _100km
 
-    def __init__(self, latlonh, lon=None, height=0, datum=None, wrap=False, name=NN):
+    def __init__(self, latlonh, lon=None, height=0, datum=None, wrap=False, **name):
         '''Create a spherical C{LatLon} point frome the given lat-, longitude and
            height on the given datum.
 
@@ -132,12 +132,12 @@ class LatLonSphericalBase(LatLonBase):
                          conventionally).
            @kwarg wrap: If C{True}, wrap or I{normalize} B{C{lat}} and B{C{lon}}
                         (C{bool}).
-           @kwarg name: Optional name (C{str}).
+           @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @raise TypeError: If B{C{latlonh}} is not a C{LatLon} or B{C{datum}} not
                              spherical.
         '''
-        LatLonBase.__init__(self, latlonh, lon=lon, height=height, wrap=wrap, name=name)
+        LatLonBase.__init__(self, latlonh, lon=lon, height=height, wrap=wrap, **name)
         if datum not in (None, self.datum):
             self.datum = datum
 
@@ -302,26 +302,22 @@ class LatLonSphericalBase(LatLonBase):
 #           raise _xError(x, this=self, point=point, other=other, **radius_exact_height_wrap)
 #       return p.midpointTo(q)
 
-    def parse(self, strllh, height=0, sep=_COMMA_, name=NN):
+    def parse(self, strllh, height=0, sep=_COMMA_, **name):
         '''Parse a string representing a similar, spherical C{LatLon}
            point, consisting of C{"lat, lon[, height]"}.
 
-           @arg strllh: Lat, lon and optional height (C{str}),
-                        see function L{pygeodesy.parse3llh}.
+           @arg strllh: Lat, lon and optional height (C{str}), see function
+                        L{pygeodesy.parse3llh}.
            @kwarg height: Optional, default height (C{meter}).
            @kwarg sep: Optional separator (C{str}).
-           @kwarg name: Optional instance name (C{str}),
-                        overriding this name.
+           @kwarg name: Optional C{B{name}=NN} (C{str}), overriding this name.
 
            @return: The similar point (spherical C{LatLon}).
 
            @raise ParseError: Invalid B{C{strllh}}.
         '''
-        t = _MODS.dms.parse3llh(strllh, height=height, sep=sep)
-        r =  self.classof(*t)
-        if name:
-            r.rename(name)
-        return r
+        llh = _MODS.dms.parse3llh(strllh, height=height, sep=sep)
+        return self.classof(*llh, **name)
 
     @property_RO
     def _radius(self):

pygeodesy/sphericalTrigonometry.py

@@ -54,7 +54,7 @@ from pygeodesy.vector3d import sumOf, Vector3d
 from math import asin, atan2, cos, degrees, fabs, radians, sin
 
 __all__ = _ALL_LAZY.sphericalTrigonometry
-__version__ = '24.045.19'
+__version__ = '24.05.25'
 
 _PI_EPS4 = PI - EPS4
 if _PI_EPS4 >= PI:
@@ -538,7 +538,7 @@ class LatLon(LatLonSphericalBase):
     def nearestOn(self, point1, point2, radius=R_M, **wrap_adjust_limit):
         '''Locate the point between two points closest to this point.
 
-           Distances are approximated by function L{pygeodesy.equirectangular_},
+           Distances are approximated by function L{pygeodesy.equirectangular4},
            subject to the supplied B{C{options}}.
 
            @arg point1: Start point (L{LatLon}).
@@ -546,12 +546,12 @@ class LatLon(LatLonSphericalBase):
            @kwarg radius: Mean earth radius (C{meter}).
            @kwarg wrap_adjust_limit: Optional keyword arguments for functions
                               L{sphericalTrigonometry.nearestOn3} and
-                              L{pygeodesy.equirectangular_},
+                              L{pygeodesy.equirectangular4},
 
            @return: Closest point on the great circle line (L{LatLon}).
 
            @raise LimitError: Lat- and/or longitudinal delta exceeds B{C{limit}},
-                              see function L{pygeodesy.equirectangular_}.
+                              see function L{pygeodesy.equirectangular4}.
 
            @raise NotImplementedError: Keyword argument C{B{within}=False}
                                        is not (yet) supported.
@@ -560,7 +560,7 @@ class LatLon(LatLonSphericalBase):
 
            @raise ValueError: Invalid B{C{radius}} or B{C{options}}.
 
-           @see: Functions L{pygeodesy.equirectangular_} and L{pygeodesy.nearestOn5}
+           @see: Functions L{pygeodesy.equirectangular4} and L{pygeodesy.nearestOn5}
                  and method L{sphericalTrigonometry.LatLon.nearestOn3}.
         '''
         # remove kwarg B{C{within}} if present
@@ -605,7 +605,7 @@ class LatLon(LatLonSphericalBase):
     def nearestOn3(self, points, closed=False, radius=R_M, **wrap_adjust_limit):
         '''Locate the point on a polygon closest to this point.
 
-           Distances are approximated by function L{pygeodesy.equirectangular_},
+           Distances are approximated by function L{pygeodesy.equirectangular4},
            subject to the supplied B{C{options}}.
 
            @arg points: The polygon points (L{LatLon}[]).
@@ -613,17 +613,17 @@ class LatLon(LatLonSphericalBase):
            @kwarg radius: Mean earth radius (C{meter}).
            @kwarg wrap_adjust_limit: Optional keyword arguments for function
                               L{sphericalTrigonometry.nearestOn3} and
-                              L{pygeodesy.equirectangular_},
+                              L{pygeodesy.equirectangular4},
 
            @return: A L{NearestOn3Tuple}C{(closest, distance, angle)} of the
-                    C{closest} point (L{LatLon}), the L{pygeodesy.equirectangular_}
+                    C{closest} point (L{LatLon}), the L{pygeodesy.equirectangular4}
                     C{distance} between this and the C{closest} point converted to
                     C{meter}, same units as B{C{radius}}.  The C{angle} from this
                     to the C{closest} point is in compass C{degrees360}, like
                     function L{pygeodesy.compassAngle}.
 
            @raise LimitError: Lat- and/or longitudinal delta exceeds B{C{limit}},
-                              see function L{pygeodesy.equirectangular_}.
+                              see function L{pygeodesy.equirectangular4}.
 
            @raise PointsError: Insufficient number of B{C{points}}.
 
@@ -631,7 +631,7 @@ class LatLon(LatLonSphericalBase):
 
            @raise ValueError: Invalid B{C{radius}} or B{C{options}}.
 
-           @see: Functions L{pygeodesy.compassAngle}, L{pygeodesy.equirectangular_}
+           @see: Functions L{pygeodesy.compassAngle}, L{pygeodesy.equirectangular4}
                  and L{pygeodesy.nearestOn5}.
         '''
         return nearestOn3(self, points, closed=closed, radius=radius,
@@ -1222,7 +1222,7 @@ def nearestOn3(point, points, closed=False, radius=R_M, wrap=False, adjust=True,
                                                         limit=9, **LatLon_and_kwds):
     '''Locate the point on a path or polygon closest to a reference point.
 
-       Distances are I{approximated} using function L{pygeodesy.equirectangular_},
+       Distances are I{approximated} using function L{pygeodesy.equirectangular4},
        subject to the supplied B{C{options}}.
 
        @arg point: The reference point (L{LatLon}).
@@ -1231,19 +1231,19 @@ def nearestOn3(point, points, closed=False, radius=R_M, wrap=False, adjust=True,
        @kwarg radius: Mean earth radius (C{meter}).
        @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the
                     B{C{points}} (C{bool}).
-       @kwarg adjust: See function L{pygeodesy.equirectangular_} (C{bool}).
-       @kwarg limit: See function L{pygeodesy.equirectangular_} (C{degrees}),
+       @kwarg adjust: See function L{pygeodesy.equirectangular4} (C{bool}).
+       @kwarg limit: See function L{pygeodesy.equirectangular4} (C{degrees}),
                      default C{9 degrees} is about C{1,000 Kmeter} (for mean
                      spherical earth radius L{R_KM}).
        @kwarg LatLon: Optional class to return the closest point (L{LatLon})
                       or C{None}.
        @kwarg options: Optional keyword arguments for function
-                       L{pygeodesy.equirectangular_}.
+                       L{pygeodesy.equirectangular4}.
 
        @return: A L{NearestOn3Tuple}C{(closest, distance, angle)} with the
                 C{closest} point as B{C{LatLon}} or L{LatLon3Tuple}C{(lat,
                 lon, height)} if B{C{LatLon}} is C{None}.  The C{distance}
-                is the L{pygeodesy.equirectangular_} distance between the
+                is the L{pygeodesy.equirectangular4} distance between the
                 C{closest} and the given B{C{point}} converted to C{meter},
                 same units as B{C{radius}}.  The C{angle} from the given
                 B{C{point}} to the C{closest} is in compass C{degrees360},
@@ -1251,7 +1251,7 @@ def nearestOn3(point, points, closed=False, radius=R_M, wrap=False, adjust=True,
                 the (interpolated) height at the C{closest} point.
 
        @raise LimitError: Lat- and/or longitudinal delta exceeds the B{C{limit}},
-                          see function L{pygeodesy.equirectangular_}.
+                          see function L{pygeodesy.equirectangular4}.
 
        @raise PointsError: Insufficient number of B{C{points}}.
 
@@ -1259,7 +1259,7 @@ def nearestOn3(point, points, closed=False, radius=R_M, wrap=False, adjust=True,
 
        @raise ValueError: Invalid B{C{radius}}.
 
-       @see: Functions L{pygeodesy.equirectangular_} and L{pygeodesy.nearestOn5}.
+       @see: Functions L{pygeodesy.equirectangular4} and L{pygeodesy.nearestOn5}.
     '''
     t = _nearestOn5(point, points, closed=closed, wrap=wrap,
                                    adjust=adjust, limit=limit)

pygeodesy/trf.py

@@ -80,8 +80,8 @@ from pygeodesy.interns import MISSING, NN, _AT_, _COMMASPACE_, _conversion_, \
                              _NAD83_, _no_, _PLUS_, _reframe_, _s_, _SPACE_, \
                              _STAR_, _to_, _vs_, _WGS84_, _x_, _intern as _i
 # from pygeodesy.lazily import _ALL_LAZY  # from .units
-from pygeodesy.named import ADict, classname, _lazyNamedEnumItem as _lazy, _Named, \
-                           _NamedEnum, _NamedEnumItem, _NamedTuple,  Fmt, unstr
+from pygeodesy.named import ADict, classname, _lazyNamedEnumItem as _lazy, _name2__, \
+                           _Named, _NamedEnum, _NamedEnumItem, _NamedTuple,  Fmt, unstr
 from pygeodesy.props import deprecated_method, property_doc_, Property_RO, property_RO
 # from pygeodesy.streprs import Fmt, unstr  # from .named
 from pygeodesy.units import Epoch, Float,  _ALL_LAZY
@@ -91,7 +91,7 @@ from math import ceil as _ceil, fabs
 # import operator as _operator  # from .datums
 
 __all__ = _ALL_LAZY.trf
-__version__ = '24.05.21'
+__version__ = '24.05.31'
 
 _EP0CH    =  Epoch(0, low=0)
 _Es       = {_EP0CH: _EP0CH}  # L{Epoch}s, deleted below
@@ -405,10 +405,11 @@ class TransformXform(Transform):
         n = name or (X.toStr() if X else NN)
         return Transform.rename(self, n)
 
-    def toRefFrame(self, point, name=NN):  # PYCHOK signature
+    def toRefFrame(self, point, **name):  # PYCHOK signature
         '''Convert an ellipsoidal point using this transform and Xform.
 
            @arg point: The point to convert (C{Cartesian} or C{LatLon}).
+           @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @return: A copy of the B{C{point}}, converted I{directly} to
                     this transform's Xform's C{refName2} and C{epoch}.
@@ -423,7 +424,7 @@ class TransformXform(Transform):
         if X:  # see _toRefFrame below
             p._reframe = X.reframe2
             p._epoch   = X.epoch
-        p.rename(name or self.name)
+        p.rename(self._name__(name))
         return p
 
     def toTransform(self, epoch1, **epoch2_inverse):
@@ -1043,7 +1044,7 @@ def _sumstr(name1, name2, p_):
 
 
 def _toRefFrame(point, reframe2, reframe=None, epoch=None,
-                       epoch2=None, name=NN, **LatLon_kwds):
+                       epoch2=None, **name_LatLon_kwds):
     '''(INTERNAL) Convert an ellipsoidal point to C{reframe2}
        and C{epoch2 or epoch or pont.epoch or reframe.epoch}.
     '''
@@ -1063,6 +1064,7 @@ def _toRefFrame(point, reframe2, reframe=None, epoch=None,
                            _to_, _AT_(reframe2.name, e2))
         raise TRFError(_no_(_conversion_), txt=t)
 
+    name, LatLon_kwds = _name2__(name_LatLon_kwds)
     if t0:  # is not ()
         if t0.isunity:
             p = point.dup()
@@ -1078,7 +1080,7 @@ def _toRefFrame(point, reframe2, reframe=None, epoch=None,
             p = point.toTransform(t0)
         p._reframe =  reframe2  # see TRFXform.toRefFrame above
         p._epoch   = _xattr(t0.Xform, epoch=e2)
-        p.rename(name or reframe2.name)
+        p.rename(reframe2._name__(name))
     else:
         p = point.dup(_reframe=reframe2,  # ditto
                       _epoch=e2, name=name) if name else point

pygeodesy/triaxials.py

@@ -59,7 +59,7 @@ from pygeodesy.vector3d import _otherV3d, Vector3d,  _ALL_LAZY, _MODS
 from math import atan2, fabs, sqrt
 
 __all__ = _ALL_LAZY.triaxials
-__version__ = '24.05.21'
+__version__ = '24.05.28'
 
 _not_ordered_ = _not_('ordered')
 _omega_       = 'omega'
@@ -1158,7 +1158,7 @@ def _getitems(items, *indices):
     return type(items)(map(items.__getitem__, indices))
 
 
-def _hartzell3(pov, los, Tun):  # in .ellipsoids.hartzell4, .formy.hartzell
+def _hartzell3(pov, los, Tun):  # in .Ellipsoid.hartzell4, .formy.hartzell
     '''(INTERNAL) Hartzell's "Satellite Line-of-Sight Intersection ...",
        formula from a Point-Of-View to an I{un-/ordered} Triaxial.
     '''

pygeodesy/ups.py

@@ -26,14 +26,14 @@ from pygeodesy.constants import EPS, EPS0, _EPSmin as _Tol90, \
                                 isnear90, _0_0, _0_5, _1_0, _2_0
 from pygeodesy.datums import _ellipsoidal_datum, _WGS84
 from pygeodesy.dms import degDMS, _neg, parseDMS2
-from pygeodesy.errors import RangeError, _ValueError
+from pygeodesy.errors import RangeError, _ValueError, _xkwds_pop2
 from pygeodesy.fmath import hypot, hypot1, sqrt0
 # from pygeodesy.internals import _under  # from .named
 from pygeodesy.interns import NN, _COMMASPACE_, _inside_, _N_, \
                              _pole_, _range_, _S_, _scale0_, \
                              _SPACE_, _std_, _to_, _UTM_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS,  _getenv
-from pygeodesy.named import nameof, _xnamed,  _under
+from pygeodesy.named import nameof,  _under
 from pygeodesy.namedTuples import EasNor2Tuple, UtmUps5Tuple, \
                                   UtmUps8Tuple, UtmUpsLatLon5Tuple
 from pygeodesy.props import deprecated_method, property_doc_, \
@@ -49,7 +49,7 @@ from pygeodesy.utmupsBase import Fmt, _LLEB, _hemi, _parseUTMUPS5, _to4lldn, \
 from math import atan2, fabs, radians, tan
 
 __all__ = _ALL_LAZY.ups
-__version__ = '25.05.13'
+__version__ = '25.05.31'
 
 _BZ_UPS  = _getenv('PYGEODESY_UPS_POLES', _std_) == _std_
 _Falsing =  Meter(2000e3)  # false easting and northing (C{meter})
@@ -57,18 +57,6 @@ _K0_UPS  =  Float(_K0_UPS= 0.994)  # scale factor at central meridian
 _K1_UPS  =  Float(_K1_UPS=_1_0)    # rescale point scale factor
 
 
-def _scale(E, rho, tau):
-    # compute the point scale factor, ala Karney
-    t = hypot1(tau)
-    return Float(scale=(rho / E.a) * t * sqrt0(E.e21 + E.e2 / t**2))
-
-
-def _toBand(lat, lon):  # see utm._toBand
-    '''(INTERNAL) Get the I{polar} Band letter for a (lat, lon).
-    '''
-    return _Bands[(0 if lat < 0 else 2) + (0 if -180 < lon < 0 else 1)]
-
-
 class UPSError(_ValueError):
     '''Universal Polar Stereographic (UPS) parse or other L{Ups} issue.
     '''
@@ -88,7 +76,7 @@ class Ups(UtmUpsBase):
     def __init__(self, zone=0, pole=_N_, easting=_Falsing,  # PYCHOK expected
                                          northing=_Falsing, band=NN, datum=_WGS84,
                                          falsed=True, gamma=None, scale=None,
-                                         name=NN, **convergence):
+                                       **name_convergence):
         '''New L{Ups} UPS coordinate.
 
            @kwarg zone: UPS zone (C{int}, zero) or zone with/-out I{polar} Band
@@ -100,13 +88,13 @@ class Ups(UtmUpsBase):
            @kwarg band: Optional, I{polar} Band (C{str}, 'A'|'B'|'Y'|'Z').
            @kwarg datum: Optional, this coordinate's datum (L{Datum},
                          L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}).
-           @kwarg falsed: If C{True}, both B{C{easting}} and B{C{northing}}
-                          are falsed (C{bool}).
-           @kwarg gamma: Optional, meridian convergence to save (C{degrees}).
-           @kwarg scale: Optional, computed scale factor k to save
-                         (C{scalar}).
-           @kwarg name: Optional name (C{str}).
-           @kwarg convergence: DEPRECATED, use keyword argument C{B{gamma}=None}.
+           @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 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
+                       keyword argument C{B{convergence}=None}, use B{C{gamma}}.
 
            @raise TypeError: Invalid B{C{datum}}.
 
@@ -114,18 +102,19 @@ class Ups(UtmUpsBase):
                             B{C{northing}}, B{C{band}}, B{C{convergence}}
                             or B{C{scale}}.
         '''
-        if name:
-            self.name = name
-
+        if name_convergence:
+            gamma, name = _xkwds_pop2(name_convergence, convergence=gamma)
+            if name:
+                self.name = name
         try:
-            z, B, p = _to3zBhp(zone, band, hemipole=pole)
+            z, B, self._pole = _to3zBhp(zone, band, hemipole=pole)
             if z != _UPS_ZONE or (B and (B not in _Bands)):
                 raise ValueError
         except (TypeError, ValueError) as x:
             raise UPSError(zone=zone, pole=pole, band=band, cause=x)
-        self._pole = p
+
         UtmUpsBase.__init__(self, easting, northing, band=B, datum=datum, falsed=falsed,
-                                                     gamma=gamma, scale=scale, **convergence)
+                                                             gamma=gamma, scale=scale)
 
     def __eq__(self, other):
         return isinstance(other, Ups) and other.zone     == self.zone \
@@ -161,13 +150,11 @@ class Ups(UtmUpsBase):
         f = _Falsing if self.falsed else 0
         return EasNor2Tuple(f, f)
 
-    def parse(self, strUPS, name=NN):
+    def parse(self, strUPS, **name):
         '''Parse a string to a similar L{Ups} instance.
 
-           @arg strUPS: The UPS coordinate (C{str}),
-                        see function L{parseUPS5}.
-           @kwarg name: Optional instance name (C{str}),
-                        overriding this name.
+           @arg strUPS: The UPS coordinate (C{str}), see function L{parseUPS5}.
+           @kwarg name: Optional C{B{name}=NN} (C{str}), overriding this name.
 
            @return: The similar instance (L{Ups}).
 
@@ -176,7 +163,7 @@ class Ups(UtmUpsBase):
            @see: Functions L{parseUTM5} and L{pygeodesy.parseUTMUPS5}.
         '''
         return parseUPS5(strUPS, datum=self.datum, Ups=self.classof,
-                                 name=name or self.name)
+                                  name=self._name__(name))
 
     @deprecated_method
     def parseUPS(self, strUPS):  # PYCHOK no cover
@@ -250,9 +237,8 @@ class Ups(UtmUpsBase):
             b, g, a = atan2(x, y), -1, _neg(a)
         ll = _LLEB(a, degrees180(b), datum=self._datum, name=self.name)
 
-        ll._gamma =  b * g
-        ll._scale = _scale(E, r, t) if r > 0 else self.scale0
-        self._latlon5args(ll, _toBand, unfalse)
+        k  = _scale(E, r, t) if r > 0 else self.scale0
+        self._latlon5args(ll, g * b, k, _toBand, unfalse)
 
     def toRepr(self, prec=0, fmt=Fmt.SQUARE, sep=_COMMASPACE_, B=False, cs=False, **unused):  # PYCHOK expected
         '''Return a string representation of this UPS coordinate.
@@ -353,7 +339,7 @@ class _Ups_K1(Ups):
     _scale0 = _K1_UPS
 
 
-def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, name=NN):
+def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, **name):
     '''Parse a string representing a UPS coordinate, consisting of
        C{"[zone][band] pole easting northing"} where B{C{zone}} is
        pseudo zone C{"00"|"0"|""} and C{band} is C{'A'|'B'|'Y'|'Z'|''}.
@@ -362,8 +348,9 @@ def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, name=NN):
        @kwarg datum: Optional datum to use (L{Datum}).
        @kwarg Ups: Optional class to return the UPS coordinate (L{Ups})
                    or C{None}.
-       @kwarg falsed: Both B{C{easting}} and B{C{northing}} are falsed (C{bool}).
-       @kwarg name: Optional B{C{Ups}} name (C{str}).
+       @kwarg falsed: If C{True}, both B{C{easting}} and B{C{northing}}
+                      are falsed (C{bool}).
+       @kwarg name: Optional B{C{Ups}} C{B{name}=NN} (C{str}).
 
        @return: The UPS coordinate (B{C{Ups}}) or a
                 L{UtmUps5Tuple}C{(zone, hemipole, easting, northing,
@@ -376,43 +363,54 @@ def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, name=NN):
     if z != _UPS_ZONE or (B and B not in _Bands):
         raise UPSError(strUPS=strUPS, zone=z, band=B)
 
-    r = UtmUps5Tuple(z, p, e, n, B, Error=UPSError) if Ups is None \
-            else Ups(z, p, e, n, band=B, falsed=falsed, datum=datum)
-    return _xnamed(r, name)
+    r = UtmUps5Tuple(z, p, e, n, B, Error=UPSError, **name) if Ups is None \
+            else Ups(z, p, e, n, band=B, falsed=falsed, datum=datum, **name)
+    return r
+
+
+def _scale(E, rho, tau):
+    # compute the point scale factor, ala Karney
+    t = hypot1(tau)
+    return Float(scale=(rho / E.a) * t * sqrt0(E.e21 + E.e2 / t**2))
+
+
+def _toBand(lat, lon):  # see utm._toBand
+    '''(INTERNAL) Get the I{polar} Band letter for a (lat, lon).
+    '''
+    return _Bands[(0 if lat < 0 else 2) + (0 if -180 < lon < 0 else 1)]
 
 
 def toUps8(latlon, lon=None, datum=None, Ups=Ups, pole=NN,
-                             falsed=True, strict=True, name=NN):
+                             falsed=True, strict=True, **name):
     '''Convert a lat-/longitude point to a UPS coordinate.
 
-       @arg latlon: Latitude (C{degrees}) or an (ellipsoidal)
-                    geodetic C{LatLon} point.
+       @arg latlon: Latitude (C{degrees}) or an (ellipsoidal) geodetic
+                    C{LatLon} point.
        @kwarg lon: Optional longitude (C{degrees}) or C{None} if
                    B{C{latlon}} is a C{LatLon}.
-       @kwarg datum: Optional datum for this UPS coordinate,
-                     overriding B{C{latlon}}'s datum (C{Datum},
-                     L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}).
-       @kwarg Ups: Optional class to return the UPS coordinate
-                   (L{Ups}) or C{None}.
+       @kwarg datum: Optional datum for this UPS coordinate, overriding
+                     B{C{latlon}}'s datum (C{Datum}, L{Ellipsoid},
+                     L{Ellipsoid2} or L{a_f2Tuple}).
+       @kwarg Ups: Optional class to return the UPS coordinate (L{Ups})
+                   or C{None}.
        @kwarg pole: Optional top/center of (stereographic) projection
                     (C{str}, C{'N[orth]'} or C{'S[outh]'}).
-       @kwarg falsed: False both easting and northing (C{bool}).
+       @kwarg falsed: If C{True}, false both easting and northing (C{bool}).
        @kwarg strict: Restrict B{C{lat}} to UPS ranges (C{bool}).
-       @kwarg name: Optional B{C{Ups}} name (C{str}).
+       @kwarg name: Optional B{C{Ups}} C{B{name}=NN} (C{str}).
 
-       @return: The UPS coordinate (B{C{Ups}}) or a
-                L{UtmUps8Tuple}C{(zone, hemipole, easting, northing,
-                band, datum, gamma, scale)} if B{C{Ups}} is C{None}.
-                The C{hemipole} is the C{'N'|'S'} pole, the UPS
-                projection top/center.
+       @return: The UPS coordinate (B{C{Ups}}) or a L{UtmUps8Tuple}C{(zone,
+                hemipole, easting, northing, band, datum, gamma, scale)} if
+                B{C{Ups}} is C{None}.  The C{hemipole} is the C{'N'|'S'}
+                pole, the UPS projection top/center.
 
        @raise RangeError: If B{C{strict}} and B{C{lat}} outside the valid
                           UPS bands or if B{C{lat}} or B{C{lon}} outside
                           the valid range and L{pygeodesy.rangerrors} set
                           to C{True}.
 
-       @raise TypeError: If B{C{latlon}} is not ellipsoidal or
-                         B{C{datum}} invalid.
+       @raise TypeError: If B{C{latlon}} is not ellipsoidal or if B{C{datum}}
+                         is invalid.
 
        @raise ValueError: If B{C{lon}} value is missing or if B{C{latlon}}
                           is invalid.
@@ -463,9 +461,7 @@ def toUps8(latlon, lon=None, datum=None, Ups=Ups, pole=NN,
         r = Ups(z, p, x, y, band=B, datum=d, falsed=falsed,
                                     gamma=g, scale=k, name=n)
         if isinstance(latlon, _LLEB) and d is latlon.datum:  # see utm._toXtm8
-            r._latlon5args(latlon, _toBand, falsed)  # XXX weakref(latlon)?
-            latlon._gamma = g
-            latlon._scale = k
+            r._latlon5args(latlon, g, k, _toBand, falsed)  # XXX weakref(latlon)?
         else:
             r._hemisphere = _hemi(lat)
             if not r._band:
@@ -473,18 +469,18 @@ def toUps8(latlon, lon=None, datum=None, Ups=Ups, pole=NN,
     return r
 
 
-def upsZoneBand5(lat, lon, strict=True, name=NN):
+def upsZoneBand5(lat, lon, strict=True, **name):
     '''Return the UTM/UPS zone number, I{polar} Band letter, 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 strict: Restrict B{C{lat}} to UPS ranges (C{bool}).
-       @kwarg name: Optional name (C{str}).
+       @kwarg name: Optional B{C{Ups}} C{B{name}=NN} (C{str}).
 
-       @return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole,
-                lat, lon)} where C{hemipole} is the C{'N'|'S'} pole,
-                the UPS projection top/center and C{lon} [-180..180).
+       @return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole, lat,
+                lon)} where C{hemipole} is the C{'N'|'S'} pole, the
+                UPS projection top/center and C{lon} [-180..180).
 
        @note: The C{lon} is set to C{0} if B{C{lat}} is C{-90} or
               C{90}, see env variable C{PYGEODESY_UPS_POLES} in
@@ -514,7 +510,7 @@ def upsZoneBand5(lat, lon, strict=True, name=NN):
 
     else:
         B, p = NN, _hemi(lat)
-    return UtmUpsLatLon5Tuple(z, B, p, lat, lon, Error=UPSError, name=name)
+    return UtmUpsLatLon5Tuple(z, B, p, lat, lon, Error=UPSError, **name)
 
 # **) MIT License
 #

pygeodesy/utily.py

@@ -17,7 +17,7 @@ from pygeodesy.constants import EPS, EPS0, INF, NAN, PI, PI2, PI_2, R_M, \
                                _N_180_0, _360_0, _400_0, _copysign_0_0, \
                                _float as _F, _isfinite, isnan, isnear0, \
                                _over, _umod_360, _umod_PI2
-from pygeodesy.errors import _ValueError, _xkwds, _xkwds_get,  _ALL_LAZY, _MODS
+from pygeodesy.errors import _ValueError, _xkwds, _xkwds_get1,  _ALL_LAZY, _MODS
 from pygeodesy.internals import _passargs  # , _MODS?
 from pygeodesy.interns import _edge_, _radians_, _semi_circular_, _SPACE_
 # from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS  # from .errors
@@ -27,7 +27,7 @@ from pygeodesy.units import Degrees, Degrees_, Feet, Float, Lam, Lam_, \
 from math import acos, asin, atan2, cos, degrees, fabs, radians, sin, tan  # pow
 
 __all__ = _ALL_LAZY.utily
-__version__ = '24.05.14'
+__version__ = '24.05.29'
 
 # read constant name "_M_Unit" as "meter per Unit"
 _M_CHAIN     = _F(  20.1168)     # yard2m(1) * 22
@@ -763,7 +763,7 @@ def sincos2d(deg, **adeg):
             q -= 1
         d = deg - q * _90_0
         if adeg:
-            t = _xkwds_get(adeg, adeg=_0_0)
+            t = _xkwds_get1(adeg, adeg=_0_0)
             d = _MODS.karney._around(d + t)
         t = _sin0cos2(q & 3, radians(d), deg)
     else: