Package polygonal

Approximate the area of a polygon or composite.

Arguments:

• points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
• adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
• radius - Mean earth radius (meter) or None.
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

Approximate area (square meter, same units as radius or radians squared if radius is None).

Raises:

• PointsError - Insufficient number of points
• TypeError - Some points are not LatLon.
• ValueError - Invalid radius.

Determine the bottom-left SW and top-right NE corners of a path or polygon.

Arguments:

• points - The path or polygon points (LatLon[]).
• wrap - If True, wrap or normalize and unroll the points (bool).
• LatLon - Optional class to return the bounds corners (LatLon) or None.

Returns:

A Bounds2Tuple(latlonSW, latlonNE) as LatLons if LatLon is None a Bounds4Tuple(latS, lonW, latN, lonE).

Raises:

• PointsError - Insufficient number of points
• TypeError - Some points are not LatLon.

Determine the centroid of a polygon.

Arguments:

• points - The polygon points (LatLon[]).
• wrap - If True, wrap or normalize and unroll the points (bool).
• LatLon - Optional class to return the centroid (LatLon) or None.

Returns:

Centroid (LatLon) or a LatLon2Tuple(lat, lon) if LatLon is None.

Raises:

• PointsError - Insufficient number of points
• TypeError - Some points are not LatLon.
• ValueError - The points enclose a pole or near-zero area.

Clip a path against a rectangular clip box using the Cohen-Sutherland algorithm.

Arguments:

• points - The points (LatLon[]).
• lowerleft - Bottom-left corner of the clip box (LatLon).
• upperight - Top-right corner of the clip box (LatLon).
• closed - Optionally, close the path (bool).
• inull - Optionally, retain null edges if inside (bool).

Returns:

Yield a ClipCS4Tuple(start, end, i, j) for each edge of the clipped path.

Raises:

• ClipError - The lowerleft and upperight corners specify an invalid clip box.
• PointsError - Insufficient number of points.

Clip one or more polygons against a clip region or box using Forster-Hormann-Popa's C++ implementation transcoded to pure Python.

Arguments:

• points - The polygon points and clips (LatLon[]).
• corners - Three or more points defining the clip regions (LatLon[]) or two points to specify a single, rectangular clip box.
• closed - If True, close each result clip (bool).
• inull - If True, retain null edges in result clips (bool).
• raiser - If True, throw ClipError exceptions (bool).
• esp - Tolerance for eliminating null edges (degrees, same units as the points and corners coordinates).

Returns:

Yield a ClipFHP4Tuple(lat, lon, height, clipid) for each clipped point. The result may consist of several clips, each a (closed) polygon with a unique clipid.

Raises:

• ClipError - Insufficient points or corners or an open clip.

Clip one or more polygons against a clip region or box using the Greiner-Hormann algorithm, Correia's implementation modified and extended.

Arguments:

• points - The polygon points and clips (LatLon[]).
• corners - Three or more points defining the clip regions (LatLon[]) or two points to specify a single, rectangular clip box.
• closed - If True, close each result clip (bool).
• inull - If True, retain null edges in result clips (bool).
• raiser - If True, throw ClipError exceptions (bool).
• xtend - If True, extend edges of degenerate cases, an attempt to handle the latter (bool).
• esp - Tolerance for eliminating null edges (degrees, same units as the points and corners coordinates).

Returns:

Yield a ClipGH4Tuple(lat, lon, height, clipid) for each clipped point. The result may consist of several clips, each a (closed) polygon with a unique clipid.

Raises:

• ClipError - Insufficient points or corners, an open clip, a degenerate case or unhandled intersection.

Clip a path against a rectangular clip box using the Liang-Barsky algorithm.

Arguments:

• points - The points (LatLon[]).
• lowerleft - Bottom-left corner of the clip box (LatLon).
• upperight - Top-right corner of the clip box (LatLon).
• closed - Optionally, close the path (bool).
• inull - Optionally, retain null edges if inside (bool).

Returns:

