datumaro.experimental.fields#

Field implementations for various data types including tensors, images, and bounding boxes.

This module provides concrete field implementations that handle serialization to/from Polars DataFrames for different data types commonly used in machine learning and computer vision applications.

Functions

`bbox_field`(dtype[, format, normalize, semantic])	Create a BBoxField instance with the specified parameters.
`convert_numpy_object_array_to_series`(data)	Convert ragged numpy object arrays to Polars Series recursively.
`image_bytes_field`([semantic])	Create an ImageBytesField instance with the specified parameters.
`image_callable_field`([format, semantic])	Create an ImageCallableField instance for storing image-generating callables.
`image_field`(dtype[, format, semantic])	Create an ImageField instance with the specified parameters.
`image_info_field`([semantic])	Create an ImageInfoField instance for storing image width and height.
`image_path_field`([semantic])	Create an ImagePathField instance with the specified semantic tags.
`instance_mask_field`([dtype, semantic])	Create an InstanceMaskField instance with the specified parameters.
`label_field`([dtype, semantic, multi_label, ...])	Create a LabelField instance with the specified parameters.
`mask_field`([dtype, semantic])	Create a MaskField instance with the specified parameters.
`polygon_field`(dtype[, format, normalize, ...])	Create a PolygonField instance with the specified parameters.
`rotated_bbox_field`(dtype[, format, ...])	Create a RotatedBBoxField instance with the specified parameters.
`tensor_field`(dtype[, semantic])	Create a TensorField instance with the specified semantic tags and data type.

Classes

`BBoxField`(semantic[, dtype, format, normalize])	Represents a bounding box field with format and normalization options.
`ImageBytesField`(semantic)	Represents an image field stored as bytes data.
`ImageCallableField`(semantic[, format])	Represents a field that stores a callable which returns an image as a numpy array.
`ImageField`(semantic[, dtype, format])	Represents an image tensor field with format information.
`ImageInfo`(width, height)	Container for image metadata (width and height).
`ImageInfoField`(semantic)	Represents image metadata (width, height) as a Polars struct.
`ImagePathField`(semantic)	Represents a field containing the file path to an image on disk.
`InstanceMaskField`(semantic[, dtype])	Represents an instance mask tensor field for instance segmentation masks.
`LabelField`(semantic[, dtype, multi_label, ...])	Represents a unified label annotation field that supports both single and multi-label scenarios.
`MaskField`(semantic[, dtype])	Represents a mask tensor field for binary or indexed segmentation masks.
`PolygonField`(semantic[, dtype, format, ...])	Represents a polygon field with format and normalization options.
`RotatedBBoxField`(semantic[, dtype, format, ...])	Represents a rotated bounding box field with format and normalization options.
`TensorField`(semantic[, dtype])	Represents a tensor field with semantic tags and data type information.

class datumaro.experimental.fields.TensorField(semantic: Semantic, dtype: type[DataType] | DataType = UInt8)[source]#

Bases: Field

Represents a tensor field with semantic tags and data type information.

This field handles n-dimensional tensor data by flattening it for storage and preserving shape information separately for reconstruction.

semantic#

Semantic tags describing the tensor’s purpose

Type:: datumaro.experimental.schema.Semantic

dtype#

Polars data type for tensor elements

Type:: type[polars.datatypes.classes.DataType] | polars.datatypes.classes.DataType

semantic: Semantic#

dtype: type[DataType] | DataType = UInt8#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate Polars schema with separate columns for data and shape.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert tensor to flattened data and shape information.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct tensor from flattened data using stored shape.

datumaro.experimental.fields.tensor_field(dtype: Any, semantic: Semantic = Semantic.Default) → Any[source]#

Create a TensorField instance with the specified semantic tags and data type.

Parameters:

dtype – Polars data type for tensor elements
semantic – Semantic tags describing the tensor’s purpose (optional)

Returns:

TensorField instance configured with the given parameters

class datumaro.experimental.fields.ImageField(semantic: Semantic, dtype: type[DataType] | DataType = UInt8, format: str = 'RGB')[source]#

Bases: TensorField

Represents an image tensor field with format information.

Extends TensorField to include image-specific metadata such as color format (RGB, BGR, etc.).

format#

Image color format (e.g., “RGB”, “BGR”, “RGBA”)

Type:: str

format: str = 'RGB'#

datumaro.experimental.fields.image_field(dtype: Any, format: str = 'RGB', semantic: Semantic = Semantic.Default) → Any[source]#

Create an ImageField instance with the specified parameters.

Parameters:

dtype – Polars data type for pixel values
format – Image color format (defaults to “RGB”)
semantic – Semantic tags describing the image’s purpose (optional)

Returns:

ImageField instance configured with the given parameters

