kornia.filters

The functions in this sections perform various image filtering operations.

filter2D(input: torch.Tensor, kernel: torch.Tensor, border_type: str = 'reflect', normalized: bool = False) → torch.Tensor[source]

Function that convolves a tensor with a 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 (torch.Tensor) – the input tensor with shape of \((B, C, H, W)\).

  • kernel (torch.Tensor) – the kernel to be convolved with the input tensor. The kernel shape must be \((1, kH, kW)\).

  • border_type (str) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.

  • normalized (bool) – If True, kernel will be L1 normalized.

Returns

the convolved tensor of same size and numbers of channels as the input.

Return type

torch.Tensor

box_blur(input: torch.Tensor, kernel_size: Tuple[int, int], border_type: str = 'reflect', normalized: bool = True) → torch.Tensor[source]

Blurs an image using the box filter.

See BoxBlur for details.

median_blur(input: torch.Tensor, kernel_size: Tuple[int, int]) → torch.Tensor[source]

Blurs an image using the median filter.

See MedianBlur for details.

gaussian_blur2d(input: torch.Tensor, kernel_size: Tuple[int, int], sigma: Tuple[float, float], border_type: str = 'reflect') → torch.Tensor[source]

Function that blurs a tensor using a Gaussian filter.

See GaussianBlur for details.

laplacian(input: torch.Tensor, kernel_size: int, border_type: str = 'reflect', normalized: bool = True) → torch.Tensor[source]

Function that returns a tensor using a Laplacian filter.

See Laplacian for details.

sobel(input: torch.Tensor, normalized: bool = True) → torch.Tensor[source]

Computes the Sobel operator and returns the magnitude per channel.

See Sobel for details.

spatial_gradient(input: torch.Tensor, mode: str = 'sobel', order: int = 1, normalized: bool = True) → torch.Tensor[source]

Computes the first order image derivative in both x and y using a Sobel operator.

See SpatialGradient for details.

get_gaussian_kernel1d(kernel_size: int, sigma: float, force_even: bool = False) → torch.Tensor[source]

Function that returns Gaussian filter coefficients.

Parameters
  • kernel_size (int) – filter size. It should be odd and positive.

  • sigma (float) – gaussian standard deviation.

  • force_even (bool) – overrides requirement for odd kernel size.

Returns

1D tensor with gaussian filter coefficients.

Return type

Tensor

Shape:
  • Output: \((\text{kernel_size})\)

Examples:

>>> kornia.image.get_gaussian_kernel(3, 2.5)
tensor([0.3243, 0.3513, 0.3243])

>>> kornia.image.get_gaussian_kernel(5, 1.5)
tensor([0.1201, 0.2339, 0.2921, 0.2339, 0.1201])
get_gaussian_kernel2d(kernel_size: Tuple[int, int], sigma: Tuple[float, float], force_even: bool = False) → torch.Tensor[source]

Function that returns Gaussian filter matrix coefficients.

Parameters
  • kernel_size (Tuple[int, int]) – filter sizes in the x and y direction. Sizes should be odd and positive.

  • sigma (Tuple[int, int]) – gaussian standard deviation in the x and y direction.

  • force_even (bool) – overrides requirement for odd kernel size.

Returns

2D tensor with gaussian filter matrix coefficients.

Return type

Tensor

Shape:
  • Output: \((\text{kernel_size}_x, \text{kernel_size}_y)\)

Examples:

>>> kornia.image.get_gaussian_kernel2d((3, 3), (1.5, 1.5))
tensor([[0.0947, 0.1183, 0.0947],
        [0.1183, 0.1478, 0.1183],
        [0.0947, 0.1183, 0.0947]])

>>> kornia.image.get_gaussian_kernel2d((3, 5), (1.5, 1.5))
tensor([[0.0370, 0.0720, 0.0899, 0.0720, 0.0370],
        [0.0462, 0.0899, 0.1123, 0.0899, 0.0462],
        [0.0370, 0.0720, 0.0899, 0.0720, 0.0370]])
get_laplacian_kernel1d(kernel_size: int) → torch.Tensor[source]

Function that returns the coefficients of a 1D Laplacian filter.

Parameters

kernel_size (int) – filter size. It should be odd and positive.

Returns

1D tensor with laplacian filter coefficients.

Return type

Tensor (float)

Shape:
  • Output: math:(text{kernel_size})

Examples::
>>> kornia.image.get_laplacian_kernel(3)
tensor([ 1., -2.,  1.])
>>> kornia.image.get_laplacian_kernel(5)
tensor([ 1.,  1., -4.,  1.,  1.])
get_laplacian_kernel2d(kernel_size: int) → torch.Tensor[source]

Function that returns Gaussian filter matrix coefficients.

Parameters

kernel_size (int) – filter size should be odd.

Returns

2D tensor with laplacian filter matrix coefficients.

