...

PiecewiseAffine

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

Apply piecewise affine transformations to the input image.

This augmentation places a regular grid of points on an image and randomly moves the neighborhood of these points around via affine transformations. This leads to local distortions in the image.

Arguments
scale
tuple[float, float] | float
[0.03,0.05]

Standard deviation of the normal distributions. These are used to sample the random distances of the subimage's corners from the full image's corners. If scale is a single float value, the range will be (0, scale). Recommended values are in the range (0.01, 0.05) for small distortions, and (0.05, 0.1) for larger distortions. Default: (0.03, 0.05).

nb_rows
tuple[int, int] | int
[4,4]

Number of rows of points that the regular grid should have. Must be at least 2. For large images, you might want to pick a higher value than 4. If a single int, then that value will always be used as the number of rows. If a tuple (a, b), then a value from the discrete interval [a..b] will be uniformly sampled per image. Default: 4.

nb_cols
tuple[int, int] | int
[4,4]

Number of columns of points that the regular grid should have. Must be at least 2. For large images, you might want to pick a higher value than 4. If a single int, then that value will always be used as the number of columns. If a tuple (a, b), then a value from the discrete interval [a..b] will be uniformly sampled per image. Default: 4.

interpolation
0 | 1 | 2 | 3 | 4
1

Flag that is used to specify the interpolation algorithm. 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.

absolute_scale
bool
false

If set to True, the value of the scale parameter will be treated as an absolute pixel value. If set to False, it will be treated as a fraction of the image height and width. Default: False.

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
>>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
>>> transform = A.Compose([
...     A.PiecewiseAffine(scale=(0.03, 0.05), nb_rows=4, nb_cols=4, p=0.5),
... ])
>>> transformed = transform(image=image)
>>> transformed_image = transformed["image"]
Notes
  • This augmentation is very slow. Consider using ElasticTransform instead, which is at least 10x faster.
  • The augmentation may not always produce visible effects, especially with small scale values.
  • For keypoints and bounding boxes, the transformation might move them outside the image boundaries. In such cases, the keypoints will be set to (-1, -1) and the bounding boxes will be removed.