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

# 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.03.25

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`. See Also: Liang-Barsky Line Clipping, Liang-Barsky line clipping algorithm and Liang-Barsky algorithm.

### 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`.