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_range, 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_range

tuple[float, float]

[-0.05,0.05]

Range of distortion coefficient, sampled per image. 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 sampling the displacement map resolution relative to the target size. Values below 1.0 generate lower-resolution maps and upscale them, trading precision for speed. 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_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

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