kornia.filters¶

The functions in this sections perform various image filtering operations.

Blurring¶

kornia.filters.bilateral_blur(input, kernel_size, sigma_color, sigma_space, border_type='reflect', color_distance_type='l1')[source]¶

Blur a torch.Tensor using a Bilateral filter.

The operator is an edge-preserving image smoothing filter. The weight for each pixel in a neighborhood is determined not only by its distance to the center pixel, but also the difference in intensity or color.

Parameters:

input (Tensor) – the input torch.Tensor with shape \((B,C,H,W)\).
kernel_size (tuple[int, int] | int) – the size of the kernel.
sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges.
sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d().
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
color_distance_type (str, optional) – the type of distance to calculate intensity/color difference. Only 'l1' or 'l2' is allowed. Use 'l1' to match OpenCV implementation. Use 'l2' to match Matlab implementation. Default: 'l1'.

Return type:

Tensor

Returns:

the blurred torch.Tensor with shape \((B, C, H, W)\).

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> output = bilateral_blur(input, (3, 3), 0.1, (1.5, 1.5))
>>> output.shape
torch.Size([2, 4, 5, 5])

kornia.filters.blur_pool2d(input, kernel_size, stride=2)[source]¶

Compute blurs and downsample a given feature map.

See BlurPool2D for details.

See [Zha19] for more details.

Parameters:

input (Tensor) – torch.Tensor to apply operation to.
kernel_size (tuple[int, int] | int) – the kernel size for max pooling.
stride (int, optional) – stride for pooling. Default: 2

Shape:

Input: \((B, C, H, W)\)
Output: \((N, C, H_{out}, W_{out})\), where

