albumentations.augmentations.geometric.transforms

Augmentation to apply affine transformations to images. Affine transformations involve: - Translation ("move" image on the x-/y-axis) - Rotation - Scaling ("zoom" in/out) - Shear (move one side of the image, turning a square into a trapezoid) All such transformations can create "new" pixels in the image without a defined content, e.g. if the image is translated to the left, pixels are created on the right. A method has to be defined to deal with these pixel values. The parameters `fill` and `fill_mask` of this class deal with this. Some transformations involve interpolations between several pixels of the input image to generate output pixel values. The parameters `interpolation` and `mask_interpolation` deals with the method of interpolation used for this.

Parameters

References

• Towards Rotation Invariance in Object Detection: https://arxiv.org/abs/2109.13488

Base class for distortion-based transformations. This class provides a foundation for implementing various types of image distortions, such as optical distortions, grid distortions, and elastic transformations. It handles the common operations of applying distortions to images, masks, bounding boxes, and keypoints.

Parameters

Notes

- This is an abstract base class and should not be used directly. - Subclasses should implement the `get_params_dependent_on_data` method to generate the distortion maps (map_x and map_y). - The distortion is applied consistently across all targets (image, mask, bboxes, keypoints) to maintain coherence in the augmented data.

Applies one of the eight possible D4 dihedral group transformations to a square-shaped input, maintaining the square shape. These transformations correspond to the symmetries of a square, including rotations and reflections. The D4 group transformations include: - 'e' (identity): No transformation is applied. - 'r90' (rotation by 90 degrees counterclockwise) - 'r180' (rotation by 180 degrees) - 'r270' (rotation by 270 degrees counterclockwise) - 'v' (reflection across the vertical midline) - 'hvt' (reflection across the anti-diagonal) - 'h' (reflection across the horizontal midline) - 't' (reflection across the main diagonal) Even if the probability (`p`) of applying the transform is set to 1, the identity transformation 'e' may still occur, which means the input will remain unchanged in one out of eight cases.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.Compose([
...     A.D4(p=1.0),
... ])
>>> transformed = transform(image=image)
>>> transformed_image = transformed['image']
# The resulting image will be one of the 8 possible D4 transformations of the input

Notes

- This transform is particularly useful for augmenting data that does not have a clear orientation, such as top-view satellite or drone imagery, or certain types of medical images. - The input image should be square-shaped for optimal results. Non-square inputs may lead to unexpected behavior or distortions. - When applied to bounding boxes or keypoints, their coordinates will be adjusted according to the selected transformation. - This transform preserves the aspect ratio and size of the input.

Apply elastic deformation to images, masks, bounding boxes, and keypoints. This transformation introduces random elastic distortions to the input data. It's particularly useful for data augmentation in training deep learning models, especially for tasks like image segmentation or object detection where you want to maintain the relative positions of features while introducing realistic deformations. The transform works by generating random displacement fields and applying them to the input. These fields are smoothed using a Gaussian filter to create more natural-looking distortions.

Parameters

Example

>>> import albumentations as A
>>> transform = A.Compose([
...     A.ElasticTransform(alpha=1, sigma=50, p=0.5),
... ])
>>> transformed = transform(image=image, mask=mask, bboxes=bboxes, keypoints=keypoints)
>>> transformed_image = transformed['image']
>>> transformed_mask = transformed['mask']
>>> transformed_bboxes = transformed['bboxes']
>>> transformed_keypoints = transformed['keypoints']

Notes

- The transform will maintain consistency across all targets (image, mask, bboxes, keypoints) by using the same displacement fields for all. - The 'approximate' parameter determines whether to use a precise or approximate method for generating displacement fields. The approximate method can be faster but may be less accurate for large sigma values. - Bounding boxes that end up outside the image after transformation will be removed. - Keypoints that end up outside the image after transformation will be removed.