Yield a ClipLB6Tuple(start, end, i, fi, fj, j) for each edge of the clipped path.

Raises:

• ClipError - The lowerleft and upperight corners specify an invalid clip box.
• PointsError - Insufficient number of points.

Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.

Arguments:

• points - The polygon points (LatLon[]).
• corners - Three or more points defining a convex clip region (LatLon[]) or two points to specify a rectangular clip box.
• closed - Close the clipped points (bool).
• inull - Optionally, include null edges (bool).

Returns:

Yield the clipped points (LatLon[]).

Raises:

• ClipError - The corners specify a polar, zero-area, non-convex or otherwise invalid clip box or region.
• PointsError - Insufficient number of points.

Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.

Arguments:

• points - The polygon points (LatLon[]).
• corners - Three or more points defining a convex clip region (LatLon[]) or two points to specify a rectangular clip box.
• closed - Close the clipped points (bool).
• inull - Optionally, include null edges (bool).

Returns:

Yield a ClipSH3Tuple(start, end, original) for each edge of the clipped polygon.

Raises:

• ClipError - The corners specify a polar, zero-area, non-convex or otherwise invalid clip box or region.
• PointsError - Insufficient number of points or corners.

Return the point at a given fractional index.

Arguments:

• points - The points (LatLon[], Numpy2LatLon[], Tuple2LatLon[], Cartesian[], Vector3d[], Vector3Tuple[]).
• fi - The fractional index (FIx, float or int).
• j - Optionally, index of the other point (int).
• wrap - If True, wrap or normalize and unroll the {points} (bool) or None for a backward compatible LatLon2Tuple or LatLon with averaged lat- and longitudes. Use True or False to get the fractional point computed by method points[fi].intermediateTo.
• LatLon - Optional class to return the intermediate, fractional point (LatLon) or None.
• Vector - Optional class to return the intermediate, fractional point (Cartesian, Vector3d) or None.
• kwds - Optional, additional LatLon or Vector keyword arguments, ignored if both LatLon and Vector are None.

Returns:

A LatLon2Tuple(lat, lon) if wrap, LatLon and Vector all are None, the defaults.

An instance of LatLon if not None or an instance of Vector if not None.

Otherwise with wrap either True or False and LatLon and Vector both None, an instance of points' (sub-)class intermediateTo fractional.

Summarized as follows:

>>>  wrap  | LatLon | Vector | returned type/value
#   -------+--------+--------+--------------+------
#          |        |        | LatLon2Tuple | favg
#    None  |  None  |  None  |   or**       |
#          |        |        | Vector3Tuple | favg
#    None  | LatLon |  None  | LatLon       | favg
#    None  |  None  | Vector | Vector       | favg
#   -------+--------+--------+--------------+------
#    True  |  None  |  None  | points'      | .iTo
#    True  | LatLon |  None  | LatLon       | .iTo
#    True  |  None  | Vector | Vector       | .iTo
#   -------+--------+--------+--------------+------
#    False |  None  |  None  | points'      | .iTo
#    False | LatLon |  None  | LatLon       | .iTo
#    False |  None  | Vector | Vector       | .iTo
# _____
# favg) averaged lat, lon or x, y, z values
# .iTo) value from points[fi].intermediateTo
# **) depends on base class of points[fi]

Raises:

• IndexError - Fractional index fi invalid or points not subscriptable or not closed.
• TypeError - Invalid LatLon, Vector or kwds argument.

Check for Boolean composites.

Arguments:

• obj - The object (any type).

Returns:

True if obj is BooleanFHP, BooleanGH oe some other composite, False otherwise.

Determine the direction of a path or polygon.

Arguments:

• points - The path or polygon points (LatLon[]).
• adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

True if points are clockwise, False otherwise.

Raises:

• PointsError - Insufficient number of points
• TypeError - Some points are not LatLon.
• ValueError - The points enclose a pole or zero area.

Determine whether a polygon is convex.

Arguments:

• points - The polygon points (LatLon[]).
• adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

True if points are convex, False otherwise.

