kornia.filters

The functions in this sections perform various image filtering operations.

filter2D(input: torch.Tensor, kernel: torch.Tensor, border_type: str = 'reflect') → torch.Tensor

Function that convolves a tensor with a kernel.

The function applies a given kernel to a tensor. The kernel is applied indepentdently at each depth channel of the tensor. Before applying the kernel, the function applies padding according to the specified mode so that the output reaims 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 \((B, kH, kW)\).
• borde_type (str) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.

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') → torch.Tensor

Blurs an image using the box filter.

See BoxBlur for details.

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

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

Function that blurs a tensor using a Gaussian filter.

See GaussianBlur for details.

laplacian(input: torch.Tensor, kernel_size: int, border_type: str = 'reflect') → torch.Tensor

Function that returns a tensor using a Laplacian filter.

See Laplacian for details.

sobel(input: torch.Tensor) → torch.Tensor

Computes the Sobel operator and returns the magnitude per channel.

See Sobel for details.

spatial_gradient(input: torch.Tensor) → torch.Tensor

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

See SpatialGradient for details.

get_gaussian_kernel(kernel_size: int, sigma: float) → torch.Tensor

Function that returns Gaussian filter coefficients.

Parameters:

• kernel_size (int) – filter size. It should be odd and positive.
• sigma (float) – gaussian standard deviation.

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]) → torch.Tensor

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.

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_kernel(kernel_size: int) → torch.Tensor

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

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')

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.
• borde_type (str) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.

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

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')

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.
• borde_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')

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.
• borde_type (str) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.

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

Computes the Sobel operator and returns the magnitude per channel.

Returns:the sobel edge gradient maginitudes map. Return type:torch.Tensor

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

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