albumentations.augmentations.geometric.functional

Resize bounding boxes according to image scaling. Args: bboxes: Array of bboxes in normalized coords [x_min, y_min, x_max, y_max, (angle), ...] image_shape: Original image shape (height, width) output_shape: Target image shape (height, width) bbox_type: Type of bboxes - "hbb" or "obb" Returns: Resized bboxes in normalized coordinates

Parameters

Rotates bounding boxes by 90 degrees CCW (see np.rot90) Args: bboxes (np.ndarray): Array of bounding boxes with shape (num_boxes, 4+) group_element (Literal["e", "r90", "r180", "r270"]): C4 group element to apply. bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB uses center/size/angle update. Returns: np.ndarray: Rotated bounding boxes

Parameters

Applies a `D_4` symmetry group transformation to a bounding box. The function transforms a bounding box according to the specified group member from the `D_4` group. These transformations include rotations and reflections, specified to work on an image's bounding box given its dimensions. Args: bboxes (np.ndarray): A numpy array of bounding boxes with shape (num_bboxes, 4+). Each row represents a bounding box (x_min, y_min, x_max, y_max, ...). group_member (Literal["e", "r90", "r180", "r270", "v", "hvt", "h", "t"]): A string identifier for the `D_4` group transformation to apply. bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB uses center/size/angle update. Returns: BoxInternalType: The transformed bounding box. Raises: ValueError: If an invalid group member is specified.

Parameters

Rotate keypoints by 90 degrees counter-clockwise (CCW) a specified number of times. Args: keypoints (np.ndarray): An array of keypoints with shape (N, 4+) in the format (x, y, angle, scale, ...). group_element (Literal["e", "r90", "r180", "r270"]): C4 group element to apply. image_shape (tuple[int, int]): The shape of the image (height, width). Returns: np.ndarray: The rotated keypoints with the same shape as the input.

Parameters

Applies a `D_4` symmetry group transformation to a keypoint. This function adjusts a keypoint's coordinates according to the specified `D_4` group transformation, which includes rotations and reflections suitable for image processing tasks. These transformations account for the dimensions of the image to ensure the keypoint remains within its boundaries. Args: keypoints (np.ndarray): An array of keypoints with shape (N, 4+) in the format (x, y, angle, scale, ...). group_member (Literal["e", "r90", "r180", "r270", "v", "hvt", "h", "t"]): A string identifier for the `D_4` group transformation to apply. Valid values are 'e', 'r90', 'r180', 'r270', 'v', 'hv', 'h', 't'. image_shape (tuple[int, int]): The shape of the image. params (Any): Not used. Returns: KeypointInternalType: The transformed keypoint. Raises: ValueError: If an invalid group member is specified, indicating that the specified transformation does not exist.

Parameters

Resize an image to the specified target shape using the backend chosen via the ALBUMENTATIONS_RESIZE environment variable. If the image is already the target size, it is returned unchanged. Args: img (np.ndarray): Input image. target_shape (tuple[int, int]): Target (height, width) dimensions. interpolation (int): Interpolation method. Returns: np.ndarray: Resized image with shape target_shape + original channel dimensions. Raises: NotImplementedError: If the selected backend is not supported.

Parameters

Resize an image to the specified dimensions using pyvips. This function resizes an input image to the target shape using the specified interpolation method. Args: img (np.ndarray): The input image as a NumPy array. target_shape (tuple[int, int]): The desired output shape (height, width). interpolation (int): The interpolation method to use. 0: Nearest-neighbor 1: Bilinear 2: Bicubic Returns: np.ndarray: The resized image as a NumPy array with the original dtype.

Parameters

Resizes an image (NumPy array) using PIL's resize method. This function resizes an input image to the target shape using the specified interpolation method. Args: img (np.ndarray): The input image as a NumPy array. target_shape (tuple[int, int]): The desired output shape (height, width). interpolation (int): The cv2 interpolation flag that will be mapped to PIL interpolation. Maps cv2 constants to PIL.Image.Resampling constants. Returns: np.ndarray: The resized image as a NumPy array.

Parameters

Scale an image by a factor while preserving aspect ratio. This function scales both height and width dimensions of the image by the same factor. Args: img (np.ndarray): Input image to scale. scale (float): Scale factor. Values > 1 will enlarge the image, values < 1 will shrink it. interpolation (int): Interpolation method to use (cv2 interpolation flag). Returns: np.ndarray: Scaled image.

Parameters

Scale keypoints by given factors. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 2+) scale_x (float): Scale factor for x coordinates scale_y (float): Scale factor for y coordinates Returns: np.ndarray: Scaled keypoints

Parameters

Apply perspective transformation to an image. This function warps an image according to a perspective transformation matrix. It can either maintain the original dimensions or use the specified max dimensions. Args: img (np.ndarray): Input image to transform. matrix (np.ndarray): 3x3 perspective transformation matrix. max_width (int): Maximum width of the output image if keep_size is False. max_height (int): Maximum height of the output image if keep_size is False. border_val (float | list[float] | np.ndarray): Border value(s) to fill areas outside the transformed image. border_mode (int): OpenCV border mode (e.g., cv2.BORDER_CONSTANT, cv2.BORDER_REFLECT). keep_size (bool): If True, maintain the original image dimensions. interpolation (int): Interpolation method for resampling (cv2 interpolation flag). Returns: np.ndarray: Perspective-transformed image.

Parameters

Apply perspective transformation to a batch of images. Args: images: Batch of images of shape (N, H, W, C). matrix: 3x3 perspective transformation matrix. max_width: Maximum width of the output image if keep_size is False. max_height: Maximum height of the output image if keep_size is False. border_val: Border value(s) to fill areas outside the transformed image. border_mode: OpenCV border mode (e.g., cv2.BORDER_CONSTANT). keep_size: If True, maintain the original image dimensions. interpolation: Interpolation method for resampling (cv2 interpolation flag). Returns: Batch of perspective-transformed images with the same shape as input when keep_size is True, or (N, max_height, max_width, C) when False.

Parameters

