raygeo.geo.algo.hull

Hull computation from binary images.

Provides convex and concave (shrink-wrap) hull generation from boolean images, using contour tracing and a vacuum-like pull of the hull toward the content. Coordinates are returned in image pixel space (y increases downward).

Functions

get_concave_hull()

get_concave_hull(
    boolean_image: numpy.ndarray,
    gravity: float = 0.1,
    allow_self_intersections: bool = False,
) -> geo.Geometry | None

Compute a concave (shrink-wrap) hull around the content.

The band behaves like a membrane under vacuum: each point is pulled along the inward normal of the convex hull toward the content, tension keeps the band smooth, and pinch points stop it where it would fold through itself or through the content. The pull is integrated in small increments, so the result changes continuously with gravity; at 1.0 the band is pulled several times the length of a free section into the content. The effective pull is the squared parameter: low values shrink almost nothing and the upper half of the range carries most of the visible tightening, matching how the shrink saturates as the band settles onto the content.

Parameter	Type	Description
boolean_image	numpy.ndarray	2D boolean array.
gravity	float = 0.1	Shrink-wrap factor 0.0-1.0. 0 gives convex hull.
allow_self_intersections	bool = False	When False, the band stops at pinch points instead of crossing itself. Set to True when a self-intersecting outline is desired.
Returns	geo.Geometry | None	Concave hull as Geometry in pixel coords, or None.
Complexity		O(wh + n log n) time, O(wh) space where w*h is the image size and n the number of contour points

Concave vs convex hull

get_enclosing_hull()

get_enclosing_hull(boolean_image: numpy.ndarray) -> geo.Geometry | None

Compute a single convex hull enclosing all content.

Parameter	Type	Description
boolean_image	numpy.ndarray	2D boolean array.
Returns	geo.Geometry | None	Convex hull as Geometry in pixel coords, or None.
Complexity		O(wh + n log n) time, O(n) space where wh is the image size and n the number of contour points

get_hulls_from_image()

get_hulls_from_image(boolean_image: numpy.ndarray) -> list[geo.Geometry]

Compute a separate convex hull for each distinct component.

Parameter	Type	Description
boolean_image	numpy.ndarray	2D boolean array.
Returns	list[geo.Geometry]	List of Geometry objects in pixel coords.
Complexity		O(wh + n log n) time, O(n) space where wh is the image size and n the total number of contour points