OpticalDistortion

Targets:

image

mask

bboxes

keypoints

Image Types:uint8, float32

Apply optical distortion (lens/camera or fisheye model) to images, masks, bboxes, keypoints. Params: distort_limit, mode (camera/fisheye), interpolation.

Supports two distortion models:

Camera matrix model (original): Uses OpenCV's camera calibration model with k1=k2=k distortion coefficients
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

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

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

>>> 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']