Applies perspective transformation to bounding boxes. This function transforms bounding boxes using the given perspective transformation matrix. It handles bounding boxes with additional attributes beyond the standard coordinates. Args: bboxes (np.ndarray): An array of bounding boxes with shape (num_bboxes, 4+). Each row represents a bounding box (x_min, y_min, x_max, y_max, ...). Additional columns beyond the first 4 are preserved unchanged. image_shape (tuple[int, int]): The shape of the image (height, width). matrix (np.ndarray): The perspective transformation matrix. max_width (int): The maximum width of the output image. max_height (int): The maximum height of the output image. keep_size (bool): If True, maintains the original image size after transformation. bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB path uses polygons. Returns: np.ndarray: An array of transformed bounding boxes with the same shape as input. The first 4 columns contain the transformed coordinates, and any additional columns are preserved from the input. Note: - This function modifies only the coordinate columns (first 4) of the input bounding boxes. - Any additional attributes (columns beyond the first 4) are kept unchanged. - The function handles denormalization and renormalization of coordinates internally. Examples: >>> bboxes = np.array([[0.1, 0.1, 0.3, 0.3, 1], [0.5, 0.5, 0.8, 0.8, 2]]) >>> image_shape = (100, 100) >>> matrix = np.array([[1.5, 0.2, -20], [-0.1, 1.3, -10], [0.002, 0.001, 1]]) >>> transformed_bboxes = perspective_bboxes(bboxes, image_shape, matrix, 150, 150, False)

Parameters

Args: matrix (np.ndarray): Rotation matrix y_up (bool): is Y axis looks up or down

Parameters

Apply perspective transformation to keypoints. Args: keypoints (np.ndarray): Array of shape (N, 5+) in format [x, y, z, angle, scale, ...] image_shape (tuple[int, int]): Original image shape (height, width) matrix (np.ndarray): 3x3 perspective transformation matrix max_width (int): Maximum width after transformation max_height (int): Maximum height after transformation keep_size (bool): Whether to keep original size Returns: np.ndarray: Transformed keypoints array with same shape as input

Parameters

Check if the given matrix is an identity matrix. Args: matrix (np.ndarray): A 3x3 affine transformation matrix. Returns: bool: True if the matrix is an identity matrix, False otherwise.

Parameters

Apply an affine transformation to keypoints. This function transforms keypoints using the given affine transformation matrix. It handles reflection padding if necessary, updates coordinates, angles, and scales. Args: keypoints (np.ndarray): Array of keypoints with shape (N, 4+) where N is the number of keypoints. Each keypoint is represented as [x, y, angle, scale, ...]. matrix (np.ndarray): The 2x3 or 3x3 affine transformation matrix. image_shape (tuple[int, int]): Shape of the image (height, width). scale (dict[str, float]): Dictionary containing scale factors for x and y directions. Expected keys are 'x' and 'y'. border_mode (int): Border mode for handling keypoints near image edges. Use cv2.BORDER_REFLECT_101, cv2.BORDER_REFLECT, etc. Returns: np.ndarray: Transformed keypoints array with the same shape as input. Notes: - The function applies reflection padding if the mode is in REFLECT_BORDER_MODES. - Coordinates (x, y) are transformed using the affine matrix. - Angles are adjusted based on the rotation component of the affine transformation. - Scales are multiplied by the maximum of x and y scale factors. - The @angle_2pi_range decorator ensures angles remain in the [0, 2π] range. Examples: >>> keypoints = np.array([[100, 100, 0, 1]]) >>> matrix = np.array([[1.5, 0, 10], [0, 1.2, 20]]) >>> scale = {'x': 1.5, 'y': 1.2} >>> transformed_keypoints = keypoints_affine(keypoints, matrix, (480, 640), scale, cv2.BORDER_REFLECT_101)

Parameters

Apply affine transformation to a set of points. This function handles potential division by zero by replacing zero values in the homogeneous coordinate with a small epsilon value. Args: points (np.ndarray): Array of points with shape (N, 2). matrix (np.ndarray): 3x3 affine transformation matrix. Returns: np.ndarray: Transformed points with shape (N, 2).

Parameters

Calculate the necessary padding for an affine transformation to avoid empty spaces.

Parameters

Apply an affine transformation to bounding boxes and return the largest enclosing boxes. This function transforms each corner of every bounding box using the given affine transformation matrix, then computes the new bounding boxes that fully enclose the transformed corners. Args: bboxes (np.ndarray): An array of bounding boxes with shape (N, 4+) where N is the number of bounding boxes. Each row should contain [x_min, y_min, x_max, y_max] followed by any additional attributes (e.g., class labels). matrix (np.ndarray): The 3x3 affine transformation matrix to apply. bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB path uses polygon transform. Returns: np.ndarray: An array of transformed bounding boxes with the same shape as the input. Each row contains [new_x_min, new_y_min, new_x_max, new_y_max] followed by any additional attributes from the input bounding boxes. Note: - This function assumes that the input bounding boxes are in the format [x_min, y_min, x_max, y_max]. - The resulting bounding boxes are the smallest axis-aligned boxes that completely enclose the transformed original boxes. They may be larger than the minimal possible bounding box if the original box becomes rotated. - Any additional attributes beyond the first 4 coordinates are preserved unchanged. - This method is called "largest box" because it returns the largest axis-aligned box that encloses all corners of the transformed bounding box. Examples: >>> bboxes = np.array([[10, 10, 20, 20, 1], [30, 30, 40, 40, 2]]) # Two boxes with class labels >>> matrix = np.array([[2, 0, 5], [0, 2, 5], [0, 0, 1]]) # Scale by 2 and translate by (5, 5) >>> transformed_bboxes = bboxes_affine_largest_box(bboxes, matrix) >>> print(transformed_bboxes) [[ 25. 25. 45. 45. 1.] [ 65. 65. 85. 85. 2.]]

Parameters