class datumaro.experimental.fields.ImageBytesField(semantic: Semantic)[source]#

Bases: Field

Represents an image field stored as bytes data.

This field stores image data as encoded bytes (PNG, JPEG, BMP, etc.) and provides conversion capabilities to decode them into numpy arrays or encode numpy arrays into bytes format.

semantic#

Semantic tags describing the image’s purpose

Type:: datumaro.experimental.schema.Semantic

format#: Image encoding format (e.g., “PNG”, “JPEG”, “BMP”). If None, auto-detects format when decoding or defaults to PNG when encoding.

semantic: Semantic#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate schema for image bytes as binary data.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert image data to bytes and store in Polars series.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct image from bytes data.

datumaro.experimental.fields.image_bytes_field(semantic: Semantic = Semantic.Default) → Any[source]#

Create an ImageBytesField instance with the specified parameters.

Parameters:: semantic – Semantic tags describing the image’s purpose (optional)
Returns:: ImageBytesField instance configured with the given parameters

class datumaro.experimental.fields.BBoxField(semantic: Semantic, dtype: type[DataType] | DataType = Float32, format: str = 'x1y1x2y2', normalize: bool = False)[source]#

Bases: Field

Represents a bounding box field with format and normalization options.

Handles bounding box data with support for different coordinate formats and optional normalization to [0,1] range.

semantic#

Semantic tags describing the bounding box purpose

Type:: datumaro.experimental.schema.Semantic

dtype#

Polars data type for coordinate values

Type:: type[polars.datatypes.classes.DataType] | polars.datatypes.classes.DataType

format#

Coordinate format (e.g., “x1y1x2y2”, “xywh”)

Type:: str

normalize#

Whether coordinates are normalized to [0,1] range

Type:: bool

semantic: Semantic#

dtype: type[DataType] | DataType = Float32#

format: str = 'x1y1x2y2'#

normalize: bool = False#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate schema for bounding box as list of 4-element arrays.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert bounding box tensor to Polars list format.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct bounding box tensor from Polars data.

datumaro.experimental.fields.bbox_field(dtype: Any, format: str = 'x1y1x2y2', normalize: bool = False, semantic: Semantic = Semantic.Default) → Any[source]#

Create a BBoxField instance with the specified parameters.

Parameters:

dtype – Polars data type for coordinate values
format – Coordinate format (defaults to “x1y1x2y2”)
normalize – Whether coordinates are normalized (defaults to False)
semantic – Semantic tags describing the bounding box purpose (optional)

Returns:

BBoxField instance configured with the given parameters

class datumaro.experimental.fields.RotatedBBoxField(semantic: Semantic, dtype: type[DataType] | DataType = Float32, format: str = 'cxcywhr', normalize: bool = False)[source]#

Bases: Field

Represents a rotated bounding box field with format and normalization options.

Handles rotated bounding box data with support for different coordinate formats and optional normalization to [0,1] range. Stores all attributes (cx, cy, w, h, r) in one tensor similar to BBoxField.

semantic#

Semantic tags describing the rotated bounding box purpose

Type:: datumaro.experimental.schema.Semantic

dtype#

Polars data type for coordinate values

Type:: type[polars.datatypes.classes.DataType] | polars.datatypes.classes.DataType

format#

Coordinate format (e.g., “cxcywhr”, “cxcywha” for angle in degrees)

Type:: str

normalize#

Whether coordinates are normalized to [0,1] range

Type:: bool

semantic: Semantic#

dtype: type[DataType] | DataType = Float32#

format: str = 'cxcywhr'#

normalize: bool = False#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate schema for rotated bounding box as list of 5-element arrays.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert rotated bounding box tensor to Polars list format.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct rotated bounding box tensor from Polars data.

datumaro.experimental.fields.rotated_bbox_field(dtype: Any, format: str = 'cxcywhr', normalize: bool = False, semantic: Semantic = Semantic.Default) → Any[source]#

Create a RotatedBBoxField instance with the specified parameters.

Parameters:

dtype – Polars data type for coordinate values
format – Coordinate format (defaults to “cxcywhr” for cx,cy,w,h,rotation_radians)
normalize – Whether coordinates are normalized (defaults to False)
semantic – Semantic tags describing the rotated bounding box purpose (optional)

Returns:

RotatedBBoxField instance configured with the given parameters

class datumaro.experimental.fields.ImageInfo(width: int, height: int)[source]#

Bases: object

Container for image metadata (width and height).

width: int#

height: int#

class datumaro.experimental.fields.ImageInfoField(semantic: Semantic)[source]#

Bases: Field

Represents image metadata (width, height) as a Polars struct.

semantic: Semantic#

to_polars_schema(name: str) → dict[str, DataType][source]#

