Skip to content

hull

Compute a geometric hull around a set of 2D points.

Parameters:

Name Type Description Default
xy ndarray

An array of shape (N, 2) representing N 2D points.

 required
hull_type str

The type of hull to compute. Must be one of "alpha_shape", "convex_hull", "bbox", or "ellipse".

 'alpha_shape'
**kwargs Any

Additional keyword arguments passed to the underlying hull computation functions (e.g., parameters for alpha shape).

 {}

Raises:

Type Description
ValueError

If an invalid hull_type is provided.

Returns:

Name Type Description
Polygon Polygon

A shapely Polygon object representing the computed hull.

Examples:

>>> hull(points, hull_type="convex_hull")
<shapely.geometry.polygon.Polygon object at ...>
Source code in src/histolytics/spatial_geom/hull.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def hull(xy: np.ndarray, hull_type: str = "alpha_shape", **kwargs: Any) -> Polygon:
    """Compute a geometric hull around a set of 2D points.

    Parameters:
        xy (np.ndarray):
            An array of shape (N, 2) representing N 2D points.
        hull_type (str):
            The type of hull to compute. Must be one of
            "alpha_shape", "convex_hull", "bbox", or "ellipse".
        **kwargs (Any):
            Additional keyword arguments passed to the underlying hull computation
            functions (e.g., parameters for alpha shape).

    Raises:
        ValueError: If an invalid hull_type is provided.

    Returns:
        Polygon: A shapely Polygon object representing the computed hull.

    Examples:
        >>> hull(points, hull_type="convex_hull")
        <shapely.geometry.polygon.Polygon object at ...>
    """
    allowed_hulls = ["alpha_shape", "convex_hull", "ellipse", "bbox"]
    if hull_type not in allowed_hulls:
        raise ValueError(f"Invalid hull type. Allowed values are: {allowed_hulls}")

    if hull_type == "alpha_shape":
        hull_poly = alpha_shape_auto(xy, **kwargs)
    elif hull_type == "convex_hull":
        hull = ConvexHull(xy)
        hull_points = xy[hull.vertices]
        hull_poly = Polygon(hull_points)
    elif hull_type == "ellipse":
        hull_poly = ellipse_poly(xy)
    elif hull_type == "bbox":
        poly = Polygon(xy)
        hull_poly = poly.envelope

    return hull_poly