\[H_{out} = \left\lfloor\frac{H_{in} + 2 \times \text{kernel\_size//2}[0] - \text{kernel\_size}[0]}{\text{stride}[0]} + 1\right\rfloor\]

\[W_{out} = \left\lfloor\frac{W_{in} + 2 \times \text{kernel\_size//2}[1] - \text{kernel\_size}[1]}{\text{stride}[1]} + 1\right\rfloor\]

Return type:: Tensor
Returns:: the transformed torch.Tensor.

Note

This function is tested against https://github.com/adobe/antialiased-cnns.

Note

See a working example here.

Examples

>>> input = torch.eye(5)[None, None]
>>> blur_pool2d(input, 3)
tensor([[[[0.3125, 0.0625, 0.0000],
          [0.0625, 0.3750, 0.0625],
          [0.0000, 0.0625, 0.3125]]]])

kornia.filters.box_blur(input, kernel_size, border_type='reflect', separable=False)[source]¶

Blur 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:

input (Tensor) – the image to blur with shape \((B,C,H,W)\).
kernel_size (tuple[int, int] | int) – the blurring kernel size.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
separable (bool, optional) – run as composition of two 1d-convolutions. Default: False

Return type:

Tensor

Returns:

the blurred torch.Tensor with shape \((B,C,H,W)\).

Note

See a working example here.

Example

>>> input = torch.rand(2, 4, 5, 7)
>>> output = box_blur(input, (3, 3))  # 2x4x5x7
>>> output.shape
torch.Size([2, 4, 5, 7])

kornia.filters.gaussian_blur2d(input, kernel_size, sigma, border_type='reflect', separable=True)[source]¶

Create an operator that blurs a torch.Tensor using a Gaussian filter.

The operator smooths the given torch.Tensor with a gaussian kernel by convolving it to each channel. It supports batched operation.

Parameters:

input (Tensor) – the input torch.Tensor with shape \((B,C,H,W)\).
kernel_size (tuple[int, int] | int) – the size of the kernel. Can be an integer or tuple of two integers (height, width).
sigma (tuple[float, float] | Tensor) – the standard deviation of the kernel. Can be a tuple of two floats or a torch.Tensor with shape \((B, 2)\). Values must be positive.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
separable (bool, optional) – run as composition of two 1d-convolutions. Default: True.

Return type:

Tensor

Returns:

the blurred torch.Tensor with shape \((B, C, H, W)\).

Raises:

RuntimeError – if input is not a 4D torch.Tensor.
RuntimeError – if sigma values are not positive.
RuntimeError – if kernel_size is not a positive odd integer.

Note

See a working example here.

Examples

>>> import torch
>>> input = torch.rand(2, 4, 5, 5)
>>> output = gaussian_blur2d(input, (3, 3), (1.5, 1.5))
>>> output.shape
torch.Size([2, 4, 5, 5])

>>> # Single kernel size applies to both dimensions
>>> output = gaussian_blur2d(input, 3, (1.5, 1.5))
>>> output.shape
torch.Size([2, 4, 5, 5])

>>> # Using batched sigma (different sigma per batch element)
>>> sigma_batch = torch.tensor([[1.5, 1.5], [2.0, 2.0]])
>>> output = gaussian_blur2d(input[:2], (3, 3), sigma_batch)
>>> output.shape
torch.Size([2, 4, 5, 5])

>>> # Using torch.tensor sigma
>>> output = gaussian_blur2d(input, (3, 3), torch.tensor([[1.5, 1.5]]))
>>> output.shape
torch.Size([2, 4, 5, 5])

kornia.filters.guided_blur(guidance, input, kernel_size, eps, border_type='reflect', subsample=1)[source]¶

Blur a torch.Tensor using a Guided filter.

The operator is an edge-preserving image smoothing filter. See [HST10] and [HS15] for details. Guidance and input can have different number of channels.

Parameters:

guidance (Tensor) – the guidance torch.Tensor with shape \((B,C,H,W)\).
input (Tensor) – the input torch.Tensor with shape \((B,C,H,W)\).
kernel_size (tuple[int, int] | int) – the size of the kernel.
eps (float | Tensor) – regularization parameter. Smaller values preserve more edges.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
subsample (int, optional) – subsampling factor for Fast Guided filtering. Default: 1 (no subsampling)

Return type:

Tensor

Returns:

the blurred torch.Tensor with same shape as input \((B, C, H, W)\).

Examples

>>> guidance = torch.rand(2, 3, 5, 5)
>>> input = torch.rand(2, 4, 5, 5)
>>> output = guided_blur(guidance, input, 3, 0.1)
>>> output.shape
torch.Size([2, 4, 5, 5])

kornia.filters.joint_bilateral_blur(input, guidance, kernel_size, sigma_color, sigma_space, border_type='reflect', color_distance_type='l1')[source]¶

Blur a torch.Tensor using a Joint Bilateral filter.

This operator is almost identical to a Bilateral filter. The only difference is that the color Gaussian kernel is computed based on another image called a guidance image. See bilateral_blur() for more information.

Parameters:

input (Tensor) – the input torch.Tensor with shape \((B,C,H,W)\).
guidance (Tensor) – the guidance torch.Tensor with shape \((B,C,H,W)\).
kernel_size (tuple[int, int] | int) – the size of the kernel.
sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges.
sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d().
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
color_distance_type (str, optional) – the type of distance to calculate intensity/color difference. Only 'l1' or 'l2' is allowed. Use 'l1' to match OpenCV implementation. Default: "l1"

Return type:

Tensor

Returns:

the blurred torch.Tensor with shape \((B, C, H, W)\).

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> guidance = torch.rand(2, 4, 5, 5)
>>> output = joint_bilateral_blur(input, guidance, (3, 3), 0.1, (1.5, 1.5))
>>> output.shape
torch.Size([2, 4, 5, 5])

kornia.filters.max_blur_pool2d(input, kernel_size, stride=2, max_pool_size=2, ceil_mode=False)[source]¶

Compute pools and blurs and downsample a given feature map.

See MaxBlurPool2D for details.

Parameters:

input (Tensor) – torch.Tensor to apply operation to.
kernel_size (tuple[int, int] | int) – the kernel size for max pooling.
stride (int, optional) – stride for pooling. Default: 2
max_pool_size (int, optional) – the kernel size for max pooling. Default: 2
ceil_mode (bool, optional) – should be true to match output size of conv2d with same kernel size. Default: False

Return type:

Tensor

Note

This function is tested against https://github.com/adobe/antialiased-cnns.

Note

See a working example here.

Examples

>>> input = torch.eye(5)[None, None]
>>> max_blur_pool2d(input, 3)
tensor([[[[0.5625, 0.3125],
          [0.3125, 0.8750]]]])

kornia.filters.median_blur(input, kernel_size)[source]¶

Blur an image using the median filter.

Parameters:

input (Tensor) – the input image with shape \((B,C,H,W)\).
kernel_size (tuple[int, int] | int) – the blurring kernel size.

Return type:

Tensor

Returns:

the blurred input torch.Tensor with shape \((B,C,H,W)\).

Note

See a working example here.

Example

>>> input = torch.rand(2, 4, 5, 7)
>>> output = median_blur(input, (3, 3))
>>> output.shape
torch.Size([2, 4, 5, 7])

kornia.filters.motion_blur(input, kernel_size, angle, direction, border_type='constant', mode='nearest')[source]¶

Perform motion blur on torch.Tensor images.

Parameters:

input (Tensor) – the input torch.Tensor with shape \((B, C, H, W)\).
kernel_size (int) – motion kernel width and height. It should be odd and positive.
angle (Union[torch.Tensor, float]) – angle of the motion blur in degrees (anti-clockwise rotation). If torch.Tensor, it must be \((B,)\).
direction (float | Tensor) – forward/backward direction of the motion blur. Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle), while higher values towards 1.0 will point the motion blur forward. A value of 0.0 leads to a uniformly (but still angled) motion blur. If torch.Tensor, it must be \((B,)\).
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'constant'.
mode (str, optional) – interpolation mode for rotating the kernel. 'bilinear' or 'nearest'. Default: "nearest"

Return type:

Tensor

Returns:

the blurred image with shape \((B, C, H, W)\).

Example

>>> input = torch.randn(1, 3, 80, 90).repeat(2, 1, 1, 1)
>>> # perform exact motion blur across the batch
>>> out_1 = motion_blur(input, 5, 90., 1)
>>> torch.allclose(out_1[0], out_1[1])
True
>>> # perform element-wise motion blur across the batch
>>> out_1 = motion_blur(input, 5, torch.tensor([90., 180,]), torch.tensor([1., -1.]))
>>> torch.allclose(out_1[0], out_1[1])
False

kornia.filters.unsharp_mask(input, kernel_size, sigma, border_type='reflect')[source]¶

Create an operator that sharpens a torch.Tensor by applying operation out = 2 * image - gaussian_blur2d(image).

Parameters:

input (Tensor) – the input torch.Tensor with shape \((B,C,H,W)\).
kernel_size (tuple[int, int] | int) – the size of the kernel.
sigma (tuple[float, float] | Tensor) – the standard deviation of the kernel.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"

Return type:

Tensor

Returns:

the blurred torch.Tensor with shape \((B,C,H,W)\).

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> output = unsharp_mask(input, (3, 3), (1.5, 1.5))
>>> output.shape
torch.Size([2, 4, 5, 5])

Interactive Demo¶

Visit the Kornia image filtering demo on the Hugging Face Spaces.

Edge detection¶

kornia.filters.canny(input, low_threshold=0.1, high_threshold=0.2, kernel_size=(5, 5), sigma=(1, 1), hysteresis=True, eps=1e-6)[source]¶

Find edges of the input image and filters them using the Canny algorithm.

Parameters:

input (Tensor) – input image torch.Tensor with shape \((B,C,H,W)\).
low_threshold (float, optional) – lower threshold for the hysteresis procedure. Default: 0.1
high_threshold (float, optional) – upper threshold for the hysteresis procedure. Default: 0.2
kernel_size (tuple[int, int] | int, optional) – the size of the kernel for the gaussian blur. Default: (5, 5)
sigma (tuple[float, float] | Tensor, optional) – the standard deviation of the kernel for the gaussian blur. Default: (1, 1)
hysteresis (bool, optional) – if True, applies the hysteresis edge tracking. Otherwise, the edges are divided between weak (0.5) and strong (1) edges. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Return type:

tuple[Tensor, Tensor]

Returns:

the canny edge magnitudes map, shape of \((B,1,H,W)\).
the canny edge detection filtered by thresholds and hysteresis, shape of \((B,1,H,W)\).

Note

See a working example here.

Example

>>> input = torch.rand(5, 3, 4, 4)
>>> magnitude, edges = canny(input)  # 5x3x4x4
>>> magnitude.shape
torch.Size([5, 1, 4, 4])
>>> edges.shape
torch.Size([5, 1, 4, 4])

kornia.filters.laplacian(input, kernel_size, border_type='reflect', normalized=True)[source]¶

Create 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 supports batched operation.

Parameters:

input (Tensor) – the input image tensor with shape \((B, C, H, W)\).
kernel_size (tuple[int, int] | int) – the size of the kernel.
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, L1 norm of the kernel is set to 1. Default: True

Return type:

Tensor

Returns:

the blurred image with shape \((B, C, H, W)\).

Note

See a working example here.

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> output = laplacian(input, 3)
>>> output.shape
torch.Size([2, 4, 5, 5])

kornia.filters.sobel(input, normalized=True, eps=1e-6)[source]¶

Compute the Sobel operator and returns the magnitude per channel.

Parameters:

input (Tensor) – the input image with shape \((B,C,H,W)\).
normalized (bool, optional) – if True, L1 norm of the kernel is set to 1. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Return type:

Tensor

Returns:

the sobel edge gradient magnitudes map with shape \((B,C,H,W)\).

Note

See a working example here.

Example

>>> input = torch.rand(1, 3, 4, 4)
>>> output = sobel(input)  # 1x3x4x4
>>> output.shape
torch.Size([1, 3, 4, 4])

kornia.filters.spatial_gradient(input, mode='sobel', order=1, normalized=True)[source]¶

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

Parameters:

input (Tensor) – input image torch.Tensor with shape \((B, C, H, W)\).
mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "sobel"
order (int, optional) – the order of the derivatives. Default: 1
normalized (bool, optional) – whether the output is normalized. Default: True

Return type:

Tensor

Returns:

the derivatives of the input feature map. with shape \((B, C, 2, H, W)\).

Note

See a working example here.

Examples

>>> input = torch.rand(1, 3, 4, 4)
>>> output = spatial_gradient(input)  # 1x3x2x4x4
>>> output.shape
torch.Size([1, 3, 2, 4, 4])

kornia.filters.spatial_gradient3d(input, mode='diff', order=1)[source]¶

Compute the first and second order volume derivative in x, y and d using a diff operator.

Parameters:

input (Tensor) – input features torch.Tensor with shape \((B, C, D, H, W)\).
mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "diff"
order (int, optional) – the order of the derivatives. Default: 1

Returns:

(B, C, 3, D, H, W) or \((B, C, 6, D, H, W)\).

Return type:

the spatial gradients of the input feature map with shape math

Examples

>>> input = torch.rand(1, 4, 2, 4, 4)
>>> output = spatial_gradient3d(input)
>>> output.shape
torch.Size([1, 4, 3, 2, 4, 4])

class kornia.filters.Laplacian(kernel_size, border_type='reflect', normalized=True)[source]¶

Create 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 supports batched operation.

Parameters:

kernel_size (tuple[int, int] | int) – the size of the kernel.
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, L1 norm of the kernel is set to 1. Default: True

Shape:

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

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> laplace = Laplacian(5)
>>> output = laplace(input)
>>> output.shape
torch.Size([2, 4, 5, 5])

class kornia.filters.Sobel(normalized=True, eps=1e-6)[source]¶

Compute the Sobel operator and returns the magnitude per channel.

Parameters:

normalized (bool, optional) – if True, L1 norm of the kernel is set to 1. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Returns:

the sobel edge gradient magnitudes map.

Shape:

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

Examples

>>> input = torch.rand(1, 3, 4, 4)
>>> output = Sobel()(input)  # 1x3x4x4

class kornia.filters.Canny(low_threshold=0.1, high_threshold=0.2, kernel_size=(5, 5), sigma=(1, 1), hysteresis=True, eps=1e-6)[source]¶

nn.Module that finds edges of the input image and filters them using the Canny algorithm.

Parameters:

input – input image torch.Tensor with shape \((B,C,H,W)\).
low_threshold (float, optional) – lower threshold for the hysteresis procedure. Default: 0.1
high_threshold (float, optional) – upper threshold for the hysteresis procedure. Default: 0.2
kernel_size (tuple[int, int] | int, optional) – the size of the kernel for the gaussian blur. Default: (5, 5)
sigma (tuple[float, float] | Tensor, optional) – the standard deviation of the kernel for the gaussian blur. Default: (1, 1)
hysteresis (bool, optional) – if True, applies the hysteresis edge tracking. Otherwise, the edges are divided between weak (0.5) and strong (1) edges. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Returns:

the canny edge magnitudes map, shape of \((B,1,H,W)\).
the canny edge detection filtered by thresholds and hysteresis, shape of \((B,1,H,W)\).

Example

>>> input = torch.rand(5, 3, 4, 4)
>>> magnitude, edges = Canny()(input)  # 5x3x4x4
>>> magnitude.shape
torch.Size([5, 1, 4, 4])
>>> edges.shape
torch.Size([5, 1, 4, 4])

class kornia.filters.SpatialGradient(mode='sobel', order=1, normalized=True)[source]¶

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

Parameters:

mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "sobel"
order (int, optional) – the order of the derivatives. Default: 1
normalized (bool, optional) – whether the output is normalized. Default: True

Returns:

the sobel edges of the input feature map.

Shape:

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

Examples

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

class kornia.filters.SpatialGradient3d(mode='diff', order=1)[source]¶

Compute the first and second order volume derivative in x, y and d using a diff operator.

Parameters:

mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "diff"
order (int, optional) – the order of the derivatives. Default: 1

Returns:

the spatial gradients of the input feature map.

Shape:

Input: \((B, C, D, H, W)\). D, H, W are spatial dimensions, gradient is calculated w.r.t to them.
Output: \((B, C, 3, D, H, W)\) or \((B, C, 6, D, H, W)\)

Examples

>>> input = torch.rand(1, 4, 2, 4, 4)
>>> output = SpatialGradient3d()(input)
>>> output.shape
torch.Size([1, 4, 3, 2, 4, 4])

Interactive Demo¶

Visit the Kornia edge detector demo on the Hugging Face Spaces.

Segmentation¶

kornia.filters.in_range(input, lower, upper, return_mask=False)[source]¶

Create a mask indicating whether elements of the input torch.Tensor are within the specified range.

The formula applied for single-channel torch.Tensor is:

\[\text{out}(I) = \text{lower}(I) \leq \text{input}(I) \geq \text{upper}(I)\]

The formula applied for multi-channel torch.Tensor is:

\[\text{out}(I) = \bigwedge_{c=0}^{C} \left( \text{lower}_c(I) \leq \text{input}_c(I) \geq \text{upper}_c(I) \right)\]

where C is the number of channels.

Parameters:

input (Tensor) – The input torch.Tensor to be filtered in the shape of \((*, *, H, W)\).
lower (Union[tuple[Any, ...], Tensor]) – The lower bounds of the filter (inclusive).
upper (Union[tuple[Any, ...], Tensor]) – The upper bounds of the filter (inclusive).
return_mask (bool, optional) – If is true, the filtered mask is returned, otherwise the filtered input image. Default: False

Return type:

Tensor

Returns:

A binary mask \((*, 1, H, W)\) of input indicating whether elements are within the range or filtered input image \((*, *, H, W)\).

Raises:

ValueError – If the shape of lower, upper, and input image channels do not match.

Note

Clarification of lower and upper:

If provided as a tuple, it should have the same number of elements as the channels in the input torch.Tensor. This bound is then applied uniformly across all batches.
When provided as a torch.Tensor, it allows for different bounds to be applied to each batch. The torch.Tensor shape should be (B, C, 1, 1), where B is the batch size and C is the number of channels.
If the torch.Tensor has a 1-D shape, same bound will be applied across all batches.

Examples

>>> rng = torch.manual_seed(1)
>>> input = torch.rand(1, 3, 3, 3)
>>> lower = (0.2, 0.3, 0.4)
>>> upper = (0.8, 0.9, 1.0)
>>> mask = in_range(input, lower, upper, return_mask=True)
>>> mask
tensor([[[[1., 1., 0.],
          [0., 0., 0.],
          [0., 1., 1.]]]])
>>> mask.shape
torch.Size([1, 1, 3, 3])

Apply different bounds (lower and upper) for each batch:

>>> rng = torch.manual_seed(1)
>>> input_tensor = torch.rand((2, 3, 3, 3))
>>> input_shape = input_tensor.shape
>>> lower = torch.tensor([[0.2, 0.2, 0.2], [0.2, 0.2, 0.2]]).reshape(input_shape[0], input_shape[1], 1, 1)
>>> upper = torch.tensor([[0.6, 0.6, 0.6], [0.8, 0.8, 0.8]]).reshape(input_shape[0], input_shape[1], 1, 1)
>>> mask = in_range(input_tensor, lower, upper, return_mask=True)
>>> mask
tensor([[[[0., 0., 1.],
          [0., 0., 0.],
          [1., 0., 0.]]],


        [[[0., 0., 0.],
          [1., 0., 0.],
          [0., 0., 1.]]]])

class kornia.filters.InRange(lower, upper, return_mask=False)[source]¶

Create a module for applying lower and upper bounds to input tensors.

Parameters:

input – The input torch.Tensor to be filtered.
lower (Union[tuple[Any, ...], Tensor]) – The lower bounds of the filter (inclusive).
upper (Union[tuple[Any, ...], Tensor]) – The upper bounds of the filter (inclusive).
return_mask (bool, optional) – If is true, the filtered mask is returned, otherwise the filtered input image. Default: False

Returns:

A binary mask \((*, 1, H, W)\) of input indicating whether elements are within the range or filtered input image \((*, *, H, W)\).

Note

View complete documentation in kornia.filters.in_range().

Examples

>>> rng = torch.manual_seed(1)
>>> input = torch.rand(1, 3, 3, 3)
>>> lower = (0.2, 0.3, 0.4)
>>> upper = (0.8, 0.9, 1.0)
>>> mask = InRange(lower, upper, return_mask=True)(input)
>>> mask
tensor([[[[1., 1., 0.],
          [0., 0., 0.],
          [0., 1., 1.]]]])

kornia.filters.otsu_threshold(x, nbins=256, slow_and_differentiable=False, return_mask=False)[source]¶

Apply automatic image thresholding using Otsu algorithm to the input tensor.

Parameters:

x (Tensor) – Input tensor (image or batch of images).
nbins (int) – Number of bins for histogram computation, default is 256. Default: 256
slow_and_differentiable (bool) – If True, use a differentiable histogram computation. Default is False. Default: False
return_mask (bool) – If True, return a binary mask indicating the thresholded pixels. If False, return the thresholded image. Default: False

Returns:

Thresholded tensor and the computed threshold values.

Return type:

Tuple[torch.Tensor, torch.Tensor]

Raises:

ValueError – If the input tensor has unsupported dimensionality or dtype.

Note

The input tensor can be of various types, but float types are preferred for accuracy in histogram computation, especially on CPU. Integer types will be cast to float.
If use_thresh is True, the threshold must have been computed previously and set in the module.
If threshold is provided, it overrides the computed threshold.

Note

You may found more information about the Otsu algorithm here: https://en.wikipedia.org/wiki/Otsu’s_method

Example

>>> import torch
>>> from kornia.filters.otsu_thresholding import otsu_threshold
>>> x = torch.tensor([[10, 20, 30], [40, 50, 60], [70, 80, 90]])
>>> x
tensor([[10, 20, 30],
        [40, 50, 60],
        [70, 80, 90]])
>>> otsu_threshold(x)
(tensor([[ 0,  0,  0],
        [ 0, 50, 60],
        [70, 80, 90]]), tensor([40]))

class kornia.filters.OtsuThreshold[source]¶: Otsu thresholding module for PyTorch tensors.

Filtering API¶

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.

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)[source]¶

Convolve a tensor with a 3d kernel.

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

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

Kernels¶

kornia.filters.get_gaussian_kernel1d(kernel_size, sigma, force_even=False, *, device=None, dtype=None)[source]¶

Return Gaussian filter coefficients.

Parameters:

kernel_size (int) – filter size. It should be odd and positive.
sigma (float | Tensor) – gaussian standard deviation.
force_even (bool, optional) – overrides requirement for odd kernel size. Default: False
device (Optional[device], optional) – This value will be used if sigma is a float. Device desired to compute. Default: None
dtype (Optional[dtype], optional) – This value will be used if sigma is a float. Dtype desired for compute. Default: None

Return type:

Tensor

Returns:

gaussian filter coefficients with shape \((B, \text{kernel_size})\).

Examples

>>> get_gaussian_kernel1d(3, 2.5)
tensor([[0.3243, 0.3513, 0.3243]])
>>> get_gaussian_kernel1d(5, 1.5)
tensor([[0.1201, 0.2339, 0.2921, 0.2339, 0.1201]])
>>> get_gaussian_kernel1d(5, torch.tensor([[1.5], [0.7]]))
tensor([[0.1201, 0.2339, 0.2921, 0.2339, 0.1201],
        [0.0096, 0.2054, 0.5699, 0.2054, 0.0096]])

kornia.filters.get_gaussian_erf_kernel1d(kernel_size, sigma, force_even=False, *, device=None, dtype=None)[source]¶

Return Gaussian filter coefficients by interpolating the error function.

Adapted from: https://github.com/Project-MONAI/MONAI/blob/master/monai/networks/layers/convutils.py.

Parameters:

kernel_size (int) – filter size. It should be odd and positive.
sigma (float | Tensor) – gaussian standard deviation. If a tensor, should be in a shape \((B, 1)\)
force_even (bool, optional) – overrides requirement for odd kernel size. Default: False
device (Optional[device], optional) – This value will be used if sigma is a float. Device desired to compute. Default: None
dtype (Optional[dtype], optional) – This value will be used if sigma is a float. Dtype desired for compute. Default: None

Return type:

Tensor

Returns:

1D tensor with gaussian filter coefficients. Shape \((B, \text{kernel_size})\)

Examples

>>> get_gaussian_erf_kernel1d(3, 2.5)
tensor([[0.3245, 0.3511, 0.3245]])
>>> get_gaussian_erf_kernel1d(5, 1.5)
tensor([[0.1226, 0.2331, 0.2887, 0.2331, 0.1226]])
>>> get_gaussian_erf_kernel1d(5, torch.tensor([[1.5], [2.1]]))
tensor([[0.1226, 0.2331, 0.2887, 0.2331, 0.1226],
        [0.1574, 0.2198, 0.2456, 0.2198, 0.1574]])

kornia.filters.get_gaussian_discrete_kernel1d(kernel_size, sigma, force_even=False, *, device=None, dtype=None)[source]¶

Return Gaussian filter coefficients based on the modified Bessel functions.

Adapted from: https://github.com/Project-MONAI/MONAI/blob/master/monai/networks/layers/convutils.py.

Parameters:

kernel_size (int) – filter size. It should be odd and positive.
sigma (float | Tensor) – gaussian standard deviation. If a tensor, should be in a shape \((B, 1)\)
force_even (bool, optional) – overrides requirement for odd kernel size. Default: False
device (Optional[device], optional) – This value will be used if sigma is a float. Device desired to compute. Default: None
dtype (Optional[dtype], optional) – This value will be used if sigma is a float. Dtype desired for compute. Default: None

Return type:

Tensor

Returns:

1D tensor with gaussian filter coefficients. With shape \((B, \text{kernel_size})\)

Examples

>>> get_gaussian_discrete_kernel1d(3, 2.5)
tensor([[0.3235, 0.3531, 0.3235]])
>>> get_gaussian_discrete_kernel1d(5, 1.5)
tensor([[0.1096, 0.2323, 0.3161, 0.2323, 0.1096]])
>>> get_gaussian_discrete_kernel1d(5, torch.tensor([[1.5],[2.4]]))
tensor([[0.1096, 0.2323, 0.3161, 0.2323, 0.1096],
        [0.1635, 0.2170, 0.2389, 0.2170, 0.1635]])

kornia.filters.get_gaussian_kernel2d(kernel_size, sigma, force_even=False, *, device=None, dtype=None)[source]¶

Return Gaussian filter matrix coefficients.

Parameters:

kernel_size (tuple[int, int] | int) – filter sizes in the y and x direction. Sizes should be odd and positive.
sigma (tuple[float, float] | Tensor) – gaussian standard deviation in the y and x.
force_even (bool, optional) – overrides requirement for odd kernel size. Default: False
device (Optional[device], optional) – This value will be used if sigma is a float. Device desired to compute. Default: None
dtype (Optional[dtype], optional) – This value will be used if sigma is a float. Dtype desired for compute. Default: None

Return type:

Tensor

Returns:

2D tensor with gaussian filter matrix coefficients.

Shape:

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

Examples

>>> get_gaussian_kernel2d((5, 5), (1.5, 1.5))
tensor([[[0.0144, 0.0281, 0.0351, 0.0281, 0.0144],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0351, 0.0683, 0.0853, 0.0683, 0.0351],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0144, 0.0281, 0.0351, 0.0281, 0.0144]]])
>>> 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_gaussian_kernel2d((5, 5), torch.tensor([[1.5, 1.5]]))
tensor([[[0.0144, 0.0281, 0.0351, 0.0281, 0.0144],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0351, 0.0683, 0.0853, 0.0683, 0.0351],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0144, 0.0281, 0.0351, 0.0281, 0.0144]]])

