pygeodesy.ellipsoidalExact

Package pygeodesy :: Module ellipsoidalExact |
[frames] | no frames]

# Module ellipsoidalExact

Exact ellipsoidal geodesy using Karney's Exact Geodesic.

Ellipsoidal geodetic (lat-/longitude) LatLon and geocentric (ECEF) Cartesian classes and functions areaOf, intersections2, isclockwise, nearestOn and perimeterOf based on classes GeodesicExact, GeodesicAreaExact and GeodesicLineExact.

Version: 25.08.28

Classes
| Cartesian Extended to convert exact Cartesian to exact LatLon points.
| LatLon An ellipsoidal LatLon like ellipsoidalKarney.LatLon but using exact geodesic classes GeodesicExact and GeodesicLineExact to compute geodesic distances, bearings (azimuths), etc.

Functions
intersecant2(center, circle, point, other, **exact_height_wrap_tol) Compute the intersections of a circle and a geodesic given as two points or as a point and (forward) bearing. |
ispolar(points, wrap=False) Check whether a polygon encloses a pole. |
areaOf(points, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True, polar=False) Compute the area of an (ellipsoidal) polygon or composite. |
intersection3(start1, end1, start2, end2, height=None, wrap=False, equidistant=None, tol=0.001, **LatLon_and_kwds) Iteratively compute the intersection point of two geodesic lines, each given as two points or as an start point and a bearing from North. |
intersections2(center1, radius1, center2, radius2, height=None, wrap=False, equidistant=None, tol=0.001, **LatLon_and_kwds) Iteratively compute the intersection points of two circles, each defined by an (ellipsoidal) center point and a radius. |
isclockwise(points, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True, polar=False) Determine the direction of a path or polygon. |
nearestOn(point, point1, point2, within=True, height=None, wrap=False, equidistant=None, tol=0.001, **LatLon_and_kwds) Iteratively locate the closest point on the geodesic (line) between two other (ellipsoidal) points. |
perimeterOf(points, closed=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True) Compute the perimeter of an (ellipsoidal) polygon or composite. |

Variables
| __all__ = `_ALL_LAZY.ellipsoidalExact`

Function Details

### intersecant2 (center, circle, point, other, **exact_height_wrap_tol) |
Compute the intersections of a circle and a geodesic given as two points or as a point and (forward) bearing. Arguments: `center` - Center of the circle (`LatLon`). `circle` - Radius of the circle (`meter`, conventionally) or a point on the circle (`LatLon`, as `center`). `point` - A point of the geodesic (`LatLon`, as `center`). `other` - An other point of the geodesic (`LatLon`, as `center`) or the (forward) bearing at the `point` (compass `degrees`). `exact_height_wrap_tol` - Optional keyword arguments `exact=False`, `height=None`, `wrap=False` and `tol`, see method intersecant2. Raises: `NotImplementedError` - Method `intersecant2` not available. `TypeError` - If `center`, `point` or `circle` or `other` points not ellipsoidal or not compatible with `center`. See Also: Method `LatLon.intersecant2` of class ellipsoidalExact.LatLon, ellipsoidalKarney.LatLon or ellipsoidalVincenty.LatLon.

### ispolar (points, wrap=False) |
Check whether a polygon encloses a pole. Arguments: `points` - The polygon points (`LatLon`[]). `wrap` - If `True`, wrap or normalize and unroll the `points` (`bool`). Returns: `True` if the polygon encloses a pole, `False` otherwise. Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon` or don't have `bearingTo2`, `initialBearingTo` and `finalBearingTo` methods.

### areaOf (points, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True, polar=False) |
Compute the area of an (ellipsoidal) polygon or composite. Arguments: `points` - The polygon points (LatLon[], BooleanFHP or BooleanGH). `datum` - Optional datum (Datum). `wrap` - If `True`, wrap or normalize and unroll the `points` (`bool`). `polar` - Use `polar=True` if the polygon encloses a pole (`bool`), see function ispolar and area of a polygon enclosing a pole. Returns: Area (`meter` squared, same units as the `datum`'s ellipsoid axes). Raises: `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not LatLon. `ValueError` - Invalid `wrap=False`, unwrapped, unrolled longitudes not supported. See Also: Functions pygeodesy.areaOf, ellipsoidalGeodSolve.areaOf, ellipsoidalKarney.areaOf, sphericalNvector.areaOf and sphericalTrigonometry.areaOf.