Apply grid distortion to images, masks, bounding boxes, and keypoints. This transformation divides the image into a grid and randomly distorts each cell, creating localized warping effects. It's particularly useful for data augmentation in tasks like medical image analysis, OCR, and other domains where local geometric variations are meaningful.

Parameters

Example

>>> import albumentations as A
>>> transform = A.Compose([
...     A.GridDistortion(num_steps=5, distort_limit=0.3, p=1.0),
... ])
>>> transformed = transform(image=image, mask=mask, bboxes=bboxes, keypoints=keypoints)
>>> transformed_image = transformed['image']
>>> transformed_mask = transformed['mask']
>>> transformed_bboxes = transformed['bboxes']
>>> transformed_keypoints = transformed['keypoints']

Notes

- The same distortion is applied to all targets (image, mask, bboxes, keypoints) to maintain consistency. - When normalized=True, the distortion is adjusted to ensure all pixels remain within the image boundaries.

Apply elastic deformations to images, masks, bounding boxes, and keypoints using a grid-based approach. This transformation overlays a grid on the input and applies random displacements to the grid points, resulting in local elastic distortions. The granularity and intensity of the distortions can be controlled using the dimensions of the overlaying distortion grid and the magnitude parameter.

Parameters

Example

>>> transform = GridElasticDeform(num_grid_xy=(4, 4), magnitude=10, p=1.0)
>>> result = transform(image=image, mask=mask)
>>> transformed_image, transformed_mask = result['image'], result['mask']

Notes

This transformation is particularly useful for data augmentation in medical imaging and other domains where elastic deformations can simulate realistic variations.

Flip the input horizontally around the y-axis.

Parameters

Apply optical distortion to images, masks, bounding boxes, and keypoints. Supports two distortion models: 1. Camera matrix model (original): Uses OpenCV's camera calibration model with k1=k2=k distortion coefficients 2. Fisheye model: Direct radial distortion: r_dist = r * (1 + gamma * r²)

Parameters

Example

>>> import albumentations as A
>>> transform = A.Compose([
...     A.OpticalDistortion(distort_limit=0.1, p=1.0),
... ])
>>> transformed = transform(image=image, mask=mask, bboxes=bboxes, keypoints=keypoints)
>>> transformed_image = transformed['image']
>>> transformed_mask = transformed['mask']
>>> transformed_bboxes = transformed['bboxes']
>>> transformed_keypoints = transformed['keypoints']

Notes

- The distortion is applied using OpenCV's initUndistortRectifyMap and remap functions. - The distortion coefficient (k) is randomly sampled from the distort_limit range. - Bounding boxes and keypoints are transformed along with the image to maintain consistency. - Fisheye model directly applies radial distortion

Pad the sides of an image by specified number of pixels.

Parameters

References

• PyTorch Pad: https://pytorch.org/vision/main/generated/torchvision.transforms.v2.Pad.html

Pads the sides of an image if the image dimensions are less than the specified minimum dimensions. If the `pad_height_divisor` or `pad_width_divisor` is specified, the function additionally ensures that the image dimensions are divisible by these values.

Parameters

Example

>>> import albumentations as A
>>> transform = A.Compose([
...     A.PadIfNeeded(min_height=1024, min_width=1024, border_mode=cv2.BORDER_CONSTANT, fill=0),
... ])
>>> transformed = transform(image=image, mask=mask, bboxes=bboxes, keypoints=keypoints)
>>> padded_image = transformed['image']
>>> padded_mask = transformed['mask']
>>> adjusted_bboxes = transformed['bboxes']
>>> adjusted_keypoints = transformed['keypoints']

Notes

- Either `min_height` or `pad_height_divisor` must be set, but not both. - Either `min_width` or `pad_width_divisor` must be set, but not both. - If `border_mode` is set to `cv2.BORDER_CONSTANT`, `value` must be provided. - The transform will maintain consistency across all targets (image, mask, bboxes, keypoints, volume). - For bounding boxes, the coordinates will be adjusted to account for the padding. - For keypoints, their positions will be shifted according to the padding.

