Geometry¶

API reference for geometry operations on contours and points.

Schemas¶

POINT_SCHEMA¶

from polars_cv import POINT_SCHEMA

# Struct({x: Float64, y: Float64})

BBOX_SCHEMA¶

from polars_cv import BBOX_SCHEMA

# Struct({x: Float64, y: Float64, width: Float64, height: Float64})

CONTOUR_SCHEMA¶

from polars_cv import CONTOUR_SCHEMA

# Struct({
#     exterior: List({x: Float64, y: Float64}),
#     holes: List(List({x: Float64, y: Float64})),
#     is_closed: Boolean
# })

Helper Functions¶

from polars_cv.geometry.schemas import contour_from_points

contour = contour_from_points([
    (10, 10), (10, 90), (90, 90), (90, 10)
])

ContourNamespace¶

Namespace for geometric operations on contour columns.

Example

df.with_columns( ... area=pl.col("contour").contour.area(), ... bbox=pl.col("contour").contour.bounding_box(), ... )

init ¶

__init__(expr: Expr) -> None

Initialize the namespace.

Parameters:

Name	Type	Description	Default
`expr`	`Expr`	The Polars expression to operate on.	required

normalize ¶

normalize(
    ref_width: int | Expr, ref_height: int | Expr
) -> pl.Expr

Convert pixel coordinates to normalized [0,1] range.

Parameters:

Name	Type	Description	Default
`ref_width`	`int \| Expr`	Reference width for normalization.	required
`ref_height`	`int \| Expr`	Reference height for normalization.	required

Returns:

Type	Description
`Expr`	Contour with coordinates in [0,1] range.

Raises:

Type	Description
`CoordinateRangeError`	If any coordinate exceeds ref dimensions.

to_absolute ¶

to_absolute(
    ref_width: int | Expr, ref_height: int | Expr
) -> pl.Expr

Convert normalized coordinates to pixel coordinates.

Parameters:

Name	Type	Description	Default
`ref_width`	`int \| Expr`	Reference width for scaling.	required
`ref_height`	`int \| Expr`	Reference height for scaling.	required

Returns:

Type	Description
`Expr`	Contour with pixel coordinates.

winding ¶

winding() -> pl.Expr

Compute winding direction from point order.

Returns:

Type	Description
`Expr`	String 'ccw' for counter-clockwise, 'cw' for clockwise.

Note

Winding is computed using the Shoelace formula: - Positive signed area = CCW - Negative signed area = CW

area ¶

area(*, signed: bool = False) -> pl.Expr

Compute contour area using the Shoelace formula.

For contours with holes, the hole areas are subtracted.

Parameters:

Name	Type	Description	Default
`signed`	`bool`	If True, return signed area (negative for CW winding). If False, return absolute area.	`False`

Returns:

Type	Description
`Expr`	Float64 area value.

Raises:

Type	Description
`OpenContourError`	If contour is not closed.

perimeter ¶

perimeter() -> pl.Expr

Compute contour perimeter (sum of edge lengths).

Returns:

Type	Description
`Expr`	Float64 perimeter value.

centroid ¶

centroid() -> pl.Expr

Compute contour centroid (center of mass).

Returns:

Type	Description
`Expr`	Point struct with x, y coordinates.

bounding_box ¶

bounding_box() -> pl.Expr

Compute axis-aligned bounding box.

Returns:

Type	Description
`Expr`	BBox struct with x, y, width, height.

convex_hull ¶

convex_hull() -> pl.Expr

Compute convex hull of the contour.

Returns:

Type	Description
`Expr`	New contour representing the convex hull.

is_convex ¶

is_convex() -> pl.Expr

Check if contour is convex.

Returns:

Type	Description
`Expr`	Boolean indicating convexity.

flip ¶

flip() -> pl.Expr

Reverse point order (flips winding direction).

Returns:

Type	Description
`Expr`	Contour with reversed point order.

ensure_winding ¶

ensure_winding(direction: Literal['ccw', 'cw']) -> pl.Expr

Ensure contour has specified winding direction.

Flips the contour if needed to match target winding.