Apply an affine transformation to bounding boxes using an ellipse approximation method. This function transforms bounding boxes by approximating each box with an ellipse, transforming points along the ellipse's circumference, and then computing the new bounding box that encloses the transformed ellipse. Args: bboxes (np.ndarray): An array of bounding boxes with shape (N, 4+) where N is the number of bounding boxes. Each row should contain [x_min, y_min, x_max, y_max] followed by any additional attributes (e.g., class labels). matrix (np.ndarray): The 3x3 affine transformation matrix to apply. bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB path uses polygon transform. Returns: np.ndarray: An array of transformed bounding boxes with the same shape as the input. Each row contains [new_x_min, new_y_min, new_x_max, new_y_max] followed by any additional attributes from the input bounding boxes. Note: - This function assumes that the input bounding boxes are in the format [x_min, y_min, x_max, y_max]. - The ellipse approximation method can provide a tighter bounding box compared to the largest box method, especially for rotations. - 360 points are used to approximate each ellipse, which provides a good balance between accuracy and computational efficiency. - Any additional attributes beyond the first 4 coordinates are preserved unchanged. - This method may be more suitable for objects that are roughly elliptical in shape.

Parameters

Apply an affine transformation to bounding boxes. For reflection border modes (cv2.BORDER_REFLECT_101, cv2.BORDER_REFLECT), this function: 1. Calculates necessary padding to avoid information loss 2. Applies padding to the bounding boxes 3. Adjusts the transformation matrix to account for padding 4. Applies the affine transformation 5. Validates the transformed bounding boxes For other border modes, it directly applies the affine transformation without padding. Args: bboxes (np.ndarray): Input bounding boxes matrix (np.ndarray): Affine transformation matrix rotate_method (str): Method for rotating bounding boxes ('largest_box' or 'ellipse'). Only applies to HBB (axis-aligned) bounding boxes. Ignored for OBB. image_shape (Sequence[int]): Shape of the input image border_mode (int): OpenCV border mode output_shape (Sequence[int]): Shape of the output image bbox_type (Literal["hbb", "obb"]): Bounding box type. OBB uses polygon transformation regardless of rotate_method. Returns: np.ndarray: Transformed and normalized bounding boxes

Parameters

Generate a `(H,W,N)` array of distance maps for `N` keypoints. The `n`-th distance map contains at every location `(y, x)` the euclidean distance to the `n`-th keypoint. This function can be used as a helper when augmenting keypoints with a method that only supports the augmentation of images. Args: keypoints (np.ndarray): A numpy array of shape (N, 2+) where N is the number of keypoints. Each row represents a keypoint's (x, y) coordinates. image_shape (tuple[int, int]): Shape of the image (height, width) inverted (bool): If `True`, inverted distance maps are returned where each distance value d is replaced by `d/(d+1)`, i.e. the distance maps have values in the range `(0.0, 1.0]` with `1.0` denoting exactly the position of the respective keypoint. Returns: np.ndarray: A float32 array of shape (H, W, N) containing `N` distance maps for `N` keypoints. Each location `(y, x, n)` in the array denotes the euclidean distance at `(y, x)` to the `n`-th keypoint. If `inverted` is `True`, the distance `d` is replaced by `d/(d+1)`. The height and width of the array match the height and width in `image_shape`.

Parameters

Validate and process `if_not_found_coords` parameter.

Parameters

Convert distance maps back to keypoints coordinates. This function is the inverse of `to_distance_maps`. It takes distance maps generated for a set of keypoints and reconstructs the original keypoint coordinates. The function supports both regular and inverted distance maps, and can handle cases where keypoints are not found or fall outside a specified threshold. Args: distance_maps (np.ndarray): A 3D numpy array of shape (height, width, nb_keypoints) containing distance maps for each keypoint. Each channel represents the distance map for one keypoint. inverted (bool): If True, treats the distance maps as inverted (where higher values indicate closer proximity to keypoints). If False, treats them as regular distance maps (where lower values indicate closer proximity). if_not_found_coords (Sequence[int] | dict[str, Any] | None, optional): Coordinates to use for keypoints that are not found or fall outside the threshold. Can be: - None: Drop keypoints that are not found. - Sequence of two integers: Use these as (x, y) coordinates for not found keypoints. - Dict with 'x' and 'y' keys: Use these values for not found keypoints. Defaults to None. threshold (float | None, optional): A threshold value to determine valid keypoints. For inverted maps, values >= threshold are considered valid. For regular maps, values <= threshold are considered valid. If None, all keypoints are considered valid. Defaults to None. Returns: np.ndarray: A 2D numpy array of shape (nb_keypoints, 2) containing the (x, y) coordinates of the reconstructed keypoints. If `drop_if_not_found` is True (derived from if_not_found_coords), the output may have fewer rows than input keypoints. Raises: ValueError: If the input `distance_maps` is not a 3D array. Notes: - The function uses vectorized operations for improved performance, especially with large numbers of keypoints. - When `threshold` is None, all keypoints are considered valid, and `if_not_found_coords` is not used. - The function assumes that the input distance maps are properly normalized and scaled according to the original image dimensions. Examples: >>> distance_maps = np.random.rand(100, 100, 3) # 3 keypoints >>> inverted = True >>> if_not_found_coords = [0, 0] >>> threshold = 0.5 >>> keypoints = from_distance_maps(distance_maps, inverted, if_not_found_coords, threshold) >>> print(keypoints.shape) (3, 2)

Parameters

Applies a `D_4` symmetry group transformation to an image array. This function manipulates an image using transformations such as rotations and flips, corresponding to the `D_4` dihedral group symmetry operations. Each transformation is identified by a unique group member code. Args: img (np.ndarray): The input image array to transform. group_member (Literal["e", "r90", "r180", "r270", "v", "hvt", "h", "t"]): A string identifier indicating the specific transformation to apply. Valid codes include: - 'e': Identity (no transformation). - 'r90': Rotate 90 degrees counterclockwise. - 'r180': Rotate 180 degrees. - 'r270': Rotate 270 degrees counterclockwise. - 'v': Vertical flip. - 'hvt': Transpose over second diagonal - 'h': Horizontal flip. - 't': Transpose (reflect over the main diagonal). Returns: np.ndarray: The transformed image array.

Parameters

Transposes the first two dimensions of an array of any dimensionality. Retains the order of any additional dimensions. Args: img (np.ndarray): Input array. Returns: np.ndarray: Transposed array.

Parameters

