Filtering API#

Convolve an image with your own kernel. These are the primitives the blur and edge operators are built on.

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

Convolve a tensor with a 2d kernel.

The function applies a given kernel to a tensor. The kernel is applied independently at each depth 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.

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, Default: "corr"
convolution (or true)

Returns:

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

Return type:

Tensor

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.filter2d_separable(input, kernel_x, kernel_y, border_type='reflect', normalized=False, padding='same')[source]#

Convolve a tensor with two 1d kernels, in x and y directions.

The function applies a given kernel to a tensor. The kernel is applied independently at each depth 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.

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:

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

Return type:

Tensor

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.filter3d(input, kernel, border_type='replicate', normalized=False, behaviour='corr')[source]#

Convolve a tensor with a 3d kernel.

The function applies a given kernel to a tensor. The kernel is applied independently at each depth 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.

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