nrtk-albumentations 2.1.0__py3-none-any.whl

albumentations/core/bbox_utils.py

@@ -0,0 +1,920 @@
+"""Utilities for handling bounding box operations during image augmentation.
+
+This module provides tools for processing bounding boxes in various formats (COCO, Pascal VOC, YOLO),
+converting between coordinate systems, normalizing and denormalizing coordinates, filtering
+boxes based on visibility and size criteria, and performing transformations on boxes to match
+image augmentations. It forms the core functionality for all bounding box-related operations
+in the albumentations library.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import numpy as np
+
+from albumentations.augmentations.utils import handle_empty_array
+from albumentations.core.type_definitions import MONO_CHANNEL_DIMENSIONS, NUM_BBOXES_COLUMNS_IN_ALBUMENTATIONS
+
+from .utils import DataProcessor, Params, ShapeType
+
+__all__ = [
+    "BboxParams",
+    "BboxProcessor",
+    "check_bboxes",
+    "convert_bboxes_from_albumentations",
+    "convert_bboxes_to_albumentations",
+    "denormalize_bboxes",
+    "filter_bboxes",
+    "normalize_bboxes",
+    "union_of_bboxes",
+]
+
+BBOX_WITH_LABEL_SHAPE = 5
+
+
+class BboxParams(Params):
+    """Parameters for bounding box transforms.
+
+    Args:
+        format (Literal["coco", "pascal_voc", "albumentations", "yolo"]): Format of bounding boxes.
+            Should be one of:
+            - 'coco': [x_min, y_min, width, height], e.g. [97, 12, 150, 200].
+            - 'pascal_voc': [x_min, y_min, x_max, y_max], e.g. [97, 12, 247, 212].
+            - 'albumentations': like pascal_voc but normalized in [0, 1] range, e.g. [0.2, 0.3, 0.4, 0.5].
+            - 'yolo': [x_center, y_center, width, height] normalized in [0, 1] range, e.g. [0.1, 0.2, 0.3, 0.4].
+
+        label_fields (Sequence[str] | None): List of fields that are joined with boxes,
+            e.g., ['class_labels', 'scores']. Default: None.
+
+        min_area (float): Minimum area of a bounding box. All bounding boxes whose visible area in pixels is less than
+            this value will be removed. Default: 0.0.
+
+        min_visibility (float): Minimum fraction of area for a bounding box to remain this box in the result.
+            Should be in [0.0, 1.0] range. Default: 0.0.
+
+        min_width (float): Minimum width of a bounding box in pixels or normalized units. Bounding boxes with width
+            less than this value will be removed. Default: 0.0.
+
+        min_height (float): Minimum height of a bounding box in pixels or normalized units. Bounding boxes with height
+            less than this value will be removed. Default: 0.0.
+
+        check_each_transform (bool): If True, performs checks for each dual transform. Default: True.
+
+        clip (bool): If True, clips bounding boxes to image boundaries before applying any transform. Default: False.
+
+        filter_invalid_bboxes (bool): If True, filters out invalid bounding boxes (e.g., boxes with negative dimensions
+            or boxes where x_max < x_min or y_max < y_min) at the beginning of the pipeline. If clip=True, filtering
+            is applied after clipping. Default: False.
+
+        max_accept_ratio (float | None): Maximum allowed aspect ratio for bounding boxes. The aspect ratio is calculated
+            as max(width/height, height/width), so it's always >= 1. Boxes with aspect ratio greater than this value
+            will be filtered out. For example, if max_accept_ratio=3.0, boxes with width:height or height:width ratios
+            greater than 3:1 will be removed. Set to None to disable aspect ratio filtering. Default: None.
+
+
+    Note:
+        The processing order for bounding boxes is:
+        1. Convert to albumentations format (normalized pascal_voc)
+        2. Clip boxes to image boundaries (if clip=True)
+        3. Filter invalid boxes (if filter_invalid_bboxes=True)
+        4. Apply transformations
+        5. Filter boxes based on min_area, min_visibility, min_width, min_height
+        6. Convert back to the original format
+
+    Examples:
+        >>> # Create BboxParams for COCO format with class labels
+        >>> bbox_params = BboxParams(
+        ...     format='coco',
+        ...     label_fields=['class_labels'],
+        ...     min_area=1024,
+        ...     min_visibility=0.1
+        ... )
+
+        >>> # Create BboxParams that clips and filters invalid boxes
+        >>> bbox_params = BboxParams(
+        ...     format='pascal_voc',
+        ...     clip=True,
+        ...     filter_invalid_bboxes=True
+        ... )
+        >>> # Create BboxParams that filters extremely elongated boxes
+        >>> bbox_params = BboxParams(
+        ...     format='yolo',
+        ...     max_accept_ratio=5.0,  # Filter boxes with aspect ratio > 5:1
+        ...     clip=True
+        ... )
+
+    """
+
+    def __init__(
+        self,
+        format: Literal["coco", "pascal_voc", "albumentations", "yolo"],  # noqa: A002
+        label_fields: Sequence[Any] | None = None,
+        min_area: float = 0.0,
+        min_visibility: float = 0.0,
+        min_width: float = 0.0,
+        min_height: float = 0.0,
+        check_each_transform: bool = True,
+        clip: bool = False,
+        filter_invalid_bboxes: bool = False,
+        max_accept_ratio: float | None = None,
+    ):
+        super().__init__(format, label_fields)
+        self.min_area = min_area
+        self.min_visibility = min_visibility
+        self.min_width = min_width
+        self.min_height = min_height
+        self.check_each_transform = check_each_transform
+        self.clip = clip
+        self.filter_invalid_bboxes = filter_invalid_bboxes
+        if max_accept_ratio is not None and max_accept_ratio < 1.0:
+            raise ValueError(
+                "max_accept_ratio must be >= 1.0 when provided, as aspect ratio is calculated as max(w/h, h/w)",
+            )
+        self.max_accept_ratio = max_accept_ratio  # e.g., 5.0
+
+    def to_dict_private(self) -> dict[str, Any]:
+        """Get the private dictionary representation of bounding box parameters.
+
+        Returns:
+            dict[str, Any]: Dictionary containing the bounding box parameters.
+
+        """
+        data = super().to_dict_private()
+        data.update(
+            {
+                "min_area": self.min_area,
+                "min_visibility": self.min_visibility,
+                "min_width": self.min_width,
+                "min_height": self.min_height,
+                "check_each_transform": self.check_each_transform,
+                "clip": self.clip,
+                "max_accept_ratio": self.max_accept_ratio,
+            },
+        )
+        return data
+
+    @classmethod
+    def is_serializable(cls) -> bool:
+        """Check if the bounding box parameters are serializable.
+
+        Returns:
+            bool: Always returns True as BboxParams is serializable.
+
+        """
+        return True
+
+    @classmethod
+    def get_class_fullname(cls) -> str:
+        """Get the full name of the class.
+
+        Returns:
+            str: The string "BboxParams".
+
+        """
+        return "BboxParams"
+
+    def __repr__(self) -> str:
+        return (
+            f"BboxParams(format={self.format}, label_fields={self.label_fields}, min_area={self.min_area},"
+            f" min_visibility={self.min_visibility}, min_width={self.min_width}, min_height={self.min_height},"
+            f" check_each_transform={self.check_each_transform}, clip={self.clip})"
+        )
+
+
+class BboxProcessor(DataProcessor):
+    """Processor for bounding box transformations.
+
+    This class handles the preprocessing and postprocessing of bounding boxes during augmentation pipeline,
+    including format conversion, validation, clipping, and filtering.
+
+    Args:
+        params (BboxParams): Parameters that control bounding box processing.
+            See BboxParams class for details.
+        additional_targets (dict[str, str] | None): Dictionary with additional targets to process.
+            Keys are names of additional targets, values are their types.
+            For example: {'bbox2': 'bboxes'} will handle 'bbox2' as another bounding box target.
+            Default: None.
+
+    Note:
+        The processing order for bounding boxes is:
+        1. Convert to albumentations format (normalized pascal_voc)
+        2. Clip boxes to image boundaries (if params.clip=True)
+        3. Filter invalid boxes (if params.filter_invalid_bboxes=True)
+        4. Apply transformations
+        5. Filter boxes based on min_area, min_visibility, min_width, min_height
+        6. Convert back to the original format
+
+    Examples:
+        >>> import albumentations as A
+        >>> # Process COCO format bboxes with class labels
+        >>> params = A.BboxParams(
+        ...     format='coco',
+        ...     label_fields=['class_labels'],
+        ...     min_area=1024,
+        ...     min_visibility=0.1
+        ... )
+        >>> processor = BboxProcessor(params)
+        >>>
+        >>> # Process multiple bbox fields
+        >>> params = A.BboxParams('pascal_voc')
+        >>> processor = BboxProcessor(
+        ...     params,
+        ...     additional_targets={'bbox2': 'bboxes'}
+        ... )
+
+    """
+
+    def __init__(self, params: BboxParams, additional_targets: dict[str, str] | None = None):
+        super().__init__(params, additional_targets)
+
+    @property
+    def default_data_name(self) -> str:
+        """Returns the default key for bounding box data in transformations.
+
+        Returns:
+            str: The string 'bboxes'.
+
+        """
+        return "bboxes"
+
+    def ensure_data_valid(self, data: dict[str, Any]) -> None:
+        """Validates the input bounding box data.
+
+        Checks that:
+        - Bounding boxes have labels (either in the bbox array or in label_fields)
+        - All specified label_fields exist in the data
+
+        Args:
+            data (dict[str, Any]): Dict with bounding boxes and optional label fields.
+
+        Raises:
+            ValueError: If bounding boxes don't have labels or if label_fields are invalid.
+
+        """
+        if self.params.label_fields and not all(i in data for i in self.params.label_fields):
+            msg = "Your 'label_fields' are not valid - them must have same names as params in dict"
+            raise ValueError(msg)
+
+    def filter(self, data: np.ndarray, shape: ShapeType) -> np.ndarray:
+        """Filter bounding boxes based on size and visibility criteria.
+
+        Args:
+            data (np.ndarray): Array of bounding boxes in Albumentations format.
+            shape (ShapeType): Shape information for validation.
+
+        Returns:
+            np.ndarray: Filtered bounding boxes that meet the criteria.
+
+        """
+        self.params: BboxParams
+        return filter_bboxes(
+            data,
+            shape,
+            min_area=self.params.min_area,
+            min_visibility=self.params.min_visibility,
+            min_width=self.params.min_width,
+            min_height=self.params.min_height,
+            max_accept_ratio=self.params.max_accept_ratio,
+        )
+
+    def check_and_convert(
+        self,
+        data: np.ndarray,
+        shape: ShapeType,
+        direction: Literal["to", "from"] = "to",
+    ) -> np.ndarray:
+        """Converts bounding boxes between formats and applies preprocessing/postprocessing.
+
+        Args:
+            data (np.ndarray): Array of bounding boxes to process.
+            shape (ShapeType): Image shape as dict with height and width keys.
+            direction (Literal["to", "from"]): Direction of conversion:
+                - "to": Convert from original format to albumentations format
+                - "from": Convert from albumentations format to original format
+                Default: "to".
+
+        Returns:
+            np.ndarray: Processed bounding boxes.
+
+        Note:
+            When direction="to":
+            1. Converts to albumentations format
+            2. Clips boxes if params.clip=True
+            3. Filters invalid boxes if params.filter_invalid_bboxes=True
+            4. Validates remaining boxes
+
+            When direction="from":
+            1. Validates boxes
+            2. Converts back to original format
+
+        """
+        if direction == "to":
+            # First convert to albumentations format
+            if self.params.format == "albumentations":
+                converted_data = data
+            else:
+                converted_data = convert_bboxes_to_albumentations(
+                    data,
+                    self.params.format,
+                    shape,
+                    check_validity=False,  # Don't check validity yet
+                )
+
+            if self.params.clip and converted_data.size > 0:
+                converted_data[:, :4] = np.clip(converted_data[:, :4], 0, 1)
+
+            # Then filter invalid boxes if requested
+            if self.params.filter_invalid_bboxes:
+                converted_data = filter_bboxes(
+                    converted_data,
+                    shape,
+                    min_area=0,
+                    min_visibility=0,
+                    min_width=0,
+                    min_height=0,
+                )
+
+            # Finally check the remaining boxes
+            self.check(converted_data, shape)
+            return converted_data
+        self.check(data, shape)
+        if self.params.format == "albumentations":
+            return data
+        return convert_bboxes_from_albumentations(data, self.params.format, shape)
+
+    def check(self, data: np.ndarray, shape: ShapeType) -> None:
+        """Check if bounding boxes are valid.
+
+        Args:
+            data (np.ndarray): Array of bounding boxes to validate.
+            shape (ShapeType): Shape to check against.
+
+        """
+        check_bboxes(data)
+
+    def convert_from_albumentations(self, data: np.ndarray, shape: ShapeType) -> np.ndarray:
+        """Convert bounding boxes from internal Albumentations format to the specified format.
+
+        Args:
+            data (np.ndarray): Bounding boxes in Albumentations format.
+            shape (ShapeType): Shape information for validation.
+
+        Returns:
+            np.ndarray: Converted bounding boxes in the target format.
+
+        """
+        return np.array(
+            convert_bboxes_from_albumentations(data, self.params.format, shape, check_validity=True),
+            dtype=data.dtype,
+        )
+
+    def convert_to_albumentations(self, data: np.ndarray, shape: ShapeType) -> np.ndarray:
+        """Convert bounding boxes from the specified format to internal Albumentations format.
+
+        Args:
+            data (np.ndarray): Bounding boxes in source format.
+            shape (ShapeType): Shape information for validation.
+
+        Returns:
+            np.ndarray: Converted bounding boxes in Albumentations format.
+
+        """
+        if self.params.clip:
+            data_np = convert_bboxes_to_albumentations(data, self.params.format, shape, check_validity=False)
+            data_np = filter_bboxes(data_np, shape, min_area=0, min_visibility=0, min_width=0, min_height=0)
+            check_bboxes(data_np)
+            return data_np
+
+        return convert_bboxes_to_albumentations(data, self.params.format, shape, check_validity=True)
+
+
+@handle_empty_array("bboxes")
+def normalize_bboxes(bboxes: np.ndarray, shape: ShapeType | tuple[int, int]) -> np.ndarray:
+    """Normalize array of bounding boxes.
+
+    Args:
+        bboxes (np.ndarray): Denormalized bounding boxes `[(x_min, y_min, x_max, y_max, ...)]`.
+        shape (ShapeType | tuple[int, int]): Image shape `(height, width)`.
+
+    Returns:
+        np.ndarray: Normalized bounding boxes `[(x_min, y_min, x_max, y_max, ...)]`.
+
+    """
+    if isinstance(shape, tuple):
+        rows, cols = shape[:2]
+    else:
+        rows, cols = shape["height"], shape["width"]
+
+    normalized = bboxes.copy().astype(float)
+    normalized[:, [0, 2]] /= cols
+    normalized[:, [1, 3]] /= rows
+    return normalized
+
+
+@handle_empty_array("bboxes")
+def denormalize_bboxes(
+    bboxes: np.ndarray,
+    shape: ShapeType | tuple[int, int],
+) -> np.ndarray:
+    """Denormalize array of bounding boxes.
+
+    Args:
+        bboxes (np.ndarray): Normalized bounding boxes `[(x_min, y_min, x_max, y_max, ...)]`.
+        shape (ShapeType | tuple[int, int]): Image shape `(height, width)`.
+
+    Returns:
+        np.ndarray: Denormalized bounding boxes `[(x_min, y_min, x_max, y_max, ...)]`.
+
+    """
+    scale_factors = (shape[1], shape[0]) if isinstance(shape, tuple) else (shape["width"], shape["height"])
+
+    # Vectorized scaling of bbox coordinates
+    return bboxes * np.array([*scale_factors, *scale_factors, *[1] * (bboxes.shape[1] - 4)], dtype=float)
+
+
+def calculate_bbox_areas_in_pixels(bboxes: np.ndarray, shape: ShapeType) -> np.ndarray:
+    """Calculate areas for multiple bounding boxes.
+    This function computes the areas of bounding boxes given their normalized coordinates
+    and the dimensions of the image they belong to. The bounding boxes are expected to be
+    in the format [x_min, y_min, x_max, y_max] with normalized coordinates (0 to 1).
+
+    Args:
+        bboxes (np.ndarray): A numpy array of shape (N, 4+) where N is the number of bounding boxes.
+                             Each row contains [x_min, y_min, x_max, y_max] in normalized coordinates.
+                             Additional columns beyond the first 4 are ignored.
+        shape (ShapeType): A tuple containing the height and width of the image (height, width).
+
+    Returns:
+        np.ndarray: A 1D numpy array of shape (N,) containing the areas of the bounding boxes in pixels.
+                    Returns an empty array if the input `bboxes` is empty.
+
+    Note:
+        - The function assumes that the input bounding boxes are valid (i.e., x_max > x_min and y_max > y_min).
+          Invalid bounding boxes may result in negative areas.
+        - The function preserves the input array and creates a copy for internal calculations.
+        - The returned areas are in pixel units, not normalized.
+
+    Examples:
+        >>> bboxes = np.array([[0.1, 0.1, 0.5, 0.5], [0.2, 0.2, 0.8, 0.8]])
+        >>> image_shape = (100, 100)
+        >>> areas = calculate_bbox_areas(bboxes, image_shape)
+        >>> print(areas)
+        [1600. 3600.]
+
+    """
+    if len(bboxes) == 0:
+        return np.array([], dtype=np.float32)
+
+    # Unpack shape to variables
+    height, width = shape["height"], shape["width"]
+
+    # Directly compute denormalized bbox dimensions and areas
+    widths = (bboxes[:, 2] - bboxes[:, 0]) * width
+    heights = (bboxes[:, 3] - bboxes[:, 1]) * height
+
+    return widths * heights
+
+
+@handle_empty_array("bboxes")
+def convert_bboxes_to_albumentations(
+    bboxes: np.ndarray,
+    source_format: Literal["coco", "pascal_voc", "yolo"],
+    shape: ShapeType,
+    check_validity: bool = False,
+) -> np.ndarray:
+    """Convert bounding boxes from a specified format to the format used by albumentations:
+    normalized coordinates of top-left and bottom-right corners of the bounding box in the form of
+    `(x_min, y_min, x_max, y_max)` e.g. `(0.15, 0.27, 0.67, 0.5)`.
+
+    Args:
+        bboxes (np.ndarray): A numpy array of bounding boxes with shape (num_bboxes, 4+).
+        source_format (Literal["coco", "pascal_voc", "yolo"]): Format of the input bounding boxes.
+        shape (ShapeType): Image shape (height, width).
+        check_validity (bool): Check if all boxes are valid boxes.
+
+    Returns:
+        np.ndarray: An array of bounding boxes in albumentations format with shape (num_bboxes, 4+).
+
+    Raises:
+        ValueError: If `source_format` is not 'coco', 'pascal_voc', or 'yolo'.
+        ValueError: If in YOLO format, any coordinates are not in the range (0, 1].
+
+    """
+    if source_format not in {"coco", "pascal_voc", "yolo"}:
+        raise ValueError(
+            f"Unknown source_format {source_format}. Supported formats are: 'coco', 'pascal_voc' and 'yolo'",
+        )
+
+    bboxes = bboxes.copy().astype(np.float32)
+    converted_bboxes = np.zeros_like(bboxes)
+    converted_bboxes[:, 4:] = bboxes[:, 4:]  # Preserve additional columns
+
+    if source_format == "coco":
+        converted_bboxes[:, 0] = bboxes[:, 0]  # x_min
+        converted_bboxes[:, 1] = bboxes[:, 1]  # y_min
+        converted_bboxes[:, 2] = bboxes[:, 0] + bboxes[:, 2]  # x_max
+        converted_bboxes[:, 3] = bboxes[:, 1] + bboxes[:, 3]  # y_max
+    elif source_format == "yolo":
+        if check_validity and np.any((bboxes[:, :4] <= 0) | (bboxes[:, :4] > 1)):
+            raise ValueError(f"In YOLO format all coordinates must be float and in range (0, 1], got {bboxes}")
+
+        w_half, h_half = bboxes[:, 2] / 2, bboxes[:, 3] / 2
+        converted_bboxes[:, 0] = bboxes[:, 0] - w_half  # x_min
+        converted_bboxes[:, 1] = bboxes[:, 1] - h_half  # y_min
+        converted_bboxes[:, 2] = bboxes[:, 0] + w_half  # x_max
+        converted_bboxes[:, 3] = bboxes[:, 1] + h_half  # y_max
+    else:  # pascal_voc
+        converted_bboxes[:, :4] = bboxes[:, :4]
+
+    if source_format != "yolo":
+        converted_bboxes[:, :4] = normalize_bboxes(converted_bboxes[:, :4], shape)
+
+    if check_validity:
+        check_bboxes(converted_bboxes)
+
+    return converted_bboxes
+
+
+@handle_empty_array("bboxes")
+def convert_bboxes_from_albumentations(
+    bboxes: np.ndarray,
+    target_format: Literal["coco", "pascal_voc", "yolo"],
+    shape: ShapeType,
+    check_validity: bool = False,
+) -> np.ndarray:
+    """Convert bounding boxes from the format used by albumentations to a specified format.
+
+    Args:
+        bboxes (np.ndarray): A numpy array of albumentations bounding boxes with shape (num_bboxes, 4+).
+                The first 4 columns are [x_min, y_min, x_max, y_max].
+        target_format (Literal["coco", "pascal_voc", "yolo"]): Required format of the output bounding boxes.
+        shape (ShapeType): Image shape (height, width).
+        check_validity (bool): Check if all boxes are valid boxes.
+
+    Returns:
+        np.ndarray: An array of bounding boxes in the target format with shape (num_bboxes, 4+).
+
+    Raises:
+        ValueError: If `target_format` is not 'coco', 'pascal_voc' or 'yolo'.
+
+    """
+    if target_format not in {"coco", "pascal_voc", "yolo"}:
+        raise ValueError(
+            f"Unknown target_format {target_format}. Supported formats are: 'coco', 'pascal_voc' and 'yolo'",
+        )
+
+    if check_validity:
+        check_bboxes(bboxes)
+
+    converted_bboxes = np.zeros_like(bboxes)
+    converted_bboxes[:, 4:] = bboxes[:, 4:]  # Preserve additional columns
+
+    denormalized_bboxes = denormalize_bboxes(bboxes[:, :4], shape) if target_format != "yolo" else bboxes[:, :4]
+
+    if target_format == "coco":
+        converted_bboxes[:, 0] = denormalized_bboxes[:, 0]  # x_min
+        converted_bboxes[:, 1] = denormalized_bboxes[:, 1]  # y_min
+        converted_bboxes[:, 2] = denormalized_bboxes[:, 2] - denormalized_bboxes[:, 0]  # width
+        converted_bboxes[:, 3] = denormalized_bboxes[:, 3] - denormalized_bboxes[:, 1]  # height
+    elif target_format == "yolo":
+        converted_bboxes[:, 0] = (denormalized_bboxes[:, 0] + denormalized_bboxes[:, 2]) / 2  # x_center
+        converted_bboxes[:, 1] = (denormalized_bboxes[:, 1] + denormalized_bboxes[:, 3]) / 2  # y_center
+        converted_bboxes[:, 2] = denormalized_bboxes[:, 2] - denormalized_bboxes[:, 0]  # width
+        converted_bboxes[:, 3] = denormalized_bboxes[:, 3] - denormalized_bboxes[:, 1]  # height
+    else:  # pascal_voc
+        converted_bboxes[:, :4] = denormalized_bboxes
+
+    return converted_bboxes
+
+
+@handle_empty_array("bboxes")
+def check_bboxes(bboxes: np.ndarray) -> None:
+    """Check if bounding boxes are valid.
+
+    Args:
+        bboxes (np.ndarray): A numpy array of bounding boxes with shape (num_bboxes, 4+).
+
+    Raises:
+        ValueError: If any bounding box is invalid.
+
+    """
+    # Check if all values are in range [0, 1]
+    in_range = (bboxes[:, :4] >= 0) & (bboxes[:, :4] <= 1)
+    close_to_zero = np.isclose(bboxes[:, :4], 0)
+    close_to_one = np.isclose(bboxes[:, :4], 1)
+    valid_range = in_range | close_to_zero | close_to_one
+
+    if not np.all(valid_range):
+        invalid_idx = np.where(~np.all(valid_range, axis=1))[0][0]
+        invalid_bbox = bboxes[invalid_idx]
+        invalid_coord = ["x_min", "y_min", "x_max", "y_max"][np.where(~valid_range[invalid_idx])[0][0]]
+        invalid_value = invalid_bbox[np.where(~valid_range[invalid_idx])[0][0]]
+        raise ValueError(
+            f"Expected {invalid_coord} for bbox {invalid_bbox} to be in the range [0.0, 1.0], got {invalid_value}.",
+        )
+
+    # Check if x_max > x_min and y_max > y_min
+    valid_order = (bboxes[:, 2] > bboxes[:, 0]) & (bboxes[:, 3] > bboxes[:, 1])
+
+    if not np.all(valid_order):
+        invalid_idx = np.where(~valid_order)[0][0]
+        invalid_bbox = bboxes[invalid_idx]
+        if invalid_bbox[2] <= invalid_bbox[0]:
+            raise ValueError(f"x_max is less than or equal to x_min for bbox {invalid_bbox}.")
+
+        raise ValueError(f"y_max is less than or equal to y_min for bbox {invalid_bbox}.")
+
+
+@handle_empty_array("bboxes")
+def clip_bboxes(bboxes: np.ndarray, shape: ShapeType) -> np.ndarray:
+    """Clip bounding boxes to the image shape.
+
+    Args:
+        bboxes (np.ndarray): A numpy array of bounding boxes with shape (num_bboxes, 4+).
+        shape (ShapeType): The shape of the image/volume:
+                           - For 2D: {'height': int, 'width': int}
+                           - For 3D: {'height': int, 'width': int, 'depth': int}
+
+    Returns:
+        np.ndarray: A numpy array of bounding boxes with shape (num_bboxes, 4+).
+
+    """
+    height, width = shape["height"], shape["width"]
+
+    # Denormalize bboxes
+    denorm_bboxes = denormalize_bboxes(bboxes, shape)
+
+    ## Note:
+    # It could be tempting to use cols - 1 and rows - 1 as the upper bounds for the clipping
+
+    # But this would cause the bounding box to be clipped to the image dimensions - 1 which is not what we want.
+    # Bounding box lives not in the middle of pixels but between them.
+
+    # Examples: for image with height 100, width 100, the pixel values are in the range [0, 99]
+    # but if we want bounding box to be 1 pixel width and height and lie on the boundary of the image
+    # it will be described as [99, 99, 100, 100] => clip by image_size - 1 will lead to [99, 99, 99, 99]
+    # which is incorrect
+
+    # It could be also tempting to clip `x_min`` to `cols - 1`` and `y_min` to `rows - 1`, but this also leads
+    # to another error. If image fully lies outside of the visible area and min_area is set to 0, then
+    # the bounding box will be clipped to the image size - 1 and will be 1 pixel in size and fully visible,
+    # but it should be completely removed.
+
+    # Clip coordinates
+    denorm_bboxes[:, [0, 2]] = np.clip(denorm_bboxes[:, [0, 2]], 0, width, out=denorm_bboxes[:, [0, 2]])
+    denorm_bboxes[:, [1, 3]] = np.clip(denorm_bboxes[:, [1, 3]], 0, height, out=denorm_bboxes[:, [1, 3]])
+
+    # Normalize clipped bboxes
+    return normalize_bboxes(denorm_bboxes, shape)
+
+
+def filter_bboxes(
+    bboxes: np.ndarray,
+    shape: ShapeType,
+    min_area: float = 0.0,
+    min_visibility: float = 0.0,
+    min_width: float = 1.0,
+    min_height: float = 1.0,
+    max_accept_ratio: float | None = None,
+) -> np.ndarray:
+    """Remove bounding boxes that either lie outside of the visible area by more than min_visibility
+    or whose area in pixels is under the threshold set by `min_area`. Also crops boxes to final image size.
+
+    Args:
+        bboxes (np.ndarray): A numpy array of bounding boxes with shape (num_bboxes, 4+).
+        shape (ShapeType): The shape of the image/volume:
+                           - For 2D: {'height': int, 'width': int}
+                           - For 3D: {'height': int, 'width': int, 'depth': int}
+        min_area (float): Minimum area of a bounding box in pixels. Default: 0.0.
+        min_visibility (float): Minimum fraction of area for a bounding box to remain. Default: 0.0.
+        min_width (float): Minimum width of a bounding box in pixels. Default: 0.0.
+        min_height (float): Minimum height of a bounding box in pixels. Default: 0.0.
+        max_accept_ratio (float | None): Maximum allowed aspect ratio, calculated as max(width/height, height/width).
+            Boxes with higher ratios will be filtered out. Default: None.
+
+    Returns:
+        np.ndarray: Filtered bounding boxes.
+
+    """
+    epsilon = 1e-7
+
+    if len(bboxes) == 0:
+        return np.array([], dtype=np.float32).reshape(0, 4)
+
+    # Calculate areas of bounding boxes before clipping in pixels
+    denormalized_box_areas = calculate_bbox_areas_in_pixels(bboxes, shape)
+
+    # Clip bounding boxes in ratio
+    clipped_bboxes = clip_bboxes(bboxes, shape)
+
+    # Calculate areas of clipped bounding boxes in pixels
+    clipped_box_areas = calculate_bbox_areas_in_pixels(clipped_bboxes, shape)
+
+    # Calculate width and height of the clipped bounding boxes
+    denormalized_bboxes = denormalize_bboxes(clipped_bboxes[:, :4], shape)
+
+    clipped_widths = denormalized_bboxes[:, 2] - denormalized_bboxes[:, 0]
+    clipped_heights = denormalized_bboxes[:, 3] - denormalized_bboxes[:, 1]
+
+    # Calculate aspect ratios if needed
+    if max_accept_ratio is not None:
+        aspect_ratios = np.maximum(
+            clipped_widths / (clipped_heights + epsilon),
+            clipped_heights / (clipped_widths + epsilon),
+        )
+        valid_ratios = aspect_ratios <= max_accept_ratio
+    else:
+        valid_ratios = np.ones_like(denormalized_box_areas, dtype=bool)
+
+    # Create a mask for bboxes that meet all criteria
+    mask = (
+        (denormalized_box_areas >= epsilon)
+        & (clipped_box_areas >= min_area - epsilon)
+        & (clipped_box_areas / (denormalized_box_areas + epsilon) >= min_visibility)
+        & (clipped_widths >= min_width - epsilon)
+        & (clipped_heights >= min_height - epsilon)
+        & valid_ratios
+    )
+
+    # Apply the mask to get the filtered bboxes
+    filtered_bboxes = clipped_bboxes[mask]
+
+    return np.array([], dtype=np.float32).reshape(0, 4) if len(filtered_bboxes) == 0 else filtered_bboxes
+
+
+def union_of_bboxes(bboxes: np.ndarray, erosion_rate: float) -> np.ndarray | None:
+    """Calculate union of bounding boxes. Boxes could be in albumentations or Pascal Voc format.
+
+    Args:
+        bboxes (np.ndarray): List of bounding boxes
+        erosion_rate (float): How much each bounding box can be shrunk, useful for erosive cropping.
+            Set this in range [0, 1]. 0 will not be erosive at all, 1.0 can make any bbox lose its volume.
+
+    Returns:
+        np.ndarray | None: A bounding box `(x_min, y_min, x_max, y_max)` or None if no bboxes are given or if
+                    the bounding boxes become invalid after erosion.
+
+    """
+    if not bboxes.size:
+        return None
+
+    if erosion_rate == 1:
+        return None
+
+    if bboxes.shape[0] == 1:
+        return bboxes[0][:4]
+
+    epsilon = 1e-6
+
+    x_min, y_min = np.min(bboxes[:, :2], axis=0)
+    x_max, y_max = np.max(bboxes[:, 2:4], axis=0)
+
+    width = x_max - x_min
+    height = y_max - y_min
+
+    erosion_x = width * erosion_rate * 0.5
+    erosion_y = height * erosion_rate * 0.5
+
+    x_min += erosion_x
+    y_min += erosion_y
+    x_max -= erosion_x
+    y_max -= erosion_y
+
+    if abs(x_max - x_min) < epsilon or abs(y_max - y_min) < epsilon:
+        return None
+
+    return np.array([x_min, y_min, x_max, y_max], dtype=np.float32)
+
+
+def bboxes_from_masks(masks: np.ndarray) -> np.ndarray:
+    """Create bounding boxes from binary masks (fast version)
+
+    Args:
+        masks (np.ndarray): Binary masks of shape (H, W) or (N, H, W) where N is the number of masks,
+                           and H, W are the height and width of each mask.
+
+    Returns:
+        np.ndarray: An array of bounding boxes with shape (N, 4), where each row is
+                   (x_min, y_min, x_max, y_max).
+
+    """
+    # Handle single mask case by adding batch dimension
+    if len(masks.shape) == MONO_CHANNEL_DIMENSIONS:
+        masks = masks[np.newaxis, ...]
+
+    rows = np.any(masks, axis=2)
+    cols = np.any(masks, axis=1)
+
+    bboxes = np.zeros((masks.shape[0], 4), dtype=np.int32)
+
+    for i, (row, col) in enumerate(zip(rows, cols)):
+        if not np.any(row) or not np.any(col):
+            bboxes[i] = [-1, -1, -1, -1]
+        else:
+            y_min, y_max = np.where(row)[0][[0, -1]]
+            x_min, x_max = np.where(col)[0][[0, -1]]
+            bboxes[i] = [x_min, y_min, x_max + 1, y_max + 1]
+
+    return bboxes
+
+
+def masks_from_bboxes(bboxes: np.ndarray, shape: ShapeType | tuple[int, int]) -> np.ndarray:
+    """Convert bounding boxes to masks.
+
+    Args:
+        bboxes (np.ndarray): A numpy array of bounding boxes with shape (num_bboxes, 4+).
+        shape (ShapeType | tuple[int, int]): Image shape (height, width).
+
+    Returns:
+        np.ndarray: A numpy array of masks with shape (num_bboxes, height, width).
+
+    """
+    if isinstance(shape, dict):
+        height, width = shape["height"], shape["width"]
+    else:
+        height, width = shape[:2]
+
+    masks = np.zeros((len(bboxes), height, width), dtype=np.uint8)
+    y, x = np.ogrid[:height, :width]
+
+    for i, (x_min, y_min, x_max, y_max) in enumerate(bboxes[:, :4].astype(int)):
+        masks[i] = (x_min <= x) & (x < x_max) & (y_min <= y) & (y < y_max)
+
+    return masks
+
+
+def bboxes_to_mask(
+    bboxes: np.ndarray,
+    image_shape: tuple[int, int],
+) -> np.ndarray:
+    """Convert bounding boxes to a single mask.
+
+    Args:
+        bboxes (np.ndarray): A numpy array of bounding boxes with shape (num_bboxes, 4+).
+        image_shape (tuple[int, int]): Image shape (height, width).
+
+    Returns:
+        np.ndarray: A numpy array of shape (height, width) with 1s where any bounding box is present.
+
+    """
+    height, width = image_shape[:2]
+    num_boxes = len(bboxes)
+
+    # Create multi-channel mask where each channel represents one bbox
+    bbox_masks = np.zeros((height, width, num_boxes), dtype=np.uint8)
+
+    # Fill each bbox in its channel
+    for idx, box in enumerate(bboxes):
+        x_min, y_min, x_max, y_max = map(round, box[:4])
+        x_min = max(0, min(width - 1, x_min))
+        x_max = max(0, min(width - 1, x_max))
+        y_min = max(0, min(height - 1, y_min))
+        y_max = max(0, min(height - 1, y_max))
+        bbox_masks[y_min : y_max + 1, x_min : x_max + 1, idx] = 1
+
+    return bbox_masks
+
+
+def mask_to_bboxes(
+    masks: np.ndarray,
+    original_bboxes: np.ndarray,
+) -> np.ndarray:
+    """Convert masks back to bounding boxes.
+
+    Args:
+        masks (np.ndarray): A numpy array of masks with shape (num_masks, height, width).
+        original_bboxes (np.ndarray): Original bounding boxes with shape (num_bboxes, 4+).
+
+    Returns:
+        np.ndarray: A numpy array of bounding boxes with shape (num_masks, 4+).
+
+    """
+    num_boxes = masks.shape[-1]
+    new_bboxes = []
+
+    num_boxes = masks.shape[-1]
+
+    if num_boxes == 0:
+        # Return empty array with correct shape
+        return np.zeros((0, original_bboxes.shape[1]), dtype=original_bboxes.dtype)
+
+    for idx in range(num_boxes):
+        mask = masks[..., idx]
+        if np.any(mask):
+            y_coords, x_coords = np.where(mask)
+            x_min, x_max = x_coords.min(), x_coords.max()
+            y_min, y_max = y_coords.min(), y_coords.max()
+            new_bboxes.append([x_min, y_min, x_max, y_max])
+        else:
+            # If bbox disappeared, use original coords
+            new_bboxes.append(original_bboxes[idx, :4])
+
+    new_bboxes = np.array(new_bboxes)
+
+    return (
+        np.column_stack([new_bboxes, original_bboxes[:, 4:]])
+        if original_bboxes.shape[1] > NUM_BBOXES_COLUMNS_IN_ALBUMENTATIONS
+        else new_bboxes
+    )