kornia.filters.get_hanning_kernel1d(kernel_size, device=None, dtype=None)[source]¶

Return Hanning (also known as Hann) kernel, used in signal processing and KCF tracker.

\[\begin{split}w(n) = 0.5 - 0.5cos\\left(\\frac{2\\pi{n}}{M-1}\\right) \\qquad 0 \\leq n \\leq M-1\end{split}\]

See further in numpy docs https://numpy.org/doc/stable/reference/generated/numpy.hanning.html

Parameters:

kernel_size (int) – The size the of the kernel. It should be positive.
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (Optional[dtype], optional) – tensor dtype desired to create the kernel Default: None

Returns:

(text{kernel_size}) .. math:: w(n) = 0.5 - 0.5cos\left(\frac{2\pi{n}}{M-1}\right)

Return type:

1D tensor with Hanning filter coefficients. Shape math

Examples

>>> get_hanning_kernel1d(4)
tensor([0.0000, 0.7500, 0.7500, 0.0000])

kornia.filters.get_hanning_kernel2d(kernel_size, device=None, dtype=None)[source]¶

Return 2d Hanning kernel, used in signal processing and KCF tracker.

Parameters:

kernel_size (tuple[int, int] | int) – The size of the kernel for the filter. It should be positive.
device (Union[str, device, None], optional) – tensor device desired to create the kernel Default: None
dtype (Optional[dtype], optional) – tensor dtype desired to create the kernel Default: None

