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
- functionapply_inpainting
- functioncalculate_grid_dimensions
- functionchannel_dropout
- functioncutout
- functionfill_holes_with_random
- functionfill_holes_with_value
- functionfilter_bboxes_by_holes
- functionfilter_keypoints_in_holes
- functiongenerate_grid_holes
- functiongenerate_random_fill
- functionget_holes_from_boxes
- functionget_holes_from_mask
- functionlabel
- functionmask_dropout_bboxes
- functionmask_dropout_keypoints
- functionresize_boxes_to_visible_area
- functionsample_points_from_components
apply_inpaintingfunction
apply_inpainting(
img: np.ndarray,
holes: np.ndarray,
method: Literal['inpaint_telea', 'inpaint_ns']
)Apply OpenCV inpainting to fill the holes in the image.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | np.ndarray | - | Input image (grayscale or BGR) |
| holes | np.ndarray | - | Array of [x1, y1, x2, y2] coordinates |
| method | One of:
| - | Inpainting method to use |
Returns
- np.ndarray: Inpainted image
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
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| image_shape | tuple[int, int] | - | The shape of the image as (height, width). |
| unit_size_range | One of:
| - | 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 | One of:
| - | 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).
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.
channel_dropoutfunction
channel_dropout(
img: np.ndarray,
channels_to_drop: int | tuple[int, ...] | np.ndarray,
fill_value: tuple[float, ...] | float = 0
)Drop channels from an image. This function drops channels from an image.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | np.ndarray | - | Input image. |
| channels_to_drop | One of:
| - | Channels to drop. |
| fill_value | One of:
| 0 | Value to fill the dropped channels with. |
Returns
- np.ndarray: Image with channels dropped.
cutoutfunction
cutout(
img: np.ndarray,
holes: np.ndarray,
fill_value: 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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | np.ndarray | - | The image to augment |
| holes | np.ndarray | - | Array of [x1, y1, x2, y2] coordinates |
| fill_value | One of:
| - | 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 |
fill_holes_with_randomfunction
fill_holes_with_random(
img: np.ndarray,
holes: np.ndarray,
random_generator: np.random.Generator,
uniform: bool
)Fill holes with random values.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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 |
fill_holes_with_valuefunction
fill_holes_with_value(
img: np.ndarray,
holes: np.ndarray,
fill_value: np.ndarray
)Fill holes with a constant value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| img | np.ndarray | - | Input image |
| holes | np.ndarray | - | Array of [x1, y1, x2, y2] coordinates |
| fill_value | np.ndarray | - | Value to fill the holes with |
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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.
filter_keypoints_in_holesfunction
filter_keypoints_in_holes(
keypoints: np.ndarray,
holes: np.ndarray
)Filter out keypoints that are inside any of the holes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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.
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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
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.
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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.
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 | - | - |
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 | - | - |
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| mask | np.ndarray | - | The array to label. Must be of integer type. |
| return_num | bool | False | If True, return the number of labels (default: False). |
| connectivity | int | 2 | 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
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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
mask_dropout_keypointsfunction
mask_dropout_keypoints(
keypoints: np.ndarray,
dropout_mask: np.ndarray
)Filter keypoints based on dropout mask.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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
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 | - | - |
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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