...

GridDistortion

Targets:
image
mask
bboxes
keypoints
volume
mask3d
Image Types:uint8, float32

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.

Arguments
num_steps
int
5

Number of grid cells on each side of the image. Higher values create more granular distortions. Must be at least 1. Default: 5.

distort_limit
tuple[float, float] | float
[-0.3,0.3]

Range of distortion. If a single float is provided, the range will be (-distort_limit, distort_limit). Higher values create stronger distortions. Should be in the range of -1 to 1. Default: (-0.3, 0.3).

interpolation
0 | 1 | 2 | 3 | 4
1

OpenCV interpolation method used for image transformation. Options include cv2.INTER_LINEAR, cv2.INTER_CUBIC, etc. Default: cv2.INTER_LINEAR.

normalized
bool
true

If True, ensures that the distortion does not move pixels outside the image boundaries. This can result in less extreme distortions but guarantees that no information is lost. Default: True.

mask_interpolation
0 | 1 | 2 | 3 | 4
0

Flag that is used to specify the interpolation algorithm for mask. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_NEAREST.

keypoint_remapping_method
direct | mask
mask

Method to use for keypoint remapping.

  • "mask": Uses mask-based remapping. Faster, especially for many keypoints, but may be less accurate for large distortions. Recommended for large images or many keypoints.
  • "direct": Uses inverse mapping. More accurate for large distortions but slower. Default: "mask"
map_resolution_range
tuple[float, float]
[1,1]

Range for downsampling the distortion map before applying it. Values should be in (0, 1] where 1.0 means full resolution. Lower values generate smaller distortion maps which are faster to compute but may result in less precise distortions. The actual resolution is sampled uniformly from this range. Default: (1.0, 1.0).

p
float
0.5

Probability of applying the transform. Default: 0.5.

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