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

pygeodesy/ellipsoidalGeodSolve.py

@@ -24,7 +24,7 @@ from pygeodesy.points import _areaError, ispolar  # PYCHOK exported
 # from math import fabs  # from .karney
 
 __all__ = _ALL_LAZY.ellipsoidalGeodSolve
-__version__ = '24.08.13'
+__version__ = '25.05.28'
 
 
 class Cartesian(CartesianEllipsoidalBase):
@@ -87,12 +87,16 @@ class LatLon(LatLonEllipsoidalBaseDI):
         return LatLonEllipsoidalBaseDI.toCartesian(self, **kwds)
 
 
-def areaOf(points, datum=_WGS84, wrap=True):
+def areaOf(points, datum=_WGS84, wrap=True, polar=False):
     '''Compute the area of an (ellipsoidal) polygon or composite.
 
        @arg points: The polygon points (L{LatLon}[], L{BooleanFHP} or L{BooleanGH}).
        @kwarg datum: Optional datum (L{Datum}).
        @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the B{C{points}} (C{bool}).
+       @kwarg polar: Use C{B{polar}=True} if the polygon encloses a pole (C{bool}), see
+                     function L{ispolar<pygeodesy.points.ispolar>} and U{area of a polygon
+                     enclosing a pole<https://GeographicLib.SourceForge.io/C++/doc/
+                     classGeographicLib_1_1GeodesicExact.html#a3d7a9155e838a09a48dc14d0c3fac525>}.
 
        @return: Area (C{meter}, same as units of the B{C{datum}}'s ellipsoid axes, I{squared}).
 
@@ -105,7 +109,7 @@ def areaOf(points, datum=_WGS84, wrap=True):
        @see: Functions L{pygeodesy.areaOf}, L{ellipsoidalExact.areaOf}, L{ellipsoidalKarney.areaOf},
              L{sphericalNvector.areaOf} and L{sphericalTrigonometry.areaOf}.
     '''
