pygeodesy 24.6.9__py2.py3-none-any.whl → 24.7.7__py2.py3-none-any.whl

pygeodesy/geodesicw.py

@@ -23,7 +23,7 @@ from pygeodesy.fsums import Fsum,  Fmt, unstr
 from pygeodesy.internals import _dunder_nameof, _under
 from pygeodesy.interns import NN, _DOT_, _SPACE_, _to_, _too_
 from pygeodesy.karney import _atan2d, Caps, Direct9Tuple, GDict, \
-                             _kWrapped, Inverse10Tuple
+                              Inverse10Tuple, _kWrapped, _llz2line
 from pygeodesy.latlonBase import LatLonBase as _LLB,  F_D, Radius_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS
 from pygeodesy.named import callername, classname, _name1__, _name2__
@@ -37,7 +37,7 @@ from contextlib import contextmanager
 # from math import fabs  # from .utily
 
 __all__ = _ALL_LAZY.geodesicw
-__version__ = '24.05.24'
+__version__ = '24.07.09'
 
 _plumb_ = 'plumb'
 _TRIPS  =  65
@@ -71,8 +71,8 @@ class _gWrapped(_kWrapped):
 
                    @arg a_ellipsoid: The equatorial radius I{a} (C{meter}, conventionally),
                                      an ellipsoid (L{Ellipsoid}) or a datum (L{Datum}).
-                   @arg f: The ellipsoid's flattening (C{scalar}), ignored if B{C{a_ellipsoid})
-                           is not C{meter}.
+                   @arg f: The ellipsoid's flattening (C{scalar}), required if B{C{a_ellipsoid})
+                           is C{meter}, ignored otherwise.
                    @kwarg name: Optional C{B{name}=NN} (C{str}).
                 '''
                 _earth_datum(self, a_ellipsoid, f=f, **name)  # raiser=NN
@@ -220,7 +220,9 @@ class _gWrapped(_kWrapped):
                 '''
                 with _wargs(self, lat1, lon1, lat2, lon2, caps, **name) as args:
                     t = _Geodesic.InverseLine(self, *args)
-                return self._Line13(t, **name)
+                gl = self._Line13(t, **name)
+                p2 = gl.Position(gl.s13, outmask=Caps.AZIMUTH)
+                return _llz2line(gl, lat2=lat2, lon2=lon2, azi2=p2.azi2)
 
             def Line(self, lat1, lon1, azi1, caps=Caps._STD_LINE, **name):
                 '''Set up a I{wrapped} C{GeodesicLine} to compute several points
@@ -429,17 +431,16 @@ class _gWrapped(_kWrapped):
 _wrapped = _gWrapped()  # PYCHOK singleton, .ellipsoids, .test/base.py
 
 
-def Geodesic(a_ellipsoid, f=None, **name):
+def Geodesic(a_ellipsoid=_EWGS84, f=None, **name):
     '''Return a I{wrapped} C{geodesic.Geodesic} instance from I{Karney}'s
        Python U{geographiclib<https://PyPI.org/project/geographiclib>},
        provide the latter is installed, otherwise an C{ImportError}.
 
        @arg a_ellipsoid: An ellipsoid (L{Ellipsoid}) or datum (L{Datum})
               or the equatorial radius I{a} of the ellipsoid (C{meter}).
-       @arg f: The flattening of the ellipsoid (C{scalar}), ignored if
-               B{C{a_ellipsoid}}) is not specified as C{meter}.
-       @kwarg name: Optional ellipsoid C{B{name}=NN} (C{str}), ignored
-                    like B{C{f}}.
+       @arg f: The flattening of the ellipsoid (C{scalar}), required if
+               B{C{a_ellipsoid}}) is C{meter}, ignored otherwise.
+       @kwarg name: Optional C{B{name}=NN} (C{str}), ignored like B{C{f}}.
     '''
     return _wrapped.Geodesic(a_ellipsoid, f=f, **name)
 
@@ -453,11 +454,10 @@ def GeodesicLine(geodesic, lat1, lon1, azi1, caps=Caps._STD_LINE):
        @arg lat1: Latitude of the first points (C{degrees}).
        @arg lon1: Longitude of the first points (C{degrees}).
        @arg azi1: Azimuth at the first points (compass C{degrees360}).
-       @kwarg caps: Optional, bit-or'ed combination of L{Caps} values
-                    specifying the capabilities the C{GeodesicLine}
-                    instance should possess, i.e., which quantities can
-                    be returned by calls to C{GeodesicLine.Position}
-                    and C{GeodesicLine.ArcPosition}.
+       @kwarg caps: Optional, bit-or'ed combination of L{Caps} values specifying
+                    the capabilities the C{GeodesicLine} instance should possess,
+                    i.e., which quantities can be returned by methods
+                    C{GeodesicLine.Position} and C{GeodesicLine.ArcPosition}.
     '''
     return _wrapped.GeodesicLine(geodesic, lat1, lon1, azi1, caps=caps)
 

