...

OpticalDistortion

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

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²)

Arguments
distort_limit
tuple[float, float] | float
[-0.05,0.05]

Range of distortion coefficient. For camera model: recommended range (-0.05, 0.05) For fisheye model: recommended range (-0.3, 0.3) Default: (-0.05, 0.05)

mode
camera | fisheye
camera

Distortion model to use:

  • 'camera': Original camera matrix model
  • 'fisheye': Fisheye lens model Default: 'camera'
interpolation
0 | 1 | 2 | 3 | 4
1

Interpolation method used for image transformation. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_LINEAR.

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