Transpose a batch of images. Args: images (np.ndarray): Batch of images to transpose with shape: - (N, H, W) for grayscale images - (N, H, W, C) for multi-channel images where N is the batch size, H is height, W is width, C is channels Returns: np.ndarray: Transposed batch of images with shape: - (N, W, H) for grayscale images - (N, W, H, C) for multi-channel images

Parameters

Transpose a batch of volumes. Args: volumes (np.ndarray): Batch of volumes to transpose with shape: - (N, D, H, W) for grayscale volumes - (N, D, H, W, C) for multi-channel volumes where N is the batch size, D is depth, H is height, W is width, C is channels Returns: np.ndarray: Transposed batch of volumes with shape: - (N, D, W, H) for grayscale volumes - (N, D, W, H, C) for multi-channel volumes

Parameters

Rotate an image 90 degrees counterclockwise. Args: img (np.ndarray): The input image to rotate. group_element (Literal["e", "r90", "r180", "r270"]): C4 group element to apply. Returns: np.ndarray: The rotated image.

Parameters

Rotate a batch of images 90 degrees counter-clockwise multiple times. Args: images (np.ndarray): Batch of images to rotate with shape: - (N, H, W) for grayscale images - (N, H, W, C) for multi-channel images where N is the batch size, H is height, W is width, C is channels group_element (Literal["e", "r90", "r180", "r270"]): C4 group element to apply. Returns: np.ndarray: Rotated batch of images with shape: - (N, W, H) for grayscale images when group_element is r90 or r270 - (N, H, W) for grayscale images when group_element is e or r180 - (N, W, H, C) for multi-channel images when group_element is r90 or r270 - (N, H, W, C) for multi-channel images when group_element is e or r180

Parameters

Flip bounding boxes vertically. Args: bboxes (np.ndarray): Array of bounding boxes with shape (num_boxes, 4+) bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB uses center/size/angle update. Returns: np.ndarray: Vertically flipped bounding boxes

Parameters

Flip bounding boxes horizontally. Args: bboxes (np.ndarray): Array of bounding boxes with shape (num_boxes, 4+) bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB uses center/size/angle update. Returns: np.ndarray: Horizontally flipped bounding boxes

Parameters

Transpose bounding boxes along the main diagonal. Args: bboxes (np.ndarray): Array of bounding boxes with shape (num_boxes, 4+) bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB uses center/size/angle update. Returns: np.ndarray: Transposed bounding boxes

Parameters

Flip keypoints vertically. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 2+) rows (int): Number of rows in the image Returns: np.ndarray: Vertically flipped keypoints

Parameters

Flip keypoints horizontally. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 2+) cols (int): Number of columns in the image Returns: np.ndarray: Horizontally flipped keypoints

Parameters

Transpose keypoints along the main diagonal. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 2+) Returns: np.ndarray: Transposed keypoints

Parameters

Pad an image to ensure minimum dimensions. This function adds padding to an image if its dimensions are smaller than the specified minimum dimensions. Padding is added evenly on all sides. Args: img (np.ndarray): Input image to pad. min_height (int): Minimum height of the output image. min_width (int): Minimum width of the output image. border_mode (int): OpenCV border mode for padding. value (tuple[float, ...] | float | None): Value(s) to fill the border pixels. Returns: np.ndarray: Padded image with dimensions at least (min_height, min_width).

Parameters

Pad an image with explicitly defined padding on each side. This function adds specified amounts of padding to each side of the image. Args: img (np.ndarray): Input image to pad. h_pad_top (int): Number of pixels to add at the top. h_pad_bottom (int): Number of pixels to add at the bottom. w_pad_left (int): Number of pixels to add on the left. w_pad_right (int): Number of pixels to add on the right. border_mode (int): OpenCV border mode for padding. value (tuple[float, ...] | float | None): Value(s) to fill the border pixels. Returns: np.ndarray: Padded image.

Parameters

Pad a batch of images with explicitly defined padding on each side. This function adds specified amounts of padding to each side of the image for each image in the batch. Args: images (np.ndarray): Input batch of images to pad. h_pad_top (int): Number of pixels to add at the top. h_pad_bottom (int): Number of pixels to add at the bottom. w_pad_left (int): Number of pixels to add on the left. w_pad_right (int): Number of pixels to add on the right. border_mode (int): OpenCV border mode for padding. value (tuple[float, ...] | float | None): Value(s) to fill the border pixels. Returns: np.ndarray: Padded batch of images.

Parameters

Remap keypoints using mask and cv2.remap method.

Parameters

Transform keypoints using coordinate mapping functions. This function applies the inverse of the mapping defined by map_x and map_y to keypoint coordinates. The inverse mapping is necessary because the mapping functions define how pixels move from the source to the destination image, while keypoints need to be transformed from the destination back to the source. Args: keypoints (np.ndarray): Array of keypoints with shape (N, 2+), where the first two columns are x and y coordinates. map_x (np.ndarray): Map of x-coordinates with shape equal to image_shape. map_y (np.ndarray): Map of y-coordinates with shape equal to image_shape. image_shape (tuple[int, int]): Shape (height, width) of the original image. Returns: np.ndarray: Transformed keypoints with the same shape as the input keypoints. Returns an empty array if input keypoints is empty.

Parameters

Generate inverse mapping for strong distortions.

Parameters

Upscale distortion maps from lower resolution to target resolution. This is used when distortion maps are generated at a lower resolution for performance, then upscaled to the original image size. Args: map_x: X-coordinate distortion map (generated at lower resolution) map_y: Y-coordinate distortion map (generated at lower resolution) target_shape: Target shape (height, width) to upscale to interpolation: OpenCV interpolation method Returns: Upscaled distortion maps with target_shape

Parameters

Remap bounding boxes using displacement maps. Args: bboxes: Bounding boxes array map_x: X displacement map map_y: Y displacement map image_shape: Image shape (height, width) bbox_type: Type of bounding box - "hbb" for axis-aligned or "obb" for oriented Returns: Remapped bounding boxes

Parameters

