2D geometric transforms#

Spatial transformations and erasing operations. Matrix, inverse and annotation support depend on the class and configuration. Slice-mode crops reject inversion; non-rigid transforms do not carry boxes or keypoints along with the image (#4420). RandomErasing changes image and mask values without moving coordinates. See AugmentationSequential for the supported data-key paths and their limitations.

class kornia.augmentation.CenterCrop(size, align_corners=True, resample=Resample.BILINEAR.name, p=1.0, keepdim=False, cropping_mode='slice')[source]#

Crop a given image torch.Tensor at the center.

_images/CenterCrop.png

Parameters:

size (Union[int, Tuple[int, int]]) – Desired output size (out_h, out_w) of the crop. If integer, out_h = out_w = size. If Tuple[int, int], out_h = size[0], out_w = size[1].
align_corners (bool, optional) – interpolation flag. Default: True
resample (Union[str, int, Resample], optional) – The interpolation mode. Default: Resample.BILINEAR.name
p (float, optional) – probability of applying the transformation for the whole batch. Default: 1.0
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False
cropping_mode (str, optional) – The used algorithm to crop. slice will use advanced slicing to extract the torch.Tensor based on the sampled indices. resample will use warp_affine using the affine transformation to extract and resize at once. Use slice for efficiency, or resample for proper differentiability. Default: "slice"

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, out_h, out_w)\)

Note

