Filtering API#

Filter an image with your own kernel, by correlation (the default) or convolution. The box, Gaussian and motion blurs and laplacian() are built on filter2d(), filter2d_separable() and filter3d().

kornia.filters.filter2d(input, kernel, border_type='reflect', normalized=False, padding='same', behaviour='corr')[source]#

Filter a tensor with a 2d kernel, by cross-correlation unless behaviour='conv'.

Try in browser

The function applies a given kernel to a tensor. The kernel is applied independently at each channel of the tensor. With padding='same' the input is first padded according to border_type, so that the output keeps the input’s height and width.

Convention:

The default behaviour='corr' is cross-correlation, \(out[y, x] = \sum_{i, j} k[i, j] \, input[y + i - a_y, x + j - a_x]\), anchored at \((a_y, a_x)\) = ((kH - 1) // 2, (kW - 1) // 2): the centre of an odd kernel and, for an even size, the tap before the middle. behaviour='conv' flips the kernel on both axes and keeps the anchor.
border_type takes the torch.nn.functional.pad() mode names, and the default 'reflect' mirrors about the edge pixel without repeating it. Filtering maps the modes and the anchor onto scipy and OpenCV. With padding='same', 'reflect' needs each axis longer than k // 2 for a kernel k taps long along it, and 'circular' at least that long; a shorter axis raises.
A \((1, kH, kW)\) kernel is shared by the whole batch, and a \((B, kH, kW)\) kernel gives each sample its own, shared by the sample’s channels; there are no per-channel kernels. Any other kernel batch raises. An empty batch accepts either a shared kernel or an empty per-sample kernel and retains the usual output spatial size, dtype promotion and gradient connections to both input and kernel.
normalized=True divides each kernel by the sum of its absolute values, so a zero-sum derivative kernel keeps its sign.
border_type, padding and behaviour are case-insensitive: 'REFLECT', 'SAME' and 'CONV' are 'reflect', 'same' and 'conv'.
For a floating input, the kernel is cast to the input’s dtype and device and stays differentiable, and the output has the input’s dtype.
An integer or bool input is filtered in float32 and the output is float32, on the input’s scale: a uint8 image is not rescaled to \([0, 1]\), and the result is not rounded or clamped back to the integer range (#5155).

Parameters:

input (Tensor) – the input tensor with shape of \((B, C, H, W)\).
kernel (Tensor) – the kernel to be convolved with the input tensor. The kernel shape must be \((1, kH, kW)\) or \((B, kH, kW)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
normalized (bool, optional) – If True, kernel will be L1 normalized. Default: False
padding (str, optional) – This defines the type of padding. 2 modes available 'same' or 'valid'. Default: "same"
behaviour (str, optional) – defines the convolution mode – correlation (default), using pytorch conv2d, or true convolution (kernel is flipped). 2 modes available 'corr' or 'conv'. Default: "corr"

Return type:

Tensor

Returns:

the filtered tensor. With padding='same' it has the input’s shape \((B, C, H, W)\). With padding='valid' it has shape \((B, C, H - kH + 1, W - kW + 1)\), and its pixel (0, 0) is the 'same' output at the anchor (a_y, a_x).

Example

>>> input = torch.tensor([[[
...    [0., 0., 0., 0., 0.],
...    [0., 0., 0., 0., 0.],
...    [0., 0., 5., 0., 0.],
...    [0., 0., 0., 0., 0.],
...    [0., 0., 0., 0., 0.],]]])
>>> kernel = torch.ones(1, 3, 3)
>>> filter2d(input, kernel, padding='same')
tensor([[[[0., 0., 0., 0., 0.],
          [0., 5., 5., 5., 0.],
          [0., 5., 5., 5., 0.],
          [0., 5., 5., 5., 0.],
          [0., 0., 0., 0., 0.]]]])

kornia.filters.correlate2d(input, kernel, border_type='reflect', normalized=False, padding='same')[source]#

Correlate a tensor with a 2d kernel.

Convenience alias for filter2d() with behaviour='corr' (cross-correlation). See filter2d() for full documentation.

See also

convolve2d(), filter2d()

Parameters:

input (Tensor) – the input tensor with shape of \((B, C, H, W)\).
kernel (Tensor) – the kernel to be correlated with the input tensor. The kernel shape must be \((1, kH, kW)\) or \((B, kH, kW)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
normalized (bool, optional) – If True, kernel will be L1 normalized. Default: False
padding (str, optional) – This defines the type of padding. 2 modes available 'same' or 'valid'. Default: "same"

Return type:

Tensor

Returns:

the correlated tensor. With padding='same' it has the input’s shape \((B, C, H, W)\). With padding='valid' it has shape \((B, C, H - kH + 1, W - kW + 1)\).

Example

Correlating an impulse gives the kernel rotated by 180 degrees; convolve2d() gives the kernel itself.

>>> input = torch.zeros(1, 1, 5, 5)
>>> input[..., 2, 2] = 1.0
>>> kernel = torch.arange(1.0, 10.0).reshape(1, 3, 3)
>>> correlate2d(input, kernel)
tensor([[[[0., 0., 0., 0., 0.],
          [0., 9., 8., 7., 0.],
          [0., 6., 5., 4., 0.],
          [0., 3., 2., 1., 0.],
          [0., 0., 0., 0., 0.]]]])

With padding='valid' the output loses kH - 1 rows and kW - 1 columns:

>>> correlate2d(input, kernel, padding='valid').shape
torch.Size([1, 1, 3, 3])

kornia.filters.convolve2d(input, kernel, border_type='reflect', normalized=False, padding='same')[source]#

Convolve a tensor with a 2d kernel using true convolution.

Convenience alias for filter2d() with behaviour='conv' (true convolution, where the kernel is flipped along both spatial axes, H and W, before applying). See filter2d() for full documentation.

See also

correlate2d(), filter2d()

Parameters:

input (Tensor) – the input tensor with shape of \((B, C, H, W)\).
kernel (Tensor) – the kernel to be convolved with the input tensor. The kernel shape must be \((1, kH, kW)\) or \((B, kH, kW)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
normalized (bool, optional) – If True, kernel will be L1 normalized. Default: False
padding (str, optional) – This defines the type of padding. 2 modes available 'same' or 'valid'. Default: "same"

Return type:

Tensor

Returns:

the convolved tensor. With padding='same' it has the input’s shape \((B, C, H, W)\). With padding='valid' it has shape \((B, C, H - kH + 1, W - kW + 1)\).

Example

Convolving an impulse gives the kernel itself; correlate2d() gives it rotated by 180 degrees.

>>> input = torch.zeros(1, 1, 5, 5)
>>> input[..., 2, 2] = 1.0
>>> kernel = torch.arange(1.0, 10.0).reshape(1, 3, 3)
>>> convolve2d(input, kernel)
tensor([[[[0., 0., 0., 0., 0.],
          [0., 1., 2., 3., 0.],
          [0., 4., 5., 6., 0.],
          [0., 7., 8., 9., 0.],
          [0., 0., 0., 0., 0.]]]])

With padding='valid' the output loses kH - 1 rows and kW - 1 columns:

>>> convolve2d(input, kernel, padding='valid').shape
torch.Size([1, 1, 3, 3])

kornia.filters.filter2d_separable(input, kernel_x, kernel_y, border_type='reflect', normalized=False, padding='same')[source]#

Correlate a tensor with two 1d kernels, one along x and one along y.

Try in browser

The function applies the given kernels to a tensor. They are applied independently at each channel of the tensor. With padding='same' the input is first padded according to border_type, so that the output keeps the input’s height and width.

Convention:: See the Convention block on filter2d(). The result equals filter2d() with the outer-product kernel kernel_y[:, :, None] * kernel_x[:, None, :], the even-size anchor included: kernel_x runs along W and comes first. There is no behaviour argument, so the kernels are always correlated. normalized=True normalizes each 1d kernel.

Parameters:

input (Tensor) – the input tensor with shape of \((B, C, H, W)\).
kernel_x (Tensor) – the kernel to be convolved with the input tensor. The kernel shape must be \((1, kW)\) or \((B, kW)\).
kernel_y (Tensor) – the kernel to be convolved with the input tensor. The kernel shape must be \((1, kH)\) or \((B, kH)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
normalized (bool, optional) – If True, kernel will be L1 normalized. Default: False
padding (str, optional) – This defines the type of padding. 2 modes available 'same' or 'valid'. Default: "same"

Returns:

\((B, C, H, W)\) with padding='same'.

Return type:

the filtered tensor, of the shape filter2d() returns for the same padding

Example

>>> input = torch.tensor([[[
...    [0., 0., 0., 0., 0.],
...    [0., 0., 0., 0., 0.],
...    [0., 0., 5., 0., 0.],
...    [0., 0., 0., 0., 0.],
...    [0., 0., 0., 0., 0.],]]])
>>> kernel = torch.ones(1, 3)

>>> filter2d_separable(input, kernel, kernel, padding='same')
tensor([[[[0., 0., 0., 0., 0.],
          [0., 5., 5., 5., 0.],
          [0., 5., 5., 5., 0.],
          [0., 5., 5., 5., 0.],
          [0., 0., 0., 0., 0.]]]])

kornia.filters.correlate3d(input, kernel, border_type='replicate', normalized=False)[source]#

Correlate a tensor with a 3d kernel.

Convenience alias for filter3d() with behaviour='corr' (cross-correlation). See filter3d() for full documentation.

See also

convolve3d(), filter3d()

Parameters:

input (Tensor) – the input tensor with shape of \((B, C, D, H, W)\).
kernel (Tensor) – the kernel to be correlated with the input tensor. The kernel shape must be \((1, kD, kH, kW)\) or \((B, kD, kH, kW)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "replicate"
normalized (bool, optional) – If True, kernel will be L1 normalized. Default: False

Return type:

Tensor

Returns:

the correlated tensor, with the input’s shape \((B, C, D, H, W)\).

Example

Correlation applies the kernel as given. A single tap at the kernel’s first corner, index (0, 0, 0) in (D, H, W), makes each output voxel copy the input voxel one step back along all three axes. An impulse at the centre (1, 1, 1) of a 3x3x3 volume therefore lands in the volume’s last corner, (2, 2, 2). convolve3d() puts it in the first corner, (0, 0, 0).

>>> input = torch.zeros(1, 1, 3, 3, 3)
>>> input[0, 0, 1, 1, 1] = 1.0  # the impulse, at the centre of the volume
>>> kernel = torch.zeros(1, 3, 3, 3)
>>> kernel[0, 0, 0, 0] = 1.0  # the tap, at the kernel's first corner
>>> output = correlate3d(input, kernel)
>>> output[0, 0].nonzero()  # (D, H, W) index of the one non-zero output voxel
tensor([[2, 2, 2]])

kornia.filters.convolve3d(input, kernel, border_type='replicate', normalized=False)[source]#

Convolve a tensor with a 3d kernel using true convolution.

Convenience alias for filter3d() with behaviour='conv' (true convolution, where the kernel is flipped along all three axes, D, H and W, before applying). See filter3d() for full documentation.

See also

correlate3d(), filter3d()

Parameters:

input (Tensor) – the input tensor with shape of \((B, C, D, H, W)\).
kernel (Tensor) – the kernel to be convolved with the input tensor. The kernel shape must be \((1, kD, kH, kW)\) or \((B, kD, kH, kW)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "replicate"
normalized (bool, optional) – If True, kernel will be L1 normalized. Default: False

Return type:

Tensor

Returns:

the convolved tensor, with the input’s shape \((B, C, D, H, W)\).

Example

Convolution flips the kernel along all three axes, which moves a tap at the kernel’s first corner, index (0, 0, 0) in (D, H, W), to its last corner. Each output voxel then copies the input voxel one step ahead along all three axes, so an impulse at the centre (1, 1, 1) of a 3x3x3 volume lands in the volume’s first corner, (0, 0, 0). correlate3d() puts it in the last corner, (2, 2, 2).

>>> input = torch.zeros(1, 1, 3, 3, 3)
>>> input[0, 0, 1, 1, 1] = 1.0  # the impulse, at the centre of the volume
>>> kernel = torch.zeros(1, 3, 3, 3)
>>> kernel[0, 0, 0, 0] = 1.0  # the tap, at the kernel's first corner
>>> output = convolve3d(input, kernel)
>>> output[0, 0].nonzero()  # (D, H, W) index of the one non-zero output voxel
tensor([[0, 0, 0]])

kornia.filters.filter3d(input, kernel, border_type='replicate', normalized=False, behaviour='corr')[source]#

Filter a tensor with a 3d kernel, by cross-correlation unless behaviour='conv'.

Try in browser

The function applies a given kernel to a tensor. The kernel is applied independently at each channel of the tensor. Before applying the kernel, the function applies padding according to the specified mode so that the output remains in the same shape.

Convention:

See the Convention block on filter2d(), applied to the (D, H, W) axes with the anchor ((kD - 1) // 2, (kH - 1) // 2, (kW - 1) // 2).
The default border_type is 'replicate', where filter2d() defaults to 'reflect'. There is no padding argument: the output always has the input’s shape.

Parameters:

input (Tensor) – the input tensor with shape of \((B, C, D, H, W)\).
kernel (Tensor) – the kernel to be convolved with the input tensor. The kernel shape must be \((1, kD, kH, kW)\) or \((B, kD, kH, kW)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "replicate"
normalized (bool, optional) – If True, kernel will be L1 normalized. Default: False
behaviour (str, optional) – defines the convolution mode – correlation (default), using pytorch conv3d, or true convolution (kernel is flipped). The expected values are: 'corr', 'conv'. Default: "corr"

Return type:

Tensor

Returns:

the convolved tensor of same size and numbers of channels as the input with shape \((B, C, D, H, W)\).

Example

>>> input = torch.tensor([[[
...    [[0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.]],
...    [[0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 5., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.]],
...    [[0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.]]
... ]]])
>>> kernel = torch.ones(1, 3, 3, 3)
>>> filter3d(input, kernel)
tensor([[[[[0., 0., 0., 0., 0.],
           [0., 5., 5., 5., 0.],
           [0., 5., 5., 5., 0.],
           [0., 5., 5., 5., 0.],
           [0., 0., 0., 0., 0.]],

          [[0., 0., 0., 0., 0.],
           [0., 5., 5., 5., 0.],
           [0., 5., 5., 5., 0.],
           [0., 5., 5., 5., 0.],
           [0., 0., 0., 0., 0.]],

          [[0., 0., 0., 0., 0.],
           [0., 5., 5., 5., 0.],
           [0., 5., 5., 5., 0.],
           [0., 5., 5., 5., 0.],
           [0., 0., 0., 0., 0.]]]]])

kornia.filters.fft_conv(input, kernel, border_type='reflect', normalized=False, padding='same', behaviour='corr')[source]#

Apply a 2D convolution (or correlation) using an FFT-based backend.

Try in browser

This function applies a spatial kernel to a batched tensor using the convolution theorem, i.e., convolution in the spatial domain is performed as element-wise multiplication in the frequency domain.

The kernel is applied independently to each channel of the input tensor. Depending on the selected padding mode, the output can either preserve the input spatial resolution (‘same’) or return only the valid region (‘valid’). Boundary handling is performed in the spatial domain prior to the FFT.

Unlike filter2d()’s, its cost barely grows with the kernel size, so it pays off only for large kernels; the crossover depends on the device and the image size.

Convention:

See the Convention block on filter2d(): for the same arguments and a finite input fft_conv returns the same result, to roundoff. A NaN or inf in a channel of the input makes that channel’s whole output non-finite, where filter2d() keeps it to the pixels whose window reaches it.
An integer or bool input is filtered in float32 and the output is float32, as in filter2d().

Parameters:

input (Tensor) – Input tensor of shape \((B, C, H, W)\).
kernel (Tensor) – Convolution kernel of shape \((1, kH, kW)\), shared by the whole batch, or \((B, kH, kW)\), where each batch element provides one kernel, which is shared across all channels of the corresponding input batch.
border_type (str, optional) – Padding mode applied to the input before convolution. Supported values are 'constant', 'reflect', 'replicate', and 'circular'. Default: "reflect"
normalized (bool, optional) – If True, the kernel is L1-normalized before applying the convolution. Default: False
padding (str, optional) – Padding strategy to use. Supported values are: 'same' (output has the same spatial size as the input) or 'valid' (no implicit padding). Default: "same"
behaviour (str, optional) – Convolution mode. If 'corr' (default), performs cross-correlation. If 'conv', performs true convolution by flipping the kernel spatially. Default: "corr"

Returns:

The filtered tensor. If padding='same', the output shape is \((B, C, H, W)\). If padding='valid', the output shape is \((B, C, H - kH + 1, W - kW + 1)\).

Return type:

Tensor

Note

Internally, the function performs zero-padding of the kernel to match the input size and uses real-valued FFTs (rfftn / irfftn).
CPU float16 and bfloat16 inputs use float32 FFTs, with the result cast back to the input dtype.
This implementation computes linear convolution via FFT by appropriate spatial padding and cropping, avoiding circular convolution artifacts.
No stride or dilation is supported.

Example

>>> input = torch.tensor([[[[
...     0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 5., 0., 0.],
...     [0., 0., 0., 0., 0.],
...     [0., 0., 0., 0., 0.],
... ]]])
>>> kernel = torch.ones(1, 3, 3)
>>> fft_conv(input, kernel, padding="same")
tensor([[[[0., 0., 0., 0., 0.],
          [0., 5., 5., 5., 0.],
          [0., 5., 5., 5., 0.],
          [0., 5., 5., 5., 0.],
          [0., 0., 0., 0., 0.]]]])