open-edge-platform
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 1 deletion b/‎CHANGELOG.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎src/datumaro/experimental/converters.py‎
Lines changed: 142 additions & 1 deletion b/‎src/datumaro/experimental/converters.py‎
Lines changed: 142 additions & 1 deletion
diff --git a/‎src/datumaro/experimental/fields.py‎
Lines changed: 172 additions & 7 deletions b/‎src/datumaro/experimental/fields.py‎
Lines changed: 172 additions & 7 deletions
@@ -57,7 +57,7 @@ This release streamlines Datumaro by removing a number of lesser-used features,
 
 ### New features
 - Experimental dataset class
-  (<https://github.com/open-edge-platform/datumaro/pull/1807>, <https://github.com/open-edge-platform/datumaro/pull/1810>, <https://github.com/open-edge-platform/datumaro/pull/1811>, <https://github.com/open-edge-platform/datumaro/pull/1834>, <https://github.com/open-edge-platform/datumaro/pull/1858>, <https://github.com/open-edge-platform/datumaro/pull/1845>, <https://github.com/open-edge-platform/datumaro/pull/1863>)
+  (<https://github.com/open-edge-platform/datumaro/pull/1807>, <https://github.com/open-edge-platform/datumaro/pull/1810>, <https://github.com/open-edge-platform/datumaro/pull/1811>, <https://github.com/open-edge-platform/datumaro/pull/1834>, <https://github.com/open-edge-platform/datumaro/pull/1858>, <https://github.com/open-edge-platform/datumaro/pull/1845>, <https://github.com/open-edge-platform/datumaro/pull/1863>, <https://github.com/open-edge-platform/datumaro/pull/1868>)
 
 ### Enhancements
 - Mark several dependencies as optional
 
@@ -11,12 +11,22 @@
 
 from typing import Any, Callable
 
+import cv2
 import numpy as np
 import polars as pl
 from PIL import Image
 
 from .converter_registry import AttributeSpec, Converter, converter
-from .fields import BBoxField, ImageField, ImagePathField
+from .fields import (
+    BBoxField,
+    ImageField,
+    ImageInfoField,
+    ImagePathField,
+    LabelField,
+    MaskField,
+    PolygonField,
+)
+from .type_registry import polars_to_numpy_dtype
 
 
 @converter
@@ -346,3 +356,134 @@ def op(x: pl.Expr, y: pl.Expr) -> pl.Expr:
         result_df = result_df.drop([temp_width_col, temp_height_col])
 
         return result_df
+
+
+@converter(lazy=True)
+class PolygonToMaskConverter(Converter):
+    """
+    Converts polygon annotations to rasterized masks.
+
+    Transforms polygon coordinates into binary or indexed masks using
+    OpenCV contour filling for efficient rasterization.
+    """
+
+    input_polygon: AttributeSpec[PolygonField]
+    input_labels: AttributeSpec[LabelField]
+    image_info: AttributeSpec[ImageInfoField]
+    output_mask: AttributeSpec[MaskField]
+
+    # Configuration options
+    background_index: int = 0  # Background value
+
+    def filter_output_spec(self) -> bool:
+        """
+        Configure mask output specification.
+
+        Returns:
+            True if the converter should be applied, False otherwise
+        """
+        # Configure output for mask format
+        self.output_mask = AttributeSpec(
+            name=self.output_mask.name,
+            field=MaskField(
+                semantic=self.input_polygon.field.semantic,
+                dtype=self.output_mask.field.dtype,
+            ),
+        )
+
+        return True
+
+    def convert(self, df: pl.DataFrame) -> pl.DataFrame:
+        """
+        Rasterize polygon coordinates into indexed masks.
+
+        Args:
+            df: DataFrame with polygon coordinates, labels, and image info
+
+        Returns:
+            DataFrame with mask data in output column
+        """
+        input_column_name = self.input_polygon.name
+        labels_column_name = self.input_labels.name
+        image_info_column_name = self.image_info.name
+        output_column_name = self.output_mask.name
+        output_shape_column_name = self.output_mask.name + "_shape"
+
+        def polygons_to_mask(
+            polygons_data: list, labels_data: list, img_info: dict
+        ) -> tuple[list[int], list[int]]:
+            """Rasterize polygons into indexed mask using OpenCV contour filling."""
+            # Extract image dimensions
+            image_width = img_info["width"]
+            image_height = img_info["height"]
+
+            # Initialize mask with background index
+            numpy_dtype = polars_to_numpy_dtype(self.output_mask.field.dtype)
+            mask = np.full(
+                shape=(image_height, image_width),
+                fill_value=self.background_index,
+                dtype=numpy_dtype,
+            )
+
+            # Rasterize each polygon
+            for i, polygon_data in enumerate(polygons_data):
+                coords = polygon_data.to_numpy()
+                class_index = labels_data[i]
+
+                # Denormalize coordinates if needed
+                if self.input_polygon.field.normalize:
+                    coords = coords.copy()
+                    coords[:, 0] *= image_width
+                    coords[:, 1] *= image_height
+
+                # Convert to OpenCV contour format
+                contour = coords.astype(np.int32)
+
+                # Fill polygon with class index
+                cv2.drawContours(
+                    mask,
+                    [contour],
+                    0,
+                    int(class_index),
+                    thickness=cv2.FILLED,
+                )
+
+            return mask.reshape(-1), [image_height, image_width]
+
+        # Apply conversion using map_batches
+        def apply_conversion_batch(batch_df: pl.DataFrame) -> pl.DataFrame:
+            """Apply polygon-to-mask conversion for a batch."""
+            batch_polygons = batch_df.struct["polygons"]
+            batch_labels = batch_df.struct["labels"]
+            batch_img_infos = batch_df.struct["img_info"]
+
+            results_batch_polygons = []
+            results_batch_shape = []
+            for polygons, labels, img_infos in zip(batch_polygons, batch_labels, batch_img_infos):
+                mask_data, shape_data = polygons_to_mask(polygons, labels, img_infos)
+                results_batch_polygons.append(pl.Series(mask_data))
+                results_batch_shape.append(shape_data)
+
+            return pl.struct(
+                pl.Series(results_batch_polygons).alias("mask"),
+                pl.Series(results_batch_shape, dtype=pl.List(pl.Int32)).alias("shape"),
+                eager=True,
+            )
+
+        mask_data = pl.struct(
+            [
+                pl.col(input_column_name).alias("polygons"),
+                pl.col(labels_column_name).alias("labels"),
+                pl.col(image_info_column_name).alias("img_info"),
+            ]
+        ).map_batches(
+            apply_conversion_batch,
+            return_dtype=pl.Struct({"mask": pl.List(pl.UInt8), "shape": pl.List(pl.Int32)}),
+        )
+
+        return df.with_columns(
+            [
+                mask_data.struct.field("mask").alias(output_column_name),
+                mask_data.struct.field("shape").alias(output_shape_column_name),
+            ]
+        )
@@ -262,22 +262,32 @@ class LabelField(Field):
     semantic: Semantic
     dtype: Any
     multi_label: bool = False  # Flag to indicate if this field should handle multi-labels
+    is_list: bool = False
+
+    @property
+    def _pl_type(self) -> pl.DataType:
+        pl_type = self.dtype
+        if self.multi_label:
+            pl_type = pl.List(pl_type)
+        if self.is_list:
+            pl_type = pl.List(pl_type)
+        return pl_type
 
     def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
         """Generate schema based on whether this is single or multi-label."""
-        if self.multi_label:
-            return {name: pl.List(self.dtype)}
-        return {name: self.dtype}
+        return {name: self._pl_type}
 
     def to_polars(self, name: str, value: Any) -> dict[str, pl.Series]:
         """Convert label(s) to Polars format for single or multi-label cases."""
+        pl_type = self._pl_type
+
         if value is None:
-            return {name: pl.Series(name, [None], dtype=self.dtype)}
+            return {name: pl.Series(name, [None], dtype=pl_type)}
 
         if self.multi_label:
             return {name: pl.Series(name, [to_numpy(value)], dtype=pl.List(self.dtype))}
 
-        return {name: pl.Series(name, [value], dtype=self.dtype)}
+        return {name: pl.Series(name, [value], dtype=pl_type)}
 
     def from_polars(self, name: str, row_index: int, df: pl.DataFrame, target_type: type[T]) -> T:
         """Reconstruct label(s) from Polars data."""
@@ -286,7 +296,10 @@ def from_polars(self, name: str, row_index: int, df: pl.DataFrame, target_type:
 
 
 def label_field(
-    dtype: Any = pl.Int32(), semantic: Semantic = Semantic.Default, multi_label: bool = False
+    dtype: Any = pl.Int32(),
+    semantic: Semantic = Semantic.Default,
+    multi_label: bool = False,
+    is_list: bool = False,
 ) -> Any:
     """
     Create a LabelField instance with the specified parameters.
@@ -295,8 +308,160 @@ def label_field(
         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
     """
-    return LabelField(semantic=semantic, dtype=dtype, multi_label=multi_label)
+    return LabelField(semantic=semantic, dtype=dtype, multi_label=multi_label, is_list=is_list)
+
+
+def convert_numpy_object_array_to_series(data: np.ndarray) -> pl.Series:
+    """
+    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]
+        ]
+    """
+    if data.dtype == object:
+        return pl.Series([convert_numpy_object_array_to_series(elem) for elem in data])
+    return pl.Series(data)
+
+
+@dataclass(frozen=True)
+class PolygonField(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.
+
+    Attributes:
+        semantic: Semantic tags describing the polygon purpose
+        dtype: Polars data type for coordinate values
+        format: Coordinate format (e.g., "xy", "yx")
+        normalize: Whether coordinates are normalized to [0,1] range
+    """
+
+    semantic: Semantic
+    dtype: Any
+    format: str
+    normalize: bool
+
+    def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
+        """Generate schema for polygon as list of coordinate values."""
+        return {name: pl.List(pl.List(pl.Array(self.dtype, 2)))}
+
+    def to_polars(self, name: str, value: Any) -> dict[str, pl.Series]:
+        """Convert polygon tensor to Polars list format."""
+        numpy_value = to_numpy(value, self.dtype)
+
+        series = convert_numpy_object_array_to_series(numpy_value)
+
+        return {name: pl.Series(name, [series], dtype=pl.List(pl.List(pl.Array(self.dtype, 2))))}
+
+    def from_polars(self, name: str, row_index: int, df: pl.DataFrame, target_type: type[T]) -> T:
+        """Reconstruct polygon tensor from Polars data."""
+        polars_data = df[name][row_index]
+        return from_polars_data(polars_data, target_type)  # type: ignore
+
+
+def polygon_field(
+    dtype: Any,
+    format: str = "xy",
+    normalize: bool = False,
+    semantic: Semantic = Semantic.Default,
+) -> Any:
+    """
+    Create a PolygonField instance with the specified parameters.
+
+    Args:
+        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
+    """
+    return PolygonField(semantic=semantic, dtype=dtype, format=format, normalize=normalize)
+
+
+@dataclass(frozen=True)
+class MaskField(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.
+
+    Attributes:
+        semantic: Semantic tags describing the mask purpose
+        dtype: Polars data type for mask values (defaults to uint8)
+    """
+
+    semantic: Semantic
+    dtype: Any
+
+    def to_polars_schema(self, name: str) -> dict[str, pl.DataType]:
+        """Generate Polars schema with separate columns for data and shape."""
+        return {name: pl.List(self.dtype), name + "_shape": pl.List(pl.Int32())}
+
+    def to_polars(self, name: str, value: Any) -> dict[str, pl.Series]:
+        """Convert mask tensor to flattened data and shape information."""
+        numpy_value = to_numpy(value, self.dtype)
+        return {
+            name: pl.Series(name, [numpy_value.reshape(-1)]),
+            name + "_shape": pl.Series(name + "_shape", [numpy_value.shape]),
+        }
+
+    def from_polars(self, name: str, row_index: int, df: pl.DataFrame, target_type: type[T]) -> T:
+        """Reconstruct mask tensor from flattened data using stored shape."""
+        flat_data = df[name][row_index]
+        shape = df[name + "_shape"][row_index]
+        numpy_data = np.array(flat_data).reshape(shape)
+        return from_polars_data(numpy_data, target_type)  # type: ignore
+
+
+def mask_field(dtype: Any = pl.UInt8(), semantic: Semantic = Semantic.Default) -> Any:
+    """
+    Create a MaskField instance with the specified parameters.
+
+    Args:
+        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
+    """
+    return MaskField(semantic=semantic, dtype=dtype)