albumentations.augmentations.geometric.distortion

Apply bounded XY deformations from a compact control grid to images and annotations. Use it for shape variation in segmentation and medical imaging. `displacement_range` is measured relative to the shorter span between the first and last pixel centers. The sampled cubic B-spline coefficients use pixel units after scaling. One map is shared by every raster and annotation target in an invocation; volumes receive the same XY deformation on every depth slice.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.zeros((100, 100, 3), dtype=np.uint8)
>>> mask = np.zeros((100, 100), dtype=np.uint8)
>>> bboxes = np.array([[10, 10, 50, 50]], dtype=np.float32)
>>> bbox_labels = [1]
>>> keypoints = np.array([[20, 30]], dtype=np.float32)
>>> keypoint_labels = [0]
>>> transform = A.Compose(
...     [A.ElasticTransform(displacement_range=(0.02, 0.05), control_grid_shape=(7, 7), p=1.0)],
...     bbox_params=A.BboxParams(coord_format="pascal_voc", label_fields=["bbox_labels"]),
...     keypoint_params=A.KeypointParams(
...         coord_format="xy", label_fields=["keypoint_labels"], label_mapping={}
...     ),
... )
>>> transformed = transform(
...     image=image,
...     mask=mask,
...     bboxes=bboxes,
...     bbox_labels=bbox_labels,
...     keypoints=keypoints,
...     keypoint_labels=keypoint_labels,
... )
>>> transformed_image = transformed["image"]
>>> transformed_mask = transformed["mask"]
>>> transformed_bboxes = transformed["bboxes"]
>>> transformed_bbox_labels = transformed["bbox_labels"]
>>> transformed_keypoints = transformed["keypoints"]
>>> transformed_keypoint_labels = transformed["keypoint_labels"]

Notes

The constructor enforces `2 * high * sqrt((rows - 3)^2 + (columns - 3)^2) < 0.75`. `ReplayCompose` stores the compact sampled coefficient lattice and replays it for the same spatial shape. Applied configuration fixes the realized magnitude but samples a new lattice.

Apply grid distortion by dividing the image into cells and warping each. Params: num_steps, distort_range, interpolation, normalized. 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

Examples

>>> import albumentations as A
>>> transform = A.Compose([
...     A.GridDistortion(num_steps=5, distort_range=(-0.3, 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 optical distortion (lens/camera or fisheye model) to images, masks, bboxes, keypoints. Params: distort_range, mode (camera/fisheye), interpolation. 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

Examples

>>> import albumentations as A
>>> transform = A.Compose([
...     A.OpticalDistortion(distort_range=(-0.1, 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_range range. - Bounding boxes and keypoints are transformed along with the image to maintain consistency. - Fisheye model directly applies radial distortion

Apply piecewise affine transformations via a regular grid of control points. Params: scale_range, nb_rows_range, nb_cols_range, interpolation. 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

Examples

>>> 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_range=(0.03, 0.05), nb_rows_range=(4, 4), nb_cols_range=(4, 4), p=0.5),
... ])
>>> transformed = transform(image=image)
>>> transformed_image = transformed["image"]

Notes

- 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.

Stochastically displaces each pixel by sampling its value from a random source within a local square neighborhood, without blurring or coherent warping. For every output pixel `(row, col)` an offset `(d_row, d_col)` is drawn independently and uniformly from the square neighborhood `[-radius, radius] x [-radius, radius]` and the pixel value is read from source position `(row + d_row, col + d_col)`. The same dense remapping field is applied to all targets (image, mask, bboxes, keypoints) so spatial annotations remain consistent. This occupies a useful middle ground between blur (which aggregates a neighborhood) and smooth elastic warps (which produce coherent displacement fields): the displacement field is intentionally non-smooth and high-frequency, making it suitable for simulating sensor noise, compression artifacts, fine-grained texture corruption, and domain shifts where local pixel structure becomes unstable but global object geometry is preserved.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8)
>>> bboxes = np.array([[10, 10, 50, 50]], dtype=np.float32)
>>> bbox_labels = [1]
>>> keypoints = np.array([[20, 30]], dtype=np.float32)
>>> keypoint_labels = [0]
>>>
>>> transform = A.Compose([
...     A.PixelSpread(radius=3, p=1.0)
... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']),
...    keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels']))
>>>
>>> result = transform(
...     image=image,
...     mask=mask,
...     bboxes=bboxes,
...     bbox_labels=bbox_labels,
...     keypoints=keypoints,
...     keypoint_labels=keypoint_labels,
... )
>>> transformed_image = result['image']
>>> transformed_mask = result['mask']

Apply Thin Plate Spline (TPS) for smooth, non-rigid deformations. Control points warp the image like pins on a thin plate; smooth interpolation between points. 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

Examples

>>> import numpy as np
>>> import albumentations as A
>>> import cv2
>>>
>>> # Create sample data
>>> image = np.zeros((100, 100, 3), dtype=np.uint8)
>>> mask = np.zeros((100, 100), dtype=np.uint8)
>>> mask[25:75, 25:75] = 1  # Square mask
>>> bboxes = np.array([[10, 10, 40, 40]])  # Single box
>>> bbox_labels = [1]
>>> keypoints = np.array([[50, 50]])  # Single keypoint at center
>>> keypoint_labels = [0]
>>>
>>> # Set up transform with Compose to handle all targets
>>> transform = A.Compose([
...     A.ThinPlateSpline(scale_range=(0.2, 0.4), p=1.0)
... ], bbox_params=A.BboxParams(coord_format='pascal_voc', label_fields=['bbox_labels']),
...    keypoint_params=A.KeypointParams(coord_format='xy', label_fields=['keypoint_labels']))
>>>
>>> # Apply to all targets
>>> result = transform(
...     image=image,
...     mask=mask,
...     bboxes=bboxes,
...     bbox_labels=bbox_labels,
...     keypoints=keypoints,
...     keypoint_labels=keypoint_labels
... )
>>>
>>> # Access transformed results
>>> transformed_image = result['image']
>>> transformed_mask = result['mask']
>>> transformed_bboxes = result['bboxes']
>>> transformed_bbox_labels = result['bbox_labels']
>>> transformed_keypoints = result['keypoints']
>>> transformed_keypoint_labels = result['keypoint_labels']

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

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

Simulate looking through water or wavy glass via sine-wave displacement maps. Params: amplitude_range, wavelength_range, num_waves_range, interpolation. Generates displacement maps from overlaid sine waves at random frequencies, phases, and angles to create a refraction distortion effect.

Parameters

Examples

>>> import numpy as np
>>> import albumentations as A
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.WaterRefraction(amplitude_range=(0.02, 0.04), p=1.0)
>>> result = transform(image=image)["image"]

Notes

This is a geometric (DualTransform) because the displacement warps the image geometry - masks, bboxes, and keypoints are transformed accordingly.