Generate displacement fields for elastic transform. This function generates displacement fields for elastic transform based on the provided parameters. It generates noise either from a Gaussian or uniform distribution and normalizes it to the range [-1, 1]. Args: image_shape (tuple[int, int]): The shape of the image as (height, width). alpha (float): The alpha parameter for the elastic transform. sigma (float): The sigma parameter for the elastic transform. same_dxdy (bool): Whether to use the same displacement field for both x and y directions. kernel_size (tuple[int, int]): The size of the kernel for the elastic transform. random_generator (np.random.Generator): The random number generator to use. noise_distribution (Literal["gaussian", "uniform"]): The distribution of the noise. Returns: tuple[np.ndarray, np.ndarray]: A tuple containing: - fields: The displacement fields for the elastic transform. - output_shape: The output shape of the elastic warp.

Parameters

Pad bounding boxes by a given amount. This function pads bounding boxes by a given amount. It handles both reflection and padding. Args: bboxes (np.ndarray): The bounding boxes to pad. pad_top (int): The amount to pad the top of the bounding boxes. pad_bottom (int): The amount to pad the bottom of the bounding boxes. pad_left (int): The amount to pad the left of the bounding boxes. pad_right (int): The amount to pad the right of the bounding boxes. border_mode (int): The border mode to use. image_shape (tuple[int, int]): The shape of the image as (height, width). Returns: np.ndarray: The padded bounding boxes.

Parameters

Validate bounding boxes and remove invalid ones. Args: bboxes (np.ndarray): Array of bounding boxes with shape (n, 4) where each row is [x_min, y_min, x_max, y_max]. image_shape (tuple[int, int]): Shape of the image as (height, width). Returns: np.ndarray: Array of valid bounding boxes, potentially with fewer boxes than the input. Examples: >>> bboxes = np.array([[10, 20, 30, 40], [-10, -10, 5, 5], [100, 100, 120, 120]]) >>> valid_bboxes = validate_bboxes(bboxes, (100, 100)) >>> print(valid_bboxes) [[10 20 30 40]]

Parameters

Shift bounding boxes by a given vector. Args: bboxes (np.ndarray): Array of bounding boxes with shape (n, m) where n is the number of bboxes and m >= 4. The first 4 columns are [x_min, y_min, x_max, y_max]. shift_vector (np.ndarray): Vector to shift the bounding boxes by, with shape (4,) for [shift_x, shift_y, shift_x, shift_y]. Returns: np.ndarray: Shifted bounding boxes with the same shape as input.

Parameters

Calculate the dimensions of the grid needed for reflection padding and the position of the original image. Args: pad_top (int): Number of pixels to pad above the image. pad_bottom (int): Number of pixels to pad below the image. pad_left (int): Number of pixels to pad to the left of the image. pad_right (int): Number of pixels to pad to the right of the image. image_shape (tuple[int, int]): Shape of the original image as (height, width). Returns: dict[str, tuple[int, int]]: A dictionary containing: - 'grid_shape': A tuple (grid_rows, grid_cols) where: - grid_rows (int): Number of times the image needs to be repeated vertically. - grid_cols (int): Number of times the image needs to be repeated horizontally. - 'original_position': A tuple (original_row, original_col) where: - original_row (int): Row index of the original image in the grid. - original_col (int): Column index of the original image in the grid.

Parameters

Generate reflected bounding boxes for the entire reflection grid. Args: bboxes (np.ndarray): Original bounding boxes. grid_dims (dict[str, tuple[int, int]]): Grid dimensions and original position. image_shape (tuple[int, int]): Shape of the original image as (height, width). center_in_origin (bool): If True, center the grid at the origin. Default is False. Returns: np.ndarray: Array of reflected and shifted bounding boxes for the entire grid.

Parameters

Flip bounding boxes horizontally and/or vertically. Args: bboxes (np.ndarray): Array of bounding boxes with shape (n, m) where each row is [x_min, y_min, x_max, y_max, ...]. flip_horizontal (bool): Whether to flip horizontally. flip_vertical (bool): Whether to flip vertically. image_shape (tuple[int, int]): Shape of the image as (height, width). Returns: np.ndarray: Flipped bounding boxes.

Parameters

Apply perspective distortion to an image based on a generated mesh. This function applies a perspective transformation to each cell of the image defined by the generated mesh. The distortion is applied using OpenCV's perspective transformation and blending techniques. Args: image (np.ndarray): The input image to be distorted. Can be a 2D grayscale image or a 3D color image. generated_mesh (np.ndarray): A 2D array where each row represents a quadrilateral cell as [x1, y1, x2, y2, dst_x1, dst_y1, dst_x2, dst_y2, dst_x3, dst_y3, dst_x4, dst_y4]. The first four values define the source rectangle, and the last eight values define the destination quadrilateral. interpolation (int): Interpolation method to be used in the perspective transformation. Should be one of the OpenCV interpolation flags (e.g., cv2.INTER_LINEAR). Returns: np.ndarray: The distorted image with the same shape and dtype as the input image. Note: - The function preserves the channel dimension of the input image. - Each cell of the generated mesh is transformed independently and then blended into the output image. - The distortion is applied using perspective transformation, which allows for more complex distortions compared to affine transformations. Examples: >>> image = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8) >>> mesh = np.array([[0, 0, 50, 50, 5, 5, 45, 5, 45, 45, 5, 45]]) >>> distorted = distort_image(image, mesh, cv2.INTER_LINEAR) >>> distorted.shape (100, 100, 3)

Parameters

Distort bounding boxes based on a generated mesh. This function applies a perspective transformation to each bounding box based on the provided generated mesh. It ensures that the bounding boxes are clipped to the image boundaries after transformation. Args: bboxes (np.ndarray): The bounding boxes to distort. generated_mesh (np.ndarray): The generated mesh to distort the bounding boxes with. image_shape (tuple[int, int]): The shape of the image as (height, width). Returns: np.ndarray: The distorted bounding boxes.

Parameters

Distort keypoints based on a generated mesh. This function applies a perspective transformation to each keypoint based on the provided generated mesh. It ensures that the keypoints are clipped to the image boundaries after transformation. Args: keypoints (np.ndarray): The keypoints to distort. generated_mesh (np.ndarray): The generated mesh to distort the keypoints with. image_shape (tuple[int, int]): The shape of the image as (height, width). Returns: np.ndarray: The distorted keypoints.

