albumentations.augmentations.dropout.functional
Functional implementations of dropout operations for image augmentation. This module provides low-level functions for various dropout techniques used in image augmentation, including channel dropout, grid dropout, mask dropout, and coarse dropout. These functions create and apply dropout patterns to images, masks, bounding boxes, and keypoints, with support for different filling methods and hole generation strategies.
Members
- functionchannel_dropout
- functiongenerate_random_fill
- functionapply_inpainting
- functionfill_holes_with_value
- functionfill_volume_holes_with_value
- functionfill_volumes_holes_with_value
- functionfill_holes_with_random
- functionfill_volume_holes_with_random
- functionfill_volumes_holes_with_random
- functioncutout
- functioncutout_on_volume
- functioncutout_on_volumes
- functionfilter_keypoints_in_holes
- functionresize_boxes_to_visible_area
- functionfilter_bboxes_by_holes
- functioncalculate_grid_dimensions
- functiongenerate_grid_holes
- functionmask_dropout_bboxes
- functionmask_dropout_keypoints
- functionlabel
- functionget_holes_from_boxes
- functionsample_points_from_components
- functionget_holes_from_mask
- functionmask_to_rects
- functiongenerate_grid_mask_holes
channel_dropoutfunction
channel_dropout(
img: ImageType,
channels_to_drop: int | tuple[int, ...] | np.ndarray,
fill: tuple[float, ...] | float = 0
)Drop channels from an image. This function drops channels from an image. Args: img (np.ndarray): Input image. channels_to_drop (int | tuple[int, ...] | np.ndarray): Channels to drop. fill (tuple[float, ...] | float): Value to fill the dropped channels with. Returns: np.ndarray: Image with channels dropped.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | ImageType | - | - |
| channels_to_drop | One of:
| - | - |
| fill | One of:
| 0 | - |
generate_random_fillfunction
generate_random_fill(
dtype: np.dtype,
shape: tuple[int, ...],
random_generator: np.random.Generator
)Generate a random fill array based on the given dtype and target shape. This function creates a numpy array filled with random values. The range and type of these values depend on the input dtype. For integer dtypes, it generates random integers. For floating-point dtypes, it generates random floats. Args: dtype (np.dtype): The data type of the array to be generated. shape (tuple[int, ...]): The shape of the array to be generated. random_generator (np.random.Generator): The random generator to use for generating values. If None, the default numpy random generator is used. Returns: np.ndarray: A numpy array of the specified shape and dtype, filled with random values. Raises: ValueError: If the input dtype is neither integer nor floating-point. Examples: >>> import numpy as np >>> random_state = np.random.RandomState(42) >>> result = generate_random_fill(np.dtype('uint8'), (2, 2), random_state) >>> print(result) [[172 251] [ 80 141]]
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| dtype | np.dtype | - | - |
| shape | tuple[int, ...] | - | - |
| random_generator | np.random.Generator | - | - |
apply_inpaintingfunction
apply_inpainting(
img: ImageType,
holes: np.ndarray,
method: Literal['inpaint_telea', 'inpaint_ns']
)Apply OpenCV inpainting to fill the holes in the image. Args: img (np.ndarray): Input image (grayscale or BGR) holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates method (Literal["inpaint_telea", "inpaint_ns"]): Inpainting method to use Returns: np.ndarray: Inpainted image Raises: NotImplementedError: If image has more than 3 channels
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | ImageType | - | - |
| holes | np.ndarray | - | - |
| method | One of:
| - | - |
fill_holes_with_valuefunction
fill_holes_with_value(
img: ImageType,
holes: np.ndarray,
fill: np.ndarray
)Fill holes with a constant value. Args: img (np.ndarray): Input image holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (np.ndarray): Value to fill the holes with
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | ImageType | - | - |
| holes | np.ndarray | - | - |
| fill | np.ndarray | - | - |
fill_volume_holes_with_valuefunction
fill_volume_holes_with_value(
volume: ImageType,
holes: np.ndarray,
fill: np.ndarray
)Fill holes in a volume with a constant value. Args: volume (np.ndarray): Input volume holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (np.ndarray): Value to fill the holes with
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | ImageType | - | - |
| holes | np.ndarray | - | - |
| fill | np.ndarray | - | - |
fill_volumes_holes_with_valuefunction
fill_volumes_holes_with_value(
volumes: np.ndarray,
holes: np.ndarray,
fill: np.ndarray
)Fill holes in a batch of volumes with a constant value. Args: volumes (np.ndarray): Input batch of volumes holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (np.ndarray): Value to fill the holes with
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volumes | np.ndarray | - | - |
| holes | np.ndarray | - | - |
| fill | np.ndarray | - | - |
fill_holes_with_randomfunction
fill_holes_with_random(
img: ImageType,
holes: np.ndarray,
random_generator: np.random.Generator,
uniform: bool
)Fill holes with random values. Args: img (np.ndarray): Input image holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates random_generator (np.random.Generator): Random number generator uniform (bool): If True, use same random value for entire hole
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | ImageType | - | - |
| holes | np.ndarray | - | - |
| random_generator | np.random.Generator | - | - |
| uniform | bool | - | - |
fill_volume_holes_with_randomfunction
fill_volume_holes_with_random(
volume: ImageType,
holes: np.ndarray,
random_generator: np.random.Generator,
uniform: bool
)Fill holes in a volume with random values. Args: volume (np.ndarray): Input volume of shape (D, H, W, C) or (D, H, W) holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates random_generator (np.random.Generator): Random number generator uniform (bool): If True, use same random value for entire hole in each image.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | ImageType | - | - |
| holes | np.ndarray | - | - |
| random_generator | np.random.Generator | - | - |
| uniform | bool | - | - |
fill_volumes_holes_with_randomfunction
fill_volumes_holes_with_random(
volumes: np.ndarray,
holes: np.ndarray,
random_generator: np.random.Generator,
uniform: bool
)Fill holes in a batch of volumes with random values. Args: volumes (np.ndarray): Input volume of shape (N, D, H, W, C) or (N, D, H, W) holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates random_generator (np.random.Generator): Random number generator uniform (bool): If True, use same random value for entire hole for each image
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volumes | np.ndarray | - | - |
| holes | np.ndarray | - | - |
| random_generator | np.random.Generator | - | - |
| uniform | bool | - | - |
cutoutfunction
cutout(
img: ImageType,
holes: np.ndarray,
fill: tuple[float, ...] | float | Literal['random', 'random_uniform', 'inpaint_telea', 'inpaint_ns'],
random_generator: np.random.Generator
)Apply cutout augmentation to the image by cutting out holes and filling them. Args: img (np.ndarray): The image to augment holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (tuple[float, ...] | float | Literal["random", "random_uniform", "inpaint_telea", "inpaint_ns"]): Value to fill holes with. Can be: - number (int/float): Will be broadcast to all channels - sequence (tuple/list/ndarray): Must match number of channels - "random": Different random values for each pixel - "random_uniform": Same random value for entire hole - "inpaint_telea"/"inpaint_ns": OpenCV inpainting methods random_generator (np.random.Generator): Random number generator for random fills Raises: ValueError: If fill length doesn't match number of channels
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | ImageType | - | - |
| holes | np.ndarray | - | - |
| fill | One of:
| - | - |
| random_generator | np.random.Generator | - | - |
cutout_on_volumefunction
cutout_on_volume(
volume: ImageType,
holes: np.ndarray,
fill: tuple[float, ...] | float | Literal['random', 'random_uniform', 'inpaint_telea', 'inpaint_ns'],
random_generator: np.random.Generator
)Apply cutout augmentation to a volume of shape (D, H, W) or (D, H, W, C) by cutting out holes and filling them. Args: volume (np.ndarray): The volume to augment holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (tuple[float, ...] | float | Literal["random", "random_uniform", "inpaint_telea", "inpaint_ns"]): Value to fill holes with. Can be: - number (int/float): Will be broadcast to all channels - sequence (tuple/list/ndarray): Must match number of channels - "random": Different random values for each pixel - "random_uniform": Same random value for entire hole, different values across images - "inpaint_telea"/"inpaint_ns": OpenCV inpainting methods random_generator (np.random.Generator): Random number generator for random fills Raises: ValueError: If fill length doesn't match number of channels
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volume | ImageType | - | - |
| holes | np.ndarray | - | - |
| fill | One of:
| - | - |
| random_generator | np.random.Generator | - | - |
cutout_on_volumesfunction
cutout_on_volumes(
volumes: np.ndarray,
holes: np.ndarray,
fill: tuple[float, ...] | float | Literal['random', 'random_uniform', 'inpaint_telea', 'inpaint_ns'],
random_generator: np.random.Generator
)Apply cutout augmentation to a batch of volumes of shape (N, D, H, W) or (N, D, H, W, C) Args: volumes (np.ndarray): The image to augment holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (tuple[float, ...] | float | Literal["random", "random_uniform", "inpaint_telea", "inpaint_ns"]): Value to fill holes with. Can be: - number (int/float): Will be broadcast to all channels - sequence (tuple/list/ndarray): Must match number of channels - "random": Different random values for each pixel - "random_uniform": Same random value for entire hole, different values across images - "inpaint_telea"/"inpaint_ns": OpenCV inpainting methods random_generator (np.random.Generator): Random number generator for random fills Raises: ValueError: If fill length doesn't match number of channels
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| volumes | np.ndarray | - | - |
| holes | np.ndarray | - | - |
| fill | One of:
| - | - |
| random_generator | np.random.Generator | - | - |
filter_keypoints_in_holesfunction
filter_keypoints_in_holes(
keypoints: np.ndarray,
holes: np.ndarray
)Filter out keypoints that are inside any of the holes. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 2+). The first two columns are x and y coordinates. holes (np.ndarray): Array of holes with shape (num_holes, 4). Each hole is represented as [x1, y1, x2, y2]. Returns: np.ndarray: Array of keypoints that are not inside any hole.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | - |
| holes | np.ndarray | - | - |
resize_boxes_to_visible_areafunction
resize_boxes_to_visible_area(
boxes: np.ndarray,
hole_mask: np.ndarray
)Resize boxes to their largest visible rectangular regions.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| boxes | np.ndarray | - | - |
| hole_mask | np.ndarray | - | - |
filter_bboxes_by_holesfunction
filter_bboxes_by_holes(
bboxes: np.ndarray,
holes: np.ndarray,
image_shape: tuple[int, int],
min_area: float,
min_visibility: float
)Filter bounding boxes by holes. This function filters bounding boxes by holes. Args: bboxes (np.ndarray): Array of bounding boxes. holes (np.ndarray): Array of holes. image_shape (tuple[int, int]): Shape of the image. min_area (float): Minimum area of a bounding box. min_visibility (float): Minimum visibility of a bounding box. Returns: np.ndarray: Filtered bounding boxes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| bboxes | np.ndarray | - | - |
| holes | np.ndarray | - | - |
| image_shape | tuple[int, int] | - | - |
| min_area | float | - | - |
| min_visibility | float | - | - |
calculate_grid_dimensionsfunction
calculate_grid_dimensions(
image_shape: tuple[int, int],
unit_size_range: tuple[int, int] | None,
holes_number_xy: tuple[int, int] | None,
random_generator: np.random.Generator
)Calculate the dimensions of grid units for GridDropout. This function determines the size of grid units based on the input parameters. It supports three modes of operation: 1. Using a range of unit sizes 2. Using a specified number of holes in x and y directions 3. Falling back to a default calculation Args: image_shape (tuple[int, int]): The shape of the image as (height, width). unit_size_range (tuple[int, int] | None, optional): A range of possible unit sizes. If provided, a random size within this range will be chosen for both height and width. holes_number_xy (tuple[int, int] | None, optional): The number of holes in the x and y directions. If provided, the grid dimensions will be calculated to fit this number of holes. random_generator (np.random.Generator): The random generator to use for generating random values. Returns: tuple[int, int]: The calculated grid unit dimensions as (unit_height, unit_width). Raises: ValueError: If the upper limit of unit_size_range is greater than the shortest image edge. Notes: - If both unit_size_range and holes_number_xy are None, the function falls back to a default calculation, where the grid unit size is set to max(2, image_dimension // 10) for both height and width. - The function prioritizes unit_size_range over holes_number_xy if both are provided. - When using holes_number_xy, the actual number of holes may be slightly different due to integer division. Examples: >>> image_shape = (100, 200) >>> calculate_grid_dimensions(image_shape, unit_size_range=(10, 20)) (15, 15) # Random value between 10 and 20 >>> calculate_grid_dimensions(image_shape, holes_number_xy=(5, 10)) (20, 20) # 100 // 5 and 200 // 10 >>> calculate_grid_dimensions(image_shape) (10, 20) # Default calculation: max(2, dimension // 10)
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| image_shape | tuple[int, int] | - | - |
| unit_size_range | One of:
| - | - |
| holes_number_xy | One of:
| - | - |
| random_generator | np.random.Generator | - | - |
generate_grid_holesfunction
generate_grid_holes(
image_shape: tuple[int, int],
grid: tuple[int, int],
ratio: float,
random_offset: bool,
shift_xy: tuple[int, int],
random_generator: np.random.Generator
)Generate a list of holes for GridDropout using a uniform grid. This function creates a grid of holes for use in the GridDropout augmentation technique. It allows for customization of the grid size, hole size ratio, and positioning of holes. Args: image_shape (tuple[int, int]): The shape of the image as (height, width). grid (tuple[int, int]): The grid size as (rows, columns). This determines the number of cells in the grid, where each cell may contain a hole. ratio (float): The ratio of the hole size to the grid cell size. Should be between 0 and 1. A ratio of 1 means the hole will fill the entire grid cell. random_offset (bool): If True, applies random offsets to each hole within its grid cell. If False, uses the global shift specified by shift_xy. shift_xy (tuple[int, int]): The global shift to apply to all holes as (shift_x, shift_y). Only used when random_offset is False. random_generator (np.random.Generator): The random generator for generating random offsets and shuffling. If None, a new Generator will be created. Returns: np.ndarray: An array of hole coordinates, where each hole is represented as [x1, y1, x2, y2]. The shape of the array is (n_holes, 4), where n_holes is determined by the grid size. Notes: - The function first creates a uniform grid based on the image shape and specified grid size. - Hole sizes are calculated based on the provided ratio and grid cell sizes. - If random_offset is True, each hole is randomly positioned within its grid cell. - If random_offset is False, all holes are shifted by the global shift_xy value. - The function ensures that all holes remain within the image boundaries. Examples: >>> image_shape = (100, 100) >>> grid = (5, 5) >>> ratio = 0.5 >>> random_offset = True >>> random_state = np.random.RandomState(42) >>> shift_xy = (0, 0) >>> holes = generate_grid_holes(image_shape, grid, ratio, random_offset, random_state, shift_xy) >>> print(holes.shape) (25, 4) >>> print(holes[0]) # Example output: [x1, y1, x2, y2] of the first hole [ 1 21 11 31]
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| image_shape | tuple[int, int] | - | - |
| grid | tuple[int, int] | - | - |
| ratio | float | - | - |
| random_offset | bool | - | - |
| shift_xy | tuple[int, int] | - | - |
| random_generator | np.random.Generator | - | - |
mask_dropout_bboxesfunction
mask_dropout_bboxes(
bboxes: np.ndarray,
dropout_mask: np.ndarray,
image_shape: tuple[int, int],
min_area: float,
min_visibility: float
)Filter and resize bounding boxes based on dropout mask. Args: bboxes (np.ndarray): Array of bounding boxes with shape (num_boxes, 4+) dropout_mask (np.ndarray): Binary mask indicating dropped areas image_shape (tuple[int, int]): Shape of the image (height, width) min_area (float): Minimum area of a bounding box to keep min_visibility (float): Minimum visibility ratio of a bounding box to keep Returns: np.ndarray: Filtered and resized bounding boxes
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| bboxes | np.ndarray | - | - |
| dropout_mask | np.ndarray | - | - |
| image_shape | tuple[int, int] | - | - |
| min_area | float | - | - |
| min_visibility | float | - | - |
mask_dropout_keypointsfunction
mask_dropout_keypoints(
keypoints: np.ndarray,
dropout_mask: np.ndarray
)Filter keypoints based on dropout mask. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 2+) dropout_mask (np.ndarray): Binary mask indicating dropped areas Returns: np.ndarray: Filtered keypoints
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | - |
| dropout_mask | np.ndarray | - | - |
labelfunction
label(
mask: np.ndarray,
return_num: bool = False,
connectivity: int = 2
)Label connected regions of an integer array. This function uses OpenCV's connectedComponents under the hood but mimics the behavior of scikit-image's label function. Args: mask (np.ndarray): The array to label. Must be of integer type. return_num (bool): If True, return the number of labels (default: False). connectivity (int): Maximum number of orthogonal hops to consider a pixel/voxel as a neighbor. Accepted values are 1 or 2. Default is 2. Returns: np.ndarray | tuple[np.ndarray, int]: Labeled array, where all connected regions are assigned the same integer value. If return_num is True, it also returns the number of labels.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| mask | np.ndarray | - | - |
| return_num | bool | False | - |
| connectivity | int | 2 | - |
get_holes_from_boxesfunction
get_holes_from_boxes(
target_boxes: np.ndarray,
num_holes_per_box: int,
hole_height_range: tuple[float, float],
hole_width_range: tuple[float, float],
random_generator: np.random.Generator
)Generate holes based on bounding boxes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| target_boxes | np.ndarray | - | - |
| num_holes_per_box | int | - | - |
| hole_height_range | tuple[float, float] | - | - |
| hole_width_range | tuple[float, float] | - | - |
| random_generator | np.random.Generator | - | - |
sample_points_from_componentsfunction
sample_points_from_components(
mask: np.ndarray,
num_points: int,
random_generator: np.random.Generator
)Sample points from connected components in a mask. Args: mask (np.ndarray): Binary mask num_points (int): Number of points to sample random_generator (np.random.Generator): Random number generator Returns: tuple[np.ndarray, np.ndarray] | None: Tuple of (x_coordinates, y_coordinates) or None if no valid components
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| mask | np.ndarray | - | - |
| num_points | int | - | - |
| random_generator | np.random.Generator | - | - |
get_holes_from_maskfunction
get_holes_from_mask(
mask: np.ndarray,
num_holes_per_obj: int,
mask_indices: list[int],
hole_height_range: tuple[float, float],
hole_width_range: tuple[float, float],
random_generator: np.random.Generator
)Generate holes based on segmentation mask.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| mask | np.ndarray | - | - |
| num_holes_per_obj | int | - | - |
| mask_indices | list[int] | - | - |
| hole_height_range | tuple[float, float] | - | - |
| hole_width_range | tuple[float, float] | - | - |
| random_generator | np.random.Generator | - | - |
mask_to_rectsfunction
mask_to_rects(
mask: np.ndarray
)Decompose a binary mask's zero-regions into axis-aligned rectangles. Finds all horizontal zero-runs across every row at once, sorts them by (x_start, x_end, row), then groups consecutive rows with identical spans into a single rectangle — all without a Python loop. Args: mask: 2D uint8 mask where 0 indicates a dropped region. Returns: Array of shape (N, 4) with [x1, y1, x2, y2] rectangles, or empty (0, 4) array.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| mask | np.ndarray | - | - |
generate_grid_mask_holesfunction
generate_grid_mask_holes(
image_shape: tuple[int, int],
num_grid: int,
line_width_ratio: float,
rotation: float,
random_generator: np.random.Generator
)Generate grid-line shaped holes for GridMask. Args: image_shape: (height, width) of the image. num_grid: Number of grid divisions along the shorter side. line_width_ratio: Width of masked lines as fraction of grid cell size. rotation: Rotation angle in radians. random_generator: NumPy random generator. Returns: Array of holes as (N, 4) with [x1, y1, x2, y2] format.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| image_shape | tuple[int, int] | - | - |
| num_grid | int | - | - |
| line_width_ratio | float | - | - |
| rotation | float | - | - |
| random_generator | np.random.Generator | - | - |
On this page
- channel_dropout
- generate_random_fill
- apply_inpainting
- fill_holes_with_value
- fill_volume_holes_with_value
- fill_volumes_holes_with_value
- fill_holes_with_random
- fill_volume_holes_with_random
- fill_volumes_holes_with_random
- cutout
- cutout_on_volume
- cutout_on_volumes
- filter_keypoints_in_holes
- resize_boxes_to_visible_area
- filter_bboxes_by_holes
- calculate_grid_dimensions
- generate_grid_holes
- mask_dropout_bboxes
- mask_dropout_keypoints
- label
- get_holes_from_boxes
- sample_points_from_components
- get_holes_from_mask
- mask_to_rects
- generate_grid_mask_holes