Apply random four point perspective transformation to the input.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.Compose([
...     A.Perspective(scale=(0.05, 0.1), keep_size=True, p=0.5),
... ])
>>> result = transform(image=image)
>>> transformed_image = result['image']

Notes

This transformation creates a perspective effect by randomly moving the four corners of the image. The amount of movement is controlled by the 'scale' parameter. When 'keep_size' is True, the output image will have the same size as the input image, which may cause some parts of the transformed image to be cut off or padded. When 'fit_output' is True, the transformation ensures that the entire transformed image is visible, which may result in a larger output image if keep_size is False.

Apply piecewise affine transformations to the input image. This augmentation places a regular grid of points on an image and randomly moves the neighborhood of these points around via affine transformations. This leads to local distortions in the image.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.Compose([
...     A.PiecewiseAffine(scale=(0.03, 0.05), nb_rows=4, nb_cols=4, p=0.5),
... ])
>>> transformed = transform(image=image)
>>> transformed_image = transformed["image"]

Notes

- This augmentation is very slow. Consider using `ElasticTransform` instead, which is at least 10x faster. - The augmentation may not always produce visible effects, especially with small scale values. - For keypoints and bounding boxes, the transformation might move them outside the image boundaries. In such cases, the keypoints will be set to (-1, -1) and the bounding boxes will be removed.

Randomly shuffles the grid's cells on an image, mask, or keypoints, effectively rearranging patches within the image. This transformation divides the image into a grid and then permutes these grid cells based on a random mapping.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.array([
...     [1, 1, 1, 2, 2, 2],
...     [1, 1, 1, 2, 2, 2],
...     [1, 1, 1, 2, 2, 2],
...     [3, 3, 3, 4, 4, 4],
...     [3, 3, 3, 4, 4, 4],
...     [3, 3, 3, 4, 4, 4]
... ])
>>> transform = A.RandomGridShuffle(grid=(2, 2), p=1.0)
>>> result = transform(image=image)
>>> transformed_image = result['image']
# The resulting image might look like this (one possible outcome):
# [[4, 4, 4, 2, 2, 2],
#  [4, 4, 4, 2, 2, 2],
#  [4, 4, 4, 2, 2, 2],
#  [3, 3, 3, 1, 1, 1],
#  [3, 3, 3, 1, 1, 1],
#  [3, 3, 3, 1, 1, 1]]

Notes

- This transform maintains consistency across all targets. If applied to an image and its corresponding mask or keypoints, the same shuffling will be applied to all. - The number of cells in the grid should be at least 2 (i.e., grid should be at least (1, 2), (2, 1), or (2, 2)) for the transform to have any effect. - Keypoints are moved along with their corresponding grid cell. - This transform could be useful when only micro features are important for the model, and memorizing the global structure could be harmful. For example: - Identifying the type of cell phone used to take a picture based on micro artifacts generated by phone post-processing algorithms, rather than the semantic features of the photo. See more at https://ieeexplore.ieee.org/abstract/document/8622031 - Identifying stress, glucose, hydration levels based on skin images.

Randomly apply affine transforms: translate, scale and rotate the input.

Parameters

Applies one of the eight possible square symmetry transformations to a square-shaped input. This is an alias for D4 transform with a more intuitive name for those not familiar with group theory. The square symmetry transformations include: - Identity: No transformation is applied - 90° rotation: Rotate 90 degrees counterclockwise - 180° rotation: Rotate 180 degrees - 270° rotation: Rotate 270 degrees counterclockwise - Vertical flip: Mirror across vertical axis - Anti-diagonal flip: Mirror across anti-diagonal - Horizontal flip: Mirror across horizontal axis - Main diagonal flip: Mirror across main diagonal

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.Compose([
...     A.SquareSymmetry(p=1.0),
... ])
>>> transformed = transform(image=image)
>>> transformed_image = transformed['image']
# The resulting image will be one of the 8 possible square symmetry transformations of the input

Notes

