ConstrainedCoarseDropout

Targets:

image

mask

bboxes

keypoints

Image Types:uint8, float32

Apply coarse dropout only in regions containing specified objects (mask or bbox labels). mask_indices or bbox_labels; num_holes_range, hole size ranges.

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:

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:

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

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.

>>> # 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'] ... )