2D geometric transforms#

Spatial transforms, plus RandomErasing, which changes image and mask values without moving coordinates. The non-rigid RandomElasticTransform, RandomThinPlateSpline and RandomFisheye cannot move boxes or keypoints, so a container call that passes them raises; the last two raise for masks too. .inverse() leaves these steps applied (#4420). See AugmentationSequential for the supported data-key paths.

RandomAffine combines rotation, translation, scale and shear in one warp; RandomPerspective warps projectively. RandomCrop cuts a fixed-size patch at a random position, RandomResizedCrop cuts a patch of random size and aspect ratio and resizes it, and CenterCrop always cuts the center. RandomRotation90 rotates by multiples of 90 degrees.

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

Crop the centered patch of each image, applied to a batch with probability p (default 1.0).

Try in browser

output = CenterCrop(size)(input) extracts a centered patch of size size from images of shape (B, C, H, W). Use RandomCrop to sample the crop position instead.

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. Both modes support inverse(), which warps the crop back onto the original canvas with the inverse of transform_matrix (zero padding unless the call passes padding_mode) and cannot restore discarded data.

See also

RandomCrop: samples a crop position for each selected image.
CenterCrop3D: extracts a centered subvolume.

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, crop_if_exceeds=True)[source]#

Pad or crop an image batch to a requested size. Always occurs (p=1.0).

Try in browser

output = PadTo(size)(input) pads or crops the right and bottom edges of an image batch (B, C, H, W) to size. Set crop_if_exceeds=False to keep oversized axes unchanged; use Resize when the content itself should be resampled.

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
crop_if_exceeds (bool, optional) – if True (default), an input dimension larger than size is cropped to size. If False, that dimension passes through unchanged, so the output is at least size on each axis and its shape depends on the input. Default: True

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. With the default crop_if_exceeds=True, a target smaller than the input crops that axis instead, so a target can pad one axis while cropping the other. With crop_if_exceeds=False, that axis passes through unchanged.

inverse() restores the prior input shape on every axis. It exactly removes right/bottom padding, and it regrows a cropped axis at the right/bottom with zeros, as the crop augmentations’ inverses do: the discarded pixels cannot be recovered. The transformation matrix is identity, because every kept pixel keeps its coordinates, so keypoints and boxes are neither moved nor clipped when cropping puts them outside the canvas.

See also

Resize: resamples an image to a requested size.

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.]]]])

>>> crop = PadTo((2, 4))
>>> crop.inverse(crop(torch.ones(1, 1, 3, 3)))
tensor([[[[1., 1., 1.],
          [1., 1., 1.],
          [0., 0., 0.]]]])

>>> img_large = torch.zeros(1, 1, 4, 4)
>>> PadTo((2, 2), crop_if_exceeds=False)(img_large).shape
torch.Size([1, 1, 4, 4])

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

Warp images by a random 2D affine transformation, applied per sample with probability p (default 0.5).

Try in browser

output = RandomAffine(degrees, ...)(input) warps each image of shape (B, C, H, W) with one sampled affine transform about its center.

Note

Unlike torchvision’s RandomAffine, which transforms every image, this class transforms each sample with probability p, 0.5 by default; with same_on_batch=True one draw decides for the whole batch. Pass p=1.0 to transform every sample.

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 (a, b) 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 to each sample. 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 center with the sign and the x-then-y order of get_shear_matrix2d(), as Affine applies its shear.
in AugmentationSequential, a fill_value with more than one element pads only the image: masks are padded with zero, forward and inverse, unless extra_args[DataKey.MASK] sets their fill_value; a one-element fill_value applies to both.

Note

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

See also

RandomRotation: samples rotation without translation, scaling or shear.
RandomPerspective: samples a projective four-corner warp.
RandomAffine3D: applies the corresponding sampled transform to volumes.

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 image patches to a requested size, applied to a batch with probability p (default 1.0).

Try in browser

output = RandomCrop(size, ...)(input) chooses crop positions in images of shape (B, C, H, W) and returns patches of size. Use RandomResizedCrop to resize the sampled patch.

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, a size larger than the canvas after explicit padding raises ValueError on either axis, whether or not the batch is selected; it used to return an upscale of the input. A crop that fits once padded is unaffected. Replayed params whose src box exceeds the canvas are not checked: slice mode resizes the available slice and scales only the matrix axes along which the box exceeds the canvas, on the resize’s half-pixel grid, x' = (x + 0.5) * W_out / W_in - 0.5 along a stretched axis (likewise for y), and resample mode uses a warp that rescales both matrix axes and can blend in zero padding.

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. Both modes support inverse(), for images, masks, boxes and keypoints: it warps with the inverse of the mode’s transform_matrix, removes the pre-crop padding, and 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.