- This transform is particularly useful for augmenting data that does not have a clear orientation, such as top-view satellite or drone imagery, or certain types of medical images. - The input image should be square-shaped for optimal results. Non-square inputs may lead to unexpected behavior or distortions. - When applied to bounding boxes or keypoints, their coordinates will be adjusted according to the selected transformation. - This transform preserves the aspect ratio and size of the input.

Apply Thin Plate Spline (TPS) transformation to create smooth, non-rigid deformations. Imagine the image printed on a thin metal plate that can be bent and warped smoothly: - Control points act like pins pushing or pulling the plate - The plate resists sharp bending, creating smooth deformations - The transformation maintains continuity (no tears or folds) - Areas between control points are interpolated naturally The transform works by: 1. Creating a regular grid of control points (like pins in the plate) 2. Randomly displacing these points (like pushing/pulling the pins) 3. Computing a smooth interpolation (like the plate bending) 4. Applying the resulting deformation to the image

Parameters

Example

>>> import albumentations as A
>>> # Basic usage
>>> transform = A.ThinPlateSpline()
>>>
>>> # Subtle deformation
>>> transform = A.ThinPlateSpline(
...     scale_range=(0.1, 0.2),
...     num_control_points=3
... )
>>>
>>> # Strong warping with fine control
>>> transform = A.ThinPlateSpline(
...     scale_range=(0.3, 0.5),
...     num_control_points=5,
... )

Notes

- The transformation preserves smoothness and continuity - Stronger scale values may create more extreme deformations - Higher number of control points allows more local deformations - The same deformation is applied consistently to all targets

References

• "Principal Warps: Thin-Plate Splines and the Decomposition of Deformations" by F.L. Bookstein https://doi.org/10.1109/34.24792
• Thin Plate Splines in Computer Vision: https://en.wikipedia.org/wiki/Thin_plate_spline
• Similar implementation in Kornia: https://kornia.readthedocs.io/en/latest/augmentation.html#kornia.augmentation.RandomThinPlateSpline

Transpose the input by swapping its rows and columns. This transform flips the image over its main diagonal, effectively switching its width and height. It's equivalent to a 90-degree rotation followed by a horizontal flip.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.array([
...     [[1, 2, 3], [4, 5, 6]],
...     [[7, 8, 9], [10, 11, 12]]
... ])
>>> transform = A.Transpose(p=1.0)
>>> result = transform(image=image)
>>> transposed_image = result['image']
>>> print(transposed_image)
[[[ 1  2  3]
  [ 7  8  9]]
 [[ 4  5  6]
  [10 11 12]]]
# The original 2x2x3 image is now 2x2x3, with rows and columns swapped

Notes

- The dimensions of the output will be swapped compared to the input. For example, an input image of shape (100, 200, 3) will result in an output of shape (200, 100, 3). - This transform is its own inverse. Applying it twice will return the original input. - For multi-channel images (like RGB), the channels are preserved in their original order. - Bounding boxes will have their coordinates adjusted to match the new image dimensions. - Keypoints will have their x and y coordinates swapped.

Flip the input vertically around the x-axis.

Parameters

Example

>>> import numpy as np
>>> import albumentations as A
>>> image = np.array([
...     [[1, 2, 3], [4, 5, 6]],
...     [[7, 8, 9], [10, 11, 12]]
... ])
>>> transform = A.VerticalFlip(p=1.0)
>>> result = transform(image=image)
>>> flipped_image = result['image']
>>> print(flipped_image)
[[[ 7  8  9]
  [10 11 12]]
 [[ 1  2  3]
  [ 4  5  6]]]
# The original image is flipped vertically, with rows reversed

Notes

- This transform flips the image upside down. The top of the image becomes the bottom and vice versa. - The dimensions of the image remain unchanged. - For multi-channel images (like RGB), each channel is flipped independently. - Bounding boxes are adjusted to match their new positions in the flipped image. - Keypoints are moved to their new positions in the flipped image.