Parameters

Generate distorted grid polygons based on input dimensions and magnitude. This function creates a grid of polygons and applies random distortions to the internal vertices, while keeping the boundary vertices fixed. The distortion is applied consistently across shared vertices to avoid gaps or overlaps in the resulting grid. Args: dimensions (np.ndarray): A 3D array of shape (grid_height, grid_width, 4) where each element is [x_min, y_min, x_max, y_max] representing the dimensions of a grid cell. magnitude (int): Maximum pixel-wise displacement for distortion. The actual displacement will be randomly chosen in the range [-magnitude, magnitude]. random_generator (np.random.Generator): A random number generator. Returns: np.ndarray: A 2D array of shape (total_cells, 8) where each row represents a distorted polygon as [x1, y1, x2, y1, x2, y2, x1, y2]. The total_cells is equal to grid_height * grid_width. Note: - Only internal grid points are distorted; boundary points remain fixed. - The function ensures consistent distortion across shared vertices of adjacent cells. - The distortion is applied to the following points of each internal cell: * Bottom-right of the cell above and to the left * Bottom-left of the cell above * Top-right of the cell to the left * Top-left of the current cell - Each square represents a cell, and the X marks indicate the coordinates where displacement occurs. +--+--+--+--+ | | | | | +--X--X--X--+ | | | | | +--X--X--X--+ | | | | | +--X--X--X--+ | | | | | +--+--+--+--+ - For each X, the coordinates of the left, right, top, and bottom edges in the four adjacent cells are displaced. Examples: >>> dimensions = np.array([[[0, 0, 50, 50], [50, 0, 100, 50]], ... [[0, 50, 50, 100], [50, 50, 100, 100]]]) >>> distorted = generate_distorted_grid_polygons(dimensions, magnitude=10) >>> distorted.shape (4, 8)

Parameters

Pad keypoints by a given amount. This function pads keypoints by a given amount. It handles both reflection and padding. Args: keypoints (np.ndarray): The keypoints to pad. pad_top (int): The amount to pad the top of the keypoints. pad_bottom (int): The amount to pad the bottom of the keypoints. pad_left (int): The amount to pad the left of the keypoints. pad_right (int): The amount to pad the right of the keypoints. border_mode (int): The border mode to use. image_shape (tuple[int, int]): The shape of the image as (height, width). Returns: np.ndarray: The padded keypoints.

Parameters

Validate keypoints and remove those that fall outside the image boundaries. Args: keypoints (np.ndarray): Array of keypoints with shape (N, M) where N is the number of keypoints and M >= 2. The first two columns represent x and y coordinates. image_shape (tuple[int, int]): Shape of the image as (height, width). Returns: np.ndarray: Array of valid keypoints that fall within the image boundaries. Note: This function only checks the x and y coordinates (first two columns) of the keypoints. Any additional columns (e.g., angle, scale) are preserved for valid keypoints.

Parameters

Shift keypoints by a given shift vector. This function shifts the keypoints by a given shift vector. It only shifts the x, y and z coordinates of the keypoints. Args: keypoints (np.ndarray): The keypoints to shift. shift_vector (np.ndarray): The shift vector to apply to the keypoints. Returns: np.ndarray: The shifted keypoints.

Parameters

Generate reflected keypoints for the entire reflection grid. This function creates a grid of keypoints by reflecting and shifting the original keypoints. It handles both centered and non-centered grids based on the `center_in_origin` parameter. Args: keypoints (np.ndarray): Original keypoints array of shape (N, 4+), where N is the number of keypoints, and each keypoint is represented by at least 4 values (x, y, angle, scale, ...). grid_dims (dict[str, tuple[int, int]]): A dictionary containing grid dimensions and original position. It should have the following keys: - "grid_shape": tuple[int, int] representing (grid_rows, grid_cols) - "original_position": tuple[int, int] representing (original_row, original_col) image_shape (tuple[int, int]): Shape of the original image as (height, width). center_in_origin (bool, optional): If True, center the grid at the origin. Default is False. Returns: np.ndarray: Array of reflected and shifted keypoints for the entire grid. The shape is (N * grid_rows * grid_cols, 4+), where N is the number of original keypoints. Note: - The function handles keypoint flipping and shifting to create a grid of reflected keypoints. - It preserves the angle and scale information of the keypoints during transformations. - The resulting grid can be either centered at the origin or positioned based on the original grid.

Parameters

Flip keypoints horizontally or vertically. This function flips keypoints horizontally or vertically based on the provided parameters. It also flips the angle of the keypoints when flipping horizontally. Args: keypoints (np.ndarray): The keypoints to flip. flip_horizontal (bool): Whether to flip horizontally. flip_vertical (bool): Whether to flip vertically. image_shape (tuple[int, int]): The shape of the image as (height, width). Returns: np.ndarray: The flipped keypoints.

Parameters

Create an affine transformation matrix combining translation, shear, scale, and rotation. Args: translate (dict[str, float]): Translation in x and y directions. shear (dict[str, float]): Shear in x and y directions (in degrees). scale (dict[str, float]): Scale factors for x and y directions. rotate (float): Rotation angle in degrees. shift (tuple[float, float]): Shift to apply before and after transformations. Returns: np.ndarray: The resulting 3x3 affine transformation matrix.

Parameters

Compute the bounds of an image after applying an affine transformation. Args: matrix (np.ndarray): The 3x3 affine transformation matrix. image_shape (Tuple[int, int]): The shape of the image as (height, width). Returns: tuple[np.ndarray, np.ndarray]: A tuple containing: - min_coords: An array with the minimum x and y coordinates. - max_coords: An array with the maximum x and y coordinates.

Parameters

Compute the output shape of an affine warp. This function computes the output shape of an affine warp based on the input matrix and input shape. It calculates the transformed image bounds and then determines the output shape based on the input shape. Args: matrix (np.ndarray): The 3x3 affine transformation matrix. input_shape (tuple[int, ...]): The shape of the input image as (height, width, ...). Returns: tuple[np.ndarray, tuple[int, int]]: A tuple containing: - matrix: The 3x3 affine transformation matrix. - output_shape: The output shape of the affine warp.

