hafnia 0.1.27__py3-none-any.whl → 0.2.1__py3-none-any.whl

hafnia/dataset/operations/dataset_transformations.py

@@ -0,0 +1,82 @@
+"""
+Hafnia dataset transformations that takes and returns a HafniaDataset object.
+
+All functions here will have a corresponding function in both the HafniaDataset class
+and a corresponding RecipeTransform class in the `data_recipe/recipe_transformations.py` file.
+
+This allows each function to be used in three ways:
+
+```python
+from hafnia.dataset.operations import dataset_transformations
+from hafnia.dataset.hafnia_dataset import HafniaDataset
+from hafnia.dataset.data_recipe.recipe_transformations import SplitByRatios
+
+splits_by_ratios = {"train": 0.8, "val": 0.1, "test": 0.1}
+
+# Option 1: Using the function directly
+dataset = recipe_transformations.splits_by_ratios(dataset, split_ratios=splits_by_ratios)
+
+# Option 2: Using the method of the HafniaDataset class
+dataset = dataset.splits_by_ratios(split_ratios=splits_by_ratios)
+
+# Option 3: Using the RecipeTransform class
+serializable_transform = SplitByRatios(split_ratios=splits_by_ratios)
+dataset = serializable_transform(dataset)
+```
+
+Tests will ensure that all functions in this file will have a corresponding function in the
+HafniaDataset class and a RecipeTransform class in the `data_recipe/recipe_transformations.py` file and
+that the signatures match.
+"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
+import cv2
+import numpy as np
+import polars as pl
+from PIL import Image
+from tqdm import tqdm
+
+from hafnia.dataset import dataset_helpers
+
+if TYPE_CHECKING:
+    from hafnia.dataset.hafnia_dataset import HafniaDataset
+
+
+### Image transformations ###
+class AnonymizeByPixelation:
+    def __init__(self, resize_factor: float = 0.10):
+        self.resize_factor = resize_factor
+
+    def __call__(self, frame: np.ndarray) -> np.ndarray:
+        org_size = frame.shape[:2]
+        frame = cv2.resize(frame, (0, 0), fx=self.resize_factor, fy=self.resize_factor)
+        frame = cv2.resize(frame, org_size[::-1], interpolation=cv2.INTER_NEAREST)
+        return frame
+
+
+def transform_images(
+    dataset: "HafniaDataset",
+    transform: Callable[[np.ndarray], np.ndarray],
+    path_output: Path,
+) -> "HafniaDataset":
+    new_paths = []
+    path_image_folder = path_output / "data"
+    path_image_folder.mkdir(parents=True, exist_ok=True)
+
+    for org_path in tqdm(dataset.samples["file_name"].to_list(), desc="Transform images"):
+        org_path = Path(org_path)
+        if not org_path.exists():
+            raise FileNotFoundError(f"File {org_path} does not exist in the dataset.")
+
+        image = np.array(Image.open(org_path))
+        image_transformed = transform(image)
+        new_path = dataset_helpers.save_image_with_hash_name(image_transformed, path_image_folder)
+
+        if not new_path.exists():
+            raise FileNotFoundError(f"Transformed file {new_path} does not exist in the dataset.")
+        new_paths.append(str(new_path))
+
+    table = dataset.samples.with_columns(pl.Series(new_paths).alias("file_name"))
+    return dataset.update_table(table)

hafnia/dataset/operations/table_transformations.py

@@ -0,0 +1,183 @@
+from pathlib import Path
+from typing import List, Optional, Type
+
+import polars as pl
+from tqdm import tqdm
+
+from hafnia.dataset.dataset_names import (
+    FILENAME_ANNOTATIONS_JSONL,
+    FILENAME_ANNOTATIONS_PARQUET,
+    FieldName,
+)
+from hafnia.dataset.operations import table_transformations
+from hafnia.dataset.primitives import PRIMITIVE_TYPES
+from hafnia.dataset.primitives.classification import Classification
+from hafnia.dataset.primitives.primitive import Primitive
+from hafnia.log import user_logger
+
+
+def create_primitive_table(
+    samples_table: pl.DataFrame, PrimitiveType: Type[Primitive], keep_sample_data: bool = False
+) -> Optional[pl.DataFrame]:
+    """
+    Returns a DataFrame with objects of the specified primitive type.
+    """
+    column_name = PrimitiveType.column_name()
+    has_primitive_column = (column_name in samples_table.columns) and (
+        samples_table[column_name].dtype == pl.List(pl.Struct)
+    )
+    if not has_primitive_column:
+        return None
+
+    # Remove frames without objects
+    remove_no_object_frames = samples_table.filter(pl.col(column_name).list.len() > 0)
+
+    if keep_sample_data:
+        # Drop other primitive columns to avoid conflicts
+        drop_columns = set(PRIMITIVE_TYPES) - {PrimitiveType, Classification}
+        remove_no_object_frames = remove_no_object_frames.drop(*[primitive.column_name() for primitive in drop_columns])
+        # Rename columns "height", "width" and "meta" for sample to avoid conflicts with object fields names
+        remove_no_object_frames = remove_no_object_frames.rename(
+            {"height": "image.height", "width": "image.width", "meta": "image.meta"}
+        )
+        objects_df = remove_no_object_frames.explode(column_name).unnest(column_name)
+    else:
+        objects_df = remove_no_object_frames.select(pl.col(column_name).explode().struct.unnest())
+    return objects_df
+
+
+def filter_table_for_class_names(
+    samples_table: pl.DataFrame, class_names: List[str], PrimitiveType: Type[Primitive]
+) -> Optional[pl.DataFrame]:
+    table_with_selected_class_names = samples_table.filter(
+        pl.col(PrimitiveType.column_name())
+        .list.eval(pl.element().struct.field(FieldName.CLASS_NAME).is_in(class_names))
+        .list.any()
+    )
+
+    return table_with_selected_class_names
+
+
+def split_primitive_columns_by_task_name(
+    samples_table: pl.DataFrame,
+    coordinate_types: Optional[List[Type[Primitive]]] = None,
+) -> pl.DataFrame:
+    """
+    Convert Primitive columns such as "objects" (Bbox) into a column for each task name.
+    For example, if the "objects" column (containing Bbox objects) has tasks "task1" and "task2".
+
+
+    This:
+    ─┬────────────┬─
+     ┆ objects    ┆
+     ┆ ---        ┆
+     ┆ list[struc ┆
+     ┆ t[11]]     ┆
+    ═╪════════════╪═
+    becomes this:
+    ─┬────────────┬────────────┬─
+     ┆ objects.   ┆ objects.   ┆
+     ┆ task1      ┆ task2      ┆
+     ┆ ---        ┆ ---        ┆
+     ┆ list[struc ┆ list[struc ┆
+     ┆ t[11]]     ┆ t[13]]     ┆
+    ═╪════════════╪════════════╪═
+
+    """
+    coordinate_types = coordinate_types or PRIMITIVE_TYPES
+    for PrimitiveType in coordinate_types:
+        col_name = PrimitiveType.column_name()
+
+        if col_name not in samples_table.columns:
+            continue
+
+        if samples_table[col_name].dtype != pl.List(pl.Struct):
+            continue
+
+        task_names = samples_table[col_name].explode().struct.field(FieldName.TASK_NAME).unique().to_list()
+        samples_table = samples_table.with_columns(
+            [
+                pl.col(col_name)
+                .list.filter(pl.element().struct.field(FieldName.TASK_NAME).eq(task_name))
+                .alias(f"{col_name}.{task_name}")
+                for task_name in task_names
+            ]
+        )
+        samples_table = samples_table.drop(col_name)
+    return samples_table
+
+
+def read_table_from_path(path: Path) -> pl.DataFrame:
+    path_annotations = path / FILENAME_ANNOTATIONS_PARQUET
+    if path_annotations.exists():
+        user_logger.info(f"Reading dataset annotations from Parquet file: {path_annotations}")
+        return pl.read_parquet(path_annotations)
+
+    path_annotations_jsonl = path / FILENAME_ANNOTATIONS_JSONL
+    if path_annotations_jsonl.exists():
+        user_logger.info(f"Reading dataset annotations from JSONL file: {path_annotations_jsonl}")
+        return pl.read_ndjson(path_annotations_jsonl)
+
+    raise FileNotFoundError(
+        f"Unable to read annotations. No json file '{path_annotations.name}' or Parquet file '{{path_annotations.name}} in in '{path}'."
+    )
+
+
+def check_image_paths(table: pl.DataFrame) -> bool:
+    missing_files = []
+    for org_path in tqdm(table["file_name"].to_list(), desc="Check image paths"):
+        org_path = Path(org_path)
+        if not org_path.exists():
+            missing_files.append(org_path)
+
+    if len(missing_files) > 0:
+        user_logger.warning(f"Missing files: {len(missing_files)}. Show first 5:")
+        for missing_file in missing_files[:5]:
+            user_logger.warning(f" - {missing_file}")
+        raise FileNotFoundError(f"Some files are missing in the dataset: {len(missing_files)} files not found.")
+
+    return True
+
+
+def unnest_classification_tasks(table: pl.DataFrame, strict: bool = True) -> pl.DataFrame:
+    """
+    Unnest classification tasks in table.
+    Classificiations tasks are all stored in the same column in the HafniaDataset table.
+    This function splits them into separate columns for each task name.
+
+    Type is converted from a list of structs (pl.List[pl.Struct]) to a struct (pl.Struct) column.
+
+    Converts classification column from this:
+       ─┬─────────────────┬─
+        ┆ classifications ┆
+        ┆ ---             ┆
+        ┆ list[struct[6]] ┆
+       ═╪═════════════════╪═
+
+    For example, if the classification column has tasks "task1" and "task2",
+       ─┬──────────────────┬──────────────────┬─
+        ┆ classifications. ┆ classifications. ┆
+        ┆ task1            ┆ task2            ┆
+        ┆ ---              ┆ ---              ┆
+        ┆ struct[6]        ┆ struct[6]        ┆
+       ═╪══════════════════╪══════════════════╪═
+
+    """
+    coordinate_types = [Classification]
+    table_out = table_transformations.split_primitive_columns_by_task_name(table, coordinate_types=coordinate_types)
+
+    classification_columns = [c for c in table_out.columns if c.startswith(Classification.column_name() + ".")]
+    for classification_column in classification_columns:
+        has_multiple_items_per_sample = all(table_out[classification_column].list.len() > 1)
+        if has_multiple_items_per_sample:
+            if strict:
+                raise ValueError(
+                    f"Column {classification_column} has multiple items per sample, but expected only one item."
+                )
+            else:
+                user_logger.warning(
+                    f"Warning: Unnesting of column '{classification_column}' is skipped because it has multiple items per sample."
+                )
+
+    table_out = table_out.with_columns([pl.col(c).list.first() for c in classification_columns])
+    return table_out

hafnia/dataset/primitives/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import List, Type
+
+from .bbox import Bbox
+from .bitmask import Bitmask
+from .classification import Classification
+from .point import Point  # noqa: F401
+from .polygon import Polygon
+from .primitive import Primitive
+from .segmentation import Segmentation  # noqa: F401
+from .utils import class_color_by_name  # noqa: F401
+
+PRIMITIVE_TYPES: List[Type[Primitive]] = [Bbox, Classification, Polygon, Bitmask]
+PRIMITIVE_NAME_TO_TYPE = {cls.__name__: cls for cls in PRIMITIVE_TYPES}
+PRIMITIVE_COLUMN_NAMES: List[str] = [PrimitiveType.column_name() for PrimitiveType in PRIMITIVE_TYPES]

hafnia/dataset/primitives/bbox.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import cv2
+import numpy as np
+
+from hafnia.dataset.primitives.primitive import Primitive
+from hafnia.dataset.primitives.utils import (
+    anonymize_by_resizing,
+    class_color_by_name,
+    clip,
+    get_class_name,
+    round_int_clip_value,
+)
+
+
+class Bbox(Primitive):
+    # Names should match names in FieldName
+    height: float  # Height of the bounding box as a fraction of the image height, e.g. 0.1 for 10% of the image height
+    width: float  # Width of the bounding box as a fraction of the image width, e.g. 0.1 for 10% of the image width
+    top_left_x: float  # X coordinate of top-left corner of Bbox as a fraction of the image width, e.g. 0.1 for 10% of the image width
+    top_left_y: float  # Y coordinate of top-left corner of Bbox as a fraction of the image height, e.g. 0.1 for 10% of the image height
+    class_name: Optional[str] = None  # Class name, e.g. "car"
+    class_idx: Optional[int] = None  # Class index, e.g. 0 for "car" if it is the first class
+    object_id: Optional[str] = None  # Unique identifier for the object, e.g. "12345123"
+    confidence: Optional[float] = None  # Confidence score (0-1.0) for the primitive, e.g. 0.95 for Bbox
+    ground_truth: bool = True  # Whether this is ground truth or a prediction
+
+    task_name: str = ""  # Task name to support multiple Bbox tasks in the same dataset. "" defaults to "bboxes"
+    meta: Optional[Dict[str, Any]] = None  # This can be used to store additional information about the bitmask
+
+    @staticmethod
+    def default_task_name() -> str:
+        return "bboxes"
+
+    @staticmethod
+    def column_name() -> str:
+        return "objects"
+
+    def calculate_area(self) -> float:
+        return self.height * self.width
+
+    @staticmethod
+    def from_coco(bbox: List, height: int, width: int) -> Bbox:
+        """
+        Converts a COCO-style bounding box to a Bbox object.
+        The bbox is in the format [x_min, y_min, width, height].
+        """
+        x_min, y_min, bbox_width, bbox_height = bbox
+        return Bbox(
+            top_left_x=x_min / width,
+            top_left_y=y_min / height,
+            width=bbox_width / width,
+            height=bbox_height / height,
+        )
+
+    def to_bbox(self) -> Tuple[float, float, float, float]:
+        """
+        Converts Bbox to a tuple of (x_min, y_min, width, height) with normalized coordinates.
+        Values are floats in the range [0, 1].
+        """
+        return (self.top_left_x, self.top_left_y, self.width, self.height)
+
+    def to_coco(self, image_height: int, image_width: int) -> Tuple[int, int, int, int]:
+        xmin = round_int_clip_value(self.top_left_x * image_width, max_value=image_width)
+        bbox_width = round_int_clip_value(self.width * image_width, max_value=image_width)
+
+        ymin = round_int_clip_value(self.top_left_y * image_height, max_value=image_height)
+        bbox_height = round_int_clip_value(self.height * image_height, max_value=image_height)
+
+        return xmin, ymin, bbox_width, bbox_height
+
+    def to_pixel_coordinates(
+        self, image_shape: Tuple[int, int], as_int: bool = True, clip_values: bool = True
+    ) -> Union[Tuple[float, float, float, float], Tuple[int, int, int, int]]:
+        bb_height = self.height * image_shape[0]
+        bb_width = self.width * image_shape[1]
+        bb_top_left_x = self.top_left_x * image_shape[1]
+        bb_top_left_y = self.top_left_y * image_shape[0]
+        xmin, ymin, xmax, ymax = bb_top_left_x, bb_top_left_y, bb_top_left_x + bb_width, bb_top_left_y + bb_height
+
+        if as_int:
+            xmin, ymin, xmax, ymax = int(round(xmin)), int(round(ymin)), int(round(xmax)), int(round(ymax))  # noqa: RUF046
+
+        if clip_values:
+            xmin = clip(value=xmin, v_min=0, v_max=image_shape[1])
+            xmax = clip(value=xmax, v_min=0, v_max=image_shape[1])
+            ymin = clip(value=ymin, v_min=0, v_max=image_shape[0])
+            ymax = clip(value=ymax, v_min=0, v_max=image_shape[0])
+
+        return xmin, ymin, xmax, ymax
+
+    def draw(self, image: np.ndarray, inplace: bool = False, draw_label: bool = True) -> np.ndarray:
+        if not inplace:
+            image = image.copy()
+        xmin, ymin, xmax, ymax = self.to_pixel_coordinates(image_shape=image.shape[:2])
+
+        class_name = self.get_class_name()
+        color = class_color_by_name(class_name)
+        font = cv2.FONT_HERSHEY_SIMPLEX
+        margin = 5
+        bottom_left = (xmin + margin, ymax - margin)
+        if draw_label:
+            cv2.putText(
+                img=image, text=class_name, org=bottom_left, fontFace=font, fontScale=0.75, color=color, thickness=2
+            )
+        cv2.rectangle(image, pt1=(xmin, ymin), pt2=(xmax, ymax), color=color, thickness=2)
+
+        return image
+
+    def mask(
+        self, image: np.ndarray, inplace: bool = False, color: Optional[Tuple[np.uint8, np.uint8, np.uint8]] = None
+    ) -> np.ndarray:
+        if not inplace:
+            image = image.copy()
+        xmin, ymin, xmax, ymax = self.to_pixel_coordinates(image_shape=image.shape[:2])
+        xmin, ymin, xmax, ymax = int(xmin), int(ymin), int(xmax), int(ymax)
+
+        if color is None:
+            color = np.mean(image[ymin:ymax, xmin:xmax], axis=(0, 1)).astype(np.uint8)
+
+        image[ymin:ymax, xmin:xmax] = color
+        return image
+
+    def anonymize_by_blurring(self, image: np.ndarray, inplace: bool = False, max_resolution: int = 20) -> np.ndarray:
+        if not inplace:
+            image = image.copy()
+        xmin, ymin, xmax, ymax = self.to_pixel_coordinates(image_shape=image.shape[:2])
+        xmin, ymin, xmax, ymax = int(xmin), int(ymin), int(xmax), int(ymax)
+        blur_region = image[ymin:ymax, xmin:xmax]
+        blur_region_upsized = anonymize_by_resizing(blur_region, max_resolution=max_resolution)
+        image[ymin:ymax, xmin:xmax] = blur_region_upsized
+        return image
+
+    def get_class_name(self) -> str:
+        return get_class_name(self.class_name, self.class_idx)

hafnia/dataset/primitives/bitmask.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+
+import cv2
+import numpy as np
+import pycocotools.mask as coco_mask
+
+from hafnia.dataset.primitives.primitive import Primitive
+from hafnia.dataset.primitives.utils import (
+    anonymize_by_resizing,
+    class_color_by_name,
+    get_class_name,
+    text_org_from_left_bottom_to_centered,
+)
+
+
+class Bitmask(Primitive):
+    # Names should match names in FieldName
+    top: int  # Bitmask top coordinate in pixels
+    left: int  # Bitmask left coordinate in pixels
+    height: int  # Bitmask height of the bounding box in pixels
+    width: int  # Bitmask width of the bounding box in pixels
+    rleString: str  # Run-length encoding (RLE) string for the bitmask region of size (height, width) at (top, left).
+    area: Optional[float] = None  # Area of the bitmask in pixels is calculated from the RLE string
+    class_name: Optional[str] = None  # This should match the string in 'FieldName.CLASS_NAME'
+    class_idx: Optional[int] = None  # This should match the string in 'FieldName.CLASS_IDX'
+    object_id: Optional[str] = None  # This should match the string in 'FieldName.OBJECT_ID'
+    confidence: Optional[float] = None  # Confidence score (0-1.0) for the primitive, e.g. 0.95 for Bbox
+    ground_truth: bool = True  # Whether this is ground truth or a prediction
+
+    task_name: str = ""  # Task name to support multiple Bitmask tasks in the same dataset. "" defaults to "bitmask"
+    meta: Optional[Dict[str, Any]] = None  # This can be used to store additional information about the bitmask
+
+    @staticmethod
+    def default_task_name() -> str:
+        return "bitmask"
+
+    @staticmethod
+    def column_name() -> str:
+        return "bitmasks"
+
+    def calculate_area(self) -> float:
+        raise NotImplementedError()
+
+    @staticmethod
+    def from_mask(
+        mask: np.ndarray,
+        top: int,  # Bounding box top coordinate in pixels
+        left: int,  # Bounding box left coordinate in pixels
+        class_name: Optional[str] = None,  # This should match the string in 'FieldName.CLASS_NAME'
+        class_idx: Optional[int] = None,  # This should match the string in 'FieldName.CLASS_IDX'
+        object_id: Optional[str] = None,  # This should match the string in 'FieldName.OBJECT_ID') -> "Bitmask":
+    ):
+        if len(mask.shape) != 2:
+            raise ValueError("Bitmask should be a 2-dimensional array.")
+
+        if mask.dtype != "|b1":
+            raise TypeError("Bitmask should be an array of boolean values. For numpy array call .astype(bool).")
+
+        h, w = mask.shape[:2]
+        area_pixels = np.sum(mask != 0)
+        area = area_pixels / (h * w)
+
+        mask_fortran = np.asfortranarray(mask, np.prod(h * w))  # Convert to Fortran order for COCO encoding
+        rle_coding = coco_mask.encode(mask_fortran.astype(bool))  # Encode the mask using COCO RLE
+        rle_string = rle_coding["counts"].decode("utf-8")  # Convert the counts to string
+
+        return Bitmask(
+            top=top,
+            left=left,
+            height=h,
+            width=w,
+            area=area,
+            rleString=rle_string,
+            class_name=class_name,
+            class_idx=class_idx,
+            object_id=object_id,
+        )
+
+    def squeeze_mask(self):
+        """
+        A mask may have large redundant areas of zeros. This function squeezes the mask to remove those areas.
+        """
+        region_mask = self.to_region_mask()
+        shift_left, last_left = np.flatnonzero(region_mask.sum(axis=0))[[0, -1]]
+        shift_top, last_top = np.flatnonzero(region_mask.sum(axis=1))[[0, -1]]
+        new_top = self.top + shift_top
+        new_left = self.left + shift_left
+        new_region_mask = region_mask[shift_top : last_top + 1, shift_left : last_left + 1]
+
+        bitmask_squeezed = Bitmask.from_mask(
+            mask=new_region_mask,
+            top=new_top,
+            left=new_left,
+            class_name=self.class_name,
+            class_idx=self.class_idx,
+            object_id=self.object_id,
+        )
+        return bitmask_squeezed
+
+    def anonymize_by_blurring(self, image: np.ndarray, inplace: bool = False, max_resolution: int = 20) -> np.ndarray:
+        mask_tight = self.squeeze_mask()
+
+        mask_region = mask_tight.to_region_mask()
+        region_image = image[
+            mask_tight.top : mask_tight.top + mask_tight.height, mask_tight.left : mask_tight.left + mask_tight.width
+        ]
+        region_image_blurred = anonymize_by_resizing(blur_region=region_image, max_resolution=max_resolution)
+        image_mixed = np.where(mask_region[:, :, None], region_image_blurred, region_image)
+        image[
+            mask_tight.top : mask_tight.top + mask_tight.height, mask_tight.left : mask_tight.left + mask_tight.width
+        ] = image_mixed
+        return image
+
+    def to_region_mask(self) -> np.ndarray:
+        """Returns a binary mask from the RLE string. The masks is only the region of the object and not the full image."""
+        rle = {"counts": self.rleString.encode(), "size": [self.height, self.width]}
+        mask = coco_mask.decode(rle) > 0
+        return mask
+
+    def to_mask(self, img_height: int, img_width: int) -> np.ndarray:
+        """Creates a full image mask from the RLE string."""
+
+        region_mask = self.to_region_mask()
+        bitmask_np = np.zeros((img_height, img_width), dtype=bool)
+        bitmask_np[self.top : self.top + self.height, self.left : self.left + self.width] = region_mask
+        return bitmask_np
+
+    def draw(self, image: np.ndarray, inplace: bool = False, draw_label: bool = True) -> np.ndarray:
+        if not inplace:
+            image = image.copy()
+        if image.ndim == 2:  # for grayscale/monochromatic images
+            image = cv2.cvtColor(image, cv2.COLOR_GRAY2RGB)
+        img_height, img_width = image.shape[:2]
+        bitmask_np = self.to_mask(img_height=img_height, img_width=img_width)
+
+        class_name = self.get_class_name()
+        color = class_color_by_name(class_name)
+
+        # Creates transparent masking with the specified color
+        image_masked = image.copy()
+        image_masked[bitmask_np] = color
+        cv2.addWeighted(src1=image, alpha=0.3, src2=image_masked, beta=0.7, gamma=0, dst=image)
+
+        if draw_label:
+            # Determines the center of mask
+            xy = np.stack(np.nonzero(bitmask_np))
+            xy_org = tuple(np.median(xy, axis=1).astype(int))[::-1]
+
+            xy_org = np.median(xy, axis=1).astype(int)[::-1]
+            font = cv2.FONT_HERSHEY_SIMPLEX
+            font_scale = 0.75
+            thickness = 2
+            xy_centered = text_org_from_left_bottom_to_centered(xy_org, class_name, font, font_scale, thickness)
+
+            cv2.putText(
+                img=image,
+                text=class_name,
+                org=xy_centered,
+                fontFace=font,
+                fontScale=font_scale,
+                color=(255, 255, 255),
+                thickness=thickness,
+            )
+        return image
+
+    def mask(
+        self, image: np.ndarray, inplace: bool = False, color: Optional[Tuple[np.uint8, np.uint8, np.uint8]] = None
+    ) -> np.ndarray:
+        if not inplace:
+            image = image.copy()
+
+        bitmask_np = self.to_mask(img_height=image.shape[0], img_width=image.shape[1])
+
+        if color is None:
+            color = tuple(int(value) for value in np.mean(image[bitmask_np], axis=0))  # type: ignore[assignment]
+        image[bitmask_np] = color
+        return image
+
+    def get_class_name(self) -> str:
+        return get_class_name(self.class_name, self.class_idx)

hafnia/dataset/primitives/classification.py

@@ -0,0 +1,56 @@
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+
+from hafnia.dataset.primitives.primitive import Primitive
+from hafnia.dataset.primitives.utils import anonymize_by_resizing, get_class_name
+
+
+class Classification(Primitive):
+    # Names should match names in FieldName
+    class_name: Optional[str] = None  # Class name, e.g. "car"
+    class_idx: Optional[int] = None  # Class index, e.g. 0 for "car" if it is the first class
+    object_id: Optional[str] = None  # Unique identifier for the object, e.g. "12345123"
+    confidence: Optional[float] = None  # Confidence score (0-1.0) for the primitive, e.g. 0.95 for Classification
+    ground_truth: bool = True  # Whether this is ground truth or a prediction
+
+    task_name: str = ""  # To support multiple Classification tasks in the same dataset. "" defaults to "classification"
+    meta: Optional[Dict[str, Any]] = None  # This can be used to store additional information about the bitmask
+
+    @staticmethod
+    def default_task_name() -> str:
+        return "classification"
+
+    @staticmethod
+    def column_name() -> str:
+        return "classifications"
+
+    def calculate_area(self) -> float:
+        return 1.0
+
+    def draw(self, image: np.ndarray, inplace: bool = False, draw_label: bool = True) -> np.ndarray:
+        if draw_label is False:
+            return image
+        from hafnia.visualizations import image_visualizations
+
+        class_name = self.get_class_name()
+        if self.task_name == self.default_task_name():
+            text = class_name
+        else:
+            text = f"{self.task_name}: {class_name}"
+        image = image_visualizations.append_text_below_frame(image, text=text)
+
+        return image
+
+    def mask(
+        self, image: np.ndarray, inplace: bool = False, color: Optional[Tuple[np.uint8, np.uint8, np.uint8]] = None
+    ) -> np.ndarray:
+        # Classification does not have a mask effect, so we return the image as is
+        return image
+
+    def anonymize_by_blurring(self, image: np.ndarray, inplace: bool = False, max_resolution: int = 20) -> np.ndarray:
+        # Classification does not have a blur effect, so we return the image as is
+        return anonymize_by_resizing(image, max_resolution=max_resolution)
+
+    def get_class_name(self) -> str:
+        return get_class_name(self.class_name, self.class_idx)

hafnia/dataset/primitives/point.py

@@ -0,0 +1,25 @@
+from typing import Any, Tuple
+
+from pydantic import BaseModel
+
+from hafnia.dataset.primitives.utils import clip
+
+
+class Point(BaseModel):
+    x: float
+    y: float
+
+    def to_pixel_coordinates(
+        self, image_shape: Tuple[int, int], as_int: bool = True, clip_values: bool = True
+    ) -> Tuple[Any, Any]:
+        x = self.x * image_shape[1]
+        y = self.y * image_shape[0]
+
+        if as_int:
+            x, y = int(round(x)), int(round(y))  # noqa: RUF046
+
+        if clip_values:
+            x = clip(value=x, v_min=0, v_max=image_shape[1])
+            y = clip(value=y, v_min=0, v_max=image_shape[0])
+
+        return x, y