Generate Polars schema definition for this field.

Parameters:: name – The column name for this field
Returns:: Dictionary mapping column names to Polars data types
Raises:: NotImplementedError – Must be implemented by subclasses

to_polars(name: str, value: ImageInfo) → dict[str, Series][source]#

Convert the field value to Polars-compatible format.

Parameters:

name – The column name for this field
value – The value to convert

Returns:

Dictionary mapping column names to Polars Series

from_polars(name: str, row_index: int, df: DataFrame, target_type: type) → ImageInfo[source]#

Convert from Polars-compatible format back to the field’s value.

Parameters:

name – The column name for this field
row_index – The row index to extract
df – The source DataFrame
target_type – The target type to convert to

Returns:

The converted value in the target type

datumaro.experimental.fields.image_info_field(semantic: Semantic = Semantic.Default) → Any[source]#

Create an ImageInfoField instance for storing image width and height.

Parameters:: semantic – Optional semantic tags for disambiguation (e.g., Semantic.Left)
Returns:: ImageInfoField instance configured with the given semantic tags

class datumaro.experimental.fields.ImagePathField(semantic: Semantic)[source]#

Bases: Field

Represents a field containing the file path to an image on disk.

This field stores image file paths as strings and is typically used as input for lazy loading operations where images are loaded on-demand.

semantic#

Semantic tags describing the image path’s purpose

Type:: datumaro.experimental.schema.Semantic

semantic: Semantic#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate schema for string path column.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert path string to Polars series.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type)[source]#: Extract path string from Polars data.

datumaro.experimental.fields.image_path_field(semantic: Semantic = Semantic.Default) → Any[source]#

Create an ImagePathField instance with the specified semantic tags.

Parameters:: semantic – Semantic tags describing the image path’s purpose (optional)
Returns:: ImagePathField instance configured with the given semantic tags

class datumaro.experimental.fields.LabelField(semantic: Semantic, dtype: type[DataType] | DataType = UInt8, multi_label: bool = False, is_list: bool = False)[source]#

Bases: Field

Represents a unified label annotation field that supports both single and multi-label scenarios.

This field automatically detects whether the input is a single label or multiple labels and handles the conversion accordingly: - Single labels: stored as Int32 - Multi-labels: stored as List(Int32)

semantic: Semantic#

dtype: type[DataType] | DataType = UInt8#

multi_label: bool = False#

is_list: bool = False#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate schema based on whether this is single or multi-label.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert label(s) to Polars format for single or multi-label cases.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct label(s) from Polars data.

datumaro.experimental.fields.label_field(dtype: Any = Int32, semantic: Semantic = Semantic.Default, multi_label: bool = False, is_list: bool = False) → Any[source]#

Create a LabelField instance with the specified parameters.

Parameters:

dtype – Polars data type for label values (defaults to pl.Int32())
semantic – Semantic tags describing the label purpose (optional)
multi_label – Whether this field should handle multiple labels (defaults to False)
is_list – Whether this field should be treated as a list type (defaults to False)

Returns:

LabelField instance configured with the given parameters

datumaro.experimental.fields.convert_numpy_object_array_to_series(data: ndarray) → Series[source]#

Convert ragged numpy object arrays to Polars Series recursively.

Handles nested object arrays containing variable-length lists.

Example

>>> import numpy as np
>>> ragged = np.array([
...     np.array([1, 2, 3]),
...     np.array([4, 5]),
...     np.array([6, 7, 8, 9])
... ], dtype=object)
>>> series = convert_numpy_object_array_to_series(ragged)
>>> print(series)
shape: (3,)
Series: '' [list[i64]]
[
        [1, 2, 3]
        [4, 5]
        [6, 7, … 9]
]

# Compare with direct conversion which results # into an object Series instead of a list Series: >>> direct = pl.Series(ragged) >>> print(direct) shape: (3,) Series: ‘’ [o][object] [

[1 2 3] [4 5] [6 7 8 9]

]

class datumaro.experimental.fields.PolygonField(semantic: Semantic, dtype: type[DataType] | DataType = Float32, format: str = 'xy', normalize: bool = False)[source]#

Bases: Field

Represents a polygon field with format and normalization options.

Handles polygon data with support for different coordinate formats and optional normalization to [0,1] range. Polygons are stored as variable-length lists of coordinate pairs.

semantic#

Semantic tags describing the polygon purpose

Type:: datumaro.experimental.schema.Semantic

dtype#

Polars data type for coordinate values

Type:: type[polars.datatypes.classes.DataType] | polars.datatypes.classes.DataType

format#

Coordinate format (e.g., “xy”, “yx”)

Type:: str

normalize#

Whether coordinates are normalized to [0,1] range

Type:: bool

semantic: Semantic#

