image-match/python/py/Lib/site-packages/albumentations/augmentations/dropout/mask_dropout.py

"""Implementation of mask-based dropout augmentation.

This module provides the MaskDropout transform, which identifies objects in a segmentation mask
and drops out random objects completely. This augmentation is particularly useful for instance
segmentation and object detection tasks, as it simulates occlusions or missing objects in a
semantically meaningful way, rather than dropping out random pixels or regions.
"""

from __future__ import annotations

from typing import Any, Literal, cast

import cv2
import numpy as np

import albumentations.augmentations.dropout.functional as fdropout
from albumentations.core.bbox_utils import BboxProcessor, denormalize_bboxes, normalize_bboxes
from albumentations.core.keypoints_utils import KeypointsProcessor
from albumentations.core.pydantic import OnePlusIntRangeType
from albumentations.core.transforms_interface import BaseTransformInitSchema, DualTransform
from albumentations.core.type_definitions import ALL_TARGETS

__all__ = ["MaskDropout"]


class MaskDropout(DualTransform):
    """Apply dropout to random objects in a mask, zeroing out the corresponding regions in both the image and mask.

    This transform identifies objects in the mask (where each unique non-zero value represents a distinct object),
    randomly selects a number of these objects, and sets their corresponding regions to zero in both the image and mask.
    It can also handle bounding boxes and keypoints, removing or adjusting them based on the dropout regions.

    Args:
        max_objects (int | tuple[int, int]): Maximum number of objects to dropout. If a single int is provided,
            it's treated as the upper bound. If a tuple of two ints is provided, it's treated as a range [min, max].
        fill (float | Literal["inpaint_telea", "inpaint_ns"]): Value to fill dropped out regions in the image.
            Can be one of:
            - float: Constant value to fill the regions (e.g., 0 for black, 255 for white)
            - "inpaint_telea": Use Telea inpainting algorithm (for 3-channel images only)
            - "inpaint_ns": Use Navier-Stokes inpainting algorithm (for 3-channel images only)
        fill_mask (float): Value to fill the dropped out regions in the mask.
        min_area (float): Minimum area (in pixels) of a bounding box that must remain visible after dropout to be kept.
            Only applicable if bounding box augmentation is enabled. Default: 0.0
        min_visibility (float): Minimum visibility ratio (visible area / total area) of a bounding box after dropout
            to be kept. Only applicable if bounding box augmentation is enabled. Default: 0.0
        p (float): Probability of applying the transform. Default: 0.5.

    Targets:
        image, mask, bboxes, keypoints, volume, mask3d

    Image types:
        uint8, float32

    Note:
        - The mask should be a single-channel image where 0 represents the background and non-zero values represent
          different object instances.
        - For bounding box and keypoint augmentation, make sure to set up the corresponding processors in the pipeline.

    Examples:
        >>> import numpy as np
        >>> import albumentations as A
        >>>
        >>> # Prepare sample data
        >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
        >>> mask = np.zeros((100, 100), dtype=np.uint8)
        >>> mask[20:40, 20:40] = 1  # Object 1
        >>> mask[60:80, 60:80] = 2  # Object 2
        >>> bboxes = np.array([[20, 20, 40, 40], [60, 60, 80, 80]], dtype=np.float32)
        >>> bbox_labels = [1, 2]
        >>> keypoints = np.array([[30, 30], [70, 70]], dtype=np.float32)
        >>> keypoint_labels = [0, 1]
        >>>
        >>> # Define the transform with tuple for max_objects
        >>> transform = A.Compose(
        ...     transforms=[
        ...         A.MaskDropout(
        ...             max_objects=(1, 2),  # Using tuple to specify min and max objects to drop
        ...             fill=0,  # Fill value for dropped regions in image
        ...             fill_mask=0,  # Fill value for dropped regions in mask
        ...             p=1.0
        ...         ),
        ...     ],
        ...     bbox_params=A.BboxParams(
        ...         format='pascal_voc',
        ...         label_fields=['bbox_labels'],
        ...         min_area=1,
        ...         min_visibility=0.1
        ...     ),
        ...     keypoint_params=A.KeypointParams(
        ...         format='xy',
        ...         label_fields=['keypoint_labels'],
        ...         remove_invisible=True
        ...     )
        ... )
        >>>
        >>> # Apply the transform
        >>> transformed = transform(
        ...     image=image,
        ...     mask=mask,
        ...     bboxes=bboxes,
        ...     bbox_labels=bbox_labels,
        ...     keypoints=keypoints,
        ...     keypoint_labels=keypoint_labels
        ... )
        >>>
        >>> # Get the transformed data
        >>> transformed_image = transformed['image']  # Image with dropped out regions
        >>> transformed_mask = transformed['mask']    # Mask with dropped out regions
        >>> transformed_bboxes = transformed['bboxes']  # Remaining bboxes after dropout
        >>> transformed_bbox_labels = transformed['bbox_labels']  # Labels for remaining bboxes
        >>> transformed_keypoints = transformed['keypoints']  # Remaining keypoints after dropout
        >>> transformed_keypoint_labels = transformed['keypoint_labels']  # Labels for remaining keypoints

    """

    _targets = ALL_TARGETS

    class InitSchema(BaseTransformInitSchema):
        max_objects: OnePlusIntRangeType

        fill: float | Literal["inpaint_telea", "inpaint_ns"]
        fill_mask: float

    def __init__(
        self,
        max_objects: tuple[int, int] | int = (1, 1),
        fill: float | Literal["inpaint_telea", "inpaint_ns"] = 0,
        fill_mask: float = 0,
        p: float = 0.5,
    ):
        super().__init__(p=p)
        self.max_objects = cast("tuple[int, int]", max_objects)
        self.fill = fill  # type: ignore[assignment]
        self.fill_mask = fill_mask

    @property
    def targets_as_params(self) -> list[str]:
        """Get targets as parameters.

        Returns:
            list[str]: List of targets as parameters.

        """
        return ["mask"]

    def get_params_dependent_on_data(self, params: dict[str, Any], data: dict[str, Any]) -> dict[str, Any]:
        """Get parameters dependent on the data.

        Args:
            params (dict[str, Any]): Dictionary containing parameters.
            data (dict[str, Any]): Dictionary containing data.

        Returns:
            dict[str, Any]: Dictionary with parameters for transformation.

        """
        mask = data["mask"]

        label_image, num_labels = fdropout.label(mask, return_num=True)

        if num_labels == 0:
            dropout_mask = None
        else:
            objects_to_drop = self.py_random.randint(*self.max_objects)
            objects_to_drop = min(num_labels, objects_to_drop)

            if objects_to_drop == num_labels:
                dropout_mask = mask > 0
            else:
                labels_index = self.py_random.sample(range(1, num_labels + 1), objects_to_drop)
                dropout_mask = np.zeros(mask.shape[:2], dtype=bool)
                for label_index in labels_index:
                    dropout_mask |= label_image == label_index

        return {"dropout_mask": dropout_mask}

    def apply(self, img: np.ndarray, dropout_mask: np.ndarray | None, **params: Any) -> np.ndarray:
        """Apply dropout to the image.

        Args:
            img (np.ndarray): The image to apply the transform to.
            dropout_mask (np.ndarray | None): The dropout mask for the image.
            **params (Any): Additional parameters for the transform.

        Returns:
            np.ndarray: The transformed image.

        """
        if dropout_mask is None:
            return img

        if self.fill in {"inpaint_telea", "inpaint_ns"}:
            dropout_mask = dropout_mask.astype(np.uint8)
            _, _, width, height = cv2.boundingRect(dropout_mask)
            radius = min(3, max(width, height) // 2)
            return cv2.inpaint(img, dropout_mask, radius, cast("Literal['inpaint_telea', 'inpaint_ns']", self.fill))

        img = img.copy()
        img[dropout_mask] = self.fill

        return img

    def apply_to_mask(self, mask: np.ndarray, dropout_mask: np.ndarray | None, **params: Any) -> np.ndarray:
        """Apply dropout to the mask.

        Args:
            mask (np.ndarray): The mask to apply the transform to.
            dropout_mask (np.ndarray | None): The dropout mask for the mask.
            **params (Any): Additional parameters for the transform.

        Returns:
            np.ndarray: The transformed mask.

        """
        if dropout_mask is None or self.fill_mask is None:
            return mask

        mask = mask.copy()
        mask[dropout_mask] = self.fill_mask
        return mask

    def apply_to_bboxes(self, bboxes: np.ndarray, dropout_mask: np.ndarray | None, **params: Any) -> np.ndarray:
        """Apply dropout to bounding boxes.

        Args:
            bboxes (np.ndarray): The bounding boxes to apply the transform to.
            dropout_mask (np.ndarray | None): The dropout mask for the bounding boxes.
            **params (Any): Additional parameters for the transform.

        Returns:
            np.ndarray: The transformed bounding boxes.

        """
        if dropout_mask is None:
            return bboxes

        processor = cast("BboxProcessor", self.get_processor("bboxes"))
        if processor is None:
            return bboxes

        image_shape = params["shape"][:2]

        denormalized_bboxes = denormalize_bboxes(bboxes, image_shape)

        result = fdropout.mask_dropout_bboxes(
            denormalized_bboxes,
            dropout_mask,
            image_shape,
            processor.params.min_area,
            processor.params.min_visibility,
        )

        return normalize_bboxes(result, image_shape)

    def apply_to_keypoints(self, keypoints: np.ndarray, dropout_mask: np.ndarray | None, **params: Any) -> np.ndarray:
        """Apply dropout to keypoints.

        Args:
            keypoints (np.ndarray): The keypoints to apply the transform to.
            dropout_mask (np.ndarray | None): The dropout mask for the keypoints.
            **params (Any): Additional parameters for the transform.

        Returns:
            np.ndarray: The transformed keypoints.

        """
        if dropout_mask is None:
            return keypoints
        processor = cast("KeypointsProcessor", self.get_processor("keypoints"))

        if processor is None or not processor.params.remove_invisible:
            return keypoints

        return fdropout.mask_dropout_keypoints(keypoints, dropout_mask)