Returns:

math:(text{kernel_size[0], kernel_size[1]}) .. math:: w(n) = 0.5 - 0.5cos\left(\frac{2\pi{n}}{M-1}\right)

Return type:

2D tensor with Hanning filter coefficients. Shape

kornia.filters.get_laplacian_kernel1d(kernel_size, *, device=None, dtype=torch.float32)[source]¶

Return the coefficients of a 1D Laplacian filter.

Parameters:

kernel_size (int) – filter size. It should be odd and positive.
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (dtype, optional) – tensor dtype desired to create the kernel Default: torch.float32

Return type:

Tensor

Returns:

1D tensor with laplacian filter coefficients.

Shape:

Output: math:(text{kernel_size})

Examples

>>> get_laplacian_kernel1d(3)
tensor([ 1., -2.,  1.])
>>> get_laplacian_kernel1d(5)
tensor([ 1.,  1., -4.,  1.,  1.])

kornia.filters.get_laplacian_kernel2d(kernel_size, *, device=None, dtype=torch.float32)[source]¶

Return Gaussian filter matrix coefficients.

Parameters:

kernel_size (tuple[int, int] | int) – filter size should be odd.
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (dtype, optional) – tensor dtype desired to create the kernel Default: torch.float32

Return type:

Tensor

Returns:

2D tensor with laplacian filter matrix coefficients.

Shape:

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

Examples

>>> get_laplacian_kernel2d(3)
tensor([[ 1.,  1.,  1.],
        [ 1., -8.,  1.],
        [ 1.,  1.,  1.]])
>>> 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.]])

kornia.filters.get_motion_kernel2d(kernel_size, angle, direction=0.0, mode='nearest')[source]¶

Return 2D motion blur filter.

Parameters:

kernel_size (int) – motion kernel width and height. It should be odd and positive.
angle (Tensor | float) – angle of the motion blur in degrees (anti-clockwise rotation).
direction (Tensor | float, optional) – forward/backward direction of the motion blur. Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle), while higher values towards 1.0 will point the motion blur forward. A value of 0.0 leads to a uniformly (but still angled) motion blur. Default: 0.0
mode (str, optional) – interpolation mode for rotating the kernel. 'bilinear' or 'nearest'. Default: "nearest"

Return type:

Tensor

Returns:

The motion blur kernel of shape \((B, k_\text{size}, k_\text{size})\).

Examples

>>> get_motion_kernel2d(5, 0., 0.)
tensor([[[0.0000, 0.0000, 0.0000, 0.0000, 0.0000],
         [0.0000, 0.0000, 0.0000, 0.0000, 0.0000],
         [0.2000, 0.2000, 0.2000, 0.2000, 0.2000],
         [0.0000, 0.0000, 0.0000, 0.0000, 0.0000],
         [0.0000, 0.0000, 0.0000, 0.0000, 0.0000]]])

