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

# Module ellipsoidalKarney

Ellipsoidal, Karney-based geodesy.

Ellipsoidal geodetic (lat-/longitude) LatLon and geocentric (ECEF) Cartesian classes and functions areaOf, intersections2, isclockwise, nearestOn and perimeterOf, all requiring Charles Karney's geographiclib Python package to be installed.

Here's an example usage of `ellipsoidalKarney`:

    >>> from pygeodesy.ellipsoidalKarney import LatLon
    >>> Newport_RI = LatLon(41.49008, -71.312796)
    >>> Cleveland_OH = LatLon(41.499498, -81.695391)
    >>> Newport_RI.distanceTo(Cleveland_OH)
    866,455.4329098687  # meter

You can change the ellipsoid model used by the Karney formulae as follows:

    >>> from pygeodesy import Datums
    >>> from pygeodesy.ellipsoidalKarney import LatLon
    >>> p = LatLon(0, 0, datum=Datums.OSGB36)

or by converting to anothor datum:

    >>> p = p.toDatum(Datums.OSGB36)

Version: 24.02.21

Classes
| Cartesian Extended to convert `Karney`-based Cartesian to `Karney`-based LatLon points.
| LatLon An ellipsoidal LatLon similar to ellipsoidalVincenty.LatLon but using Charles F. F. Karney's Python geographiclib 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) Compute the area of an (ellipsoidal) polygon or composite. |
intersection3(start1, end1, start2, end2, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_kwds) 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. |
intersections2(center1, radius1, center2, radius2, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_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) Determine the direction of a path or polygon. |
nearestOn(point, point1, point2, within=True, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_kwds) Iteratively locate the closest point on the geodesic 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.ellipsoidalKarney`

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, see below. 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) |
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`). Returns: Area (`meter`, same as units of the `datum`'s ellipsoid axes, squared). Raises: `ImportError` - Package geographiclib not installed or not found. `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not LatLon. `ValueError` - Invalid `wrap=False`, unwrapped, unrolled longitudes not supported. Notes: This function requires the geographiclib package. The area of a polygon enclosing a pole can be found by adding half the datum's ellipsoid surface area to the polygon's area. See Also: Functions pygeodesy.areaOf, ellipsoidalExact.areaOf, ellipsoidalGeodSolve.areaOf, sphericalNvector.areaOf and sphericalTrigonometry.areaOf.

### intersection3 (start1, end1, start2, end2, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_kwds) |
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. Arguments: `start1` - Start point of the first line (LatLon). `end1` - End point of the first line (LatLon) or the initial bearing at the first point (compass `degrees360`). `start2` - Start point of the second line (LatLon). `end2` - End point of the second line (LatLon) or the initial bearing at the second point (compass `degrees360`). `height` - Optional height at the intersection (`meter`, conventionally) or `None` for the mean height. `wrap` - If `True`, wrap or normalize and unroll the `start2` and `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` - Optional class to return the intersection points (LatLon) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is 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=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_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` - Optional class to return the intersection points (LatLon) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is 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) |
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`). Returns: `True` if `points` are clockwise, `False` otherwise. Raises: `ImportError` - Package geographiclib not installed or not found. `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not `LatLon`. `ValueError` - The `points` enclose a pole or zero area. Note: This function requires the geographiclib package. See Also: pygeodesy.isclockwise.

### nearestOn (point, point1, point2, within=True, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_kwds) |
Iteratively locate the closest point on the geodesic 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` - Optional class to return the closest point (LatLon) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is None`. Returns: Closest point, a `LatLon` instance or if `LatLon is None`, a LatLon4Tuple`(lat, lon, height, datum)`. Raises: `ImportError` - Package geographiclib not installed or not found. `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 as units of the `datum`'s ellipsoid axes). Raises: `ImportError` - Package geographiclib not installed or not found. `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not LatLon or `closed=False` with `points` a composite. `ValueError` - Invalid `wrap=False`, unwrapped, unrolled longitudes not supported or `closed=False` with `points` a composite. Note: This function requires the geographiclib package. See Also: Functions pygeodesy.perimeterOf, ellipsoidalExact.perimeterOf, ellipsoidalGeodSolve.perimeterOf, sphericalNvector.perimeterOf and sphericalTrigonometry.perimeterOf.