Return type

Tensor

Shape:
  • Output: \((\text{kernel_size}_x, \text{kernel_size}_y)\)

Examples:

>>> kornia.image.get_laplacian_kernel2d(3)
tensor([[ 1.,  1.,  1.],
        [ 1., -8.,  1.],
        [ 1.,  1.,  1.]])

>>> kornia.image.get_laplacian_kernel2d(5)
tensor([[  1.,   1.,   1.,   1.,   1.],
        [  1.,   1.,   1.,   1.,   1.],
        [  1.,   1., -24.,   1.,   1.],
        [  1.,   1.,   1.,   1.,   1.],
        [  1.,   1.,   1.,   1.,   1.]])
class BoxBlur(kernel_size: Tuple[int, int], border_type: str = 'reflect', normalized: bool = True)[source]

Blurs an image using the box filter.

The function smooths an image using the kernel:

\[\begin{split}K = \frac{1}{\text{kernel_size}_x * \text{kernel_size}_y} \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \vdots & \vdots & \vdots & \ddots & \vdots & \vdots \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \end{bmatrix}\end{split}\]
Parameters
  • kernel_size (Tuple[int, int]) – the blurring kernel size.

  • border_type (str) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.

  • normalized (bool) – if True, L1 norm of the kernel is set to 1.

Returns

the blurred input tensor.

Return type

torch.Tensor

Shape:
  • Input: \((B, C, H, W)\)

  • Output: \((B, C, H, W)\)

Example

>>> input = torch.rand(2, 4, 5, 7)
>>> blur = kornia.filters.BoxBlur((3, 3))
>>> output = blur(input)  # 2x4x5x7
class MedianBlur(kernel_size: Tuple[int, int])[source]

Blurs an image using the median filter.

Parameters

kernel_size (Tuple[int, int]) – the blurring kernel size.

Returns

the blurred input tensor.

Return type

torch.Tensor

Shape:
  • Input: \((B, C, H, W)\)

  • Output: \((B, C, H, W)\)

Example

>>> input = torch.rand(2, 4, 5, 7)
>>> blur = kornia.filters.MedianBlur((3, 3))
>>> output = blur(input)  # 2x4x5x7
class GaussianBlur2d(kernel_size: Tuple[int, int], sigma: Tuple[float, float], border_type: str = 'reflect')[source]

Creates an operator that blurs a tensor using a Gaussian filter.

The operator smooths the given tensor with a gaussian kernel by convolving it to each channel. It suports batched operation.

Parameters
  • kernel_size (Tuple[int, int]) – the size of the kernel.

  • sigma (Tuple[float, float]) – the standard deviation of the kernel.

  • border_type (str) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.

Returns

the blurred tensor.

Return type

Tensor

Shape:
  • Input: \((B, C, H, W)\)

  • Output: \((B, C, H, W)\)

Examples:

>>> input = torch.rand(2, 4, 5, 5)
>>> gauss = kornia.filters.GaussianBlur((3, 3), (1.5, 1.5))
>>> output = gauss(input)  # 2x4x5x5
class Laplacian(kernel_size: int, border_type: str = 'reflect', normalized: bool = True)[source]

Creates an operator that returns a tensor using a Laplacian filter.

The operator smooths the given tensor with a laplacian kernel by convolving it to each channel. It suports batched operation.

Parameters
  • kernel_size (int) – the size of the kernel.

  • border_type (str) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.

  • normalized (bool) – if True, L1 norm of the kernel is set to 1.

Returns

the tensor.

Return type

Tensor

Shape:
  • Input: \((B, C, H, W)\)

  • Output: \((B, C, H, W)\)

Examples:

>>> input = torch.rand(2, 4, 5, 5)
>>> laplace = kornia.filters.Laplacian(5)
>>> output = laplace(input)  # 2x4x5x5
class Sobel(normalized: bool = True)[source]

Computes the Sobel operator and returns the magnitude per channel.

Returns

the sobel edge gradient maginitudes map.

Return type

torch.Tensor

Parameters

normalized (bool) – if True, L1 norm of the kernel is set to 1.

Shape:
  • Input: \((B, C, H, W)\)

  • Output: \((B, C, H, W)\)

Examples

>>> input = torch.rand(1, 3, 4, 4)
>>> output = kornia.filters.Sobel()(input)  # 1x3x4x4
class SpatialGradient(mode: str = 'sobel', order: int = 1, normalized: bool = True)[source]

Computes the first order image derivative in both x and y using a Sobel operator.

Returns

the sobel edges of the input feature map.

Return type

torch.Tensor

Shape:
  • Input: \((B, C, H, W)\)

  • Output: \((B, C, 2, H, W)\)

Examples

>>> input = torch.rand(1, 3, 4, 4)
>>> output = kornia.filters.SpatialGradient()(input)  # 1x3x2x4x4