Blurring#

Functions#

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 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, separable=False)[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)
separable (bool, optional) – run as composition of two 1d-convolutions. Default: False

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

Modules#

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.

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:

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:

\[\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] | 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, separable=False)[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)
separable (bool, optional) – run as composition of two 1d-convolutions. Default: False

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