See also

CenterCrop: extracts the deterministic centered patch.
RandomResizedCrop: samples a crop and resizes it to the requested output size.
RandomCrop3D: samples a fixed-size subvolume.

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

Warp images with a random elastic displacement field, applied per sample with probability p (default 0.5).

Try in browser

output = RandomElasticTransform(kernel_size, sigma, alpha, ...)(input) displaces pixels in selected images of shape (B, C, H, W).

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 to each sample. 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().

Note

Unlike torchvision’s ElasticTransform, which warps every image, this class warps each sample with probability p, 0.5 by default; with same_on_batch=True one draw decides for the whole batch. Pass p=1.0 to warp every sample.

Convention:: This is a dense backward sampling field with no transform_matrix or inverse. A mask data key is resampled through the same field; keypoint and box data keys raise NotImplementedError, even at p=0 (#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. Coordinates displaced outside the image are filled by padding_mode as in grid_sample. 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.

See also

RandomThinPlateSpline: warps from sampled thin-plate-spline control points.

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 the image, applied per sample with probability p (default 0.5).

Try in browser

output = RandomErasing(scale, ratio, value, ...)(input) replaces one sampled rectangle in each selected image (B, C, H, W).

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 of applying the transformation to each sample. 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:

this operation is range-independent: it does not clamp the input into [0, 1].
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.

See also

RandomChannelDropout: fills selected complete channels instead of one rectangle.
RandomDissolving: creates semantic image-to-image occlusion with a diffusion model.

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 a random radial (fisheye) distortion, applied per sample with probability p (default 0.5).

Try in browser

output = RandomFisheye(...)(input) radially distorts each selected image of shape (B, C, H, W).

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 to each sample. 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

Convention:: Coordinates are normalized to [-1, 1] with corner pixel centers at the endpoints. At output coordinate (x, y), let r be its distance from the sampled center. The input sampling coordinate is (x * (1 + r**gamma), y * (1 + r**gamma)): the center 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. A mask, keypoint or box data key raises NotImplementedError identifying this augmentation, even at p=0 (#4420).

See also

RandomPerspective: samples a projective rather than radial warp.

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

Flip images horizontally, applied per sample with probability p (default 0.5).

Try in browser

output = RandomHorizontalFlip(...)(input) reverses the width axis of images of shape (B, C, H, W).

Parameters:

p (float, optional) – probability of applying the transformation to each sample. 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().

See also

RandomHorizontalFlip3D: reverses the width axis of a volume.
RandomVerticalFlip: reflects across the horizontal center line.

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

Warp images with a random perspective transformation, applied per sample with probability p (default 0.5).

Try in browser

output = RandomPerspective(distortion_scale, ...)(input) applies a projective warp to selected images of shape (B, C, H, W).

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 applying the transformation to each sample. 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().

See also

RandomAffine: samples an affine rather than projective transform.
RandomPerspective3D: applies a projective warp to volumes.

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 image patches and resize them, applied to a batch with probability p (default 1.0).

Try in browser

output = RandomResizedCrop(size, scale, ratio, ...)(input) samples regions from images of shape (B, C, H, W) and resamples them to size. Use RandomCrop to preserve the sampled patch size.

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 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. 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 centers 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 centers onto the output’s. Nearest sampling in slice mode uses the half-pixel grid and PyTorch’s nearest-exact interpolation. With corner alignment, an axis where the output is one pixel long samples the crop’s first row or column, and one where the crop is one pixel long repeats it, as F.interpolate does, in both modes. Both modes support inverse(), which warps the output back onto the original canvas with the inverse of the mode’s transform_matrix 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.

See also

RandomCrop: samples a fixed-size patch without resizing it.

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

Rotate images by a random multiple of 90 degrees, applied per sample with probability p (default 0.5).

Try in browser

output = RandomRotation90(times, ...)(input) rotates selected images of shape (B, C, H, W) by quarter turns. Use RandomRotation to sample arbitrary angles.

Parameters:

times (tuple[int, int]) – the range of n times 90 degree rotation needs to be applied. A range of whole numbers is closed: every whole number from the lower to the upper bound is drawn with the same probability.
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 to each sample. 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.
a range of whole numbers for times is closed and uniform: times=(-1, 1) gives a clockwise quarter turn, no turn and a counter-clockwise quarter turn with the same probability. A range with a fractional bound is still drawn continuously and rounded.
an odd number of quarter turns swaps the height and the width, but the output keeps the (H, W) of the input, so part of a non-square image would be cut off. A non-square input therefore raises ValueError when the times range allows an odd number of quarter turns, even if a given call would draw an even one. Square images, and ranges of even numbers only such as times=(2, 2), are unaffected. Use RandomRotation with a fixed angle of 90 degrees to rotate and crop, or torch.rot90() to turn a whole batch exactly.

Note

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

See also

RandomRotation: samples an arbitrary angle in degrees.

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

Rotate images by a random angle in degrees, applied per sample with probability p (default 0.5).

Try in browser

output = RandomRotation(degrees, ...)(input) rotates selected images of shape (B, C, H, W) about their centers. Use RandomRotation90 when only quarter turns are wanted.

Note

Unlike torchvision’s RandomRotation, which rotates every image, this class rotates each sample with probability p, 0.5 by default; with same_on_batch=True one draw decides for the whole batch. Pass p=1.0 to rotate every sample.

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 to each sample. 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().

See also

RandomRotation90: samples only multiples of 90 degrees.
RandomRotation3D: rotates volumes by a sampled 3D axis-angle vector.

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

Shear images by random angles in degrees, applied per sample with probability p (default 0.5).

Try in browser

output = RandomShear(shear, ...)(input) shears images of shape (B, C, H, W) about their centers by sampled angles.

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 (a, b) 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 to each sample. 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().

Note

Unlike torchvision’s RandomAffine(degrees=0, shear=...), which shears every image, this class shears each sample with probability p, 0.5 by default; with same_on_batch=True one draw decides for the whole batch. Pass p=1.0 to shear every sample.

See also

RandomAffine: samples a combined affine transformation.

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

Warp images with a random thin plate spline, applied per sample with probability p (default 0.5).

Try in browser

output = RandomThinPlateSpline(...)(input) deforms selected images of shape (B, C, H, W) using a sampled thin-plate spline.

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 to each sample. 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().

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. A mask, keypoint or box data key raises NotImplementedError identifying this augmentation, even at p=0 (#4420). Its defaults and the align_corners split across classes (#4412) are listed on GeometricAugmentationBase2D.

See also

RandomElasticTransform: samples a smooth pixel displacement field.

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

Translate images by a random 2D shift, applied per sample with probability p (default 0.5).

Try in browser

output = RandomTranslate(translate_x, translate_y, ...)(input) shifts selected images of shape (B, C, H, W).

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 to each sample. 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().

Note

Unlike torchvision’s RandomAffine(degrees=0, translate=...), which translates every image, this class translates each sample with probability p, 0.5 by default; with same_on_batch=True one draw decides for the whole batch. Pass p=1.0 to translate every sample.

See also

RandomAffine: samples a combined affine transformation.

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

Flip images vertically, applied per sample with probability p (default 0.5).

Try in browser

output = RandomVerticalFlip(...)(input) reverses the height axis of selected images of shape (B, C, H, W).

Parameters:

p (float, optional) – probability of applying the transformation to each sample. 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().

See also

RandomVerticalFlip3D: reverses the height axis of a volume.
RandomHorizontalFlip: reflects across the vertical center line.

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

Resize so the longest side equals max_size, applied to a batch with probability p (default 1.0).

Try in browser

output = LongestMaxSize(max_size)(input) resizes images while preserving their aspect ratio. Use SmallestMaxSize to set the shortest side instead.

Parameters:

max_size (int) – length of the longest output side.
resample (Union[str, int, Resample], optional) – Resampling mode, as in Resize. Default: Resample.BILINEAR.name
align_corners (bool, optional) – interpolation flag, as in Resize. Default: True
p (float, optional) – probability of resizing the batch; one draw decides for every sample. Default: 1.0

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.

See also

SmallestMaxSize: makes the shortest side equal to its bound.
Resize: resamples to an explicit output size.

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

Resample images to a requested spatial size, applied to a batch with probability p (default 1.0).

Try in browser

output = Resize(size, ...)(input) resamples images of shape (B, C, H, W) 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 resizing the batch; one draw decides for every sample. 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 centers onto each other; along an axis where the input or output is one pixel, it is a translation sending the first input pixel onto output pixel 0, the pixel that resize samples there. 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.

See also

LongestMaxSize: bounds the longest image side while preserving aspect ratio.
SmallestMaxSize: sets the shortest image side while preserving aspect ratio.

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

Resize so the shortest side equals max_size, applied to a batch with probability p (default 1.0).

Try in browser

output = SmallestMaxSize(max_size)(input) resizes images while preserving their aspect ratio. Use LongestMaxSize to bound the longest side instead.

Parameters:

max_size (int) – length of the shortest output side.
resample (Union[str, int, Resample], optional) – Resampling mode, as in Resize. Default: Resample.BILINEAR.name
align_corners (bool, optional) – interpolation flag, as in Resize. Default: True
p (float, optional) – probability of resizing the batch; one draw decides for every sample. Default: 1.0

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.

See also

LongestMaxSize: makes the longest side equal to its bound.
Resize: resamples to an explicit output size.