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

# Module ellipsoidalKarney

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.02.25

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. |
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 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` ellipsoid, 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, sphericalNvector.areaOf and sphericalTrigonometry.areaOf.

### 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, overriding the "radical height" at the "radical line" between both centers (`meter`, conventionally) or `None`. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class Equidistant or function equidistant) or `None` for EquidistantKarney. `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=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 intersection points are the same instance. 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 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`) or `None`. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection (class Equidistant or function equidistant) or `None` for EquidistantKarney. `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=None`. Returns: Closest point (`LatLon`). Raises: `ImportError` - Package geographiclib not installed or not found. `TypeError` - Invalid or non-ellipsoidal `point`, `point1` or `point2` or invalid `equidistant`.

### 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` ellipsoid). 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 and sphericalTrigonometry.perimeterOf.