pygeodesy 24.10.24__py2.py3-none-any.whl → 24.12.12__py2.py3-none-any.whl

pygeodesy/ellipsoidalExact.py

@@ -24,7 +24,7 @@ from pygeodesy.points import _areaError, ispolar  # PYCHOK exported
 # from math import fabs  # from .karney
 
 __all__ = _ALL_LAZY.ellipsoidalExact
-__version__ = '24.08.13'
+__version__ = '24.11.06'
 
 
 class Cartesian(CartesianEllipsoidalBase):
@@ -119,30 +119,28 @@ def areaOf(points, datum=_WGS84, wrap=True):
 
 
 def intersection3(start1, end1, start2, end2, height=None, wrap=False,  # was=True
-                  equidistant=None, tol=_TOL_M, LatLon=LatLon, **LatLon_kwds):
-    '''I{Iteratively} compute the intersection point of two lines, each defined
-       by two (ellipsoidal) points or by an (ellipsoidal) start point and an
-       initial bearing from North.
+                                equidistant=None, tol=_TOL_M, **LatLon_and_kwds):
+    '''I{Iteratively} compute the intersection point of two geodesic lines, each
+       given as two points or as an start point and a bearing from North.
 
        @arg start1: Start point of the first line (L{LatLon}).
        @arg end1: End point of the first line (L{LatLon}) or the initial bearing
-                  at the first point (compass C{degrees360}).
+                  at B{C{start1}} (compass C{degrees360}).
        @arg start2: Start point of the second line (L{LatLon}).
        @arg end2: End point of the second line (L{LatLon}) or the initial bearing
-                  at the second point (compass C{degrees360}).
+                  at B{C{start2}} (compass C{degrees360}).
        @kwarg height: Optional height at the intersection (C{meter}, conventionally)
                       or C{None} for the mean height.
-       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the B{C{start2}}
-                    and B{C{end*}} points (C{bool}).
+       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll B{C{start2}} and
+                    both B{C{end*}} points (C{bool}).
        @kwarg equidistant: An azimuthal equidistant projection (I{class} or function
                            L{pygeodesy.equidistant}) or C{None} for the preferred
                            C{B{start1}.Equidistant}.
        @kwarg tol: Tolerance for convergence and for skew line distance and length
                    (C{meter}, conventionally).
