ThinPlateSpline

Targets:

image

mask

bboxes

keypoints

Image Types:uint8, float32

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:

Creating a regular grid of control points (like pins in the plate)
Randomly displacing these points (like pushing/pulling the pins)
Computing a smooth interpolation (like the plate bending)
Applying the resulting deformation to the image

Arguments

scale_range

tuple[float, float]

[0.2,0.4]

Range for random displacement of control points. Values should be in [0.0, 1.0]:

0.0: No displacement (identity transform)
0.1: Subtle warping
0.2-0.4: Moderate deformation (recommended range)
0.5+: Strong warping Default: (0.2, 0.4)

num_control_points

int

Number of control points per side. Creates a grid of num_control_points x num_control_points points.

2: Minimal deformation (affine-like)
3-4: Moderate flexibility (recommended)
5+: More local deformation control Must be >= 2. Default: 4

interpolation

0 | 1 | 2 | 3 | 4

OpenCV interpolation flag. Used for image sampling. See also: cv2.INTER_* Default: cv2.INTER_LINEAR

mask_interpolation

0 | 1 | 2 | 3 | 4

OpenCV interpolation flag. Used for mask sampling. See also: cv2.INTER_* 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 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

See Also

ElasticTransform: For different type of non-rigid deformation
GridDistortion: For grid-based warping
OpticalDistortion: For lens-like distortions

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

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