Parameters

Calculate the center coordinates if image. Used by images, masks and keypoints. Args: image_shape (tuple[int, int]): The shape of the image. Returns: tuple[float, float]: center_x, center_y

Parameters

Calculate the center coordinates for of image for bounding boxes. Args: image_shape (tuple[int, int]): The shape of the image. Returns: tuple[float, float]: center_x, center_y

Parameters

Generate a distorted grid for image transformation based on given step sizes. This function creates two 2D arrays (map_x and map_y) that represent a distorted version of the original image grid. These arrays can be used with OpenCV's remap function to apply grid distortion to an image. Args: image_shape (tuple[int, int]): The shape of the image as (height, width). steps_x (list[float]): List of step sizes for the x-axis distortion. The length should be num_steps + 1. Each value represents the relative step size for a segment of the grid in the x direction. steps_y (list[float]): List of step sizes for the y-axis distortion. The length should be num_steps + 1. Each value represents the relative step size for a segment of the grid in the y direction. num_steps (int): The number of steps to divide each axis into. This determines the granularity of the distortion grid. Returns: tuple[np.ndarray, np.ndarray]: A tuple containing two 2D numpy arrays: - map_x: A 2D array of float32 values representing the x-coordinates of the distorted grid. - map_y: A 2D array of float32 values representing the y-coordinates of the distorted grid. Note: - The function generates a grid where each cell can be distorted independently. - The distortion is controlled by the steps_x and steps_y parameters, which determine how much each grid line is shifted. - The resulting map_x and map_y can be used directly with cv2.remap() to apply the distortion to an image. - The distortion is applied smoothly across each grid cell using linear interpolation. Examples: >>> image_shape = (100, 100) >>> steps_x = [1.1, 0.9, 1.0, 1.2, 0.95, 1.05] >>> steps_y = [0.9, 1.1, 1.0, 1.1, 0.9, 1.0] >>> num_steps = 5 >>> map_x, map_y = generate_grid(image_shape, steps_x, steps_y, num_steps) >>> distorted_image = cv2.remap(image, map_x, map_y, cv2.INTER_LINEAR)

Parameters

Normalize the grid distortion steps. This function normalizes the grid distortion steps, ensuring that the distortion never leaves the image bounds. It compensates for smaller last steps in the source image and normalizes the steps such that the distortion never leaves the image bounds. Args: image_shape (tuple[int, int]): The shape of the image as (height, width). num_steps (int): The number of steps to divide each axis into. This determines the granularity of the distortion grid. x_steps (list[float]): List of step sizes for the x-axis distortion. The length should be num_steps + 1. Each value represents the relative step size for a segment of the grid in the x direction. y_steps (list[float]): List of step sizes for the y-axis distortion. The length should be num_steps + 1. Each value represents the relative step size for a segment of the grid in the y direction. Returns: dict[str, np.ndarray]: A dictionary containing the normalized step sizes for the x and y axes.

Parameters

Generates an array of nearly equal integer intervals that sum up to `n`. This function divides the number `n` into `parts` nearly equal parts. It ensures that the sum of all parts equals `n`, and the difference between any two parts is at most one. This is useful for distributing a total amount into nearly equal discrete parts. Args: n (int): The total value to be split. parts (int): The number of parts to split into. Returns: np.ndarray: An array of integers where each integer represents the size of a part. Examples: >>> almost_equal_intervals(20, 3) array([7, 7, 6]) # Splits 20 into three parts: 7, 7, and 6 >>> almost_equal_intervals(16, 4) array([4, 4, 4, 4]) # Splits 16 into four equal parts

Parameters

Generate shuffled splits for a given dimension size and number of divisions. Args: size (int): Total size of the dimension (height or width). divisions (int): Number of divisions (rows or columns). random_generator (np.random.Generator | None): The random generator to use for shuffling the splits. If None, the splits are not shuffled. Returns: np.ndarray: Cumulative edges of the shuffled intervals.

Parameters

Splits an image shape into a uniform grid specified by the grid dimensions. Args: image_shape (tuple[int, int]): The shape of the image as (height, width). grid (tuple[int, int]): The grid size as (rows, columns). random_generator (np.random.Generator): The random generator to use for shuffling the splits. If None, the splits are not shuffled. Returns: np.ndarray: An array containing the tiles' coordinates in the format (start_y, start_x, end_y, end_x). Note: The function uses `generate_shuffled_splits` to generate the splits for the height and width of the image. The splits are then used to calculate the coordinates of the tiles.

Parameters

Generate perspective points for a given image shape and scale. This function generates perspective points for a given image shape and scale. It uses a normal distribution to generate the points, and then modulates them to be within the image bounds. Args: image_shape (tuple[int, int]): The shape of the image as (height, width). scale (float): The scale of the perspective points. random_generator (np.random.Generator): The random generator to use for generating the points. Returns: np.ndarray: The perspective points.

Parameters

Order points in a clockwise manner. This function orders the points in a clockwise manner, ensuring that the points are in the correct order for perspective transformation. Args: pts (np.ndarray): The points to order. Returns: np.ndarray: The ordered points.

Parameters

Compute perspective transformation parameters. This function computes the perspective transformation parameters for a given set of points. It adjusts the points to ensure that the transformed image retains its original dimensions. Args: points (np.ndarray): The points to compute the perspective transformation parameters for. image_shape (tuple[int, int]): The shape of the image. Returns: tuple[np.ndarray, int, int]: The perspective transformation parameters and the maximum dimensions of the transformed image.

Parameters

Expand a transformation matrix to include padding. This function expands a transformation matrix to include padding, ensuring that the transformed image retains its original dimensions. It first calculates the destination points of the transformed image, then adjusts the matrix to include padding, and finally returns the expanded matrix and the maximum dimensions of the transformed image. Args: matrix (np.ndarray): The transformation matrix to expand. shape (tuple[int, int]): The shape of the image. Returns: tuple[np.ndarray, int, int]: The expanded matrix and the maximum dimensions of the transformed image.

Parameters

