Package pygeodesy :: Module clipy

Module clipy

Clip a path or polygon of LatLon points against a rectangular box or an arbitrary (convex) region.

Box clip functions clipCS4 Cohen-Sutherland and clipLB6 Liang-Barsky, region clip functions clipFHP4 Foster-Hormann-Popa, clipGH4 Greiner-Hormann and clipSH and clipSH3 Sutherland-Hodgeman. .

Version: 23.09.20

Classes
	ClipCS4Tuple 4-Tuple `(start, end, i, j)` for each edge of a clipped path with the `start` and `end` points (`LatLon`) of the portion of the edge inside or on the clip box and the indices `i` and `j` (`int`) of the edge start and end points in the original path.
	ClipFHP4Tuple 4-Tuple `(lat, lon, height, clipid)` for each point of the clipFHP4 result with the `lat`-, `lon`gitude, `height` and `clipid` of the polygon or clip.
	ClipGH4Tuple 4-Tuple `(lat, lon, height, clipid)` for each point of the clipGH4 result with the `lat`-, `lon`gitude, `height` and `clipid` of the polygon or clip.
	ClipLB6Tuple 6-Tuple `(start, end, i, fi, fj, j)` for each edge of the clipped path with the `start` and `end` points (`LatLon`) of the portion of the edge inside or on the clip box, indices `i` and `j` (both `int`) of the original path edge start and end points and fractional indices `fi` and `fj` (both FIx) of the `start` and `end` points along the edge of the original path.
	ClipSH3Tuple 3-Tuple `(start, end, original)` for each edge of a clipped polygon, the `start` and `end` points (`LatLon`) of the portion of the edge inside or on the clip region and `original` indicates whether the edge is part of the original polygon or part of the clip region (`bool`).

Functions

clipCS4(points, lowerleft, upperight, closed=False, inull=False)
Clip a path against a rectangular clip box using the Cohen-Sutherland algorithm.

clipFHP4(points, corners, closed=False, inull=False, raiser=False, eps=2.220446049250313e-16)
Clip one or more polygons against a clip region or box using Forster-Hormann-Popa's C++ implementation transcoded to pure Python.

clipGH4(points, corners, closed=False, inull=False, raiser=True, xtend=False, eps=2.220446049250313e-16)
Clip one or more polygons against a clip region or box using the Greiner-Hormann algorithm, Correia's implementation modified and extended.

clipLB6(points, lowerleft, upperight, closed=False, inull=False)
Clip a path against a rectangular clip box using the Liang-Barsky algorithm.

clipSH(points, corners, closed=False, inull=False)
Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.

clipSH3(points, corners, closed=False, inull=False)
Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.

Variables
	__all__ = `_ALL_LAZY.clipy`

Function Details

clipCS4 (points, lowerleft, upperight, closed=False, inull=False)

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.

clipFHP4 (points, corners, closed=False, inull=False, raiser=False, eps=2.220446049250313e-16)

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.

See Also: Forster, Hormann and Popa, class BooleanFHP and function clipGH4.

clipGH4 (points, corners, closed=False, inull=False, raiser=True, xtend=False, eps=2.220446049250313e-16)

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.

Note: To handle degenerate cases like point-edge and point-point intersections, use function clipFHP4.

See Also: Greiner-Hormann, Ionel Daniel Stroe, Correia's univ-polyclip, class BooleanGH and function clipFHP4.

clipLB6 (points, lowerleft, upperight, closed=False, inull=False)

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.

clipSH (points, corners, closed=False, inull=False)

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.

clipSH3 (points, corners, closed=False, inull=False)

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.