Parameters:

Name	Type	Description	Default
`direction`	`Literal['ccw', 'cw']`	Target winding direction.	required

Returns:

Type	Description
`Expr`	Contour with guaranteed winding direction.

translate ¶

translate(dx: float | Expr, dy: float | Expr) -> pl.Expr

Translate contour by offset.

Parameters:

Name	Type	Description	Default
`dx`	`float \| Expr`	X offset.	required
`dy`	`float \| Expr`	Y offset.	required

Returns:

Type	Description
`Expr`	Translated contour.

scale ¶

scale(
    sx: float | Expr,
    sy: float | Expr,
    *,
    origin: Literal[
        "centroid", "bbox_center", "origin"
    ] = "origin",
) -> pl.Expr

Scale contour relative to specified origin.

Parameters:

Name	Type	Description	Default
`sx`	`float \| Expr`	X scale factor.	required
`sy`	`float \| Expr`	Y scale factor.	required
`origin`	`Literal['centroid', 'bbox_center', 'origin']`	Point to scale around: - "centroid": Center of mass - "bbox_center": Bounding box center - "origin": Coordinate origin (0, 0)	`'origin'`

Returns:

Type	Description
`Expr`	Scaled contour.

simplify ¶

simplify(tolerance: float) -> pl.Expr

Simplify contour using Douglas-Peucker algorithm.

Parameters:

Name	Type	Description	Default
`tolerance`	`float`	Simplification tolerance. Higher = fewer points.	required

Returns:

Type	Description
`Expr`	Simplified contour.

iou ¶

iou(other: Expr) -> pl.Expr

Compute Intersection over Union with another contour.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Another contour column to compare with.	required

Returns:

Type	Description
`Expr`	Float64 IoU value in [0, 1].

pairwise_iou ¶

pairwise_iou(other: Expr) -> pl.Expr

Compute full pairwise IoU matrix between contour sets.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Ground-truth contour-set expression (`List[Contour]`).	required

Returns:

Type	Description
`Expr`	A nested list (`List[List[Float64]]`) representing an N x M IoU matrix.

match_detections ¶

match_detections(
    other: Expr,
    *,
    threshold: float = 0.5,
    scores: Expr | None = None,
    strategy: Literal["greedy"] = "greedy",
) -> pl.Expr

Match prediction contour set against ground truth contour set.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Ground-truth contour-set expression (`List[Contour]`).	required
`threshold`	`float`	IoU threshold for positive matches.	`0.5`
`scores`	`Expr \| None`	Optional per-prediction confidence score list used for ordering.	`None`
`strategy`	`Literal['greedy']`	Matching strategy. Currently only `"greedy"` is supported.	`'greedy'`

Returns:

Type	Description
`Expr`	A struct containing per-prediction match indices, IoUs, and TP/FP/FN counts.

label_reduce ¶

label_reduce(
    image: Expr | None = None,
    *,
    heatmap: Expr | None = None,
    reduction: Literal["max", "mean", "sum"] = "max",
    region_mode: Literal["interior", "bbox"] = "interior",
) -> pl.Expr

Score each contour from an image/array expression with configurable reduction.

Parameters:

Name	Type	Description	Default
`image`	`Expr \| None`	Image/array expression aligned by row with contour sets.	`None`
`heatmap`	`Expr \| None`	Backward-compatible alias for `image`.	`None`
`reduction`	`Literal['max', 'mean', 'sum']`	Aggregation method over pixels in each contour region.	`'max'`
`region_mode`	`Literal['interior', 'bbox']`	Region selector - `"interior"` or `"bbox"`.	`'interior'`

Returns:

Type	Description
`Expr`	A list of float scores, aligned to the input contour order.

dice ¶

dice(other: Expr) -> pl.Expr

Compute Dice coefficient with another contour.

Dice = 2 * intersection / (area1 + area2)

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Another contour column to compare with.	required

Returns:

Type	Description
`Expr`	Float64 Dice coefficient in [0, 1].

hausdorff_distance ¶

hausdorff_distance(other: Expr) -> pl.Expr