Raises:

• CrossError - Some points are colinear.
• PointsError - Insufficient number of points
• TypeError - Some points are not LatLon.

Determine whether a polygon is convex and clockwise.

Arguments:

• points - The polygon points (LatLon[]).
• adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

+1 if points are convex clockwise, -1 for convex counter-clockwise points, 0 otherwise.

Raises:

• CrossError - Some points are colinear.
• PointsError - Insufficient number of points
• TypeError - Some points are not LatLon.

Determine whether a point is enclosed by a polygon or composite.

Arguments:

• point - The point (LatLon or 2-tuple (lat, lon)).
• points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

True if the point is inside the polygon or composite, False otherwise.

Raises:

• PointsError - Insufficient number of points
• TypeError - Some points are not LatLon.
• ValueError - Invalid point, lat- or longitude.

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.

Generate an ellipsoidal or spherical lune-shaped path or polygon.

Arguments:

• lon1 - Left longitude (degrees90).
• lon2 - Right longitude (degrees90).
• closed - Optionally, close the path (bool).
• LatLon - Class to use (LatLon_).
• LatLon_kwds - Optional, additional LatLon keyword arguments.

Returns:

A tuple of 4 or 5 LatLon instances outlining the lune shape.

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

The closest point on each polygon edge is either the nearest of that edge's end points or a point in between.

Arguments:

• point - The reference point (LatLon).
• points - The path or polygon points (LatLon[]).
• closed - Optionally, close the path or polygon (bool).
• wrap - If True, wrap or normalize and unroll the points (bool).
• adjust - See function pygeodesy3.equirectangular_ (bool).
• limit - See function pygeodesy3.equirectangular_ (degrees), default 9 degrees is about 1,000 Kmeter (for mean spherical earth radius R_KM).
• LatLon_and_kwds - Optional, LatLon=None class to use for the closest point and additional LatLon keyword arguments, ignored if LatLon=None or not given.

Returns:

A NearestOn3Tuple(closest, distance, angle) with the {closest} point (LatLon) or if LatLon is None, a NearestOn5Tuple(lat, lon, distance, angle, height). The distance is the pygeodesy3.equirectangular distance between the closest and reference point in degrees. The angle from the point to the closest is in compass degrees, like function pygeodesy3.compassAngle.

Raises:

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

Approximate the perimeter of a path, polygon. or composite.

Arguments:

• points - The path or polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
• closed - Optionally, close the path or polygon (bool).
• adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
• radius - Mean earth radius (meter).
• wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

Approximate perimeter (meter, same units as radius).

Raises:

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

Generate a quadrilateral path or polygon from two points.

Arguments:

• latS - Souther-nmost latitude (degrees90).
• lonW - Western-most longitude (degrees180).
• latN - Norther-nmost latitude (degrees90).
• lonE - Eastern-most longitude (degrees180).
• closed - Optionally, close the path (bool).
• LatLon - Class to use (LatLon_).
• LatLon_kwds - Optional, additional LatLon keyword arguments.

Returns:

Return a tuple of 4 or 5 LatLon instances outlining the quadrilateral.

Basic simplification of a path of LatLon points.

Eliminates any points closer together than the given distance tolerance.

Arguments:

• points - Path points (LatLon[]).
• distance - Tolerance (meter, same units as radius).
• radius - Mean earth radius (meter).
• indices - If True return the simplified point indices instead of the simplified points (bool).
• options - Optional keyword arguments passed thru to function pygeodesy3.equirectangular_.

Returns:

Simplified points (LatLon[]).

Raises:

• LimitError - Lat- and/or longitudinal delta exceeds the limit, see function pygeodesy3.equirectangular_.
• ValueError - Tolerance distance or radius too small.

Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points.

Eliminates any points too close together or closer to an edge than the given distance tolerance.

This RDP method exhaustively searches for the point with the largest distance, resulting in worst-case complexity O(n**2) where n is the number of points.

Arguments:

