albumentations.augmentations.dropout.functional

Replace selected channels with fill; others unchanged. channels_to_drop: index/indices; fill: scalar or per-channel. Multi-channel only. This function drops channels from an image. Args: img (ImageType): 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: ImageType: Image with channels dropped.

Parameters

Generate random fill array for dropout holes. dtype and shape; int or float range. Used by fill_holes_with_random and similar. 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

Apply OpenCV inpainting to fill holes. holes: [x1,y1,x2,y2]; method inpaint_telea or inpaint_ns. uint8; grayscale or 3-channel. Args: img (ImageType): 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: ImageType: Inpainted image Raises: NotImplementedError: If image has more than 3 channels

Parameters

Fill rectangular holes with constant value. holes: [x1,y1,x2,y2]; fill broadcast. Mutates img. Used by cutout for numeric fill. Args: img (ImageType): Input image holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (np.ndarray): Value to fill the holes with

Parameters

Fill rectangular holes in a volume (D,H,W,C) with constant value. holes: [x1,y1,x2,y2]; fill broadcast. Used by cutout_on_volume for numeric fill. Args: volume (ImageType): Input volume holes (np.ndarray): Array of [x1, y1, x2, y2] coordinates fill (np.ndarray): Value to fill the holes with

Parameters

Fill rectangular holes in batch of volumes (N,D,H,W,C) with constant value. holes: [x1,y1,x2,y2]; fill broadcast. Used by cutout_on_volumes for numeric fill. 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

Fill rectangular holes with random values. holes: [x1,y1,x2,y2]; uniform: one per hole or per pixel. Used by cutout fill='random'. Args: img (ImageType): 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

Fill rectangular holes in volume (D,H,W,C) with random values. holes: [x1,y1,x2,y2]; uniform: one per hole or per pixel. Used by cutout_on_volume fill='random'. Args: volume (ImageType): 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

Fill rectangular holes in batch of volumes (N,D,H,W,C) with random values. holes: [x1,y1,x2,y2]; uniform: one per hole or per pixel. Used by cutout_on_volumes. 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

Apply cutout: cut rectangular holes and fill. holes: [x1,y1,x2,y2]; fill: constant, 'random', 'random_uniform', or inpaint_telea/inpaint_ns. Args: img (ImageType): 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

Apply cutout to volume (D,H,W,C): cut holes and fill. fill: constant, 'random', 'random_uniform', or inpaint. holes: [x1,y1,x2,y2]. Args: volume (ImageType): 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

Apply cutout to batch of volumes (N,D,H,W,C): cut holes and fill. fill: constant, 'random', 'random_uniform', or inpaint. holes: [x1,y1,x2,y2]. 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

Filter keypoints inside any rectangular hole. keypoints (N,2+); holes (K,4) [x1,y1,x2,y2]. Returns keypoints not inside any hole. 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

Resize boxes to largest visible rectangular region inside hole_mask. boxes (N,4); hole_mask: binary. Returns resized boxes for dropout bbox handling.

Parameters

Filter bboxes overlapping holes by area and visibility. min_area, min_visibility; resizes to visible region. Returns filtered bboxes. 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

Calculate grid unit dimensions (height, width) for GridDropout. unit_size_range or holes_number_xy; random_generator. Returns (unit_h, unit_w). 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

Generate rectangular holes for GridDropout from uniform grid. grid (rows,cols), ratio, random_offset, shift_xy. Returns (n_holes, 4) [x1,y1,x2,y2]. 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

Filter bboxes by visible area under dropout_mask. min_area, min_visibility; removes boxes fully inside dropped region. For MaskDropout. 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

Filter keypoints on dropped pixels. dropout_mask (H,W); keypoints (N,2+). Returns keypoints on non-dropped pixels. For MaskDropout. 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

Label connected regions of an integer array. OpenCV connectedComponents; connectivity 1 or 2. return_num: also return label count. For mask-based hole sampling. 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

Generate rectangular holes inside bounding boxes. num_holes_per_box, height/width ranges (relative). Returns (n, 4) [x1,y1,x2,y2]. For CoarseDropout.

Parameters

Sample random points from connected components in a labeled mask. num_points per component. Returns (centers, obj_sizes) for mask-based dropout hole sampling. 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

Generate rectangular holes from a segmentation mask. mask_indices select objects; num_holes_per_obj, hole height/width ranges (relative). Returns (n, 4). Args: mask (np.ndarray): Segmentation mask. num_holes_per_obj (int): Holes to sample per object. mask_indices (list[int]): Object indices to use. hole_height_range (tuple[float, float]): Relative height range. hole_width_range (tuple[float, float]): Relative width range. random_generator (np.random.Generator): RNG. Returns: np.ndarray: Holes (n, 4) [x1,y1,x2,y2].

Parameters

Decompose binary mask zero-regions into axis-aligned rectangles. Returns list of [x1,y1,x2,y2]. For hole extraction in mask-based dropout. 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 (np.ndarray): 2D uint8 mask where 0 indicates a dropped region. Returns: np.ndarray: Array of shape (N, 4) with [x1, y1, x2, y2] rectangles, or empty (0, 4) array.

Parameters

Generate grid-line shaped holes for GridMask. num_grid, line_width_ratio, rotation. Returns (n_holes, 4) [x1,y1,x2,y2]. Horizontal and vertical grid lines. Args: image_shape (tuple[int, int]): (height, width) of the image. num_grid (int): Number of grid divisions along the shorter side. line_width_ratio (float): Width of masked lines as fraction of grid cell size. rotation (float): Rotation angle in radians. random_generator (np.random.Generator): NumPy random generator. Returns: np.ndarray: Array of holes as (N, 4) with [x1, y1, x2, y2] format.

Parameters