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

Module ellipsoidalKarney

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

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.convertDatum(Datums.OSGB36)

Version: 20.10.08

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 a (n 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)
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 a (n 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 a (n 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 missing.
  • TypeError - Some points are not LatLon.
  • PointsError - Insufficient number of points.
  • ValueError - Invalid wrap, longitudes not wrapped, unrolled.

Note: This function requires installation of 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).
  • center2 - Center of the second circle (LatLon).
  • radius2 - Radius of the second circle (meter).
  • height - Optional height for the intersection points, overriding the "radical height" at the "radical line" between both centers (meter) or None.
  • wrap - Wrap and unroll longitudes (bool).
  • equidistant - An azimuthal equidistant projection class (Equidistant or equidistant) or None for EquidistantKarney.
  • tol - Convergence tolerance (meter).
  • 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, the 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:
  • TypeError - Some points are not LatLon.
  • PointsError - Insufficient number of points.
  • ValueError - The points enclose a pole or zero area.

Note: This function requires installation of 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)

 

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 EquidistantKarney), function azimuthal.equidistant will be invoked if left unspecified.
  • 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 a (n 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 missing.
  • TypeError - Some points are not LatLon.
  • PointsError - Insufficient number of points.
  • ValueError - Invalid wrap, longitudes not wrapped, unrolled.

Note: This function requires installation of the geographiclib package.

See Also: pygeodesy.perimeterOf and sphericalTrigonometry.perimeterOf.