### intersection3 (start1, end1, start2, end2, height=None, wrap=False, equidistant=None, tol=0.001, **LatLon_and_kwds) |
Iteratively compute the intersection point of two geodesic lines, each given as two points or as an start point and a bearing from North. Arguments: `start1` - Start point of the first line (LatLon). `end1` - End point of the first line (LatLon) or the initial bearing at `start1` (compass `degrees360`). `start2` - Start point of the second line (LatLon). `end2` - End point of the second line (LatLon) or the initial bearing at `start2` (compass `degrees360`). `height` - Optional height at the intersection (`meter`, conventionally) or `None` for the mean height. `wrap` - If `True`, wrap or normalize and unroll `start2` and both `end*` points (`bool`). `equidistant` - An azimuthal equidistant projection (class or function pygeodesy.equidistant) or `None` for the preferred `start1.Equidistant`. `tol` - Tolerance for convergence and for skew line distance and length (`meter`, conventionally). `LatLon_and_kwds` - Optional class `LatLon=`LatLon to return the intersection points and optionally, additional `LatLon` keyword arguments, ignored if `LatLon=None`. Returns: An Intersection3Tuple`(point, outside1, outside2)` with `point` a `LatLon` or if `LatLon is None`, a LatLon4Tuple`(lat, lon, height, datum)`. Raises: `IntersectionError` - Skew, colinear, parallel or otherwise non-intersecting lines or no convergence for the given `tol`. `TypeError` - Invalid or non-ellipsoidal `start1`, `end1`, `start2` or `end2` or invalid `equidistant`. Note: For each line specified with an initial bearing, a pseudo-end point is computed as the `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 Also: The ellipsoidal case and Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES for more details about the iteration algorithm.

### intersections2 (center1, radius1, center2, radius2, height=None, wrap=False, equidistant=None, tol=0.001, **LatLon_and_kwds) |
Iteratively compute the intersection points of two circles, each defined by an (ellipsoidal) center point and a radius. Arguments: `center1` - Center of the first circle (LatLon). `radius1` - Radius of the first circle (`meter`, conventionally). `center2` - Center of the second circle (LatLon). `radius2` - Radius of the second circle (`meter`, same units as `radius1`). `height` - Optional height for the intersection points (`meter`, conventionally) or `None` for the "radical height" at the radical line between both centers. `wrap` - If `True`, wrap or normalize and unroll `center2` (`bool`). `equidistant` - An azimuthal equidistant projection (class or function pygeodesy.equidistant) or `None` for the preferred `center1.Equidistant`. `tol` - Convergence tolerance (`meter`, same units as `radius1` and `radius2`). `LatLon_and_kwds` - Optional class `LatLon=`LatLon to return the intersection points and optionally, additional `LatLon` keyword arguments, ignored if `LatLon=None`. Returns: 2-Tuple of the intersection points, each a `LatLon` instance or LatLon4Tuple`(lat, lon, height, datum)` if `LatLon is None`. For abutting circles, both points are the same instance, aka the radical center. Raises: `IntersectionError` - Concentric, antipodal, invalid or non-intersecting circles or no convergence for the `tol`. `TypeError` - Invalid or non-ellipsoidal `center1` or `center2` or invalid `equidistant`. `UnitError` - Invalid `radius1`, `radius2` or `height`. See Also: The ellipsoidal case, Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES, circle-circle and sphere-sphere intersections.

### isclockwise (points, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True, polar=False) |
Determine the direction of a path or polygon. Arguments: `points` - The path or polygon points (`LatLon`[]). `datum` - Optional datum (Datum). `wrap` - If `True`, wrap or normalize and unroll the `points` (`bool`). `polar` - Use `polar=True` if the `points` enclose a pole (`bool`), see function ispolar. Returns: `True` if `points` are clockwise, `False` otherwise. Raises: `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not `LatLon`. `ValueError` - The `points` enclose a pole or zero area. See Also: pygeodesy.isclockwise.

### nearestOn (point, point1, point2, within=True, height=None, wrap=False, equidistant=None, tol=0.001, **LatLon_and_kwds) |
Iteratively locate the closest point on the geodesic (line) between two other (ellipsoidal) points. Arguments: `point` - Reference point (`LatLon`). `point1` - Start point of the geodesic (`LatLon`). `point2` - End point of the geodesic (`LatLon`). `within` - If `True`, return the closest point between `point1` and `point2`, otherwise the closest point elsewhere on the geodesic (`bool`). `height` - Optional height for the closest point (`meter`, conventionally) or `None` or `False` for the interpolated height. If `False`, the closest takes the heights of the points into account. `wrap` - If `True`, wrap or normalize and unroll both `point1` and `point2` (`bool`). `equidistant` - An azimuthal equidistant projection (class or function pygeodesy.equidistant) or `None` for the preferred `point.Equidistant`. `tol` - Convergence tolerance (`meter`). `LatLon_and_kwds` - Optional class `LatLon=`LatLon to return the closest point and optionally, additional `LatLon` keyword arguments, ignored if `LatLon=None`. Returns: Closest point, a `LatLon` instance or if `LatLon is None`, a LatLon4Tuple`(lat, lon, height, datum)`. Raises: `TypeError` - Invalid or non-ellipsoidal `point`, `point1` or `point2` or invalid `equidistant`. `ValueError` - No convergence for the `tol`. See Also: The ellipsoidal case and Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES for more details about the iteration algorithm.

### perimeterOf (points, closed=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True) |
Compute the perimeter of an (ellipsoidal) polygon or composite. Arguments: `points` - The polygon points (LatLon[], BooleanFHP or BooleanGH). `closed` - Optionally, close the polygon (`bool`). `datum` - Optional datum (Datum). `wrap` - If `True`, wrap or normalize and unroll the `points` (`bool`). Returns: Perimeter (`meter`, same units as the `datum`'s ellipsoid axes). Raises: `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not LatLon. `ValueError` - Invalid `wrap=False`, unwrapped, unrolled longitudes not supported or `closed=False` with `points` a composite. See Also: Functions pygeodesy.perimeterOf, ellipsoidalGeodSolve.perimeterOf, ellipsoidalKarney.perimeterOf, sphericalNvector.perimeterOf and sphericalTrigonometry.perimeterOf.