Compute Hausdorff distance to another contour.

The Hausdorff distance is the maximum distance from any point on one contour to the nearest point on the other.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Another contour column to compare with.	required

Returns:

Type	Description
`Expr`	Float64 Hausdorff distance.

contains_point ¶

contains_point(point: Expr) -> pl.Expr

Test if contour contains a point.

Parameters:

Name	Type	Description	Default
`point`	`Expr`	Point column to test.	required

Returns:

Type	Description
`Expr`	Boolean indicating if point is inside contour.

PointNamespace¶

Operations on point columns.

This namespace provides geometric operations for point data, including coordinate transformations and distance calculations.

The point column must match POINT_SCHEMA or POINT_SET_SCHEMA. Operations automatically handle both single points and sets of points.

Example

df.with_columns( ... normalized=pl.col("keypoint").point.normalize(width=100, height=100), ... shifted=pl.col("keypoint").point.translate(dx=10, dy=20), ... )

init ¶

__init__(expr: Expr) -> None

Initialize the namespace.

Parameters:

Name	Type	Description	Default
`expr`	`Expr`	The Polars expression to operate on.	required

normalize ¶

normalize(
    ref_width: int | float, ref_height: int | float
) -> pl.Expr

Convert pixel coordinates to normalized [0,1] range.

Parameters:

Name	Type	Description	Default
`ref_width`	`int \| float`	Reference width for normalization.	required
`ref_height`	`int \| float`	Reference height for normalization.	required

Returns:

Type	Description
`Expr`	Point with coordinates in [0,1] range.

to_absolute ¶

to_absolute(
    ref_width: int | float, ref_height: int | float
) -> pl.Expr

Convert normalized coordinates to pixel coordinates.

Parameters:

Name	Type	Description	Default
`ref_width`	`int \| float`	Reference width for scaling.	required
`ref_height`	`int \| float`	Reference height for scaling.	required

Returns:

Type	Description
`Expr`	Point with pixel coordinates.

translate ¶

translate(dx: float, dy: float) -> pl.Expr

Translate point by offset.

Parameters:

Name	Type	Description	Default
`dx`	`float`	X offset.	required
`dy`	`float`	Y offset.	required

Returns:

Type	Description
`Expr`	Translated point.

scale ¶

scale(sx: float, sy: float) -> pl.Expr

Scale point coordinates.

Parameters:

Name	Type	Description	Default
`sx`	`float`	X scale factor.	required
`sy`	`float`	Y scale factor.	required

Returns:

Type	Description
`Expr`	Scaled point.

distance ¶

distance(other: Expr) -> pl.Expr

Compute Euclidean distance to another point.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Another point column.	required

Returns:

Type	Description
`Expr`	Float64 distance.

manhattan_distance ¶

manhattan_distance(other: Expr) -> pl.Expr

Compute Manhattan (L1) distance to another point.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Another point column.	required

Returns:

Type	Description
`Expr`	Float64 distance.

distance_to_contour ¶

distance_to_contour(contour: Expr) -> pl.Expr

Compute minimum distance from point to contour boundary.

This computes the distance to the nearest edge of the contour, considering both the exterior ring and any holes.

Parameters:

Name	Type	Description	Default
`contour`	`Expr`	A contour column.	required

Returns:

Type	Description
`Expr`	Float64 distance (always non-negative).

Example

df.with_columns( ... dist=pl.col("point").point.distance_to_contour(pl.col("polygon")) ... )

signed_distance_to_contour ¶

signed_distance_to_contour(contour: Expr) -> pl.Expr

Compute signed distance from point to contour boundary.

Returns negative distance if point is inside the contour, positive distance if outside. Zero if on the boundary.

Parameters:

Name	Type	Description	Default
`contour`	`Expr`	A contour column.	required

Returns:

Type	Description
`Expr`	Float64 signed distance.

Example

df.with_columns( ... sdf=pl.col("point").point.signed_distance_to_contour(pl.col("polygon")) ... )

nearest_point_on_contour ¶

nearest_point_on_contour(contour: Expr) -> pl.Expr

