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

Module clipy

Clip a path or polygon of LatLon points against a rectangular box or a (convex or arbitrary) clip 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.09

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-, longitude, height and clipid of the polygon or polygonal clip.
  ClipGH4Tuple
4-Tuple (lat, lon, height, clipid) for each point of the clipGH4 result with the lat-, longitude, height and clipid of the polygon or polygonal 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, upperright, 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 a polygon 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=False, xtend=False)
Clip a polygon against a clip region or box using the Greiner-Hormann algorithm, Correia's implementation modified and extended.
 
clipLB6(points, lowerleft, upperright, 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, upperright, 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).
  • upperright - 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 upperright 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 a polygon 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 a clip region (LatLon[]) or two points to specify a rectangular clip box.
  • closed - Optionally, close each result clip (bool).
  • inull - Optionally, retain null edges in result clips (bool).
  • raiser - If True throw ClipError exceptions.
  • esp - Tolerance for eliminating null edges (scalar).
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 - No points, no corners or an open clip.

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

clipGH4 (points, corners, closed=False, inull=False, raiser=False, xtend=False)

 

Clip a polygon 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 a clip region (LatLon[]) or two points to specify a rectangular clip box.
  • closed - Optionally, close each result clip (bool).
  • inull - Optionally, retain null edges in result clips (bool).
  • raiser - If True throw ClipError exceptions.
  • xtend - Cover degenerate cases (bool), but not (yet) based on Forster-Hormann-Popa.
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 - No points, no 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, Forster, Hormann and Popa, Correia's univ-polyclip, class BooleanGH and function clipFHP4.

clipLB6 (points, lowerleft, upperright, 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).
  • upperright - 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 upperright 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.