pygeodesy 25.5.28__py2.py3-none-any.whl → 25.7.25__py2.py3-none-any.whl

pygeodesy/__init__.py

@@ -125,7 +125,7 @@ C{epydoc --html --no-private --no-source --name=pygeodesy --url=... -v pygeodesy
 Tests
 =====
 
-The tests ran with Python 3.13.3 (with U{geographiclib<https://PyPI.org/project/geographiclib>} 2.0),
+The tests ran with Python 3.13.5 (with U{geographiclib<https://PyPI.org/project/geographiclib>} 2.0),
 Python 3.12.7 (with U{geographiclib<https://PyPI.org/project/geographiclib>} 2.0,
 U{numpy<https://PyPI.org/project/numpy>} 2.1.0, U{scipy<https://PyPI.org/project/scipy>} 1.14.1,
 U{GeodSolve<https://GeographicLib.SourceForge.io/C++/doc/utilities.html>} 2.5,
@@ -150,13 +150,13 @@ env variable C{PYGEODESY_WARNINGS=on} for all Python versions.  The results of t
 the distribution files.
 
 Test coverage has been measured with U{coverage<https://PyPI.org/project/coverage>} 7.6.1 using Python
-3.13.3, 3.12.7, 3.11.5 and 3.10.8.  The complete coverage report in HTML and a PDF summary are included in
+3.13.4, 3.12.7, 3.11.5 and 3.10.8.  The complete coverage report in HTML and a PDF summary are included in
 the distribution files.
 
-Python 3.13.3, 3.12.7, 3.11.5 and 3.10.8 run on Apple M4 Si (C{arm64}), I{natively}.  Python 2.7.18 runs
+Python 3.13.5, 3.12.7, 3.11.5 and 3.10.8 run on Apple M4 Si (C{arm64}), I{natively}.  Python 2.7.18 runs
 on Intel (C{x86_64}) or Intel I{emulation} ("C{arm64_x86_64}", see function L{machine<pygeodesy.machine>}).
 
-The tests also ran with Python 3.13.3 (and U{geographiclib<https://PyPI.org/project/geographiclib>} 2.0) on
+The tests also ran with Python 3.13.5 (and U{geographiclib<https://PyPI.org/project/geographiclib>} 2.0) on
 U{Debian 12<https://Cirrus-CI.com/github/mrJean1/PyGeodesy/master>} in 64-bit only, with Python 3.12.8 (and
 U{geographiclib<https://PyPI.org/project/geographiclib>} 2.0) on U{Windows 2019Server
 <https://CI.AppVeyor.com/project/mrJean1/pygeodesy>} in 64-bit only and with Python 2.7.18 (and U{geographiclib
@@ -166,7 +166,7 @@ in 64- and 32-bit.
 A single-File and single-Directory application with C{pygeodesy} has been bundled using U{PyInstaller
 <https://PyPI.org/project/pyinstaller>} 3.4 and 64-bit Python 3.7.3 on macOS 10.13.6 High Sierra.
 
-Previously, the tests were run with Python 3.13.0-2, 3.12.0-6, 3.11.2-4, 3.10.1-7, 3.9.6, 3.9.1, 3.8.7, 3.7.1, 2.7.15,
+Previously, the tests were run with Python 3.13.0-4, 3.12.0-6, 3.11.2-4, 3.10.1-7, 3.9.6, 3.9.1, 3.8.7, 3.7.1, 2.7.15,
 U{PyPy<https://PyPy.org>} 7.3.12 (Python 3.10.12), 7.3.1 (Python 3.6.9) and U{PyPy<https://PyPy.org>} 7.1.1 (Python
 2.7.13) (and U{geographiclib <https://PyPI.org/project/geographiclib>} 1.52, U{numpy<https://PyPI.org/project/numpy>}
 1.16.3, 1.16.4, 1.16.6, 1.19.0, 1.19.4, 1.19.5 or 1.22.4 and U{scipy<https://PyPI.org/project/scipy>} 1.2.1, 1.4.1,
@@ -187,10 +187,10 @@ Notes
 =====
 
 All Python source code has been statically U{checked<https://GitHub.com/ActiveState/code/tree/master/recipes/Python/
-546532_PyChecker_postprocessor>} with U{Ruff<https://GitHub.com/astral-sh/ruff>} using Python 3.13.3 and with
+546532_PyChecker_postprocessor>} with U{Ruff<https://GitHub.com/astral-sh/ruff>} using Python 3.13.5 and with
 U{PyChecker<https://PyPI.org/project/pychecker>}, U{PyFlakes<https://PyPI.org/project/pyflakes>}, U{PyCodeStyle
 <https://PyPI.org/project/pycodestyle>} (formerly Pep8) and U{McCabe<https://PyPI.org/project/mccabe>} using Python
-2.7.18, both in 64-bit on macOS 15.5 Sequoia only.
+2.7.18, both in 64-bit on macOS 15.5 Sequoia.
 
 For a summary of all I{Karney}-based functionality in C{pygeodesy}, see module U{karney
 <https://mrJean1.GitHub.io/PyGeodesy/docs/pygeodesy.karney-module.html>}.
@@ -604,7 +604,7 @@ else:
 
 from pygeodesy.internals import _version2,  _DOT_  # noqa: E402
 # from pygeodesy.interns import _DOT_  # from .internals
-__version__ = '25.05.28'
+__version__ = '25.07.25'
 # see setup.py for similar logic
 version     = _DOT_(*_version2(__version__, n=3))
 

pygeodesy/ellipsoidalBase.py

@@ -46,7 +46,7 @@ from pygeodesy.units import Epoch, _isDegrees, Radius_, _1mm as _TOL_M
 # from math import fabs  # from .latlonBase
 
 __all__ = _ALL_LAZY.ellipsoidalBase
-__version__ = '25.05.12'
+__version__ = '25.07.21'
 
 
 class CartesianEllipsoidalBase(CartesianBase):
@@ -136,7 +136,7 @@ class CartesianEllipsoidalBase(CartesianBase):
 
                     If C{B{sphere} is False}, a 2-tuple with the two intersection points
                     of the I{circles}.  For abutting circles, both points are the same
-                    instance, aka the I{radical center}.
+                    instance (aka the I{radical center}).
 
            @raise IntersectionError: Concentric, invalid or non-intersecting spheres or circles.
 
@@ -449,8 +449,7 @@ class LatLonEllipsoidalBase(LatLonBase):
     def _etm(self):
         '''(INTERNAL) Get this C{LatLon} point as an ETM coordinate (L{pygeodesy.toEtm8}).
         '''
-        etm = _MODS.etm
-        return etm.toEtm8(self, datum=self.datum, Etm=etm.Etm)
+        return self._toX8(_MODS.etm.toEtm8)
 
     @property_RO
     def gamma(self):
@@ -523,8 +522,8 @@ class LatLonEllipsoidalBase(LatLonBase):
                     a C{LatLon} instance.
 
            @raise ImportError: Package U{geographiclib
-                               <https://PyPI.org/project/geographiclib>} not
-                               installed or not found, but only in case
+                               <https://PyPI.org/project/geographiclib>}
+                               not installed or not found, but only if
                                C{B{equidistant}=}L{EquidistantKarney}.
 
            @raise IntersectionError: Skew, colinear, parallel or otherwise non-intersecting
@@ -676,8 +675,8 @@ class LatLonEllipsoidalBase(LatLonBase):
            @kwarg wrap: If C{True}, wrap or I{normalize} and unroll both B{C{point1}} and
                         B{C{point2}} (C{bool}).
            @kwarg equidistant: An azimuthal equidistant projection (I{class} or function
-                               L{pygeodesy.equidistant}) or C{None} for this point's preferred
-                               C{Equidistant}, like L{Equidistant<LatLonEllipsoidalBase.Equidistant>}.
+                               L{pygeodesy.equidistant}) or C{None} for this point's
+                               preferred C{Equidistant}, like L{Equidistant}.
            @kwarg tol: Convergence tolerance (C{meter}, conventionally).
 
            @return: Closest point (C{LatLon}).
@@ -778,6 +777,11 @@ class LatLonEllipsoidalBase(LatLonBase):
         '''
         return self._scale
 
+    def _toX8(self, toX8, **kwds):
+        '''(INTERNAL) Return toX8(self, ...).
+        '''
+        return toX8(self, **_xkwds(kwds, datum=self.datum, name=self.name))
+
     def toCartesian(self, height=None, **Cartesian_and_kwds):  # PYCHOK signature
         '''Convert this point to cartesian, I{geocentric} coordinates,
            also known as I{Earth-Centered, Earth-Fixed} (ECEF).
@@ -793,11 +797,10 @@ class LatLonEllipsoidalBase(LatLonBase):
     def toCss(self, **toCss_kwds):
         '''Convert this C{LatLon} point to a Cassini-Soldner location.
 
-           @kwarg toCss_kwds: Optional L{pygeodesy.toCss} keyword arguments.
+           @kwarg toCss_kwds: Optional keyword arguments for function
+                              L{pygeodesy.toCss}.
 
            @return: The Cassini-Soldner location (L{Css}).
-
-           @see: Function L{pygeodesy.toCss}.
         '''
         return _MODS.css.toCss(self, **self._name1__(toCss_kwds))
 
@@ -829,39 +832,38 @@ class LatLonEllipsoidalBase(LatLonBase):
     def toEtm(self, **toEtm8_kwds):
         '''Convert this C{LatLon} point to an ETM coordinate.
 
-           @kwarg toEtm8_kwds: Optional L{pygeodesy.toEtm8} keyword arguments.
+           @kwarg toEtm8_kwds: Optional keyword arguments for
+                               function L{pygeodesy.toEtm8}.
 
            @return: The ETM coordinate (L{Etm}).
-
-           @see: Function L{pygeodesy.toEtm8}.
         '''
-        return _MODS.etm.toEtm8(self, **self._name1__(toEtm8_kwds)) if toEtm8_kwds else self._etm
+        return self._etm if not toEtm8_kwds else \
+               self._toX8(_MODS.etm.toEtm8, **toEtm8_kwds)
 
     def toLcc(self, **toLcc_kwds):
         '''Convert this C{LatLon} point to a Lambert location.
 
-           @kwarg toLcc_kwds: Optional L{pygeodesy.toLcc} keyword arguments.
+           @kwarg toLcc_kwds: Optional keyword arguments for
+                              function L{pygeodesy.toLcc}.
 
            @return: The Lambert location (L{Lcc}).
-
-           @see: Function L{pygeodesy.toLcc}.
         '''
         return _MODS.lcc.toLcc(self, **self._name1__(toLcc_kwds))
 
-    def toMgrs(self, center=False, pole=NN):
+    def toMgrs(self, center=False, **toUtmUps_kwds):
         '''Convert this C{LatLon} point to an MGRS coordinate.
 
            @kwarg center: If C{True}, try to I{un}-center MGRS
                           to its C{lowerleft} (C{bool}) or by
                           C{B{center} meter} (C{scalar}).
-           @kwarg pole: Optional top/center for the MGRS UPS
-                        projection (C{str}, 'N[orth]' or 'S[outh]').
+           @kwarg toUtmUps_kwds: Optional keyword arguments for
+                                 method L{toUtmUps}.
 
            @return: The MGRS coordinate (L{Mgrs}).
 
-           @see: Method L{toUtmUps} and L{Mgrs.toLatLon}.
+           @see: Methods L{toUtmUps} and L{toMgrs<pygeodesy.utmupsBase.UtmUpsBase.toMgrs>}.
         '''
-        return self.toUtmUps(center=center, pole=pole).toMgrs(center=False)
+        return self.toUtmUps(center=center, **toUtmUps_kwds).toMgrs(center=False)
 
     def toOsgr(self, kTM=False, **toOsgr_kwds):
         '''Convert this C{LatLon} point to an OSGR coordinate.
@@ -869,11 +871,10 @@ class LatLonEllipsoidalBase(LatLonBase):
            @kwarg kTM: If C{True}, use I{Karney}'s Krüger method from module
                        L{ktm}, otherwise I{Ordinance Survery}'s recommended
                        formulation (C{bool}).
-           @kwarg toOsgr_kwds: Optional L{pygeodesy.toOsgr} keyword arguments.
+           @kwarg toOsgr_kwds: Optional keyword arguments for function
+                               L{pygeodesy.toOsgr}.
 
            @return: The OSGR coordinate (L{Osgr}).
-
-           @see: Function L{pygeodesy.toOsgr}.
         '''
         return _MODS.osgr.toOsgr(self, kTM=kTM, **self._name1__(toOsgr_kwds))
 
@@ -928,42 +929,40 @@ class LatLonEllipsoidalBase(LatLonBase):
             r = c.toLatLon(LatLon=self.classof, **_xkwds(LatLon_kwds, height=self.height))
         return r
 
-    def toUps(self, pole=NN, falsed=True, center=False):
+    def toUps(self, center=False, **toUps8_kwds):
         '''Convert this C{LatLon} point to a UPS coordinate.
 
-           @kwarg pole: Optional top/center of (stereographic)
-                        projection (C{str}, 'N[orth]' or 'S[outh]').
-           @kwarg falsed: False easting and northing (C{bool}).
            @kwarg center: If C{True}, I{un}-center the UPS to its
                           C{lowerleft} (C{bool}) or by C{B{center}
                           meter} (C{scalar}).
+           @kwarg toUps8_kwds: Optional keyword arguments for
+                               function L{pygeodesy.toUps8}.
 
            @return: The UPS coordinate (L{Ups}).
-
-           @see: Function L{pygeodesy.toUps8}.
         '''
-        if self._upsOK(pole, falsed):
-            u = self._ups
-        else:
-            ups = _MODS.ups
-            u = ups.toUps8(self, datum=self.datum, Ups=ups.Ups,
-                                 pole=pole, falsed=falsed)
+        u = self._ups if (not toUps8_kwds) and self._upsOK() else \
+            self._toX8(_MODS.ups.toUps8, **toUps8_kwds)
         return _lowerleft(u, center)
 
-    def toUtm(self, center=False):
+    def toUtm(self, center=False, **toUtm8_kwds):
         '''Convert this C{LatLon} point to a UTM coordinate.
 
            @kwarg center: If C{True}, I{un}-center the UTM to its
                           C{lowerleft} (C{bool}) or by C{B{center}
                           meter} (C{scalar}).
+           @kwarg toUtm8_kwds: Optional keyword arguments for function
+                               L{pygeodesy.toUtm8}.
 
            @return: The UTM coordinate (L{Utm}).
 
-           @see: Method L{Mgrs.toUtm} and function L{pygeodesy.toUtm8}.
+           @note: For the highest accuracy, use method L{toEtm} and
+                  class L{pygeodesy.Etm} instead of L{pygeodesy.Utm}.
         '''
-        return _lowerleft(self._utm, center)
+        u = self._utm if not toUtm8_kwds else \
+            self._toX8(_MODS.utm.toUtm8, **toUtm8_kwds)
+        return _lowerleft(u, center)
 
-    def toUtmUps(self, pole=NN, center=False):
+    def toUtmUps(self, pole=NN, center=False, **toUtmUps8_kwds):
         '''Convert this C{LatLon} point to a UTM or UPS coordinate.
 
            @kwarg pole: Optional top/center of UPS (stereographic)
@@ -971,19 +970,19 @@ class LatLonEllipsoidalBase(LatLonBase):
            @kwarg center: If C{True}, I{un}-center the UTM or UPS to
                           its C{lowerleft} (C{bool}) or by C{B{center}
                           meter} (C{scalar}).
+           @kwarg toUtmUps8_kwds: Optional keyword arguments for
+                                  function L{pygeodesy.toUtmUps8}.
 
            @return: The UTM or UPS coordinate (L{Utm} or L{Ups}).
-
-           @see: Function L{pygeodesy.toUtmUps8}.
         '''
-        if self._utmOK():
+        x = not toUtmUps8_kwds
+        if x and self._utmOK():
             u = self._utm
-        elif self._upsOK(pole):
+        elif x and self._upsOK(pole):
             u = self._ups
         else:  # no cover
             utmups = _MODS.utmups
-            u = utmups.toUtmUps8(self, datum=self.datum, pole=pole, name=self.name,
-                                       Utm=utmups.Utm, Ups=utmups.Ups)
+            u = self._toX8(utmups.toUtmUps8, pole=pole, **toUtmUps8_kwds)
             if isinstance(u, utmups.Utm):
                 self._update(False, _utm=u)  # PYCHOK kwds
             elif isinstance(u, utmups.Ups):
@@ -1011,13 +1010,11 @@ class LatLonEllipsoidalBase(LatLonBase):
            @arg other: The other point (C{LatLon}).
            @arg bearing2: Bearing at the B{C{other}} point (compass C{degrees360}).
            @kwarg height_wrap_tol: Optional keyword arguments C{B{height}=None},
-                         C{B{wrap}=False} and C{B{tol}}, see method L{intersection3
-                         <pygeodesy.ellipsoidalBase.LatLonEllipsoidalBase>}.
+                         C{B{wrap}=False} and C{B{tol}}, see method L{intersection3}.
 
            @return: Triangulated point (C{LatLon}).
 
-           @see: Method L{intersection3<pygeodesy.ellipsoidalBase.LatLonEllipsoidalBase>}
-                 for further details.
+           @see: Method L{intersection3} for further details.
         '''
         if _isDegrees(bearing1) and _isDegrees(bearing2):
             r = self.intersection3(bearing1, other, bearing2, **height_wrap_tol)
@@ -1086,11 +1083,9 @@ class LatLonEllipsoidalBase(LatLonBase):
         '''(INTERNAL) Get this C{LatLon} point as UPS coordinate (L{Ups}),
            see L{pygeodesy.toUps8}.
         '''
-        ups = _MODS.ups
-        return ups.toUps8(self, datum=self.datum, Ups=ups.Ups,
-                                pole=NN, falsed=True, name=self.name)
+        return self._toX8(_MODS.ups.toUps8)  # pole=NN, falsed=True
 
-    def _upsOK(self, pole=NN, falsed=True):
+    def _upsOK(self, pole=NN, falsed=True, **unused):
         '''(INTERNAL) Check matching C{Ups}.
         '''
         try:
@@ -1104,8 +1099,7 @@ class LatLonEllipsoidalBase(LatLonBase):
         '''(INTERNAL) Get this C{LatLon} point as UTM coordinate (L{Utm}),
            see L{pygeodesy.toUtm8}.
         '''
-        utm = _MODS.utm
-        return utm.toUtm8(self, datum=self.datum, Utm=utm.Utm, name=self.name)
+        return self._toX8(_MODS.utm.toUtm8)
 
     def _utmOK(self):
         '''(INTERNAL) Check C{Utm}.