>>> get_motion_kernel2d(3, 215., -0.5)
tensor([[[0.0000, 0.0000, 0.1667],
         [0.0000, 0.3333, 0.0000],
         [0.5000, 0.0000, 0.0000]]])

Module¶

class kornia.filters.BilateralBlur(kernel_size, sigma_color, sigma_space, border_type='reflect', color_distance_type='l1')[source]¶

Blur a torch.Tensor using a Bilateral filter.

Parameters:

kernel_size (tuple[int, int] | int) – the size of the kernel.
sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges.
sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d().
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
color_distance_type (str, optional) – the type of distance to calculate intensity/color difference. Only 'l1' or 'l2' is allowed. Use 'l1' to match OpenCV implementation. Use 'l2' to match Matlab implementation. Default: 'l1'.

Returns:

the blurred input torch.Tensor.

Shape:

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

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> blur = BilateralBlur((3, 3), 0.1, (1.5, 1.5))
>>> output = blur(input)
>>> output.shape
torch.Size([2, 4, 5, 5])

class kornia.filters.BlurPool2D(kernel_size, stride=2)[source]¶

Compute blur (anti-aliasing) and downsample a given feature map.

See [Zha19] for more details.

Parameters:

kernel_size (tuple[int, int] | int) – the kernel size for max pooling.
stride (int, optional) – stride for pooling. Default: 2

