datumaro.experimental.converters#

Converter implementations for data transformation between different schemas.

This module contains concrete converter implementations that handle various data transformations such as format conversions, dtype conversions, and multi-field transformations.

Functions

list_eval_ref(list_col, ref_col, op)

Apply an operation element-wise between a list column and a reference column.

Classes

`BBoxCoordinateConverter`(**kwargs)	Convert bounding box coordinates between normalized and absolute formats.
`ImageBytesToImageConverter`(**kwargs)	Lazy converter that decodes images from byte data.
`ImageCallableToImageConverter`(**kwargs)	Lazy converter that executes callables to generate image data.
`ImagePathToImageConverter`(**kwargs)	Lazy converter that loads images from file paths using Pillow.
`PolygonToBBoxConverter`(**kwargs)	Converts polygon annotations to bounding boxes.
`PolygonToInstanceMaskConverter`(**kwargs)	Converts polygon annotations to instance masks.
`PolygonToMaskConverter`(**kwargs)	Converts polygon annotations to rasterized masks.
`RGBToBGRConverter`(**kwargs)	Converter that transforms RGB image format to BGR format.
`RotatedBBoxToPolygonConverter`(**kwargs)	Converts rotated bounding boxes to polygon coordinates.
`UInt8ToFloat32Converter`(**kwargs)	Convert image data from UInt8 to Float32 with normalization.

class datumaro.experimental.converters.RGBToBGRConverter(**kwargs: Any)[source]#

Bases: Converter

Converter that transforms RGB image format to BGR format.

This converter swaps the red and blue channels of RGB images to produce BGR format images, commonly used for OpenCV compatibility.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_image: AttributeSpec[ImageField]#

output_image: AttributeSpec[ImageField]#

filter_output_spec() → bool[source]#

Check if input is RGB and configure output for BGR conversion.

Returns:: True if the converter should be applied (RGB to BGR), False otherwise

convert(df: DataFrame) → DataFrame[source]#

Convert RGB image format to BGR using numpy channel swapping.

Parameters:: df – Input DataFrame containing RGB image data
Returns:: DataFrame with BGR image data in the output column

lazy: bool = False#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.UInt8ToFloat32Converter(**kwargs: Any)[source]#

Bases: Converter

Convert image data from UInt8 to Float32 with normalization.

This converter transforms 8-bit integer pixel values (0-255) to 32-bit floating point values normalized to the range [0.0, 1.0].

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_image: AttributeSpec[ImageField]#

output_image: AttributeSpec[ImageField]#

filter_output_spec() → bool[source]#

Check if input uses UInt8 dtype and configure Float32 output.

Returns:: True if the converter should be applied (UInt8 input), False otherwise

convert(df: DataFrame) → DataFrame[source]#

Convert image data from UInt8 to normalized Float32.

Transforms pixel values from the range [0, 255] to [0.0, 1.0] by dividing by 255.0.

Parameters:: df – Input DataFrame containing UInt8 image data
Returns:: DataFrame with normalized Float32 image data

lazy: bool = False#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.ImagePathToImageConverter(**kwargs: Any)[source]#

Bases: Converter

Lazy converter that loads images from file paths using Pillow.

This converter reads image files from disk and converts them to tensor format. It’s marked as lazy to defer the expensive I/O operation until the data is actually accessed.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_path: AttributeSpec[ImagePathField]#

output_image: AttributeSpec[ImageField]#

output_info: AttributeSpec[ImageInfoField]#

filter_output_spec() → bool[source]#: Configure output image specification based on input.

convert(df: DataFrame) → DataFrame[source]#

Convert image paths to loaded image tensors and image info.

Parameters:: df – DataFrame containing image path column
Returns:: DataFrame with loaded image data, shape information, and image info

lazy: bool = True#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.ImageBytesToImageConverter(**kwargs: Any)[source]#

Bases: Converter

Lazy converter that decodes images from byte data.

This converter takes encoded image bytes (PNG, JPEG, BMP, etc.) and decodes them to tensor format. It’s marked as lazy to defer the expensive decoding operation until the data is actually accessed.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_bytes: AttributeSpec[ImageBytesField]#

output_image: AttributeSpec[ImageField]#

output_info: AttributeSpec[ImageInfoField]#

filter_output_spec() → bool[source]#: Configure output image specification based on input.

convert(df: DataFrame) → DataFrame[source]#

Convert image bytes to decoded image tensors and image info.

Parameters:: df – DataFrame containing image bytes column
Returns:: DataFrame with decoded image data, shape information, and image info

lazy: bool = True#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

datumaro.experimental.converters.list_eval_ref(list_col: str, ref_col: str, op: Callable[[Expr, Expr], Expr]) → Expr[source]#

Apply an operation element-wise between a list column and a reference column.

This helper function enables operations between elements of a list column and values from a reference column, returning a new list column with the results.

Parameters:

list_col – Name of the list column
ref_col – Name of the reference column
op – Operation function to apply between list elements and reference values

Returns:

Polars expression for the computed list column

Note

See pola-rs/polars#7210 for implementation details

