Module sphericalTrigonometry

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.

Compute the vectorial sum of two oe more vectors.

Arguments:

• vectors - Vectors to be added (Vector3d[]).
• Vector - Optional class for the vectorial sum (Vector3d).
• Vector_kwds - Optional Vector keyword arguments, ignored if Vector is None.

Returns:

Vectorial sum as Vector or if Vector is None, a named Vector3Tuple(x, y, z).

Raises:

• VectorError - No vectors.

Calculate the area of a (spherical) polygon or composite (with the pointsjoined by great circle arcs).

Arguments:

• points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
• radius - Mean earth radius, ellipsoid or datum (meter, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple) or None.
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

Polygon area (meter quared, same units as radius or radians if radius is None).

Raises:

• PointsError - Insufficient number of points.
• TypeError - Some points are not LatLon.
• ValueError - Invalid radius or semi-circular polygon edge.

Compute the intersections of a circle and a (great circle) line given as two points or as a point and bearing.

Arguments:

• center - Center of the circle (LatLon).
• circle - Radius of the circle (meter, same units as the earth radius) or a point on the circle (LatLon).
• point - A point on the (great circle) line (LatLon).
• other - An other point on the (great circle) line (LatLon) or the bearing at the point (compass degrees360).
• radius_exact_height_wrap - Optional keyword arguments, see method intersecant2 for further details.

Returns:

2-Tuple of the intersection points (representing a chord), each an instance of the point class. Both points are the same instance if the (great circle) line is tangent to the circle.

Raises:

• IntersectionError - The circle and line do not intersect.
• TypeError - If center, point, circle or other not LatLon.
• UnitError - Invalid circle, other, radius, exact, height or napieradius.

Compute the intersection point of two lines, each defined by two points or a start point and 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 start 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 start point (compass degrees360).
• height - Optional height for the intersection point, overriding the mean height (meter).
• wrap - If True, wrap or normalize and unroll start2 and both end* points (bool).
• LatLon - Optional class to return the intersection point (LatLon) or None.
• LatLon_kwds - Optional, additional LatLon keyword arguments, ignored if LatLon is None.

Returns:

The intersection point as a (LatLon) or if LatLon is None a LatLon3Tuple(lat, lon, height). An alternate intersection point might be the antipode to the returned result.

Raises:

• IntersectionError - Ambiguous or infinite intersection or colinear, parallel or otherwise non-intersecting lines.
• TypeError - A start1, end1, start2 or end2 point not LatLon.
• ValueError - Invalid height or null line.

Compute the intersection points of two circles each defined by a center point and a radius.

Arguments:

• center1 - Center of the first circle (LatLon).
• rad1 - Radius of the first circle (meter or radians, see radius).
• center2 - Center of the second circle (LatLon).
• rad2 - Radius of the second circle (meter or radians, see radius).
• radius - Mean earth radius (meter or None if rad1, rad2 and eps are given in radians).
• eps - Required overlap (meter or radians, see radius).
• 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).
• 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 if LatLon is None a LatLon3Tuple(lat, lon, height). For abutting circles, both intersection points are the same instance, aka the radical center.

Raises:

• IntersectionError - Concentric, antipodal, invalid or non-intersecting circles.
• TypeError - If center1 or center2 not LatLon.
• ValueError - Invalid rad1, rad2, radius, eps or height.

DEPRECATED, use function pygeodesy.ispolar.

Decorators:

• @deprecated_function

Compute the geographic mean of several points.

Arguments:

• points - Points to be averaged (LatLon[]).
• height - Optional height at mean point, overriding the mean height (meter).
• wrap - If True, wrap or normalize the points (bool).
• LatLon - Optional class to return the mean point (LatLon) or None.
• LatLon_kwds - Optional, additional LatLon keyword arguments, ignored if LatLon is None.

Returns:

The geographic mean and height (LatLon) or if LatLon is None, a LatLon3Tuple(lat, lon, height).

Raises:

• TypeError - Some points are not LatLon.
• ValueError - No points or invalid height.

DEPRECATED, use function sphericalTrigonometry.nearestOn3.

Returns:

... 2-tuple (closest, distance) of the closest point (LatLon) on the polygon and the distance between the closest and the given point. The closest is a LatLon or a LatLon2Tuple(lat, lon) if LatLon is None ...

Decorators:

• @deprecated_function

Locate the point on a path or polygon closest to a reference point.

Distances are approximated using function equirectangular4, subject to the supplied options.

Arguments:

• point - The reference point (LatLon).
• points - The path or polygon points (LatLon[]).
• closed - Optionally, close the polygon (bool).
• radius - Mean earth radius (meter).
• wrap - If True, wrap or normalize and unroll the points (bool).
• adjust - See function equirectangular4 (bool).
• limit - See function equirectangular4 (degrees), default 9 degrees is about 1,000 Km (for (mean spherical earth radius R_KM).
• LatLon_and_kwds - Optional class LatLon=LatLon to return the closest point and optional, additional LatLon keyword arguments or specify LatLon=None.

Returns:

A NearestOn3Tuple(closest, distance, angle) with the closest point as LatLon or LatLon3Tuple(lat, lon, height) if LatLon is None. The distance is the equirectangular4 distance between the closest and the given point converted to meter, same units as radius. The angle from the given point to the closest is in compass degrees360, like function compassAngle. The height is the (interpolated) height at the closest point.

Raises:

• LimitError - Lat- and/or longitudinal delta exceeds the limit, see function equirectangular4.
• PointsError - Insufficient number of points.
• TypeError - Some points are not LatLon.
• ValueError - Invalid radius.

Compute the perimeter of a (spherical) polygon or composite (with great circle arcs joining the points).

Arguments:

• points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
• closed - Optionally, close the polygon (bool).
• radius - Mean earth radius (meter) or None.
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

Polygon perimeter (meter, same units as radius or radians if radius is None).

Raises:

• PointsError - Insufficient number of points.
• TypeError - Some points are not LatLon.
• ValueError - Invalid radius or closed=False with points a composite.

Compute the angles, sides, and area of a (spherical) triangle.

Arguments:

• latA - First corner latitude (degrees).
• lonA - First corner longitude (degrees).
• latB - Second corner latitude (degrees).
• lonB - Second corner longitude (degrees).
• latC - Third corner latitude (degrees).
• lonC - Third corner longitude (degrees).
• radius - Mean earth radius, ellipsoid or datum (meter, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple) or None.
• excess - Spherical excess callable (excessAbc_, excessGirard_ or excessLHuilier_).
• wrap - If True, wrap and unroll180 longitudes (bool).

Returns:

A Triangle7Tuple(A, a, B, b, C, c, area) with spherical angles A, B and C, angular sides a, b and c all in degrees and area in square meter or same units as radius squared or if radius=0 or None, a Triangle8Tuple(A, a, B, b, C, c, D, E) all in radians with the spherical excess E as the unit area in radians.

Compute the angles, sides, spherical deficit and spherical excess of a (spherical) triangle.

Arguments:

• phiA - First corner latitude (radians).
• lamA - First corner longitude (radians).
• phiB - Second corner latitude (radians).
• lamB - Second corner longitude (radians).
• phiC - Third corner latitude (radians).
• lamC - Third corner longitude (radians).
• excess - Spherical excess callable (excessAbc_, excessGirard_ or excessLHuilier_).
• wrap - If True, unrollPI the longitudinal deltas (bool).

Returns:

A Triangle8Tuple(A, a, B, b, C, c, D, E) with spherical angles A, B and C, angular sides a, b and c, spherical deficit D and spherical excess E, all in radians.