Functions¶
Utility functions for working with polars-cv outputs.
NumPy Conversion¶
numpy_from_struct¶
Convert numpy/torch sink output (struct) to NumPy array.
The numpy and torch sinks return a Polars Struct with three fields:
- data: Binary - raw bytes of the array
- dtype: String - NumPy dtype code (e.g., "f4" for float32)
- shape: List[UInt64] - shape of the array
from polars_cv import numpy_from_struct
# From a Series element (dict)
arr = numpy_from_struct(result["tensor"][0])
print(f"Shape: {arr.shape}, dtype: {arr.dtype}")
# Or pass a Series directly (takes first element)
arr = numpy_from_struct(result["tensor"])
Mask Metrics¶
mask_iou¶
Compute IoU between two mask pipelines.
from polars_cv import mask_iou, Pipeline
import polars as pl
pred_pipe = Pipeline().source("image_bytes").grayscale().threshold(128)
gt_pipe = Pipeline().source("contour", width=256, height=256)
result = df.with_columns(
iou=mask_iou(
pl.col("prediction").cv.pipe(pred_pipe),
pl.col("ground_truth").cv.pipe(gt_pipe),
)
)
mask_dice¶
Compute Dice coefficient between two mask pipelines.
from polars_cv import mask_dice
result = df.with_columns(
dice=mask_dice(
pl.col("prediction").cv.pipe(pred_pipe),
pl.col("ground_truth").cv.pipe(gt_pipe),
)
)
Hash Comparison¶
hamming_distance¶
Compute Hamming distance between two perceptual hashes.
from polars_cv import hamming_distance, Pipeline
import polars as pl
hash_pipe = Pipeline().source("image_bytes").perceptual_hash()
result = df.with_columns(
distance=hamming_distance(
pl.col("image_a").cv.pipe(hash_pipe),
pl.col("image_b").cv.pipe(hash_pipe),
)
)
hash_similarity¶
Compute similarity percentage between two perceptual hashes.
from polars_cv import hash_similarity
result = df.with_columns(
similarity=hash_similarity(
pl.col("image_a").cv.pipe(hash_pipe),
pl.col("image_b").cv.pipe(hash_pipe),
hash_bits=64, # Match your hash size
)
)
Display¶
show_images¶
Display images from a binary column in Jupyter notebooks. Falls back to a text summary outside notebook environments.
Supports PNG, JPEG, WebP, TIFF, BMP, GIF, VIEW protocol blobs, and numpy-sink struct columns. Format is auto-detected.
Types¶
AlphaMode¶
Declares how an operation handles alpha channels.
from polars_cv import AlphaMode
AlphaMode.PASSTHROUGH # All channels processed uniformly
AlphaMode.STRIP_PROCESS_RESTORE # Alpha separated, restored after op
AlphaMode.DROP # Alpha discarded, output channels fixed
AlphaMode.NOT_APPLICABLE # Non-image ops
ColorSpace¶
Color space identifiers for cvt_color.
from polars_cv import ColorSpace
ColorSpace.RGB
ColorSpace.BGR
ColorSpace.HSV
ColorSpace.LAB
ColorSpace.YCBCR
ColorSpace.GRAY
CloudOptions¶
Configuration for cloud storage access.
from polars_cv import CloudOptions
options = CloudOptions(
aws_region="us-east-1",
aws_access_key_id="...",
aws_secret_access_key="...",
)
pipe = Pipeline().source("file_path", cloud_options=options)
HashAlgorithm¶
Perceptual hash algorithm selection.