...

ConstrainedCoarseDropout

Targets:
image
mask
bboxes
keypoints
volume
mask3d
Image Types:uint8, float32

Applies coarse dropout to regions containing specific objects in the image.

This augmentation creates holes (dropout regions) for each target object in the image. Objects can be specified either by their class indices in a segmentation mask or by their labels in bounding box annotations.

The hole generation differs between mask and box modes:

Mask mode:

  1. For each connected component in the mask matching target indices:
    • Samples N points randomly from within the object region (with replacement)
    • Creates holes centered at these points
    • Hole sizes are proportional to sqrt(component area), not total object area
    • Each component's holes are sized based on its own area

Box mode:

  1. For each bounding box matching target labels:
    • Creates N holes with random positions inside the box
    • Hole sizes are proportional to the box dimensions

In both modes:

  • N is sampled once from num_holes_range and used for all objects
  • For example, if num_holes_range=(2,4) and 3 is sampled:
    • With 3 target objects, you'll get exactly 3 holes per object (9 total)
    • Holes may overlap within or between objects
    • All holes are clipped to image boundaries
Arguments
num_holes_range
tuple[int, int]
[1,1]

Range for number of holes per object (min, max)

hole_height_range
tuple[float, float]
[0.1,0.1]

Range for hole height as proportion of object height/size (min, max). E.g., (0.2, 0.4) means:

  • For boxes: 20-40% of box height
  • For masks: 20-40% of sqrt(component area)
hole_width_range
tuple[float, float]
[0.1,0.1]

Range for hole width, similar to height

fill
tuple[float, ...] | float | random | random_uniform | inpaint_telea | inpaint_ns
0

Value used to fill the erased regions. Can be:

  • int or float: fills all channels with this value
  • tuple: fills each channel with corresponding value
  • "random": fills each pixel with random values
  • "random_uniform": fills entire erased region with a single random color
  • "inpaint_telea": uses OpenCV Telea inpainting method
  • "inpaint_ns": uses OpenCV Navier-Stokes inpainting method Default: 0
fill_mask
tuple[float, ...] | float | None

Value used to fill erased regions in the mask. If None, mask regions are not modified. Default: None

p
float
0.5

Probability of applying the transform

mask_indices
list[int] | None

List of class indices in segmentation mask to target. Only objects of these classes will be considered for hole placement.

bbox_labels
list[str | int | float] | None

List of object labels in bbox annotations to target. String labels will be automatically encoded. When multiple label fields are specified in BboxParams, only the first label field is used for filtering.

Examples
>>> # Using segmentation mask
>>> transform = ConstrainedCoarseDropout(
...     num_holes_range=(2, 4),        # 2-4 holes per object
...     hole_height_range=(0.2, 0.4),  # 20-40% of sqrt(object area)
...     hole_width_range=(0.2, 0.4),   # 20-40% of sqrt(object area)
...     mask_indices=[1, 2],           # Target objects of class 1 and 2
...     fill=0,                        # Fill holes with black
... )
>>> # Apply to image and its segmentation mask
>>> transformed = transform(image=image, mask=mask)

>>> # Using bounding boxes with Compose
>>> transform = A.Compose([
...     ConstrainedCoarseDropout(
...         num_holes_range=(1, 3),
...         hole_height_range=(0.3, 0.5),  # 30-50% of box height
...         hole_width_range=(0.3, 0.5),   # 30-50% of box width
...         bbox_labels=['person'],        # Target people
...         fill=127,                      # Fill holes with gray
...     )
... ], bbox_params=A.BboxParams(
...     format='pascal_voc',  # [x_min, y_min, x_max, y_max]
...     label_fields=['labels']  # Specify field containing labels
... ))
>>> # Apply to image and its bounding boxes
>>> transformed = transform(
...     image=image,
...     bboxes=[[0, 0, 100, 100, 'car'], [150, 150, 300, 300, 'person']],
...     labels=['car', 'person']
... )
Notes

At least one of mask_indices or bbox_labels must be provided. If both are provided, mask_indices takes precedence.