-    return fabs(_polygon(datum.ellipsoid.geodsolve, points, True, False, wrap))
+    return fabs(_polygon(datum.ellipsoid.geodsolve, points, True, False, wrap, polar))
 
 
 def intersection3(start1, end1, start2, end2, height=None, wrap=False,  # was=True
@@ -209,13 +213,14 @@ def intersections2(center1, radius1, center2, radius2, height=None, wrap=False,
                            equidistant=equidistant, tol=tol, LatLon=LatLon, **LatLon_kwds)
 
 
-def isclockwise(points, datum=_WGS84, wrap=True):
+def isclockwise(points, datum=_WGS84, wrap=True, polar=False):
     '''Determine the direction of a path or polygon.
 
        @arg points: The path or polygon points (C{LatLon}[]).
        @kwarg datum: Optional datum (L{Datum}).
-       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the
-                    B{C{points}} (C{bool}).
+       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the B{C{points}} (C{bool}).
+       @kwarg polar: Use C{B{polar}=True} if the C{B{points}} enclose a pole (C{bool}),
+                     see function U{ispolar<pygeodeys.points.ispolar>}.
 
        @return: C{True} if B{C{points}} are clockwise, C{False} otherwise.
 
@@ -223,12 +228,11 @@ def isclockwise(points, datum=_WGS84, wrap=True):
 
        @raise TypeError: Some B{C{points}} are not C{LatLon}.
 
-       @raise ValueError: The B{C{points}} enclose a pole or zero
-                          area.
+       @raise ValueError: The B{C{points}} enclose a pole or zero area.
 
        @see: L{pygeodesy.isclockwise}.
     '''
-    a = _polygon(datum.ellipsoid.geodsolve, points, True, False, wrap)
+    a = _polygon(datum.ellipsoid.geodsolve, points, True, False, wrap, polar)
     if a < 0:
         return True
     elif a > 0:
@@ -282,29 +286,25 @@ def nearestOn(point, point1, point2, within=True, height=None, wrap=False,
 def perimeterOf(points, closed=False, datum=_WGS84, wrap=True):
     '''Compute the perimeter of an (ellipsoidal) polygon or composite.
 
-       @arg points: The polygon points (L{LatLon}[], L{BooleanFHP} or
-                    L{BooleanGH}).
+       @arg points: The polygon points (L{LatLon}[], L{BooleanFHP} or L{BooleanGH}).
        @kwarg closed: Optionally, close the polygon (C{bool}).
        @kwarg datum: Optional datum (L{Datum}).
-       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the
-                    B{C{points}} (C{bool}).
+       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the B{C{points}} (C{bool}).
 
-       @return: Perimeter (C{meter}, same as units of the B{C{datum}}'s
-                ellipsoid axes).
+       @return: Perimeter (C{meter}, same as units of the B{C{datum}}'s ellipsoid axes).
 
        @raise PointsError: Insufficient number of B{C{points}}.
 
        @raise TypeError: Some B{C{points}} are not L{LatLon}.
 
-       @raise ValueError: Invalid C{B{wrap}=False}, unwrapped, unrolled
-                          longitudes not supported or C{B{closed}=False}
-                          with C{B{points}} a composite.
+       @raise ValueError: Invalid C{B{wrap}=False}, unwrapped, unrolled longitudes not
+                          supported or C{B{closed}=False} with C{B{points}} a composite.
 
        @see: Functions L{pygeodesy.perimeterOf}, L{ellipsoidalExact.perimeterOf},
              L{ellipsoidalKarney.perimeterOf}, L{sphericalNvector.perimeterOf}
              and L{sphericalTrigonometry.perimeterOf}.
     '''
-    return _polygon(datum.ellipsoid.geodsolve, points, closed, True, wrap)
+    return _polygon(datum.ellipsoid.geodsolve, points, closed, True, wrap, False)
 
 
 __all__ += _ALL_OTHER(Cartesian, LatLon,  # classes

pygeodesy/ellipsoidalKarney.py

@@ -42,7 +42,7 @@ from pygeodesy.props import deprecated_method, Property_RO
 # from math import fabs  # from .karney
 
 __all__ = _ALL_LAZY.ellipsoidalKarney
-__version__ = '24.08.13'
+__version__ = '25.05.27'
 
 
 class Cartesian(CartesianEllipsoidalBase):
@@ -110,13 +110,17 @@ class LatLon(LatLonEllipsoidalBaseDI):
         return LatLonEllipsoidalBaseDI.toCartesian(self, **kwds)
 
 
-def areaOf(points, datum=_WGS84, wrap=True):
+def areaOf(points, datum=_WGS84, wrap=True, polar=False):
     '''Compute the area of an (ellipsoidal) polygon or composite using I{Karney}'s
        U{geographiclib<https://PyPI.org/project/geographiclib>} package.
 
        @arg points: The polygon points (L{LatLon}[], L{BooleanFHP} or L{BooleanGH}).
        @kwarg datum: Optional datum (L{Datum}).
        @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the B{C{points}} (C{bool}).
+       @kwarg polar: Use C{B{polar}=True} if the polygon encloses a pole (C{bool}), see
+                     function L{ispolar<pygeodesy.points.ispolar>} and U{area of a polygon
+                     enclosing a pole<https://GeographicLib.SourceForge.io/C++/doc/
+                     classGeographicLib_1_1GeodesicExact.html#a3d7a9155e838a09a48dc14d0c3fac525>}.
 
        @return: Area (C{meter}, same as units of the B{C{datum}}'s ellipsoid axes, I{squared}).
 
@@ -131,12 +135,8 @@ def areaOf(points, datum=_WGS84, wrap=True):
 
        @see: Functions L{pygeodesy.areaOf}, L{ellipsoidalExact.areaOf}, L{ellipsoidalGeodSolve.areaOf},
              L{sphericalNvector.areaOf} and L{sphericalTrigonometry.areaOf}.
-
-       @note: The U{area of a polygon enclosing a pole<https://GeographicLib.SourceForge.io/
-              C++/doc/classGeographicLib_1_1GeodesicExact.html#a3d7a9155e838a09a48dc14d0c3fac525>}
-              can be found by adding half the datum's ellipsoid surface area to the polygon's area.
     '''
-    return fabs(_polygon(datum.ellipsoid.geodesic, points, True, False, wrap))
+    return fabs(_polygon(datum.ellipsoid.geodesic, points, True, False, wrap, polar))
 
 
 def intersection3(start1, end1, start2, end2, height=None, wrap=False,  # was=True
@@ -240,19 +240,19 @@ def intersections2(center1, radius1, center2, radius2, height=None, wrap=False,
                            equidistant=equidistant, tol=tol, LatLon=LatLon, **LatLon_kwds)
 
 
-def isclockwise(points, datum=_WGS84, wrap=True):
+def isclockwise(points, datum=_WGS84, wrap=True, polar=False):
     '''Determine the direction of a path or polygon using I{Karney}'s
        U{geographiclib<https://PyPI.org/project/geographiclib>} package.
 
        @arg points: The path or polygon points (C{LatLon}[]).
        @kwarg datum: Optional datum (L{Datum}).
-       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the
-                    B{C{points}} (C{bool}).
+       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the B{C{points}} (C{bool}).
+       @kwarg polar: Use C{B{polar}=True} if the C{B{points}} enclose a pole (C{bool}),
+                     see function U{ispolar<pygeodeys.points.ispolar>}.
 
        @return: C{True} if B{C{points}} are clockwise, C{False} otherwise.
 
-       @raise ImportError: Package U{geographiclib
-                           <https://PyPI.org/project/geographiclib>}
+       @raise ImportError: Package U{geographiclib<https://PyPI.org/project/geographiclib>}
                            not installed or not found.
 
        @raise PointsError: Insufficient number of B{C{points}}.
@@ -263,7 +263,7 @@ def isclockwise(points, datum=_WGS84, wrap=True):
 
        @see: L{pygeodesy.isclockwise}.
     '''
-    a = _polygon(datum.ellipsoid.geodesic, points, True, False, wrap)
+    a = _polygon(datum.ellipsoid.geodesic, points, True, False, wrap, polar)
     if a < 0:
         return True
     elif a > 0:
@@ -322,34 +322,29 @@ def perimeterOf(points, closed=False, datum=_WGS84, wrap=True):
     '''Compute the perimeter of an (ellipsoidal) polygon or composite using I{Karney}'s
        U{geographiclib<https://PyPI.org/project/geographiclib>} package.
 
-       @arg points: The polygon points (L{LatLon}[], L{BooleanFHP} or
-                    L{BooleanGH}).
+       @arg points: The polygon points (L{LatLon}[], L{BooleanFHP} or L{BooleanGH}).
        @kwarg closed: Optionally, close the polygon (C{bool}).
        @kwarg datum: Optional datum (L{Datum}).
-       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the
-                    B{C{points}} (C{bool}).
+       @kwarg wrap: If C{True}, wrap or I{normalize} and unroll the B{C{points}} (C{bool}).
 
-       @return: Perimeter (C{meter}, same as units of the B{C{datum}}'s
-                ellipsoid axes).
+       @return: Perimeter (C{meter}, same as units of the B{C{datum}}'s ellipsoid axes).
 
-       @raise ImportError: Package U{geographiclib
-                           <https://PyPI.org/project/geographiclib>}
+       @raise ImportError: Package U{geographiclib<https://PyPI.org/project/geographiclib>}
                            not installed or not found.
 
        @raise PointsError: Insufficient number of B{C{points}}.
 
-       @raise TypeError: Some B{C{points}} are not L{LatLon} or C{B{closed}=False}
-                         with B{C{points}} a composite.
+       @raise TypeError: Some B{C{points}} are not L{LatLon} or C{B{closed}=False} with
+                         B{C{points}} a composite.
 
-       @raise ValueError: Invalid C{B{wrap}=False}, unwrapped, unrolled
-                          longitudes not supported or C{B{closed}=False}
-                          with C{B{points}} a composite.
+       @raise ValueError: Invalid C{B{wrap}=False}, unwrapped, unrolled longitudes not
+                          supported or C{B{closed}=False} with C{B{points}} a composite.
 
        @see: Functions L{pygeodesy.perimeterOf}, L{ellipsoidalExact.perimeterOf},
              L{ellipsoidalGeodSolve.perimeterOf}, L{sphericalNvector.perimeterOf}
              and L{sphericalTrigonometry.perimeterOf}.
     '''
-    return _polygon(datum.ellipsoid.geodesic, points, closed, True, wrap)
+    return _polygon(datum.ellipsoid.geodesic, points, closed, True, wrap, False)
 
 
 __all__ += _ALL_OTHER(Cartesian, LatLon,  # classes

pygeodesy/ellipsoidalVincenty.py

@@ -76,7 +76,7 @@ from pygeodesy.utily import atan2, atan2b, atan2d, sincos2, sincos2d, \
 from math import cos, degrees, fabs, radians, tan as _tan
 
 __all__ = _ALL_LAZY.ellipsoidalVincenty
-__version__ = '25.05.23'
+__version__ = '25.05.26'
 
 _antipodal_to_ = _SPACE_(_antipodal_, _to_)
 
@@ -349,13 +349,6 @@ def _c2sm2(c2sm):
     return c2sm**2 * _2_0 - _1_0
 
 
-def _ellipsoidal():  # helper for areaOf and perimeterOf
-    try:
-        return _MODS.ellipsoidalKarney
-    except ImportError:
-        return _MODS.ellipsoidalExact
-
-
 def _Dl(f, ca2, sa, s, cs, ss, c2sm, dl=_0_0):
     # C{Dl}
     if f and sa:
@@ -385,6 +378,14 @@ def _Ecef():
     return E
 
 
+def _ellipsoidalOf(_Of, points, **kwds):  # helper for DEPRECATED areaOf and perimeterOf
+    try:
+        r = getattr(_MODS.ellipsoidalKarney, _Of.__name__)(points, **kwds)
+    except ImportError:  # no geographiclib
+        r = getattr(_MODS.ellipsoidalExact, _Of.__name__)(points, **kwds)
+    return r
+
+
 def _sincos22(sa):
     # 2-Tuple C{(sin(a), cos(a)**2)}
     ca2 = _1_0 - sa**2
@@ -403,10 +404,10 @@ def _sincostan3r(a, f):
 
 
 @deprecated_function
-def areaOf(points, **datum_wrap):
+def areaOf(points, **datum_wrap_polar):
     '''DEPRECATED, use function L{ellipsoidalExact.areaOf} or L{ellipsoidalKarney.areaOf}.
     '''
-    return _ellipsoidal().areaOf(points, **datum_wrap)
+    return _ellipsoidalOf(areaOf, points, **datum_wrap_polar)
 
 
 def intersection3(start1, end1, start2, end2, height=None, wrap=False,  # was=True
@@ -562,7 +563,7 @@ def nearestOn(point, point1, point2, within=True, height=None, wrap=False,
 def perimeterOf(points, **closed_datum_wrap):
     '''DEPRECATED, use function L{ellipsoidalExact.perimeterOf} or L{ellipsoidalKarney.perimeterOf}.
     '''
-    return _ellipsoidal().perimeterOf(points, **closed_datum_wrap)
+    return _ellipsoidalOf(perimeterOf, points, **closed_datum_wrap)
 
 
 __all__ += _ALL_DOCS(Cartesian, LatLon, intersecant2,  # from .ellipsoidalBaseDI