class datumaro.experimental.converters.BBoxCoordinateConverter(**kwargs: Any)[source]#

Bases: Converter

Convert bounding box coordinates between normalized and absolute formats.

This converter handles transformations between normalized coordinates (range [0,1]) and absolute pixel coordinates using image dimensions.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_bbox: AttributeSpec[BBoxField]#

input_image: AttributeSpec[ImageField]#

output_bbox: AttributeSpec[BBoxField]#

filter_output_spec() → bool[source]#

Check if bbox normalization conversion is needed and configure output.

Returns:: True if conversion is needed (normalization status differs), False otherwise

convert(df: DataFrame) → DataFrame[source]#

Convert bbox coordinates between normalized and absolute formats.

Uses image dimensions to transform coordinates. For normalized to absolute: multiplies by image dimensions. For absolute to normalized: divides by image dimensions.

Parameters:: df – Input DataFrame containing bbox and image data
Returns:: DataFrame with converted bounding box coordinates

lazy: bool = False#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.PolygonToMaskConverter(**kwargs: Any)[source]#

Bases: Converter

Converts polygon annotations to rasterized masks.

Transforms polygon coordinates into binary or indexed masks using OpenCV contour filling for efficient rasterization.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_polygon: AttributeSpec[PolygonField]#

input_labels: AttributeSpec[LabelField]#

input_image_info: AttributeSpec[ImageInfoField]#

output_mask: AttributeSpec[MaskField]#

background_index: int = 0#

filter_output_spec() → bool[source]#

Configure mask output specification.

Returns:: True if the converter should be applied, False otherwise

convert(df: DataFrame) → DataFrame[source]#

Rasterize polygon coordinates into indexed masks.

Parameters:: df – DataFrame with polygon coordinates, labels, and image info
Returns:: DataFrame with mask data in output column

lazy: bool = True#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.PolygonToInstanceMaskConverter(**kwargs: Any)[source]#

Bases: Converter

Converts polygon annotations to instance masks.

Transforms polygon coordinates into binary instance masks of shape (N, H, W) where N is the number of instances. Each mask represents a single instance without category information.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_polygon: AttributeSpec[PolygonField]#

input_image_info: AttributeSpec[ImageInfoField]#

output_instance_mask: AttributeSpec[InstanceMaskField]#

filter_output_spec() → bool[source]#: Configure output specification for instance mask format.

convert(df: DataFrame) → DataFrame[source]#

Rasterize polygon coordinates into instance masks.

Parameters:: df – DataFrame with polygon coordinates and image info
Returns:: DataFrame with instance mask data in output column

lazy: bool = True#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.PolygonToBBoxConverter(**kwargs: Any)[source]#

Bases: Converter

Converts polygon annotations to bounding boxes.

Extracts the bounding box coordinates that enclose each polygon.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_polygon: AttributeSpec[PolygonField]#

output_bbox: AttributeSpec[BBoxField]#

filter_output_spec() → bool[source]#: Configure output specification for bounding box format.

convert(df: DataFrame) → DataFrame[source]#

Extract bounding boxes from polygon coordinates.

Parameters:: df – DataFrame with polygon coordinates
Returns:: DataFrame with bounding box data in output column

lazy: bool = False#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.ImageCallableToImageConverter(**kwargs: Any)[source]#

Bases: Converter

Lazy converter that executes callables to generate image data.

This converter takes a callable stored in an ImageCallableField, executes it to get image data as a numpy array, and produces both ImageField and ImageInfoField outputs.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_callable: AttributeSpec[ImageCallableField]#

output_image: AttributeSpec[ImageField]#

output_info: AttributeSpec[ImageInfoField]#

filter_output_spec() → bool[source]#: Configure output image and info specifications based on input.

convert(df: DataFrame) → DataFrame[source]#

Execute callables to generate image data and metadata.

Parameters:: df – DataFrame containing callable column
Returns:: DataFrame with image tensor data, shape information, and image info

lazy: bool = True#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.

class datumaro.experimental.converters.RotatedBBoxToPolygonConverter(**kwargs: Any)[source]#

Bases: Converter

Converts rotated bounding boxes to polygon coordinates.

Transforms rotated bounding box parameters (cx, cy, w, h, r) into polygon corner points by rotating the rectangle corners around the center.

Initialize converter with input and output AttributeSpec instances.

Parameters:: **kwargs – AttributeSpec instances for converter inputs/outputs based on input_*/output_* class attributes

input_rotated_bbox: AttributeSpec[RotatedBBoxField]#

output_polygon: AttributeSpec[PolygonField]#

filter_output_spec() → bool[source]#: Configure output specification for polygon format.

convert(df: DataFrame) → DataFrame[source]#

Convert rotated bounding boxes to polygon corner points.

Parameters:: df – DataFrame with rotated bounding box coordinates
Returns:: DataFrame with polygon data in output column

lazy: bool = False#

Whether this converter performs lazy operations.

Lazy converters defer expensive operations (like loading images from disk) until data is actually accessed. When a lazy converter is in the conversion path, all dependent converters must also be executed lazily.