pygeodesy/geodesicx/__init__.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 u'''A pure Python version of I{Karney}'s C++ classes U{GeodesicExact
-<https://GeographicLib.SourceForge.io/C++/classGeographicLib_1_1GeodesicExact.html>}
+<https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GeodesicExact.html>}
 and U{GeodesicLineExact
 <https://geographiclib.sourceforge.io/C++/doc/classGeographicLib_1_1GeodesicLine.html>}.
 
@@ -13,8 +13,8 @@ and the background information at U{Geodesics on an ellipsoid of revolution
 
 Also, compare C{GeodesicExact} and C{GeodesicLineExact} to I{standard} classes C{Geodesic}
 respectively C{GeodesicLine} from I{Karney}'s Python implementation U{geographiclib
-<https://GeographicLib.SourceForge.io/C++/doc/other.html#python>}, see module
-L{pygeodesy.karney}.
+<https://GeographicLib.SourceForge.io/C++/doc/other.html#python>}, see modules
+L{pygeodesy.geodesicw} and L{pygeodesy.karney}.
 '''
 
 from pygeodesy.geodesicx.gx import GeodesicExact, GeodesicLineExact  # PYCHOK exported
@@ -23,7 +23,7 @@ from pygeodesy.karney import Caps, GeodesicError
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY
 
 __all__ = _ALL_LAZY.geodesicx + _ALL_DOCS(Caps, GeodesicError)
-__version__ = '24.05.31'
+__version__ = '24.07.09'
 
 # **) MIT License
 #

pygeodesy/geodesicx/gx.py

@@ -44,25 +44,26 @@ from pygeodesy.constants import EPS, EPS0, EPS02, MANT_DIG, NAN, PI, _EPSqrt, \
 from pygeodesy.datums import _earth_datum, _WGS84,  _EWGS84
 # from pygeodesy.ellipsoids import _EWGS84  # from .datums
 from pygeodesy.errors import GeodesicError, _xkwds_pop2
-from pygeodesy.fmath import hypot as _hypot
+from pygeodesy.fmath import hypot as _hypot,  Fmt
 from pygeodesy.fsums import fsumf_, fsum1f_
 from pygeodesy.geodesicx.gxbases import _cosSeries, _GeodesicBase, \
-                                        _sincos12, _sin1cos2, _xnC4
-from pygeodesy.geodesicx.gxline import _GeodesicLineExact, _TINY, _update_glXs
-from pygeodesy.interns import NN, _COMMASPACE_, _DOT_, _UNDER_
+                                        _sincos12, _sin1cos2, _sinf1cos2d, \
+                                        _TINY, _xnC4
+from pygeodesy.geodesicx.gxline import _GeodesicLineExact, _update_glXs
+from pygeodesy.interns import NN, _DOT_, _UNDER_
 from pygeodesy.karney import GDict, _around, _atan2d, Caps, _cbrt, _diff182, \
                             _fix90, _K_2_0, _norm2, _norm180, _polynomial, \
                             _signBit, _sincos2, _sincos2d, _sincos2de, _unsigned2
 from pygeodesy.lazily import _ALL_DOCS, _ALL_MODS as _MODS
 from pygeodesy.namedTuples import Destination3Tuple, Distance3Tuple
 from pygeodesy.props import deprecated_Property, Property, Property_RO, property_RO
