• AlbumentationsAlbumentations
All TransformsGet LicenseDocumentationNews & Insights
Report IssueJoin Discord...

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:

  1. Creating a regular grid of control points (like pins in the plate)
  2. Randomly displacing these points (like pushing/pulling the pins)
  3. Computing a smooth interpolation (like the plate bending)
  4. 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
4

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
1

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

mask_interpolation
0 | 1 | 2 | 3 | 4
0

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