-       @kwarg LatLon: Optional class to return the intersection points (L{LatLon})
-                      or C{None}.
-       @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword arguments,
-                           ignored if C{B{LatLon} is None}.
+       @kwarg LatLon_and_kwds: Optional class C{B{LatLon}=}L{LatLon} to return the
+                     intersection points and optionally, additional B{C{LatLon}}
+                     keyword arguments, ignored if C{B{LatLon}=None}.
 
        @return: An L{Intersection3Tuple}C{(point, outside1, outside2)} with C{point}
                 a B{C{LatLon}} or if C{B{LatLon} is None}, a L{LatLon4Tuple}C{(lat,
@@ -154,23 +152,23 @@ def intersection3(start1, end1, start2, end2, height=None, wrap=False,  # was=Tr
        @raise TypeError: Invalid or non-ellipsoidal B{C{start1}}, B{C{end1}},
                          B{C{start2}} or B{C{end2}} or invalid B{C{equidistant}}.
 
-       @note: For each line specified with an initial bearing, a pseudo-end point
-              is computed as the C{destination} along that bearing at about 1.5
-              times the distance from the start point to an initial gu-/estimate
-              of the intersection point (and between 1/8 and 3/8 of the authalic
-              earth perimeter).
+       @note: For each line specified with an initial bearing, a pseudo-end point is
+              computed as the C{destination} along that bearing at about 1.5 times the
+              distance from the start point to an initial gu-/estimate of the intersection
+              point (and between 1/8 and 3/8 of the authalic earth perimeter).
 
        @see: U{The B{ellipsoidal} case<https://GIS.StackExchange.com/questions/48937/
              calculating-intersection-of-two-circles>} and U{Karney's paper
              <https://ArXiv.org/pdf/1102.1215.pdf>}, pp 20-21, section B{14. MARITIME
              BOUNDARIES} for more details about the iteration algorithm.
     '''
+    kwds = _xkwds(LatLon_and_kwds, LatLon=LatLon)
     return _intersection3(start1, end1, start2, end2, height=height, wrap=wrap,
-                          equidistant=equidistant, tol=tol, LatLon=LatLon, **LatLon_kwds)
+                                        equidistant=equidistant, tol=tol, **kwds)
 
 
 def intersections2(center1, radius1, center2, radius2, height=None, wrap=False,  # was=True
-                   equidistant=None, tol=_TOL_M, LatLon=LatLon, **LatLon_kwds):
+                                     equidistant=None, tol=_TOL_M, **LatLon_and_kwds):
     '''I{Iteratively} compute the intersection points of two circles, each defined
        by an (ellipsoidal) center point and a radius.
 
@@ -189,10 +187,9 @@ def intersections2(center1, radius1, center2, radius2, height=None, wrap=False,
                            the preferred C{B{center1}.Equidistant}.
        @kwarg tol: Convergence tolerance (C{meter}, same units as B{C{radius1}}
                    and B{C{radius2}}).
-       @kwarg LatLon: Optional class to return the intersection points (L{LatLon})
-                      or C{None}.
-       @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword arguments,
-                           ignored if C{B{LatLon} is None}.
+       @kwarg LatLon_and_kwds: Optional class C{B{LatLon}=}L{LatLon} to return the
+                     intersection points and optionally, additional B{C{LatLon}}
+                     keyword arguments, ignored if C{B{LatLon}=None}.
 
        @return: 2-Tuple of the intersection points, each a B{C{LatLon}} instance
                 or L{LatLon4Tuple}C{(lat, lon, height, datum)} if C{B{LatLon} is
@@ -214,8 +211,9 @@ def intersections2(center1, radius1, center2, radius2, height=None, wrap=False,
              U{sphere-sphere<https://MathWorld.Wolfram.com/Sphere-SphereIntersection.html>}
              intersections.
     '''
+    kwds = _xkwds(LatLon_and_kwds, LatLon=LatLon)
     return _intersections2(center1, radius1, center2, radius2, height=height, wrap=wrap,
-                           equidistant=equidistant, tol=tol, LatLon=LatLon, **LatLon_kwds)
+                                             equidistant=equidistant, tol=tol, **kwds)
 
 
 def isclockwise(points, datum=_WGS84, wrap=True):
@@ -245,9 +243,9 @@ def isclockwise(points, datum=_WGS84, wrap=True):
 
 
 def nearestOn(point, point1, point2, within=True, height=None, wrap=False,
-              equidistant=None, tol=_TOL_M, LatLon=LatLon, **LatLon_kwds):
-    '''I{Iteratively} locate the closest point on the geodesic between
-       two other (ellispoidal) points.
+                     equidistant=None, tol=_TOL_M, **LatLon_and_kwds):
+    '''I{Iteratively} locate the closest point on the geodesic (line)
+       between two other (ellipsoidal) points.
 
        @arg point: Reference point (C{LatLon}).
        @arg point1: Start point of the geodesic (C{LatLon}).
@@ -265,16 +263,15 @@ def nearestOn(point, point1, point2, within=True, height=None, wrap=False,
                            or function L{pygeodesy.equidistant}) or C{None}
                            for the preferred C{B{point}.Equidistant}.
        @kwarg tol: Convergence tolerance (C{meter}).
-       @kwarg LatLon: Optional class to return the closest point
-                      (L{LatLon}) or C{None}.
-       @kwarg LatLon_kwds: Optional, additional B{C{LatLon}} keyword
-                           arguments, ignored if C{B{LatLon} is None}.
+       @kwarg LatLon_and_kwds: Optional class C{B{LatLon}=}L{LatLon} to return the
+                     closest point and optionally, additional B{C{LatLon}} keyword
+                     arguments, ignored if C{B{LatLon}=None}.
 
-       @return: Closest point, a B{C{LatLon}} instance or if C{B{LatLon}
-                is None}, a L{LatLon4Tuple}C{(lat, lon, height, datum)}.
+       @return: Closest point, a B{C{LatLon}} instance or if C{B{LatLon} is None},
+                a L{LatLon4Tuple}C{(lat, lon, height, datum)}.
 
-       @raise TypeError: Invalid or non-ellipsoidal B{C{point}}, B{C{point1}}
-                         or B{C{point2}} or invalid B{C{equidistant}}.
+       @raise TypeError: Invalid or non-ellipsoidal B{C{point}}, B{C{point1}} or
+                         B{C{point2}} or invalid B{C{equidistant}}.
 
        @raise ValueError: No convergence for the B{C{tol}}.
 
@@ -283,8 +280,9 @@ def nearestOn(point, point1, point2, within=True, height=None, wrap=False,
              <https://ArXiv.org/pdf/1102.1215.pdf>}, pp 20-21, section B{14. MARITIME
              BOUNDARIES} for more details about the iteration algorithm.
     '''
+    kwds = _xkwds(LatLon_and_kwds, LatLon=LatLon)
     return _nearestOn(point, point1, point2, within=within, height=height, wrap=wrap,
-                      equidistant=equidistant, tol=tol, LatLon=LatLon, **LatLon_kwds)
+                                             equidistant=equidistant, tol=tol, **kwds)
 
 
 def perimeterOf(points, closed=False, datum=_WGS84, wrap=True):
@@ -322,7 +320,7 @@ __all__ += _ALL_OTHER(Cartesian, LatLon,  # classes
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/ellipsoidalGeodSolve.py

@@ -314,7 +314,7 @@ __all__ += _ALL_OTHER(Cartesian, LatLon,  # classes
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/ellipsoidalKarney.py

@@ -359,7 +359,7 @@ __all__ += _ALL_OTHER(Cartesian, LatLon,  # classes
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/ellipsoidalNvector.py

@@ -657,7 +657,7 @@ __all__ += _ALL_OTHER(Cartesian, LatLon, Ned, Nvector,  # classes
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/ellipsoidalVincenty.py

@@ -67,12 +67,13 @@ from pygeodesy.props import deprecated_function, deprecated_method, \
                             property_doc_, property_RO
 # from pygeodesy.streprs import Fmt  # from .points
 from pygeodesy.units import Number_, Scalar_
-from pygeodesy.utily import atan2b, atan2d, sincos2, sincos2d, unroll180, wrap180
+from pygeodesy.utily import atan2, atan2b, atan2d, sincos2, sincos2d, \
+                            unroll180, wrap180
 
-from math import atan2, cos, degrees, fabs, radians, tan
+from math import cos, degrees, fabs, radians, tan as _tan
 
 __all__ = _ALL_LAZY.ellipsoidalVincenty
-__version__ = '24.10.12'
+__version__ = '24.11.26'
 
 _antipodal_to_ = _SPACE_(_antipodal_, _to_)
 
@@ -383,7 +384,7 @@ def _sincos22(sa):
 def _sincostan3r(a, f):
     # I{Reduced} 3-tuple C{(sin(B{a}), cos(B{a}), tan(B{a}))}
     if a:  # see L{sincostan3}
-        t = (_1_0 - f) * tan(a)
+        t = (_1_0 - f) * _tan(a)
         if t:
             c = _1_0 / hypot1(t)
             s =  c * t
@@ -567,7 +568,7 @@ __all__ += _ALL_DOCS(Cartesian, LatLon, intersecant2,  # from .ellipsoidalBaseDI
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/ellipsoids.py

@@ -90,10 +90,10 @@ from pygeodesy.units import Bearing_, Distance, Float, Float_, Height, Lamd, Lat
                             Meter2, Meter3, Phi, Phid, Radius, Radius_, Scalar
 from pygeodesy.utily import atan1, atan1d, atan2b, degrees90, m2radians, radians2m, sincos2d
 
-from math import asinh, atan, atanh, cos, degrees, exp, fabs, radians, sin, sinh, sqrt, tan
+from math import asinh, atan, atanh, cos, degrees, exp, fabs, radians, sin, sinh, sqrt, tan  # as _tan
 
 __all__ = _ALL_LAZY.ellipsoids
-__version__ = '24.10.15'
+__version__ = '24.11.26'
 
 _f_0_0    = Float(f =_0_0)  # zero flattening
 _f__0_0   = Float(f_=_0_0)  # zero inverse flattening
@@ -660,8 +660,7 @@ class Ellipsoid(_NamedEnumItem):
 
            @arg lat: Geodetic latitude (C{degrees90}, C{str}).
 
-           @return: A L{Circle4Tuple}C{(radius, height, lat, beta)}
-                    instance.
+           @return: A L{Circle4Tuple}C{(radius, height, lat, beta)}.
 
            @raise RangeError: Latitude B{C{lat}} outside valid range and
                               L{rangerrors<pygeodesy.rangerrors>} is C{True}.
@@ -811,9 +810,9 @@ class Ellipsoid(_NamedEnumItem):
 
     eccentricity     = e    # eccentricity
 #   eccentricity2    = e2   # eccentricity squared
-    eccentricity1st2 = e2   # first eccentricity squared
-    eccentricity2nd2 = e22  # second eccentricity squared
-    eccentricity3rd2 = e32  # third eccentricity squared
+    eccentricity1st2 = e2   # first eccentricity squared, signed
+    eccentricity2nd2 = e22  # second eccentricity squared, signed
+    eccentricity3rd2 = e32  # third eccentricity squared, signed
 
     def ecef(self, Ecef=None):
         '''Return U{ECEF<https://WikiPedia.org/wiki/ECEF>} converter.
@@ -2427,7 +2426,7 @@ if __name__ == '__main__':
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/elliptic.py

@@ -24,7 +24,7 @@ Following is a copy of I{Karney}'s U{EllipticFunction.hpp
 <https://GeographicLib.SourceForge.io/C++/doc/EllipticFunction_8hpp_source.html>}
 file C{Header}.
 
-Copyright (C) U{Charles Karney<mailto:Karney@Alum.MIT.edu>} (2008-2023)
+Copyright (C) U{Charles Karney<mailto:Karney@Alum.MIT.edu>} (2008-2024)
 and licensed under the MIT/X11 License.  For more information, see the
 U{GeographicLib<https://GeographicLib.SourceForge.io>} documentation.
 
@@ -93,13 +93,13 @@ from pygeodesy.named import _Named, _NamedTuple,  _ALL_LAZY, Fmt, unstr
 from pygeodesy.props import _allPropertiesOf_n, Property_RO, _update_all
 # from pygeodesy.streprs import Fmt, unstr  # from .named
 from pygeodesy.units import Scalar, Scalar_
-# from pygeodesy.utily import sincos2 as _sincos2  # from .karney
+from pygeodesy.utily import atan2  # sincos2 as _sincos2
 
-from math import asin, asinh, atan, atan2, ceil, cosh, fabs, floor, \
-                 radians, sin, sinh, sqrt, tan, tanh
+from math import asin, asinh, atan, ceil, cosh, fabs, floor, radians, \
+                 sin, sinh, sqrt, tan, tanh  # tan as _tan
 
 __all__ = _ALL_LAZY.elliptic
-__version__ = '24.10.14'
+__version__ = '24.11.26'
 
 _TolRD  =  zqrt(EPS * 0.002)
 _TolRF  =  zqrt(EPS * 0.030)
@@ -1246,7 +1246,7 @@ def _RJ(inst, x, y, z, p, *over):
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/epsg.py

@@ -223,7 +223,7 @@ __all__ += _ALL_DOCS(decode2, encode)
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

pygeodesy/errors.py

@@ -27,7 +27,7 @@ from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS, _PYTHON_X_DEV
 from copy import copy as _copy
 
 __all__ = _ALL_LAZY.errors  # _ALL_DOCS('_InvalidError', '_IsnotError')  _under
-__version__ = '24.10.14'
+__version__ = '24.11.02'
 
 _argument_   = 'argument'
 _box_        = 'box'
@@ -777,7 +777,7 @@ except AttributeError:
         return d
 
 
-# def _xkwds_bool(inst, **kwds):  # no longer in .frechet, .hausdorff, .heights
+# def _xkwds_bool(inst, **kwds):  # unused
 #     '''(INTERNAL) Set applicable C{bool} properties/attributes.
 #     '''
 #     for n, v in kwds.items():
@@ -789,18 +789,18 @@ except AttributeError:
 #             setattr(inst, NN(_UNDER_, n), v)
 
 
-def _xkwds_from(orig, *args, **kwds):
-    '''(INTERNAL) Return the items from C{orig} with the keys
-       from C{kwds} and a value not in C{args} and C{kwds}.
-    '''
-    def _items(orig, args, items):
-        for n, m in items:
-            if n in orig:  # n in (orig.keys() & kwds.keys())
-                t = orig[n]
-                if t is not m and t not in args:
-                    yield n, t
-
-    return _items(orig, args, kwds.items())
+# def _xkwds_from(orig, *args, **kwds):  # unused
+#     '''(INTERNAL) Return the items from C{orig} with the keys
+#        from C{kwds} and a value not in C{args} and C{kwds}.
+#     '''
+#     def _items(orig, args, items):
+#         for n, m in items:
+#             if n in orig:  # n in (orig.keys() & kwds.keys())
+#                 t = orig[n]
+#                 if t is not m and t not in args:
+#                     yield n, t
+#
+#     return _items(orig, args, kwds.items())
 
 
 def _xkwds_get(kwds, **name_default):
@@ -813,14 +813,14 @@ def _xkwds_get(kwds, **name_default):
     raise _xAssertionError(_xkwds_get, kwds, **name_default)
 
 
-def _xkwds_get_(kwds, **names_defaults):
-    '''(INTERNAL) Yield each C{kwds} value or its C{default}
-       in I{case-insensitive, alphabetical} C{name} order.
-    '''
-    if not isinstance(kwds, dict):
-        raise _xAssertionError(_xkwds_get_, kwds)
-    for n, v in _MODS.basics.itemsorted(names_defaults):
-        yield kwds.get(n, v)
+# def _xkwds_get_(kwds, **names_defaults):  # unused
+#     '''(INTERNAL) Yield each C{kwds} value or its C{default}
+#        in I{case-insensitive, alphabetical} C{name} order.
+#     '''
+#     if not isinstance(kwds, dict):
+#         raise _xAssertionError(_xkwds_get_, kwds)
+#     for n, v in _MODS.basics.itemsorted(names_defaults):
+#         yield kwds.get(n, v)
 
 
 def _xkwds_get1(kwds, **name_default):
@@ -844,11 +844,11 @@ def _xkwds_item2(kwds):
     raise _xAssertionError(_xkwds_item2, kwds)
 
 
-def _xkwds_kwds(kwds, **names_defaults):
+def _xkwds_kwds(kwds, **names_defaults):  # in .geodesici  # PYCHOK no cover
     '''(INTERNAL) Return a C{dict} of C{named_defaults} items replaced with C{kwds}.
     '''
     if not isinstance(kwds, dict):
-        raise _xAssertionError(_xkwds_get_, kwds)
+        raise _xAssertionError(_xkwds_kwds, kwds)
     _g = kwds.get
     return dict((n, _g(n, v)) for n, v in names_defaults.items())
 
@@ -914,7 +914,7 @@ def _xStrError(*Refs, **name_value_Error):  # in .gars, .geohash, .wgrs
 
 # **) MIT License
 #
-# Copyright (C) 2016-2024 -- mrJean1 at Gmail -- All Rights Reserved.
+# Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),