Create maps for piecewise affine transformation using OpenCV's remap function. This function creates maps for piecewise affine transformation using OpenCV's remap function. It generates the control points for the transformation, then uses the remap function to create the transformation maps. Args: image_shape (tuple[int, int]): The shape of the image as (height, width). grid (tuple[int, int]): The grid size as (rows, columns). scale (float): The scale of the transformation. absolute_scale (bool): Whether to use absolute scale. random_generator (np.random.Generator): The random generator to use for generating the points. Returns: tuple[np.ndarray | None, np.ndarray | None]: The transformation maps.

Parameters

Apply a piecewise affine transformation to bounding boxes. This function applies a piecewise affine transformation to the bounding boxes of an image. It first converts the bounding boxes to masks, then applies the transformation, and finally converts the transformed masks back to bounding boxes. Args: bboxes (np.ndarray): The bounding boxes to transform. map_x (np.ndarray): The x-coordinates of the transformation. map_y (np.ndarray): The y-coordinates of the transformation. border_mode (int): The border mode to use for the transformation. image_shape (tuple[int, int]): The shape of the image. Returns: np.ndarray: The transformed bounding boxes.

Parameters

Calculate padding for a single dimension. Args: current_size (int): Current size of the dimension min_size (int | None): Minimum size requirement, if any divisor (int | None): Divisor for padding to make size divisible, if any Returns: tuple[int, int]: (pad_before, pad_after)

Parameters

Calculate padding parameters based on target dimensions. Args: image_shape (tuple[int, int]): (height, width) of the image min_height (int | None): Minimum height requirement, if any min_width (int | None): Minimum width requirement, if any pad_height_divisor (int | None): Divisor for height padding, if any pad_width_divisor (int | None): Divisor for width padding, if any Returns: tuple[int, int, int, int]: (pad_top, pad_bottom, pad_left, pad_right)

Parameters

Adjust padding values based on desired position.

Parameters

Swap the positions of keypoints based on a tile mapping. This function takes a set of keypoints and repositions them according to a mapping of tile swaps. Keypoints are moved from their original tiles to new positions in the swapped tiles. Args: keypoints (np.ndarray): A 2D numpy array of shape (N, 2) where N is the number of keypoints. Each row represents a keypoint's (x, y) coordinates. tiles (np.ndarray): A 2D numpy array of shape (M, 4) where M is the number of tiles. Each row represents a tile's (start_y, start_x, end_y, end_x) coordinates. mapping (np.ndarray): A 1D numpy array of shape (M,) where M is the number of tiles. Each element i contains the index of the tile that tile i should be swapped with. Returns: np.ndarray: A 2D numpy array of the same shape as the input keypoints, containing the new positions of the keypoints after the tile swap. Raises: RuntimeWarning: If any keypoint is not found within any tile. Notes: - Keypoints that do not fall within any tile will remain unchanged. - The function assumes that the tiles do not overlap and cover the entire image space.

Parameters

Swap tiles on the image according to the new format. Args: image (np.ndarray): Input image. tiles (np.ndarray): Array of tiles with each tile as [start_y, start_x, end_y, end_x]. mapping (list[int] | None): list of new tile indices. Returns: np.ndarray: Output image with tiles swapped according to the random shuffle.

Parameters

Validate if a component meets the minimum requirements.

Parameters

Shuffle bounding boxes according to grid mapping. Args: bboxes (np.ndarray): Array of bounding boxes with shape (num_boxes, 4+) tiles (np.ndarray): Array of grid tiles mapping (list[int]): Mapping of tile indices 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 bbox_type (Literal["hbb", "obb"]): Bounding box type; OBB is not supported here. Returns: np.ndarray: Shuffled bounding boxes

Parameters

Groups tiles by their shape and stores the indices for each shape.

Parameters

Shuffles indices within each group of similar shapes and creates a list where each index points to the index of the tile it should be mapped to. Args: shape_groups (dict[tuple[int, int], list[int]]): Groups of tile indices categorized by shape. random_generator (np.random.Generator): The random generator to use for shuffling the indices. If None, a new random generator will be used. Returns: list[int]: A list where each index is mapped to the new index of the tile after shuffling.

Parameters

Compute pairwise distances between two sets of points. Args: points1 (np.ndarray): First set of points with shape (N, 2) points2 (np.ndarray): Second set of points with shape (M, 2) Returns: np.ndarray: Matrix of pairwise distances with shape (N, M)

Parameters

Compute Thin Plate Spline weights. Args: src_points (np.ndarray): Source control points with shape (num_points, 2) dst_points (np.ndarray): Destination control points with shape (num_points, 2) Returns: tuple[np.ndarray, np.ndarray]: Tuple of (nonlinear_weights, affine_weights) - nonlinear_weights: TPS kernel weights for nonlinear deformation (num_points, 2) - affine_weights: Weights for affine transformation (3, 2) [constant term, x scale/shear, y scale/shear] Note: The TPS interpolation is decomposed into: 1. Nonlinear part (controlled by kernel weights) 2. Affine part (global scaling, rotation, translation)

Parameters

Apply TPS transformation with consistent types.

Parameters

Generate distortion maps using camera matrix model. Args: image_shape (tuple[int, int]): Image shape (height, width) k (float): Distortion coefficient Returns: tuple[np.ndarray, np.ndarray]: Tuple of (map_x, map_y) distortion maps

Parameters

Generate distortion maps using fisheye model. Args: image_shape (tuple[int, int]): Image shape (height, width) k (float): Distortion coefficient Returns: tuple[np.ndarray, np.ndarray]: Tuple of (map_x, map_y) distortion maps

Parameters

Generate control points for TPS transformation. Args: num_control_points (int): Number of control points per side Returns: np.ndarray: Control points with shape (N, 2)

Parameters

Perform horizontal flip on a volume (numpy array). Flips the volume along the width axis (axis=2). Handles inputs with shapes (D, H, W) or (D, H, W, C). Args: volume (np.ndarray): Input volume. Returns: np.ndarray: Horizontally flipped volume.

Parameters

Perform vertical flip on a volume (numpy array). Flips the volume along the height axis (axis=1). Handles inputs with shapes (D, H, W) or (D, H, W, C). Args: volume (np.ndarray): Input volume. Returns: np.ndarray: Vertically flipped volume.

Parameters