-from pygeodesy.streprs import Fmt, pairs
+# from pygeodesy.streprs import Fmt  # from .fmath
 from pygeodesy.utily import atan2d as _atan2d_reverse, _unrollon, _Wrap, wrap360
 
 from math import atan2, copysign, cos, degrees, fabs, radians, sqrt
 
 __all__ = ()
-__version__ = '24.05.31'
+__version__ = '24.07.09'
 
 _MAXIT1 = 20
 _MAXIT2 = 10 + _MAXIT1 + MANT_DIG  # MANT_DIG == C++ digits
@@ -211,7 +212,7 @@ class GeodesicExact(_GeodesicBase):
                  <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GeodesicExact.html>} and
                  Python U{Geodesic.ArcDirectLine<https://GeographicLib.SourceForge.io/Python/doc/code.html>}.
         '''
-        return self._GenDirectLine(lat1, lon1, azi1, True, a12, caps, **name)
+        return GeodesicLineExact(self, lat1, lon1, azi1, caps=caps, **name)._GenSet(self._debug, a12=a12)
 
     def Area(self, polyline=False, **name):
         '''Set up a L{GeodesicAreaExact} to compute area and
@@ -389,7 +390,7 @@ class GeodesicExact(_GeodesicBase):
                  <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GeodesicExact.html>} and
                  Python U{Geodesic.DirectLine<https://GeographicLib.SourceForge.io/Python/doc/code.html>}.
         '''
-        return self._GenDirectLine(lat1, lon1, azi1, False, s12, caps, **name)
+        return GeodesicLineExact(self, lat1, lon1, azi1, caps=caps, **name)._GenSet(self._debug, s12=s12)
 
     def _dn(self, sbet, cbet):  # in gxline._GeodesicLineExact.__init__
         '''(INTERNAL) Helper.
@@ -496,7 +497,7 @@ class GeodesicExact(_GeodesicBase):
         Cs = Caps
         if self._debug:  # PYCHOK no cover
             outmask |= Cs._DEBUG_INVERSE & self._debug
-        outmask &= Cs._OUT_MASK  # incl. _SALPs_CALPs and _DEBUG_
+        outmask &= Cs._OUT_MASK  # incl. _S_CALPs_ and _DEBUG_
         # compute longitude difference carefully (with _diff182):
         # result is in [-180, +180] but -180 is only for west-going
         # geodesics, +180 is for east-going and meridional geodesics
@@ -504,8 +505,10 @@ class GeodesicExact(_GeodesicBase):
         # see C{result} from geographiclib.geodesic.Inverse
         if (outmask & Cs.LONG_UNROLL):  # == (lon1 + lon12) + lon12s
             r = GDict(lon1=lon1, lon2=fsumf_(lon1, lon12, lon12s))
-        else:
+        elif (outmask & Cs.LONGITUDE):
             r = GDict(lon1=_norm180(lon1), lon2=_norm180(lon2))
+        else:
+            r = GDict()
         if _K_2_0:  # GeographicLib 2.0
             # make longitude difference positive
             lon12, lon_ = _unsigned2(lon12)
@@ -534,7 +537,8 @@ class GeodesicExact(_GeodesicBase):
         # If really close to the equator, treat as on equator.
         lat1 = _around(_fix90(lat1))
         lat2 = _around(_fix90(lat2))
-        r.set_(lat1=lat1, lat2=lat2)
+        if (outmask & Cs.LATITUDE):
+            r.set_(lat1=lat1, lat2=lat2)
         # Swap points so that point with higher (abs) latitude is
         # point 1.  If one latitude is a NAN, then it becomes lat1.
         swap_ = fabs(lat1) < fabs(lat2) or isnan(lat2)
@@ -553,10 +557,10 @@ class GeodesicExact(_GeodesicBase):
         # to check, e.g., on verifying quadrants in atan2.  In addition,
         # this enforces some symmetries in the results returned.
 
-        # Initialize for the meridian.  No longitude calculation is
-        # done in this case to let the parameter default to 0.
-        sbet1, cbet1 = self._sinf1cos2d(lat1)
-        sbet2, cbet2 = self._sinf1cos2d(lat2)
+        # Initialize for the meridian.  No longitude calculation is done in
+        # this case to let the parameter default to 0.
+        sbet1, cbet1 = _sinf1cos2d(lat1, self.f1)
+        sbet2, cbet2 = _sinf1cos2d(lat2, self.f1)
         # If cbet1 < -sbet1, then cbet2 - cbet1 is a sensitive measure
         # of the |bet1| - |bet2|.  Alternatively (cbet1 >= -sbet1),
         # abs(sbet2) + sbet1 is a better measure.  This logic is used
@@ -670,7 +674,7 @@ class GeodesicExact(_GeodesicBase):
                 S12 = -S12
             r.set_(S12=unsigned0(S12))
 
-        if (outmask & (Cs.AZIMUTH | Cs._SALPs_CALPs)):
+        if (outmask & (Cs.AZIMUTH | Cs._S_CALPs_)):
             if swap_:
                 salp1, salp2 = salp2, salp1
                 calp1, calp2 = calp2, calp1
@@ -682,7 +686,7 @@ class GeodesicExact(_GeodesicBase):
             if (outmask & Cs.AZIMUTH):
                 r.set_(azi1=_atan2d(salp1, calp1),
                        azi2=_atan2d_reverse(salp2, calp2, reverse=outmask & Cs.REVERSE2))
-            if (outmask & Cs._SALPs_CALPs):
+            if (outmask & Cs._S_CALPs_):
                 r.set_(salp1=salp1, calp1=calp1,
                        salp2=salp2, calp2=calp2)
 
@@ -706,25 +710,13 @@ class GeodesicExact(_GeodesicBase):
         r = self._GDictDirect(lat1, lon1, azi1, arcmode, s12_a12, outmask)
         return r.toDirect9Tuple()
 
-    def _GenDirectLine(self, lat1, lon1, azi1, arcmode, s12_a12, caps, **name):
-        '''(INTERNAL) Helper for C{ArcDirectLine} and C{DirectLine}.
-
-           @return: A L{GeodesicLineExact} instance.
-        '''
-        azi1 = _norm180(azi1)
-        # guard against underflow in salp0.  Also -0 is converted to +0.
-        s, c = _sincos2d(_around(azi1))
-        C    =  caps if arcmode else (caps | Caps.DISTANCE_IN)
-        return _GeodesicLineExact(self, lat1, lon1, azi1, C,
-                                  self._debug, s, c, **name)._GenSet(arcmode, s12_a12)
-
     def _GenInverse(self, lat1, lon1, lat2, lon2, outmask=Caps.STANDARD):
         '''(INTERNAL) The general I{Inverse} geodesic calculation.
 
            @return: L{Inverse10Tuple}C{(a12, s12, salp1, calp1, salp2, calp2,
                                              m12,   M12,   M21,   S12)}.
         '''
-        r = self._GDictInverse(lat1, lon1, lat2, lon2, outmask | Caps._SALPs_CALPs)
+        r = self._GDictInverse(lat1, lon1, lat2, lon2, outmask | Caps._S_CALPs_)
         return r.toInverse10Tuple()
 
     def _Inverse(self, ll1, ll2, wrap, **outmask):
@@ -814,11 +806,9 @@ class GeodesicExact(_GeodesicBase):
                  Python U{Geodesic.InverseLine<https://GeographicLib.SourceForge.io/Python/doc/code.html>}.
         '''
         Cs = Caps
-        r  = self._GDictInverse(lat1, lon1, lat2, lon2, Cs._SALPs_CALPs)  # No need for AZIMUTH
-        C  = (caps | Cs.DISTANCE) if (caps & (Cs.DISTANCE_IN & Cs._OUT_MASK)) else caps
-        azi1 = _atan2d(r.salp1, r.calp1)
-        return _GeodesicLineExact(self, lat1, lon1, azi1, C,  # ensure a12 is distance
-                                  self._debug, r.salp1, r.calp1, **name)._GenSet(True, r.a12)
+        r  = self._GDictInverse(lat1, lon1, lat2, lon2, Cs.AZIMUTH | Cs.DISTANCE | Cs._S_CALPs_)
+        return GeodesicLineExact(self, lat1, lon1, None, caps=caps, _s_calp1=(r.salp1, r.calp1),
+                               **name)._GenSet(self._debug, lat2=lat2, lon2=lon2, **r)
 
     def _InverseArea(self, _meridian, salp1, calp1,  # PYCHOK 9 args
                                       salp2, calp2,
@@ -1129,7 +1119,7 @@ class GeodesicExact(_GeodesicBase):
                  <https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GeodesicExact.html>}
                  and Python U{Geodesic.Line<https://GeographicLib.SourceForge.io/Python/doc/code.html>}.
         '''
-        return _GeodesicLineExact(self, lat1, lon1, azi1, caps, self._debug, **name)
+        return GeodesicLineExact(self, lat1, lon1, azi1, caps=caps, **name)._GenSet(self._debug)
 
     @Property_RO
     def n(self):
@@ -1241,27 +1231,16 @@ class GeodesicExact(_GeodesicBase):
 
     Polygon = Area  # for C{geographiclib} compatibility
 
-    def _sinf1cos2d(self, lat):
-        '''(INTERNAL) Helper, also for C{_G_GeodesicLineExact}.
-        '''
-        sbet, cbet = _sincos2d(lat)
-        # ensure cbet1 = +epsilon at poles; doing the fix on beta means
-        # that sig12 will be <= 2*tiny for two points at the same pole
-        sbet, cbet = _norm2(sbet * self.f1, cbet)
-        return sbet, (cbet if fabs(cbet) > _TINY else _TINY)
-
-    def toStr(self, prec=6, sep=_COMMASPACE_, **unused):  # PYCHOK signature
+    def toStr(self, **prec_sep_name):  # PYCHOK signature
         '''Return this C{GeodesicExact} as string.
 
-           @kwarg prec: The C{float} precision, number of decimal digits (0..9).
-                        Trailing zero decimals are stripped for B{C{prec}} values
-                        of 1 and above, but kept for negative B{C{prec}} values.
-           @kwarg sep: Separator to join (C{str}).
+           @see: L{Ellipsoid.toStr<pygeodesy.ellipsoids.Ellipsoid.toStr>}
+                 for further details.
 
-           @return: Tuple items (C{str}).
+           @return: C{GeodesicExact} (C{str}).
         '''
-        d = dict(ellipsoid=self.ellipsoid, C4order=self.C4order)
-        return sep.join(pairs(d, prec=prec))
+        t = GeodesicExact.caps, GeodesicExact.ellipsoid
+        return self._instr(props=t, C4order=self.C4order, **prec_sep_name)
 
 
 class GeodesicLineExact(_GeodesicLineExact):
@@ -1290,9 +1269,9 @@ class GeodesicLineExact(_GeodesicLineExact):
         '''
         _xinstanceof(GeodesicExact, geodesic=geodesic)
         if (caps & Caps.LINE_OFF):  # copy to avoid updates
-            geodesic = geodesic.copy(deep=False, name=_UNDER_(NN, geodesic.name))  # NOT _under!
+            geodesic = geodesic.copy(deep=False, name=_UNDER_(NN, geodesic.name))
 #           _update_all(geodesic)
-        _GeodesicLineExact.__init__(self, geodesic, lat1, lon1, azi1, caps, 0, **name)
+        _GeodesicLineExact.__init__(self, geodesic, lat1, lon1, azi1, caps, **name)
 
 
 def _Astroid(x, y):

pygeodesy/geodesicx/gxbases.py

@@ -9,19 +9,21 @@ U{GeographicLib<https://GeographicLib.SourceForge.io>} documentation.
 '''
 
 from pygeodesy.basics import isodd,  _MODS
-from pygeodesy.constants import _0_0, _100_0
+from pygeodesy.constants import _EPSmin as _TINY, _0_0, _100_0
 from pygeodesy.errors import _or, _xkwds_item2
 from pygeodesy.fmath import hypot as _hypot
-from pygeodesy.karney import _CapsBase, GeodesicError, _2cos2x, _sum2_
+from pygeodesy.karney import _CapsBase, GeodesicError, _2cos2x, \
+                             _norm2, _sincos2d, _sum2_
 # from pygeodesy.lazily import _MODS, printf  # .basics, _MODS
 
-from math import ldexp as _ldexp
+from math import fabs, ldexp as _ldexp
 
 __all__ = ()
-__version__ = '24.05.19'
+__version__ = '24.06.16'
 
 # valid C{nC4}s and C{C4order}s, see _xnC4 below
 _nC4s = {24: 2900, 27: 4032, 30: 5425}
+# assert (_TINY * EPS) > 0 and (_TINY + EPS) == EPS  # underflow guard
 
 
 class _GeodesicBase(_CapsBase):  # in .geodsolve
@@ -71,15 +73,15 @@ def _cosSeries(c4s, sx, cx):  # PYCHOK shared .geodesicx.gx and -.gxline
     y0  =  t0 = y1 = t1 = _0_0
     c4  =  list(c4s)
     _c4 =  c4.pop
-    _s2 = _sum2_
     if isodd(len(c4)):
         y0 = _c4()
+    _s2 = _sum2_
     while c4:
         # y1 = ar * y0 - y1 + c4.pop()
         # y0 = ar * y1 - y0 + c4.pop()
         y1, t1 = _s2(ar * y0, ar * t0, -y1, -t1, _c4())
         y0, t0 = _s2(ar * y1, ar * t1, -y0, -t0, _c4())
-    # s  = cx * (y0 - y1)
+    # s  = (y0 - y1) * cx
     s, _ = _s2(cx * y0, _0_0, cx * t0, -cx * y1, -cx * t1)
     return s
 
@@ -93,7 +95,7 @@ def _f2(hi, lo):  # in .geodesicx._C4_24, _27 and _30
     return _ldexp(_f(hi), 52) + _f(lo)
 
 
-def _sincos12(sin1, cos1, sin2, cos2, sineg0=False):  # PYCHOK shared
+def _sincos12(sin1, cos1, sin2, cos2, sineg0=False):
     '''(INTERNAL) Compute the sine and cosine of angle
        M{ang12 = atan2(sin2, cos2) - atan2(sin1, cos1)}.
 
@@ -111,7 +113,7 @@ def _sincos12(sin1, cos1, sin2, cos2, sineg0=False):  # PYCHOK shared
     return s, c
 
 
-def _sin1cos2(sin1, cos1, sin2, cos2):  # PYCHOK shared
+def _sin1cos2(sin1, cos1, sin2, cos2):
     '''(INTERNAL) Compute the C{sin1 * cos2} sine and its cosine.
 
        @return: 2-Tuple C{(sin1 * cos2, hypot(sin1 * sin2, cos1)}.
@@ -121,6 +123,16 @@ def _sin1cos2(sin1, cos1, sin2, cos2):  # PYCHOK shared
     return s, c  # _norm2(s, c)
 
 
+def _sinf1cos2d(lat, f1):
+    '''(INTERNAL) See C{GeodesicExact} and C{_GeodesicLineExact}.
+    '''
+    sbet, cbet = _sincos2d(lat)
+    # ensure cbet1 = +epsilon at poles; doing the fix on beta means
+    # that sig12 will be <= 2*tiny for two points at the same pole
+    sbet, cbet = _norm2(sbet * f1, cbet)
+    return sbet, (cbet if fabs(cbet) > _TINY else _TINY)
+
+
 def _xnC4(**name_nC4):
     '''(INTERNAL) Validate C{C4order}.
     '''