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: 21.08.07

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 the geodesic distance, initial and final bearing (azimuths) between two given points or the destination point given a start point and an (initial) bearing.

Functions
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. |
intersection3(start1, end1, start2, end2, height=None, wrap=True, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_kwds) Interatively compute the intersection point of two paths, each defined by an (ellipsoidal) start and end point. |
intersections2(center1, radius1, center2, radius2, height=None, wrap=True, 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 arc 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. |

Variables
| __all__ = `_ALL_LAZY.ellipsoidalKarney`

Function Details

### ispolar (points, wrap=False) |
Check whether a polygon encloses a pole. Arguments: `points` - The polygon points (`LatLon`[]). `wrap` - Wrap and unroll longitudes (`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. Arguments: `points` - The polygon points (LatLon[]). `datum` - Optional datum (Datum). `wrap` - Wrap and unroll longitudes (`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. Note: This function requires the geographiclib package. See Also: pygeodesy.areaOf, ellipsoidalExact.areaOf, ellipsoidalGeodSolve.areaOf, sphericalNvector.areaOf and sphericalTrigonometry.areaOf.

### intersection3 (start1, end1, start2, end2, height=None, wrap=True, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalKarney.LatLon'>, **LatLon_kwds) |
Interatively compute the intersection point of two paths, each defined by an (ellipsoidal) start and end point. Arguments: `start1` - Start point of the first path (LatLon). `end1` - End point of the first path (LatLon). `start2` - Start point of the second path (LatLon). `end2` - End point of the second path (LatLon). `height` - Optional height at the intersection (`meter`, conventionally) or `None` for the mean height. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class or function equidistant) or `None` for the preferred `start1.Equidistant`. `tol` - Tolerance for skew line distance and length and for convergence (`meter`, conventionally). `LatLon` - Optional class to return the intersection point (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: `ImportError` - Package geographiclib not installed or not found, but only if `equidistant=`EquidistantKarney. `IntersectionError` - Skew, colinear, parallel or otherwise non-intersecting paths or no convergence for the `tol`. `TypeError` - Invalid or non-ellipsoidal `start1`, `end1`, `start2` or `end2` or invalide `equidistant`.

### intersections2 (center1, radius1, center2, radius2, height=None, wrap=True, 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` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class or function 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 radical center. Raises: `ImportError` - Package geographiclib not installed or not found. `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` - Wrap and unroll longitudes (`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 arc between two other (ellipsoidal) points. Arguments: `point` - Reference point (`LatLon`). `point1` - Start point of the arc (`LatLon`). `point2` - End point of the arc (`LatLon`). `within` - If `True` return the closest point between `point1` and `point2`, otherwise the closest point elsewhere on the arc (`bool`). `height` - Optional height for the closest point (`meter`, conventionally) or `None` or `False` for the interpolated height. If `False`, the distance between points takes height into account. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class or function 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`.

### perimeterOf (points, closed=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True) |
Compute the perimeter of an (ellipsoidal) polygon. Arguments: `points` - The polygon points (LatLon[]). `closed` - Optionally, close the polygon (`bool`). `datum` - Optional datum (Datum). `wrap` - Wrap and unroll longitudes (`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. `ValueError` - Invalid `wrap=False`, unwrapped, unrolled longitudes not supported. Note: This function requires the geographiclib package. See Also: pygeodesy.perimeterOf, ellipsoidalExact.perimeterOf, ellipsoidalGeodSolve.perimeterOf, sphericalNvector.perimeterOf and sphericalTrigonometry.perimeterOf.