Find the nearest point on a contour boundary.

Returns the point on the contour boundary that is closest to this point.

Parameters:

Name	Type	Description	Default
`contour`	`Expr`	A contour column.	required

Returns:

Type	Description
`Expr`	Point struct with x, y coordinates of nearest boundary point.

Example

df.with_columns( ... nearest=pl.col("point").point.nearest_point_on_contour(pl.col("polygon")) ... )

angle_to ¶

angle_to(other: Expr) -> pl.Expr

Compute angle from this point to another in radians.

Returns the angle in [-pi, pi] using atan2, where: - 0 radians points to the right (positive x) - pi/2 radians points up (positive y) - pi radians points left (negative x) - -pi/2 radians points down (negative y)

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Target point column.	required

Returns:

Type	Description
`Expr`	Float64 angle in radians.

Example

df.with_columns( ... angle=pl.col("p1").point.angle_to(pl.col("p2")) ... )

rotate ¶

rotate(
    angle: float, *, origin: Expr | None = None
) -> pl.Expr

Rotate point around an origin by angle (in radians).

Parameters:

Name	Type	Description	Default
`angle`	`float`	Rotation angle in radians (counter-clockwise positive).	required
`origin`	`Expr \| None`	Center of rotation. If None, rotates around (0, 0).	`None`

Returns:

Type	Description
`Expr`	Rotated point.

Example

import math df.with_columns( ... rotated=pl.col("point").point.rotate(math.pi / 2) # 90 degrees ... )

midpoint ¶

midpoint(other: Expr) -> pl.Expr

Compute midpoint between this point and another.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Another point column.	required

Returns:

Type	Description
`Expr`	Point at the midpoint.

Example

df.with_columns( ... mid=pl.col("p1").point.midpoint(pl.col("p2")) ... )

interpolate ¶

interpolate(other: Expr, t: float = 0.5) -> pl.Expr

Linear interpolation between two points.

Parameters:

Name	Type	Description	Default
`other`	`Expr`	Target point column.	required
`t`	`float`	Interpolation parameter (0 = self, 1 = other). Values outside [0, 1] extrapolate beyond the endpoints.	`0.5`

Returns:

Type	Description
`Expr`	Interpolated point.

Example

df.with_columns( ... quarter=pl.col("p1").point.interpolate(pl.col("p2"), t=0.25) ... )

within_bbox ¶

within_bbox(bbox: Expr) -> pl.Expr

Check if point is within a bounding box.

Parameters:

Name	Type	Description	Default
`bbox`	`Expr`	Bounding box column with x, y, width, height fields.	required

Returns:

Type	Description
`Expr`	Boolean indicating if point is within the bbox.

Example

df.with_columns( ... inside=pl.col("point").point.within_bbox(pl.col("bbox")) ... )

x ¶

x() -> pl.Expr

Extract X coordinate.

Returns:

Type	Description
`Expr`	Float64 X coordinate.

y ¶

y() -> pl.Expr

Extract Y coordinate.

Returns:

Type	Description
`Expr`	Float64 Y coordinate.

Geometry¶

Schemas¶

POINT_SCHEMA¶

BBOX_SCHEMA¶

CONTOUR_SCHEMA¶

Helper Functions¶

ContourNamespace¶

__init__ ¶

normalize ¶

to_absolute ¶

winding ¶

area ¶

perimeter ¶

centroid ¶

bounding_box ¶

convex_hull ¶

is_convex ¶

flip ¶

ensure_winding ¶

translate ¶

scale ¶

simplify ¶

iou ¶

pairwise_iou ¶

match_detections ¶

label_reduce ¶

dice ¶

hausdorff_distance ¶

contains_point ¶

PointNamespace¶

__init__ ¶

normalize ¶

to_absolute ¶

translate ¶

scale ¶

distance ¶

manhattan_distance ¶

distance_to_contour ¶

signed_distance_to_contour ¶

nearest_point_on_contour ¶

angle_to ¶

rotate ¶

midpoint ¶

interpolate ¶

within_bbox ¶

x ¶

y ¶

init ¶

init ¶