• points - Path points (LatLon[]).
• distance - Tolerance (meter, same units as radius).
• radius - Mean earth radius (meter).
• shortest - If True use the shortest otherwise the perpendicular distance (bool).
• indices - If True return the simplified point indices instead of the simplified points (bool).
• options - Optional keyword arguments passed thru to function pygeodesy3.equirectangular_.

Returns:

Simplified points (LatLon[]).

Raises:

• LimitError - Lat- and/or longitudinal delta exceeds the limit, see function pygeodesy3.equirectangular_.
• ValueError - Tolerance distance or radius too small.

Modified Ramer-Douglas-Peucker (RDPm) simplification of a path of LatLon points.

Eliminates any points too close together or closer to an edge than the given distance tolerance.

This RDPm method stops at the first point farther than the given distance tolerance, significantly reducing the run time (but producing results different from the original RDP method).

Arguments:

• points - Path points (LatLon[]).
• distance - Tolerance (meter, same units as radius).
• radius - Mean earth radius (meter).
• shortest - If True use the shortest otherwise the perpendicular distance (bool).
• indices - If True return the simplified point indices instead of the simplified points (bool).
• options - Optional keyword arguments passed thru to function pygeodesy3.equirectangular_.

Returns:

Simplified points (LatLon[]).

Raises:

• LimitError - Lat- and/or longitudinal delta exceeds the limit, see function pygeodesy3.equirectangular_.
• ValueError - Tolerance distance or radius too small.

Reumann-Witkam (RW) simplification of a path of LatLon points.

Eliminates any points too close together or within the given pipe tolerance along an edge.

Arguments:

• points - Path points (LatLon[]).
• pipe - Pipe radius, half-width (meter, same units as radius).
• radius - Mean earth radius (meter).
• shortest - If True use the shortest otherwise the perpendicular distance (bool).
• indices - If True return the simplified point indices instead of the simplified points (bool).
• options - Optional keyword arguments passed thru to function pygeodesy3.equirectangular_.

Returns:

Simplified points (LatLon[]).

Raises:

• LimitError - Lat- and/or longitudinal delta exceeds the limit, see function pygeodesy3.equirectangular_.
• ValueError - Tolerance pipe or radius too small.

Visvalingam-Whyatt (VW) simplification of a path of LatLon points.

Eliminates any points too close together or with a triangular area not exceeding the given area tolerance squared.

This VW method exhaustively searches for the single point with the smallest triangular area, resulting in worst-case complexity O(n**2) where n is the number of points.

Arguments:

• points - Path points (LatLon[]).
• area - Tolerance (meter, same units as radius).
• radius - Mean earth radius (meter).
• attr - Optional, points attribute to save the area value (str).
• indices - If True return the simplified point indices instead of the simplified points (bool).
• options - Optional keyword arguments passed thru to function pygeodesy3.equirectangular_.

Returns:

Simplified points (LatLon[]).

Raises:

• AttributeError - If an attr is specified for Numpy2 points.
• LimitError - Lat- and/or longitudinal delta exceeds the limit, see function pygeodesy3.equirectangular_.
• ValueError - Tolerance area or radius too small.

Modified Visvalingam-Whyatt (VWm) simplification of a path of LatLon points.

Eliminates any points too close together or with a triangular area not exceeding the given area tolerance squared.

This VWm method removes all points with a triangular area below the tolerance in each iteration, significantly reducing the run time (but producing results different from the original VW method).

Arguments:

• points - Path points (LatLon[]).
• area - Tolerance (meter, same units as radius).
• radius - Mean earth radius (meter).
• attr - Optional, points attribute to save the area value (str).
• indices - If True return the simplified point indices instead of the simplified points (bool).
• options - Optional keyword arguments passed thru to function pygeodesy3.equirectangular_.

Returns:

Simplified points (LatLon[]).

Raises:

• AttributeError - If an attr is specified for Numpy2 points.
• LimitError - Lat- and/or longitudinal delta exceeds the limit, see function pygeodesy3.equirectangular_.
• ValueError - Tolerance area or radius too small.