dtype: type[DataType] | DataType = Float32#

format: str = 'xy'#

normalize: bool = False#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate schema for polygon as list of coordinate values.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert polygon tensor to Polars list format.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct polygon tensor from Polars data.

datumaro.experimental.fields.polygon_field(dtype: Any, format: str = 'xy', normalize: bool = False, semantic: Semantic = Semantic.Default) → Any[source]#

Create a PolygonField instance with the specified parameters.

Parameters:

dtype – Polars data type for coordinate values
format – Coordinate format (defaults to “xy”)
normalize – Whether coordinates are normalized (defaults to False)
semantic – Semantic tags describing the polygon purpose (optional)

Returns:

PolygonField instance configured with the given parameters

class datumaro.experimental.fields.MaskField(semantic: Semantic, dtype: type[DataType] | DataType = UInt8)[source]#

Bases: Field

Represents a mask tensor field for binary or indexed segmentation masks.

Similar to TensorField but specialized for masks: handles single-channel 2D arrays with no color format specification. Uses uint8 as the default data type suitable for binary masks, class masks, or instance masks.

semantic#

Semantic tags describing the mask purpose

Type:: datumaro.experimental.schema.Semantic

dtype#

Polars data type for mask values (defaults to uint8)

Type:: type[polars.datatypes.classes.DataType] | polars.datatypes.classes.DataType

semantic: Semantic#

dtype: type[DataType] | DataType = UInt8#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate Polars schema with separate columns for data and shape.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert mask tensor to flattened data and shape information.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct mask tensor from flattened data using stored shape.

datumaro.experimental.fields.mask_field(dtype: Any = UInt8, semantic: Semantic = Semantic.Default) → Any[source]#

Create a MaskField instance with the specified parameters.

Parameters:

dtype – Polars data type for mask values (defaults to pl.UInt8())
semantic – Semantic tags describing the mask purpose (optional)

Returns:

MaskField instance configured with the given parameters

class datumaro.experimental.fields.InstanceMaskField(semantic: Semantic, dtype: type[DataType] | DataType = Boolean)[source]#

Bases: Field

Represents an instance mask tensor field for instance segmentation masks.

Handles 3D tensor data of shape (N, H, W) where N is the number of instances, H and W are the mask height and width. Each mask is a binary mask representing a single instance. Unlike MaskField, this does not contain category information.

semantic#

Semantic tags describing the instance mask purpose

Type:: datumaro.experimental.schema.Semantic

dtype#

Polars data type for mask values (defaults to bool for binary masks)

Type:: type[polars.datatypes.classes.DataType] | polars.datatypes.classes.DataType

semantic: Semantic#

dtype: type[DataType] | DataType = Boolean#

to_polars_schema(name: str) → dict[str, DataType][source]#: Generate Polars schema with separate columns for data and shape.

to_polars(name: str, value: Any) → dict[str, Series][source]#: Convert instance mask tensor to flattened data and shape information.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type[T]) → T[source]#: Reconstruct instance mask tensor from flattened data using stored shape.

datumaro.experimental.fields.instance_mask_field(dtype: Any = Boolean, semantic: Semantic = Semantic.Default) → Any[source]#

Create an InstanceMaskField instance with the specified parameters.

Parameters:

dtype – Polars data type for mask values (defaults to pl.Boolean())
semantic – Semantic tags describing the instance mask purpose (optional)

Returns:

InstanceMaskField instance configured with the given parameters

class datumaro.experimental.fields.ImageCallableField(semantic: Semantic, format: str = 'RGB')[source]#

Bases: Field

Represents a field that stores a callable which returns an image as a numpy array.

This field is useful for lazy loading scenarios where images are generated or loaded on-demand. The callable should return a numpy array representing the image data when invoked.

semantic#

Semantic tags describing the callable’s purpose

Type:: datumaro.experimental.schema.Semantic

format#

Expected image color format (e.g., “RGB”, “BGR”, “RGBA”)

Type:: str

semantic: Semantic#

format: str = 'RGB'#

to_polars_schema(name: str) → dict[str, DataType][source]#: Return schema with Object type to store callable.

to_polars(name: str, value: callable) → dict[str, Series][source]#: Store callable as Object in Polars series.

from_polars(name: str, row_index: int, df: DataFrame, target_type: type) → callable[source]#: Extract callable from Polars dataframe.

datumaro.experimental.fields.image_callable_field(format: str = 'RGB', semantic: Semantic = Semantic.Default) → Any[source]#

Create an ImageCallableField instance for storing image-generating callables.

Parameters:

format – Expected image color format (defaults to “RGB”)
semantic – Semantic tags describing the callable’s purpose (optional)

Returns:

ImageCallableField instance configured with the given parameters