This function internally uses kornia.geometry.transform.crop_by_boxes().

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse. size accepts an integer for a square crop or an (height, width) tuple, unlike RandomCrop and RandomResizedCrop (#4417).

cropping_mode="slice" indexes the input and returns a copy, so writing to the result leaves the input unchanged. cropping_mode="resample" warps with the configured resample and align_corners. Only resample mode supports inverse(), which resamples onto the original canvas (zero padding unless the call passes padding_mode) and cannot restore discarded data.

Examples

>>> import torch
>>> rng = torch.manual_seed(0)
>>> inputs = torch.randn(1, 1, 4, 4)
>>> inputs
tensor([[[[-1.1258, -1.1524, -0.2506, -0.4339],
          [ 0.8487,  0.6920, -0.3160, -2.1152],
          [ 0.3223, -1.2633,  0.3500,  0.3081],
          [ 0.1198,  1.2377,  1.1168, -0.2473]]]])
>>> aug = CenterCrop(2, p=1., cropping_mode="resample")
>>> out = aug(inputs)
>>> out
tensor([[[[ 0.6920, -0.3160],
          [-1.2633,  0.3500]]]])
>>> aug.inverse(out, padding_mode="border")
tensor([[[[ 0.6920,  0.6920, -0.3160, -0.3160],
          [ 0.6920,  0.6920, -0.3160, -0.3160],
          [-1.2633, -1.2633,  0.3500,  0.3500],
          [-1.2633, -1.2633,  0.3500,  0.3500]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = CenterCrop(2, p=1., cropping_mode="resample")
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.PadTo(size, pad_mode='constant', pad_value=0, keepdim=False)[source]#

Pad the given sample to a specific size. Always occurs (p=1.0).

_images/PadTo.png

Parameters:

size (Tuple[int, int]) – a tuple of ints in the format (height, width) that give the spatial dimensions to pad inputs to.
pad_mode (str, optional) – the type of padding to perform on the image (valid values are those accepted by torch.nn.functional.pad) Default: "constant"
pad_value (float, optional) – fill value for ‘constant’ padding applied to the image Default: 0
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Note

This function internally uses torch.nn.functional.pad().

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse. This operation always runs and pads on the right and bottom, using pad_mode and pad_value. A target smaller than the input crops that axis instead, so a target can pad one axis while cropping the other (#4410).

inverse() slices to the prior input size. It exactly removes right/bottom padding, but after a crop it returns the cropped result unchanged rather than restoring discarded pixels. The transformation matrix is identity, so keypoints and boxes are neither moved nor clipped when cropping puts them outside the canvas.

Examples

>>> import torch
>>> img = torch.tensor([[[[0., 0., 0.],
...                       [0., 0., 0.],
...                       [0., 0., 0.]]]])
>>> pad = PadTo((4, 5), pad_value=1.)
>>> out = pad(img)
>>> out
tensor([[[[0., 0., 0., 1., 1.],
          [0., 0., 0., 1., 1.],
          [0., 0., 0., 1., 1.],
          [1., 1., 1., 1., 1.]]]])
>>> pad.inverse(out)
tensor([[[[0., 0., 0.],
          [0., 0., 0.],
          [0., 0., 0.]]]])

class kornia.augmentation.RandomAffine(degrees, translate=None, scale=None, shear=None, resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=False, padding_mode=SamplePadding.ZEROS.name, fill_value=None, p=0.5, keepdim=False)[source]#

Apply a random 2D affine transformation to a torch.Tensor image.

_images/RandomAffine.png

The transformation is computed so that the image center is kept invariant.

Parameters:

degrees (Union[Tensor, float, Tuple[float, float]]) – Range of degrees to select from. If degrees is a number instead of sequence like (min, max), the range of degrees will be (-degrees, +degrees). Set to 0 to deactivate rotations.
translate (Union[Tensor, Tuple[float, float], None], optional) – tuple of maximum absolute fraction for horizontal and vertical translations. For example translate=(a, b), then horizontal shift is randomly sampled in the range -img_width * a < dx < img_width * a and vertical shift is randomly sampled in the range -img_height * b < dy < img_height * b. Will not translate by default. Default: None
scale (Union[Tensor, Tuple[float, float], Tuple[float, float, float, float], None], optional) – scaling factor interval. If (a, b) represents isotropic scaling, the scale is randomly sampled from the range a <= scale <= b. If (a, b, c, d), the scale is randomly sampled from the range a <= scale_x <= b, c <= scale_y <= d. Will keep original scale by default. Default: None
shear (Union[Tensor, float, Tuple[float, float], None], optional) – Range of degrees to select from. If float, a shear parallel to the x axis in the range (-shear, +shear) will be applied. If (a, b), a shear parallel to the x axis in the range (-shear, +shear) will be applied. If (a, b, c, d), then x-axis shear in (shear[0], shear[1]) and y-axis shear in (shear[2], shear[3]) will be applied. Will not apply shear by default. Default: None
resample (Union[str, int, Resample], optional) – resample mode from “nearest” (0) or “bilinear” (1). Default: Resample.BILINEAR.name
padding_mode (Union[str, int, SamplePadding], optional) – padding mode from “torch.zeros” (0), “border” (1), “reflection” (2) or “fill” (3). Default: SamplePadding.ZEROS.name
fill_value (Union[float, int, Tensor, None], optional) – the value to be filled in the padding area when padding_mode=”fill”. Can be a float, int, or a torch.Tensor of shape (C) or (1). Default: None
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
align_corners (bool, optional) – interpolation flag. Default: False
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse.
translate=(a, b) samples pixel offsets from [-a W, a W] and [-b H, b H]; positive offsets move content right and down.
a positive degrees rotates the displayed image clockwise, unlike RandomRotation (Conventions & Pitfalls, #4408).
shear draws degrees, converted to radians and applied about the image centre with the sign and the x-then-y order of get_shear_matrix2d(), as Affine applies its shear.

Note

This function internally uses kornia.geometry.transform.warp_affine().

Examples

>>> import torch
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 3, 3)
>>> aug = RandomAffine((-15., 20.), p=1.)
>>> out = aug(input)
>>> out, aug.transform_matrix
(tensor([[[[0.3961, 0.7310, 0.1574],
          [0.1781, 0.3074, 0.5648],
          [0.4804, 0.8379, 0.4234]]]]), tensor([[[ 0.9923, -0.1241,  0.1319],
         [ 0.1241,  0.9923, -0.1164],
         [ 0.0000,  0.0000,  1.0000]]]))
>>> aug.inverse(out)
tensor([[[[0.3890, 0.6573, 0.1865],
          [0.2063, 0.3074, 0.5459],
          [0.3892, 0.7896, 0.4224]]]])
>>> input
tensor([[[[0.4963, 0.7682, 0.0885],
          [0.1320, 0.3074, 0.6341],
          [0.4901, 0.8964, 0.4556]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomAffine((-15., 20.), p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomCrop(size, padding=None, pad_if_needed=False, fill=0, padding_mode='constant', resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=True, p=1.0, keepdim=False, cropping_mode='slice')[source]#

Crop random patches of a torch.Tensor image on a given size.

_images/RandomCrop.png

Parameters:

size (Tuple[int, int]) – Desired output size (out_h, out_w) of the crop. Must be Tuple[int, int], then out_h = size[0], out_w = size[1].
padding (Union[int, Tuple[int, int], Tuple[int, int, int, int], None], optional) – Optional padding on each border of the image. Default is None, i.e no padding. If a sequence of length 4 is provided, it is used to F.pad left, top, right, bottom borders respectively. If a sequence of length 2 is provided, it is used to F.pad left/right, top/bottom borders, respectively. Default: None
pad_if_needed (Optional[bool], optional) – It will F.pad the image if smaller than the desired size to avoid raising an exception. Since cropping is done after padding, the padding seems to be done at a random offset. Default: False
fill (Union[float, Sequence[float]], optional) – Pixel fill value for constant fill. Default is 0. A sequence gives one value per channel, so it must be as long as the input’s channel dimension. This value is only used when the padding_mode is constant, and a sequence requires it. Default: 0
padding_mode (str, optional) – Type of padding. Should be: constant, reflect, replicate. Default: "constant"
resample (Union[str, int, Resample], optional) – the interpolation mode. Default: Resample.BILINEAR.name
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
align_corners (bool, optional) – interpolation flag. Default: True
p (float, optional) – probability of applying the transformation for the whole batch. Default: 1.0
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False
cropping_mode (str, optional) – The used algorithm to crop. slice will use advanced slicing to extract the torch.Tensor based on the sampled indices. resample will use warp_affine using the affine transformation to extract and resize at once. Use slice for efficiency, or resample for proper differentiability. Default: "slice"

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, out_h, out_w)\)

Note

Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support. Additionally, this function accepts another transformation torch.Tensor (\((B, 3, 3)\)), then the applied transformation will be merged int to the input transformation torch.Tensor and returned.

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse. size is an (height, width) tuple; a bare integer raises, unlike CenterCrop (#4417). p selects or skips the whole batch together; a skipped batch is returned unchanged and unpadded. transform_matrix maps original input coordinates to the crop, including the translation from padding or pad_if_needed.

Explicit padding is applied before sampling, in (left, top, right, bottom) order after its scalar or two-value shorthand is expanded. pad_if_needed=True pads each side by the maximum of that padding and the crop-minus-input size on its axis, so asymmetric explicit padding can stay asymmetric. In AugmentationSequential, a per-channel fill pads only the image and the mask is padded with zero unless extra_args[DataKey.MASK] sets its fill; a scalar fill applies to both.

With pad_if_needed=False, an oversized request does not raise: slice mode resizes the available slice, and resample mode uses a mis-scaled warp that rescales both matrix axes and can blend in zero padding (#4414). Slice mode scales only the matrix axes along which the request exceeds the canvas, as its resize does, and on the resize’s half-pixel grid: x' = (x + 0.5) * W_out / W_in - 0.5 along a stretched axis (likewise for y). The scale is computed against the padded canvas, so a crop that fits after explicit padding gets no scale correction.

Slice mode uses crop_by_indices() with its own defaults and ignores this class’s resample and align_corners. Resample mode uses the configured interpolation and align_corners and maps constant, replicate and reflect pre-padding to zero, border and reflection sampler padding. Only resample mode supports inverse(), which removes the pre-crop padding but cannot restore cropped or interpolated content. For an empty batch, forward_input_shape records the original, unpadded canvas for inverse replay.

Note

Compiled slice-mode interpolation matches eager execution to floating-point tolerance, not bitwise. Eager execution retains native slicing and resizing for performance; the tensorized compiled path avoids recompilation as crop coordinates change.

Examples

>>> import torch
>>> _ = torch.manual_seed(0)
>>> inputs = torch.arange(1*1*3*3.).view(1, 1, 3, 3)
>>> aug = RandomCrop((2, 2), p=1., cropping_mode="resample")
>>> out = aug(inputs)
>>> out
tensor([[[[3., 4.],
          [6., 7.]]]])
>>> aug.inverse(out, padding_mode="replicate")
tensor([[[[3., 4., 4.],
          [3., 4., 4.],
          [6., 7., 7.]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomCrop((2, 2), p=1., cropping_mode="resample")
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomElasticTransform(kernel_size=(63, 63), sigma=(32.0, 32.0), alpha=(1.0, 1.0), align_corners=False, resample=Resample.BILINEAR.name, padding_mode='zeros', same_on_batch=False, p=0.5, keepdim=False)[source]#

Add random elastic transformation to a torch.Tensor image.

_images/RandomElasticTransform.png

Convention:: This is a dense backward sampling field with no transform_matrix or inverse; spatial labels in containers have limitations (#4420). Noise has shape (B, 2, H, W) with channels (x, y); alpha scales displacement in normalized sampling coordinates, whereas kernel_size and sigma use (y, x) order. The displaced grid is clamped to [-1, 1] before sampling. Zero alpha is an identity warp up to interpolation roundoff for either align_corners. Its defaults and the align_corners split across classes (#4412) are listed on GeometricAugmentationBase2D.

Parameters:

kernel_size (Tuple[int, int], optional) – the size of the Gaussian kernel, in the y and x directions, respectively. Default: (63, 63)
sigma (Tuple[float, float], optional) – The standard deviation of the Gaussian in the y and x directions, respectively. Larger sigma results in smaller pixel displacements. Default: (32.0, 32.0)
alpha (Tuple[float, float], optional) – The scaling factor that controls the intensity of the deformation in the x and y directions, respectively – the opposite order to kernel_size and sigma. Default: (1.0, 1.0)
align_corners (bool, optional) – Interpolation flag used by grid_sample. Default: False
resample (Union[str, int, Resample], optional) – Interpolation mode used by grid_sample. Either ‘nearest’ (0) or ‘bilinear’ (1). Default: Resample.BILINEAR.name
padding_mode (str, optional) – The padding used by grid_sample. Either ‘zeros’, ‘border’ or ‘reflection’. Default: "zeros"
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Note

This function internally uses kornia.geometry.transform.elastic_transform2d().

Examples

>>> import torch
>>> img = torch.ones(1, 1, 2, 2)
>>> out = RandomElasticTransform()(img)
>>> out.shape
torch.Size([1, 1, 2, 2])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomElasticTransform(p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomErasing(scale=(0.02, 0.33), ratio=(0.3, 3.3), value=0.0, same_on_batch=False, p=0.5, keepdim=False)[source]#

Erase a random rectangle of a torch.Tensor image according to a probability p value.

_images/RandomErasing.png

See the Convention block on IntensityAugmentationBase2D.

The operator removes image parts and fills them with value at a selected rectangle for each of the images in the batch.

The rectangle targets an area equal to the original image area multiplied by a value sampled from scale, with an aspect ratio sampled from ratio.

Parameters:

scale (Union[Tensor, Tuple[float, float]], optional) – range of proportion of erased area against input image. Default: (0.02, 0.33)
ratio (Union[Tensor, Tuple[float, float]], optional) – range of aspect ratio of erased area. Default: (0.3, 3.3)
value (float, optional) – the value to fill the erased area. Default: 0.0
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
p (float, optional) – probability that the random erasing operation will be performed. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Convention:

scale is the fraction of the image area the rectangle targets and ratio is its height over its width, so a ratio above 1 targets a tall box and below 1 a wide one. The box is rounded to whole pixels and then clamped to [1, H] x [1, W], so it is never empty and never larger than the image, and the erased area can miss the target in either direction: scale=(0.25, 0.25) with ratio=(3.0, 3.0) on a 10 x 20 image erases 10 x 4 = 40 pixels of the 50 asked for, while scale=(0.0, 0.0) still erases one pixel.
when ratio straddles 1 the draw is not uniform over the interval: a fair coin picks between [ratio[0], 1] and [1, ratio[1]], so at the default ratio=(0.3, 3.3) half the draws are above 1.
the erased region is the half-open rectangle [ys, ys + h) x [xs, xs + w) in pixels, recorded as _params["ys"], ["xs"], ["heights"] and ["widths"].
the erased pixels carry the literal value, which has to lie in [0, 1] – the parameter generator rejects anything else at construction. Every other pixel is carried through unclamped, so every pixel outside the box keeps the input’s range.
inside AugmentationSequential a mask data key is erased in the same rectangle, but the mask is filled with 0 whatever value is.

Note

This function accepts another transformation torch.Tensor (\((B, 3, 3)\)), then the applied transformation will be merged int to the input transformation torch.Tensor and returned.

Examples

>>> rng = torch.manual_seed(0)
>>> inputs = torch.ones(1, 1, 3, 3)
>>> aug = RandomErasing((.4, .8), (.3, 1/.3), p=0.5)
>>> aug(inputs)
tensor([[[[1., 0., 0.],
          [1., 0., 0.],
          [1., 0., 0.]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomErasing((.4, .8), (.3, 1/.3), p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomFisheye(center_x, center_y, gamma, same_on_batch=False, p=0.5, keepdim=False)[source]#

Add random camera radial distortion.

_images/RandomFisheye.png

Convention:: Coordinates are normalized to [-1, 1] with corner pixel centres at the endpoints. At output coordinate (x, y), let r be its distance from the sampled centre. The input sampling coordinate is (x * (1 + r**gamma), y * (1 + r**gamma)): the centre changes the distance, but scaling is about the coordinate origin. Sampling is bilinear with zero padding and align_corners=True; these settings are fixed. There is no transform_matrix or inverse; spatial labels in containers have limitations (#4420).

Parameters:

center_x (Tensor) – Ranges to sample respect to x-coordinate center with shape (2,).
center_y (Tensor) – Ranges to sample respect to y-coordinate center with shape (2,).
gamma (Tensor) – Ranges to sample for the gamma values respect to optical center with shape (2,).
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Examples

>>> import torch
>>> img = torch.ones(1, 1, 2, 2)
>>> center_x = torch.tensor([-.3, .3])
>>> center_y = torch.tensor([-.3, .3])
>>> gamma = torch.tensor([.9, 1.])
>>> out = RandomFisheye(center_x, center_y, gamma)(img)
>>> out.shape
torch.Size([1, 1, 2, 2])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomFisheye(center_x, center_y, gamma, p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomHorizontalFlip(p=0.5, p_batch=1.0, same_on_batch=False, keepdim=False)[source]#

Apply a random horizontal flip to a torch.Tensor image or a batch of torch.Tensor images.

The flip is applied with a given probability.

_images/RandomHorizontalFlip.png

Input should be a torch.Tensor of shape (C, H, W) or a batch of tensors \((B, C, H, W)\). If Input is a tuple it is assumed that the first element contains the aforementioned tensors and the second, the corresponding transformation matrix that has been applied to them. In this case the module will Horizontally flip the tensors and torch.cat the corresponding transformation matrix to the previous one. This is especially useful when using this functionality as part of an nn.Sequential module.

Parameters:

p (float, optional) – probability of the image being flipped. Default: 0.5
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Convention:

A selected flip maps (x, y) to (W - 1 - x, y) with the exact discrete hflip(), without resampling; see GeometricAugmentationBase2D for the shared contract.

Note

This function internally uses kornia.geometry.transform.hflip().

Examples

>>> import torch
>>> input = torch.tensor([[[[0., 0., 0.],
...                         [0., 0., 0.],
...                         [0., 1., 1.]]]])
>>> seq = RandomHorizontalFlip(p=1.0)
>>> seq(input), seq.transform_matrix
(tensor([[[[0., 0., 0.],
          [0., 0., 0.],
          [1., 1., 0.]]]]), tensor([[[-1.,  0.,  2.],
         [ 0.,  1.,  0.],
         [ 0.,  0.,  1.]]]))
>>> seq.inverse(seq(input)).equal(input)
True

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> seq = RandomHorizontalFlip(p=1.0)
>>> (seq(input) == seq(input, params=seq._params)).all()
tensor(True)

class kornia.augmentation.RandomPerspective(distortion_scale=0.5, resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=False, p=0.5, keepdim=False, sampling_method='basic')[source]#

Apply a random perspective transformation to an image torch.Tensor with a given probability.

_images/RandomPerspective.png

Parameters:

distortion_scale (Union[Tensor, float], optional) – the degree of distortion, ranged from 0 to 1. Default: 0.5
resample (Union[str, int, Resample], optional) – the interpolation method to use. Default: Resample.BILINEAR.name
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False.
align_corners (bool, optional) – interpolation flag. Default: False
p (float, optional) – probability of the image being perspectively transformed. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False
sampling_method (str, optional) – 'basic' | 'area_preserving'. Default: 'basic' If 'basic', samples by translating the image corners randomly inwards. If 'area_preserving', samples by randomly translating the image corners in any direction. Preserves area on average. See https://arxiv.org/abs/2104.03308 for further details.

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse. The source corners are (0, 0), (W - 1, 0), (W - 1, H - 1) and (0, H - 1); transform_matrix maps them to the sampled destination corners.
basic samples each corner inward by at most distortion_scale * (W, H) / 2. area_preserving samples each coordinate in both directions over the same extent.
with distortion_scale=0 and H > 1, W > 1, the warp is an identity up to numerical precision for either align_corners.
a spatial dimension of 1 is not distorted: its source corners span a unit extent instead of 0 and its offsets are zero, so the single row or column maps onto itself and only the other axis is warped. At distortion_scale=0 this is the identity.

Note

This function internally uses kornia.geometry.transform.warp_perspective().

Examples

>>> rng = torch.manual_seed(0)
>>> inputs= torch.tensor([[[[1., 0., 0.],
...                         [0., 1., 0.],
...                         [0., 0., 1.]]]])
>>> aug = RandomPerspective(0.5, p=0.5)
>>> out = aug(inputs)
>>> out
tensor([[[[0.2795, 0.3852, 0.0000],
          [0.0000, 0.6243, 0.0000],
          [0.0000, 0.0000, 0.0000]]]])
>>> aug.inverse(out)
tensor([[[[0.3417, 0.3022, 0.0436],
          [0.3767, 0.4769, 0.1879],
          [0.1434, 0.1958, 0.1091]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomPerspective(0.5, p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomResizedCrop(size, scale=(0.08, 1.0), ratio=(3.0 / 4.0, 4.0 / 3.0), resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=True, p=1.0, keepdim=False, cropping_mode='slice')[source]#

Crop random patches in an image torch.Tensor and resizes to a given size.

_images/RandomResizedCrop.png

Parameters:

size (Tuple[int, int]) – Desired output size (out_h, out_w) of each edge. Must be Tuple[int, int], then out_h = size[0], out_w = size[1].
scale (Union[Tensor, Tuple[float, float]], optional) – range of size of the origin size cropped. Default: (0.08, 1.0)
ratio (Union[Tensor, Tuple[float, float]], optional) – range of aspect ratio of the origin aspect ratio cropped. Default: (3.0 / 4.0, 4.0 / 3.0)
resample (Union[str, int, Resample], optional) – the interpolation mode. Default: Resample.BILINEAR.name
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
align_corners (bool, optional) – interpolation flag. Default: True
p (float, optional) – probability of the augmentation been applied. Default: 1.0
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False
cropping_mode (str, optional) – The used algorithm to crop. slice will use advanced slicing to extract the torch.Tensor based on the sampled indices. resample will use warp_affine using the affine transformation to extract and resize at once. Use slice for efficiency, or resample for proper differentiability. Default: "slice"

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, out_h, out_w)\)

Note

Input torch.Tensor must be float and normalized into [0, 1] for the best differentiability support. Additionally, this function accepts another transformation torch.Tensor (\((B, 3, 3)\)), then the applied transformation will be merged int to the input transformation torch.Tensor and returned.

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse. size is an (height, width) tuple; a bare integer raises, unlike CenterCrop (#4417). p selects or skips the whole batch together. Within a selected batch, the generator tries ten candidate crops per image, sampling area fractions from scale and width/height ratios from ratio (shared with same_on_batch=True), and resizes the first that fits to the requested output size. As in torchvision’s get_params, a candidate may equal the input, and when none fits the fallback keeps an input whose width/height is within ratio whole, or else its full width (input narrower than min(ratio)) or its full height (wider than max(ratio)). So scale=(1.0, 1.0) keeps an input within ratio whole, except that a candidate rounded a pixel or two short on the longer side also fits (8x6 gives 7x6 in about 18% of draws, as in torchvision). Unlike torchvision, which centres the fallback crop, it is placed at a random position like any other crop.

Both cropping modes use the configured interpolation and align_corners. Slice mode ignores align_corners for resample="nearest". With bilinear or bicubic interpolation, each mode’s image follows its transform_matrix, and at align_corners=False the two modes give different images: slice mode resizes the crop on the half-pixel grid, x' = (x - x0 + 0.5) * W_out / W_crop - 0.5 for a crop starting at column x0 (likewise for y), while resample mode maps the crop’s corner pixel centres onto the output’s. Nearest sampling in slice mode uses the half-pixel grid and PyTorch’s nearest-exact interpolation. Only resample mode supports inverse(), which resamples onto the original canvas and cannot recover discarded information.

Note

Compiled slice-mode interpolation matches eager execution to floating-point tolerance, not bitwise. Eager execution retains native slicing and resizing for performance; the tensorized compiled path avoids recompilation as crop coordinates change.

Example

>>> rng = torch.manual_seed(0)
>>> inputs = torch.tensor([[[0., 1., 2.],
...                         [3., 4., 5.],
...                         [6., 7., 8.]]])
>>> aug = RandomResizedCrop(size=(3, 3), scale=(3., 3.), ratio=(2., 2.), p=1., cropping_mode="resample")
>>> out = aug(inputs)
>>> out
tensor([[[[3.0000, 4.0000, 5.0000],
          [4.5000, 5.5000, 6.5000],
          [6.0000, 7.0000, 8.0000]]]])
>>> aug.inverse(out, padding_mode="border")
tensor([[[[3., 4., 5.],
          [3., 4., 5.],
          [6., 7., 8.]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomResizedCrop(size=(3, 3), scale=(3., 3.), ratio=(2., 2.), p=1., cropping_mode="resample")
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomRotation90(times, resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=True, p=0.5, keepdim=False)[source]#

Apply a random 90 * n degree rotation to a torch.Tensor image or a batch of torch.Tensor images.

Parameters:

times (tuple[int, int]) – the range of n times 90 degree rotation needs to be applied.
resample (Union[str, int, Resample], optional) – Default: the interpolation mode.
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
align_corners (bool, optional) – interpolation flag. Default: True
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse.
a positive rounded times rotates the displayed image counter-clockwise by times * 90 degrees.
times is sampled from a continuous uniform range and rounded, and a non-square image keeps its (H, W) shape (#4409).

Note

This function internally uses kornia.geometry.transform.affine(). This version is relatively slow as it operates based on affine transformations.

Examples

>>> rng = torch.manual_seed(1)
>>> input = torch.tensor([[1., 0., 0., 2.],
...                       [0., 0., 0., 0.],
...                       [0., 1., 2., 0.],
...                       [0., 0., 1., 2.]])
>>> aug = RandomRotation90(times=(1, 1), p=1.)
>>> out = aug(input)
>>> out.round()  # rounded: the warp leaves float32 noise around 1e-7
tensor([[[[2., 0., 0., 2.],
          [0., 0., 2., 1.],
          [0., 0., 1., 0.],
          [1., 0., 0., 0.]]]])
>>> aug.transform_matrix.round(decimals=4) + 0.  # + 0. turns -0. into 0.
tensor([[[ 0.,  1.,  0.],
         [-1.,  0.,  3.],
         [ 0.,  0.,  1.]]])
>>> inv = aug.inverse(out)

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomRotation90(times=(-1, 1), p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomRotation(degrees, resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=True, p=0.5, keepdim=False)[source]#

Apply a random rotation to a torch.Tensor image or a batch of torch.Tensor images given an amount of degrees.

_images/RandomRotation.png

Parameters:

degrees (Union[Tensor, float, Tuple[float, float], List[float]]) – range of degrees to select from. If degrees is a number the range of degrees to select from will be (-degrees, +degrees).
resample (Union[str, int, Resample], optional) – Default: the interpolation mode.
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
align_corners (bool, optional) – interpolation flag. Default: True
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse.
a positive sampled angle rotates the displayed image counter-clockwise, as rotate() does and unlike RandomAffine (Conventions & Pitfalls, #4408).

Note

This function internally uses kornia.geometry.transform.affine().

Examples

>>> rng = torch.manual_seed(0)
>>> input = torch.tensor([[1., 0., 0., 2.],
...                       [0., 0., 0., 0.],
...                       [0., 1., 2., 0.],
...                       [0., 0., 1., 2.]])
>>> aug = RandomRotation(degrees=45.0, p=1.)
>>> out = aug(input)
>>> out
tensor([[[[0.9824, 0.0088, 0.0000, 1.9649],
          [0.0000, 0.0029, 0.0000, 0.0176],
          [0.0029, 1.0000, 1.9883, 0.0000],
          [0.0000, 0.0088, 1.0117, 1.9649]]]])
>>> aug.transform_matrix
tensor([[[ 1.0000, -0.0059,  0.0088],
         [ 0.0059,  1.0000, -0.0088],
         [ 0.0000,  0.0000,  1.0000]]])
>>> inv = aug.inverse(out)

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomRotation(degrees=45.0, p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomShear(shear, resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=False, padding_mode=SamplePadding.ZEROS.name, p=0.5, keepdim=False)[source]#

Apply a random 2D shear transformation to a torch.Tensor image.

The transformation is computed so that the image center is kept invariant.

Parameters:

shear (Union[Tensor, float, Tuple[float, float], Tuple[float, float, float, float]]) – Range of degrees to select from. If float, a shear parallel to the x axis in the range (-shear, +shear) will be applied. If (a, b), a shear parallel to the x axis in the range (-shear, +shear) will be applied. If (a, b, c, d), then x-axis shear in (shear[0], shear[1]) and y-axis shear in (shear[2], shear[3]) will be applied. Will not apply shear by default.
resample (Union[str, int, Resample], optional) – resample mode from “nearest” (0) or “bilinear” (1). Default: Resample.BILINEAR.name
padding_mode (Union[str, int, SamplePadding], optional) – padding mode from “torch.zeros” (0), “border” (1) or “reflection” (2). Default: SamplePadding.ZEROS.name
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
align_corners (bool, optional) – interpolation flag. Default: False
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\)
Output: \((B, C, H, W)\)

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse.
shear supplies one or two degree ranges for the x and y shears; a scalar or pair supplies only x shear. The signs are those of RandomAffine’s shear.

Note

This function internally uses kornia.geometry.transform.warp_affine().

Examples

>>> import torch
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 3, 3)
>>> aug = RandomShear((-5., 2., 5., 10.), p=1.)
>>> out = aug(input)
>>> out, aug.transform_matrix
(tensor([[[[0.4403, 0.7614, 0.1516],
          [0.1753, 0.3074, 0.6127],
          [0.4438, 0.8924, 0.4061]]]]), tensor([[[ 1.0000,  0.0100, -0.0100],
         [-0.1183,  0.9988,  0.1194],
         [ 0.0000,  0.0000,  1.0000]]]))
>>> aug.inverse(out)
tensor([[[[0.4045, 0.7577, 0.1393],
          [0.2071, 0.3074, 0.5582],
          [0.3958, 0.8868, 0.4265]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomShear((-15., 20.), p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomThinPlateSpline(scale=0.2, align_corners=False, padding_mode=SamplePadding.ZEROS.name, same_on_batch=False, p=0.5, keepdim=False)[source]#

Add random noise to the Thin Plate Spline algorithm.

_images/RandomThinPlateSpline.png

Convention:: Five control points use normalized (x, y) coordinates: (-1, -1), (-1, 1), (1, -1), (1, 1), and (0, 0). Each destination coordinate receives uniform noise between -scale and scale; zero scale leaves these points unchanged. Sampling is bilinear, with no interpolation-mode argument. Zero scale is an identity warp up to interpolation roundoff for either align_corners. There is no transform_matrix or inverse; spatial labels in containers have limitations (#4420). Its defaults and the align_corners split across classes (#4412) are listed on GeometricAugmentationBase2D.

Parameters:

scale (float, optional) – the non-negative scale factor to apply to the destination points. Zero leaves the control points unchanged. Default: 0.2
align_corners (bool, optional) – Interpolation flag used by grid_sample. Default: False
padding_mode (Union[str, int, SamplePadding], optional) – Padding used by grid_sample: ‘zeros’, ‘border’ or ‘reflection’. Default: SamplePadding.ZEROS.name
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Note

This function internally uses kornia.geometry.transform.warp_image_tps().

Examples

>>> img = torch.ones(1, 1, 2, 2)
>>> out = RandomThinPlateSpline()(img)
>>> out.shape
torch.Size([1, 1, 2, 2])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomThinPlateSpline(p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomTranslate(translate_x=None, translate_y=None, resample=Resample.BILINEAR.name, same_on_batch=False, align_corners=False, padding_mode=SamplePadding.ZEROS.name, p=0.5, keepdim=False)[source]#

Apply a random 2D affine transformation to a torch.Tensor image.

Parameters:

translate_x (Union[Tensor, Tuple[float, float], None], optional) – tuple of maximum absolute fraction for horizontal translations. For example translate_x=(a, b), then horizontal shift is randomly sampled in the range img_width * a < dx < img_width * b Default: None
translate_y (Union[Tensor, Tuple[float, float], None], optional) – tuple of maximum absolute fraction for vertical translations. For example translate_y=(a, b), then vertical shift is randomly sampled in the range img_height * a < dy < img_height * b. Default: None
resample (Union[str, int, Resample], optional) – resample mode from “nearest” (0) or “bilinear” (1). Default: Resample.BILINEAR.name
padding_mode (Union[str, int, SamplePadding], optional) – padding mode from “torch.zeros” (0), “border” (1) or “reflection” (2). Default: SamplePadding.ZEROS.name
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
align_corners (bool, optional) – interpolation flag. Default: False
p (float, optional) – probability of applying the transformation. Default: 0.5
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\)
Output: \((B, C, H, W)\)

Convention:

See GeometricAugmentationBase2D for coordinates, defaults and inverse.
translate_x and translate_y are independently sampled fractions of W and H; positive values move content right and down. Omitting either range fixes that axis at zero.

Note

This function internally uses kornia.geometry.transform.warp_affine().

Examples

>>> import torch
>>> rng = torch.manual_seed(0)
>>> input = torch.rand(1, 1, 3, 3)
>>> aug = RandomTranslate((-0.2, 0.2), (-0.1, 0.1), p=1.)
>>> out = aug(input)
>>> out, aug.transform_matrix
(tensor([[[[0.3897, 0.6847, 0.2314],
          [0.1384, 0.3297, 0.5771],
          [0.3749, 0.7565, 0.4780]]]]), tensor([[[ 1.0000,  0.0000,  0.1588],
         [ 0.0000,  1.0000, -0.0907],
         [ 0.0000,  0.0000,  1.0000]]]))
>>> aug.inverse(out)
tensor([[[[0.3969, 0.5571, 0.1770],
          [0.1930, 0.3910, 0.4591],
          [0.4113, 0.6812, 0.4096]]]])

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> aug = RandomTranslate((-0.2, 0.2), (-0.1, 0.1), p=1.)
>>> (aug(input) == aug(input, params=aug._params)).all()
tensor(True)

class kornia.augmentation.RandomVerticalFlip(p=0.5, p_batch=1.0, same_on_batch=False, keepdim=False)[source]#

Apply a random vertical flip to a torch.Tensor image or a batch of torch.Tensor images with a given probability.

_images/RandomVerticalFlip.png

Parameters:

p (float, optional) – probability of the image being flipped. Default: 0.5
same_on_batch (bool, optional) – apply the same transformation across the batch. Default: False
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Shape:

Input: \((C, H, W)\) or \((B, C, H, W)\), Optional: \((B, 3, 3)\)
Output: \((B, C, H, W)\)

Convention:

A selected flip maps (x, y) to (x, H - 1 - y) with the exact discrete vflip(), without resampling; see GeometricAugmentationBase2D for the shared contract.

Note

This function internally uses kornia.geometry.transform.vflip().

Examples

>>> import torch
>>> input = torch.tensor([[[[0., 0., 0.],
...                         [0., 0., 0.],
...                         [0., 1., 1.]]]])
>>> seq = RandomVerticalFlip(p=1.0)
>>> seq(input), seq.transform_matrix
(tensor([[[[0., 1., 1.],
          [0., 0., 0.],
          [0., 0., 0.]]]]), tensor([[[ 1.,  0.,  0.],
         [ 0., -1.,  2.],
         [ 0.,  0.,  1.]]]))
>>> seq.inverse(seq(input)).equal(input)
True

To apply the exact augmenation again, you may take the advantage of the previous parameter state:

>>> input = torch.randn(1, 3, 32, 32)
>>> seq = RandomVerticalFlip(p=1.0)
>>> (seq(input) == seq(input, params=seq._params)).all()
tensor(True)

Resize#

Deterministic resizing operators, shape-agnostic for 2D and 3D tensors.

class kornia.augmentation.LongestMaxSize(max_size, resample=Resample.BILINEAR.name, align_corners=True, p=1.0)[source]#

Rescale an image so that maximum side is equal to max_size, keeping the aspect ratio of the initial image.

Parameters:: max_size (int) – maximum size of the image after the transformation.

Convention:: See Resize for the common resize conventions. This behaves like Resize(max_size, side="long", antialias=False, keepdim=False); antialias and keepdim are not accepted constructor arguments. Its longest output side equals max_size and the other side is truncated while preserving aspect ratio.

class kornia.augmentation.Resize(size, side='short', resample=Resample.BILINEAR.name, align_corners=True, antialias=False, p=1.0, keepdim=False)[source]#

Resize to size.

Parameters:

size (Union[int, Tuple[int, int]]) – Size (h, w) in pixels of the resized region or just one side.
side (str, optional) – Which side to resize, if size is only of type int. Default: "short"
resample (Union[str, int, Resample], optional) – Resampling mode. Default: Resample.BILINEAR.name
align_corners (bool, optional) – interpolation flag. Default: True
antialias (bool, optional) – if True, then image will be filtered with Gaussian before downscaling. No effect for upscaling. Default: False
p (float, optional) – probability of the augmentation been applied. Default: 1.0
keepdim (bool, optional) – whether to keep the output shape the same as input (True) or broadcast it to the batch form (False). Default: False

Convention:: See GeometricAugmentationBase2D for coordinates, defaults and inverse. A tuple size is the exact (height, width) output. With an integer, side selects which input side is set to that value while preserving aspect ratio: "short" (the default) selects the shortest side, "long" the longest, "vert" the height, and "horz" the width. The derived side is truncated toward zero; if it becomes zero, the resize raises AssertionError (for example, Resize(4, side="long") or LongestMaxSize(4) on a 1-by-10 image). This class uses kornia.geometry.transform.resize(); align_corners is forwarded for bilinear and bicubic sampling, and transform_matrix follows the grid they sample: at align_corners=False it is the half-pixel map x' = (x + 0.5) * W_out / W_in - 0.5 (likewise for y), and at True it maps the corner pixel centres onto each other. Nearest sampling uses the half-pixel grid and PyTorch’s nearest-exact interpolation. inverse() resamples to the prior canvas and cannot recover values discarded by a resize.

class kornia.augmentation.SmallestMaxSize(max_size, resample=Resample.BILINEAR.name, align_corners=True, p=1.0)[source]#

Rescale an image so that minimum side is equal to max_size, keeping the aspect ratio of the initial image.

Parameters:: max_size (int) – maximum size of the image after the transformation.

Convention:: See Resize for the common resize conventions. This behaves like Resize(max_size, side="short", antialias=False, keepdim=False); antialias and keepdim are not accepted constructor arguments. Its shortest output side equals max_size and the other side is truncated while preserving aspect ratio.