Domains

polars-cv supports multi-domain pipelines that seamlessly transition between different data types.

Domain Types

Domain	Description	Example Data
buffer	Image/array data	Pixels, tensors
contour	Polygon geometry	Extracted shapes
scalar	Single number	Area, perimeter
vector	Multiple numbers	Centroid (x, y), BBox, histogram buckets

Domain Transitions

mermaid flowchart LR Buffer["buffer"] <-->|"extract/rasterize"| Contour["contour"] Buffer -->|"histogram(), label_reduce()"| Vector["vector"] Contour -->|"area(), perimeter()"| Scalar["scalar"] Contour -->|"centroid(), bbox()"| Vector

Buffer → Contour

Extract contours from a binary mask:

# Create binary mask and extract contours
pipe = (
    Pipeline()
    .source("image_bytes")
    .grayscale()
    .threshold(128)
    .extract_contours()
)

df = pl.DataFrame({"image": [png_bytes]})
# Sink as "native" returns the contour structs
result = df.with_columns(
    contours=pl.col("image").cv.pipe(pipe).sink("native")
)

Contour → Buffer

Rasterize contours to a mask:

# Contour source rasterizes to buffer
pipe = Pipeline().source("contour", width=200, height=200)

df = pl.DataFrame({"contour": [contour_data]}).cast({"contour": CONTOUR_SCHEMA})
result = df.with_columns(
    mask=pl.col("contour").cv.pipe(pipe).sink("numpy")
)

Contour → Scalar/Vector

Compute geometric measurements using the .contour namespace on Polars expressions:

import polars as pl

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

Type Inference

polars-cv performs static type inference at Polars planning time. The output type of a pipeline is determined by the operations and the final .sink() format.

# Returns Binary (PNG bytes)
pl.col("image").cv.pipe(pipe).sink("png")

# Returns Float64 (Scalar)
pl.col("contour").contour.area()