Shape:

Input: \((B, C, H, W)\)
Output: \((N, C, H_{out}, W_{out})\), where

\[H_{out} = \left\lfloor\frac{H_{in} + 2 \times \text{kernel\_size//2}[0] - \text{kernel\_size}[0]}{\text{stride}[0]} + 1\right\rfloor\]

\[W_{out} = \left\lfloor\frac{W_{in} + 2 \times \text{kernel\_size//2}[1] - \text{kernel\_size}[1]}{\text{stride}[1]} + 1\right\rfloor\]

Examples

>>> from kornia.filters.blur_pool import BlurPool2D
>>> input = torch.eye(5)[None, None]
>>> bp = BlurPool2D(kernel_size=3, stride=2)
>>> bp(input)
tensor([[[[0.3125, 0.0625, 0.0000],
          [0.0625, 0.3750, 0.0625],
          [0.0000, 0.0625, 0.3125]]]])

class kornia.filters.BoxBlur(kernel_size, border_type='reflect', separable=False)[source]¶

Blur an image using the box filter.

The function smooths an image using the kernel:

Parameters:

kernel_size (tuple[int, int] | int) – the blurring kernel size.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
separable (bool, optional) – run as composition of two 1d-convolutions. Default: False

Returns:

the blurred input torch.Tensor.

Shape:

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

Example

>>> input = torch.rand(2, 4, 5, 7)
>>> blur = BoxBlur((3, 3))
>>> output = blur(input)  # 2x4x5x7
>>> output.shape
torch.Size([2, 4, 5, 7])

class kornia.filters.MaxBlurPool2D(kernel_size, stride=2, max_pool_size=2, ceil_mode=False)[source]¶

Compute pools and blurs and downsample a given feature map.

Equivalent to `nn.Sequential(nn.MaxPool2d(...), BlurPool2D(...))`

See [Zha19] for more details.

Parameters:

kernel_size (tuple[int, int] | int) – the kernel size for max pooling.
stride (int, optional) – stride for pooling. Default: 2
max_pool_size (int, optional) – the kernel size for max pooling. Default: 2
ceil_mode (bool, optional) – should be true to match output size of conv2d with same kernel size. Default: False

Shape:

Input: \((B, C, H, W)\)
Output: \((B, C, H / stride, W / stride)\)

Returns:: the transformed torch.tensor.
Return type:: torch.Tensor

Examples

>>> import torch.nn as nn
>>> from kornia.filters.blur_pool import BlurPool2D
>>> input = torch.eye(5)[None, None]
>>> mbp = MaxBlurPool2D(kernel_size=3, stride=2, max_pool_size=2, ceil_mode=False)
>>> mbp(input)
tensor([[[[0.5625, 0.3125],
          [0.3125, 0.8750]]]])
>>> seq = nn.Sequential(nn.MaxPool2d(kernel_size=2, stride=1), BlurPool2D(kernel_size=3, stride=2))
>>> seq(input)
tensor([[[[0.5625, 0.3125],
          [0.3125, 0.8750]]]])

class kornia.filters.MedianBlur(kernel_size)[source]¶

Blur an image using the median filter.

Parameters:: kernel_size (tuple[int, int] | int) – the blurring kernel size.
Returns:: the blurred input torch.Tensor.

Shape:

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

Example

>>> input = torch.rand(2, 4, 5, 7)
>>> blur = MedianBlur((3, 3))
>>> output = blur(input)
>>> output.shape
torch.Size([2, 4, 5, 7])

class kornia.filters.GaussianBlur2d(kernel_size, sigma, border_type='reflect', separable=True)[source]¶

Create an operator that blurs a torch.Tensor using a Gaussian filter.

The operator smooths the given torch.Tensor with a gaussian kernel by convolving it to each channel. It supports batched operation.

Parameters:

kernel_size (tuple[int, int] | int) – the size of the kernel.
sigma (tuple[float, float] | Tensor) – the standard deviation of the kernel.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
separable (bool, optional) – run as composition of two 1d-convolutions. Default: True

Returns:

the blurred torch.Tensor.

Shape:

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

Examples:

>>> input = torch.rand(2, 4, 5, 5)
>>> gauss = GaussianBlur2d((3, 3), (1.5, 1.5))
>>> output = gauss(input)  # 2x4x5x5
>>> output.shape
torch.Size([2, 4, 5, 5])

class kornia.filters.GuidedBlur(kernel_size, eps, border_type='reflect', subsample=1)[source]¶

Blur a torch.Tensor using a Guided filter.

The operator is an edge-preserving image smoothing filter. See [HST10] and [HS15] for details. Guidance and input can have different number of channels.

Parameters:

kernel_size (tuple[int, int] | int) – the size of the kernel.
eps (float) – regularization parameter. Smaller values preserve more edges.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
subsample (int, optional) – subsampling factor for Fast Guided filtering. Default: 1 (no subsampling)

Returns:

the blurred input torch.Tensor.

Shape:

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

Examples

>>> guidance = torch.rand(2, 3, 5, 5)
>>> input = torch.rand(2, 4, 5, 5)
>>> blur = GuidedBlur(3, 0.1)
>>> output = blur(guidance, input)
>>> output.shape
torch.Size([2, 4, 5, 5])

class kornia.filters.JointBilateralBlur(kernel_size, sigma_color, sigma_space, border_type='reflect', color_distance_type='l1')[source]¶

Blur a torch.Tensor using a Joint Bilateral filter.

This operator is almost identical to a Bilateral filter. The only difference is that the color Gaussian kernel is computed based on another image called a guidance image. See BilateralBlur for more information.

Parameters:

kernel_size (tuple[int, int] | int) – the size of the kernel.
sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges.
sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d().
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'reflect'.
color_distance_type (str, optional) – the type of distance to calculate intensity/color difference. Only 'l1' or 'l2' is allowed. Use 'l1' to match OpenCV implementation. Default: "l1"

Returns:

the blurred input torch.Tensor.

Shape:

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

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> guidance = torch.rand(2, 4, 5, 5)
>>> blur = JointBilateralBlur((3, 3), 0.1, (1.5, 1.5))
>>> output = blur(input, guidance)
>>> output.shape
torch.Size([2, 4, 5, 5])

class kornia.filters.MotionBlur(kernel_size, angle, direction, border_type='constant', mode='nearest')[source]¶

Blur 2D images (4D torch.Tensor) using the motion filter.

Parameters:

kernel_size (int) – motion kernel width and height. It should be odd and positive.
angle (float) – angle of the motion blur in degrees (anti-clockwise rotation).
direction (float) – forward/backward direction of the motion blur. Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle), while higher values towards 1.0 will point the motion blur forward. A value of 0.0 leads to a uniformly (but still angled) motion blur.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "constant"
mode (str, optional) – interpolation mode for rotating the kernel. 'bilinear' or 'nearest'. Default: "nearest"

Returns:

the blurred input torch.Tensor.

Shape:

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

Examples

>>> input = torch.rand(2, 4, 5, 7)
>>> motion_blur = MotionBlur(3, 35., 0.5)
>>> output = motion_blur(input)  # 2x4x5x7

class kornia.filters.UnsharpMask(kernel_size, sigma, border_type='reflect')[source]¶

Create an operator that sharpens image with: out = 2 * image - gaussian_blur2d(image).

Parameters:

kernel_size (tuple[int, int] | int) – the size of the kernel.
sigma (tuple[float, float] | Tensor) – the standard deviation of the kernel.
border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"

Returns:

the sharpened torch.Tensor with shape \((B,C,H,W)\).

Shape:

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

Note

See a working example here.

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> sharpen = UnsharpMask((3, 3), (1.5, 1.5))
>>> output = sharpen(input)
>>> output.shape
torch.Size([2, 4, 5, 5])