Home       Trees       Indices       Help   
PyGeodesy3
Package pygeodesy3 :: Package ellipsoidal :: Module karney
[frames] | no frames]

Module karney

Ellipsoidal, Karney-based geodesy.

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

Here's an example usage of ellipsoidal.karney:

>>> from pygeodesy3.ellipsoidal.karney 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 pygeodesy3 import Datums
>>> from pygeodesy3.ellipsoidal.karney 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 ellipsoidal.vincenty.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 'pygeodesy3.ellipsoidal.karney.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 'pygeodesy3.ellipsoidal.karney.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 'pygeodesy3.ellipsoidal.karney.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.ellipsoidal_karney
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 ellipsoidal.exact.LatLon, ellipsoidal.karney.LatLon or ellipsoidal.vincenty.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:

See Also: Functions pygeodesy3.areaOf, ellipsoidal.exact.areaOf, ellipsoidal.solve.areaOf, spherical.nvector.areaOf and spherical.trigonometry.areaOf.

intersection3 (start1, end1, start2, end2, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy3.ellipsoidal.karney.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 pygeodesy3.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 'pygeodesy3.ellipsoidal.karney.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 pygeodesy3.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: pygeodesy3.isclockwise.

nearestOn (point, point1, point2, within=True, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy3.ellipsoidal.karney.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 pygeodesy3.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 perimeterOf, ellipsoidal.exact.perimeterOf, ellipsoidal.solve.perimeterOf, spherical.nvector.perimeterOf and spherical.trigonometry.perimeterOf.


   Home       Trees       Indices       Help   
PyGeodesy3
Generated by Epydoc 3.0.1 on Mon Mar 4 16:45:44 2024 http://epydoc.sourceforge.net