Blurring#

Blur, sharpen or downsample images. Every function takes a (B, C, H, W) image (motion_blur3d() a (B, C, D, H, W) volume) and returns the same size, except blur_pool2d() and max_blur_pool2d(), which downsample.

Which function to use:

Average a window, equally with box_blur() or with Gaussian weights with gaussian_blur2d(). Both run as two 1D passes by default (separable=True).
Keep edges. median_blur() takes the median of the window, which removes outliers such as salt-and-pepper noise. bilateral_blur() weights each neighbour by its distance and colour difference. joint_bilateral_blur() and guided_blur() take the edges from a second, guidance image.
Blur along a line, as motion does: motion_blur() for images and motion_blur3d() for volumes.
Sharpen by adding back what a Gaussian blur removes: unsharp_mask().
Downsample a feature map with less aliasing: blur_pool2d(), or max_blur_pool2d() to take a local maximum first. edge_aware_blur_pool2d() blurs at the input size and keeps the pixels on edges.

Each function has a module form that stores its arguments.

Functions#

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

Smooth an image, keeping its strong edges, with a bilateral filter.

Try in browser

out = bilateral_blur(input, kernel_size, sigma_color, sigma_space) averages each pixel’s window of a (B, C, H, W) image with weights that fall with the distance in space and in colour, so a neighbour across a strong edge counts little. The output has the input’s shape.

Convention:

A neighbour weighs \(g \, \exp(-d^2 / (2 \sigma_{color}^2))\). \(g\) is the Gaussian of gaussian_blur2d() with sigma = sigma_space, \((\sigma_y, \sigma_x)\), over the whole kernel_size rectangle, and \(d\) is the neighbour’s colour distance from the centre pixel: the sum of the absolute channel differences for 'l1', their Euclidean norm for 'l2'. Filtering compares this with OpenCV.
sigma_color is in the units of the input values: an image scaled by s > 0, filtered with sigma_color * s, gives the result scaled by s.
The border modes are filter2d()’s, but only in lower case; see its Convention block.
A floating input keeps its dtype: a tensor sigma_color or sigma_space is cast to it and moved to its device.
An integer or bool input is differenced and averaged in float32 and the output is float32, as in filter2d(), so uint8 differences do not wrap.
On the CPU, a float32 or float64 input (after that conversion) with at least 65,536 values is filtered tap by tap from shifted slices of the padded input instead of from its unfolded windows, which avoids temporaries of kernel_size times the image, unless a reverse-mode gradient is recorded through any argument, or torch.export or torch.jit.trace captures the call, so an exported program keeps the windows for every input size. Under torch.compile, only kernels of up to 25 taps are filtered tap by tap, since the compiled loop has a block of operations per tap. Both forms compute the same weights and add up the weighted values in a different order, so they agree to rounding.
On MPS, each window is summed over its columns and then over its rows, because MPS reduces two non-adjacent axes much more slowly than one. In float16 and bfloat16 that rounds every partial sum, so there the gradients with respect to a tensor sigma_color or sigma_space are less accurate than on the CPU or CUDA. Tensor sigmas are cast to the input’s dtype, so keeping them in float32 does not help; pass a float32 input on MPS when those gradients matter.

Parameters:

input (Tensor) – image with shape (B, C, H, W).
kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both; each a positive odd integer.
sigma_color (float | Tensor) – standard deviation of the colour weight, positive; smaller values keep more edges. A float or a (1,) tensor, shared by the batch, or a (B,) tensor, one value per sample.
sigma_space (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) of the spatial weight in pixels, as sigma of gaussian_blur2d(). A tuple of floats, or a tensor with shape (1, 2), shared by the batch, or (B, 2), one row per sample.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
color_distance_type (str, optional) – 'l1' or 'l2' colour distance. Default: "l1"

Return type:

Tensor

Returns:

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

Raises:

BaseError – if an entry of kernel_size is even or not positive.
BaseError – if sigma_color is not positive.
BaseError – if the batch of a tensor sigma_color or sigma_space is neither 1 nor the input batch.

See also

BilateralBlur: the module form.
joint_bilateral_blur(): the colour distance comes from a second image.
guided_blur(): keeps edges by fitting a linear model to a guidance image, with eps in place of the two sigmas.
gaussian_blur2d(): the spatial weight alone, which blurs across edges.

Example

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

Blur a feature map with a binomial kernel and downsample it by stride.

Try in browser

out = blur_pool2d(input, kernel_size) blurs each channel of a (B, C, H, W) map with the normalized binomial kernel and keeps every stride-th pixel, so that strided pooling aliases less [Zha19].

Convention:

The blur is the normalised binomial (Pascal) kernel, which must be square. The blurred map is sampled every stride pixels from index 0.
The border is zero-padded, (k - 1) // 2 pixels before and k // 2 after, and there is no border_type, so a constant map comes out darker where the kernel reaches past the border. An even kernel_size is thereby anchored at (k - 1) // 2, as in filter2d(). Filtering compares the padding with antialiased-cnns, and the sampling with pyrdown().
The blur pools are network layers: an integer or bool input raises a TypeCheckError instead of being promoted to float32 as the image filters promote it. A floating input keeps its dtype.

Parameters:

input (Tensor) – feature map with shape (B, C, H, W) or (C, H, W).
kernel_size (tuple[int, int] | int) – size of the square binomial blur kernel, k or (k, k).
stride (int, optional) – step between the kept pixels. Default: 2

Shape:

Input: (B, C, H, W) or (C, H, W)
Output: (B, C, H_out, W_out), or (C, H_out, W_out) for a (C, H, W) input, where

\[H_{out} = \left\lceil\frac{H}{\text{stride}}\right\rceil, \quad W_{out} = \left\lceil\frac{W}{\text{stride}}\right\rceil\]

Return type:: Tensor
Returns:: the blurred, downsampled map.

Note

See a working example here.

See also

BlurPool2D: the module form.
max_blur_pool2d(): takes a local maximum before the blur.
edge_aware_blur_pool2d(): blurs at the input size, keeping edges.
pyrdown(): blurs with the 5x5 pyramid kernel and resizes bilinearly.

Example

>>> 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=True)[source]#

Blur an image by replacing each pixel with the mean of its kernel_size window.

Try in browser

out = box_blur(input, kernel_size) averages each channel of a (B, C, H, W) image over a window and returns an image of the same shape. Every pixel of the window has the same weight:

\[\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}\]

Convention:

kernel_size is (kH, kW). An even extent is anchored at (k - 1) // 2 and the output keeps the input’s size; see the Convention block on filter2d() for the anchor and the border modes.
An integer or bool input is blurred in float32 and the output is float32, as in filter2d().

Parameters:

input (Tensor) – image with shape (B, C, H, W).
kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both; each positive.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
separable (bool, optional) – True applies two 1D passes, which saves work for large windows, False one 2D kernel. They agree to floating-point roundoff while the sum of a window’s absolute values stays below the dtype’s largest finite value; beyond it the result can be inf or NaN. Default: True

Return type:

Tensor

Returns:

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

Note

See a working example here.

See also

BoxBlur: the module form.
gaussian_blur2d(): weights the window by a Gaussian instead of equally.
median_blur(): takes the median of the window, which keeps edges sharper.
get_box_kernel2d(): the 2D kernel this blur applies.

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.edge_aware_blur_pool2d(input, kernel_size, edge_threshold=1.25, edge_dilation_kernel_size=3, epsilon=1e-6)[source]#

Blur a feature map at its input size, keeping the pixels on edges.

Try in browser

out = edge_aware_blur_pool2d(input, kernel_size) blurs a (B, C, H, W) map with the binomial kernel of blur_pool2d() at stride 1, except on the edges it finds, where it keeps the input pixels.

Convention:

An integer or bool input raises, as in blur_pool2d().
A pixel is on an edge when, along x or y, the channel mean of log2(input + epsilon) differs by more than log2(edge_threshold) between the pixels two before and two after it, so scaling the image does not move the edges while the intensities stay well above epsilon. Pixels on the edge map, dilated by edge_dilation_kernel_size, keep their input value; every other pixel takes the value blurred with blur_pool2d()’s kernel at stride 1, with the border reflected as border_type='reflect' reflects it in filter2d(), so a constant image keeps its value to roundoff.
The input is taken to be positive. Where input + epsilon is negative its logarithm is NaN, which never exceeds the threshold, so a test that reads such a value never finds an edge, and those regions are blurred except where the dilation of an adjacent edge reaches them. Values in (-epsilon, 0] keep a finite logarithm and can form edges, and input = -epsilon gives -inf, an edge against any value above it.

Parameters:

input (Tensor) – feature map with shape (B, C, H, W) or (C, H, W).
kernel_size (tuple[int, int] | int) – size of the square binomial blur kernel, k or (k, k).
edge_threshold (float, optional) – intensity ratio between pixels 4 apart above which a pixel counts as an edge and keeps its value. It must be greater than 1. Default: 1.25
edge_dilation_kernel_size (int, optional) – kernel size for dilating the edges. It must be an odd positive integer. Default: 3
epsilon (float, optional) – value added to the input before the logarithm of the edge test. Default: 1e-6

Return type:

Tensor

Returns:

the blurred map, with the shape of input.

See also

EdgeAwareBlurPool2D: the module form.
blur_pool2d(): blurs everywhere and downsamples.
bilateral_blur(): another blur that keeps edges, weighting each neighbour by its colour distance.

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

Blur an image with a Gaussian kernel of size kernel_size and standard deviation sigma.

Try in browser

out = gaussian_blur2d(input, kernel_size, sigma) smooths each channel of a (B, C, H, W) image with a Gaussian and returns an image of the same shape. For a kernel of your own, use filter2d().

Convention:

kernel_size is (kH, kW) and sigma is \((\sigma_y, \sigma_x)\): both give the rows (y) first, so sigma[0] blurs along H and sigma[1] along W. Filtering maps both pairs onto OpenCV and scipy.
The border modes are filter2d()’s; see its Convention block.
Float16 and bfloat16 inputs use float32 kernels and convolution, including both separable passes, and are rounded to the input dtype once at return. Enclosing autocast is disabled for this computation.
An integer or bool input is blurred in float32 and the output is float32, as in filter2d(); sigma is cast to float32 as well.

Parameters:

input (Tensor) – image with shape (B, C, H, W).
kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both; each a positive odd integer.
sigma (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) in pixels, positive. A tuple of floats, or a tensor with shape (1, 2), shared by the batch, or (B, 2), one row per sample.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular', case-insensitive. Default: "reflect"
separable (bool, optional) – True applies two 1D passes, False one 2D kernel. The results agree to rounding. Default: True

Return type:

Tensor

Returns:

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

Raises:

TypeCheckError – if input is not a torch.Tensor.
ShapeError – if input is not 4D.
AsyncCheckError – if sigma values are not positive, for a tuple or a CPU tensor sigma. It is also a RuntimeError.
RuntimeError – by the next synchronization, if a sigma tensor on an accelerator has a value that is not positive.
BaseError – if the sigma batch is neither 1 nor the input batch.
BaseError – if kernel_size is not a positive odd integer.

Note

On CUDA a failed check of a device sigma is a device-side assert, after which the CUDA context cannot be used. The positivity check is skipped under torch.compile and after kornia.core.check.disable_checks().

Note

See a working example here.

See also

GaussianBlur2d: the module form.
filter2d(): filters with a kernel you pass in.
bilateral_blur(): also weights neighbours by value difference, so edges survive.
get_gaussian_kernel2d(): the 2D kernel this blur applies.

Example

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

Smooth an image with a guided filter, which follows the edges of a guidance image.

Try in browser

out = guided_blur(guidance, input, kernel_size, eps) smooths a (B, C_i, H, W) input along the edges of a (B, C_g, H, W) guidance by fitting a local linear model [HST10]. subsample above 1 selects the fast guided filter [HS15]. Pass the same tensor twice to smooth an image along its own edges.

Convention:

guidance comes first and input second, the opposite of joint_bilateral_blur().
kernel_size is the whole (kH, kW) window, 2 * r + 1 for the radius r of [HST10]. The window means are box_blur()’s, so the border modes and the anchor of an even size follow its Convention block.
eps is added to the local variance of guidance, so it is in squared guidance units: guidance and input scaled by s, filtered with eps * s**2, give the result scaled by s. Filtering maps the arguments onto OpenCV’s guidedFilter.
An integer or bool guidance or input is converted to float32 before the covariance products, on its own scale, and the result has the promoted dtype of the two: a float16 input with a uint8 guidance returns float32, where joint_bilateral_blur() keeps input’s dtype. With grayscale guidance, a tensor-valued eps also participates in result dtype promotion; multichannel guidance retains the promoted dtype of guidance and input.
A float16 or bfloat16 guidance or input is converted to float32 before the window statistics, and the coefficients are solved in float32 as well (in float64 with a float64 tensor eps). Autocast is disabled inside the filter, so a float32 call in an autocast region returns float32. The result has the dtype of the rule above.

Parameters:

guidance (Tensor) – image whose edges are kept, with shape (B, C_g, H, W).
input (Tensor) – image to smooth, with shape (B, C_i, H, W).
kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
eps (float | Tensor) – regularization of the local variance; smaller values keep more edges.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
subsample (int, optional) – subsampling factor of the fast guided filter, a positive integer; 1 means none. Guidance and input are subsampled by nearest neighbour and the coefficient maps resized back to the input’s size, so H and W need not be multiples of it. Default: 1
separable (bool, optional) – True applies the window means as two 1D passes, which saves work for large windows. Default: False

Return type:

Tensor

Returns:

the smoothed image with shape (B, C_i, H, W).

Raises:

TypeCheckError – if subsample is not an integer (NumPy integers are accepted).
BaseError – if subsample is not positive, or is a bool.

See also

GuidedBlur: the module form.
joint_bilateral_blur(): another filter that follows a guidance image, with sigmas in place of eps, and input first.
bilateral_blur(): weights each neighbour by its distance and colour instead of fitting a linear model.

Example

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

Smooth an image, keeping the edges found in a second, guidance image.

Try in browser

out = joint_bilateral_blur(input, guidance, kernel_size, sigma_color, sigma_space) is bilateral_blur() with the colour distance measured in guidance, a (B, C_g, H, W) image, while input, a (B, C, H, W) image, is what gets averaged. The output has the shape of input.

Convention:

See the Convention block on bilateral_blur() for the weights, the borders and the dtypes.
input comes first and guidance second, the opposite of guided_blur().
guidance may have its own channel count; its batch size and (H, W) must equal input’s.
guidance is cast to the dtype of a floating input, so the output keeps input’s dtype. An integer input is filtered in float32, as by bilateral_blur(), and its guidance is cast to float32.

Parameters:

input (Tensor) – image to average, with shape (B, C, H, W).
guidance (Tensor) – image that gives the colour distance, with shape (B, C_g, H, W).
kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both; each a positive odd integer.
sigma_color (float | Tensor) – standard deviation of the colour weight, positive; smaller values keep more edges. A float or a (1,) tensor, shared by the batch, or a (B,) tensor, one value per sample.
sigma_space (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) of the spatial weight in pixels, as sigma of gaussian_blur2d(). A tuple of floats, or a tensor with shape (1, 2), shared by the batch, or (B, 2), one row per sample.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"
color_distance_type (str, optional) – 'l1' or 'l2' colour distance. Default: "l1"

Return type:

Tensor

Returns:

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

Raises:

BaseError – if an entry of kernel_size is even or not positive.
BaseError – if sigma_color is not positive.
BaseError – if the batch of a tensor sigma_color or sigma_space is neither 1 nor the input batch.

See also

JointBilateralBlur: the module form.
bilateral_blur(): the colour distance comes from input itself.
guided_blur(): takes guidance first and eps in place of the two sigmas.

Example

>>> 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=None)[source]#

Max-pool a feature map, then blur it with a binomial kernel and downsample it by stride.

Try in browser

out = max_blur_pool2d(input, kernel_size) takes the maximum over each max_pool_size window of a (B, C, H, W) map, then blurs and downsamples as blur_pool2d() does [Zha19].

Convention:

The result equals blur_pool2d(F.max_pool2d(input, max_pool_size, stride=1), kernel_size, stride): the max pool runs at stride 1 without padding and stride belongs to the blur. See the Convention block on blur_pool2d() for the kernel, the border and integer input, which raises.
With an integer max_pool_size, each spatial axis must contain at least that many pixels (2 by default); otherwise a ShapeError names the minimum size. Tuple windows retain PyTorch’s validation.

Parameters:

input (Tensor) – feature map with shape (B, C, H, W) or (C, H, W).
kernel_size (tuple[int, int] | int) – size of the square binomial blur kernel, k or (k, k).
stride (int, optional) – step between the kept pixels of the blur. Default: 2
max_pool_size (int, optional) – size of the max-pooling window. Default: 2
ceil_mode (bool | None, optional) – deprecated, has no effect. The max pool runs at stride 1, where floor and ceil rounding give the same size, and the strided blur has no rounding mode. Passing it emits a DeprecationWarning; it will be removed in a future release. Default: None

Shape:

Input: (B, C, H, W) or (C, H, W)
Output: (B, C, H_out, W_out), or (C, H_out, W_out) for a (C, H, W) input, where

\[H_{out} = \left\lceil\frac{H - \text{max\_pool\_size} + 1}{\text{stride}}\right\rceil, \quad W_{out} = \left\lceil\frac{W - \text{max\_pool\_size} + 1}{\text{stride}}\right\rceil\]

Return type:: Tensor
Returns:: the pooled, blurred, downsampled map.

Note

See a working example here.

See also

MaxBlurPool2D: the module form.
blur_pool2d(): blurs without the max pool.

Example

>>> 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, border_type='reflect')[source]#

Blur an image by replacing each pixel with the median of its kernel_size window.

Try in browser

out = median_blur(input, kernel_size) takes the median of each channel’s window in a (B, C, H, W) image and returns an image of the same shape. It removes isolated outliers, such as salt-and-pepper noise, and keeps an edge sharp where box_blur() and gaussian_blur2d() spread it.

Convention:

kernel_size is (kH, kW), rows first, and both entries are odd, so every window has one middle value.
A window of more than one pixel that holds a NaN or an infinity returns NaN, even where the median of its values is finite; a 1x1 window returns its pixel, infinity included.
The border modes are filter2d()’s; see its Convention block.
An integer or bool image is filtered in float32 and the result is float32 on its own scale, like box_blur(); a floating image keeps its dtype. A median selects one of its window’s values, so the result equals that of input.float() exactly.

Parameters:

input (Tensor) – image with shape (B, C, H, W).
kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both; each a positive odd integer.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"

Return type:

Tensor

Returns:

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

Note

See a working example here.

See also

MedianBlur: the module form.
box_blur(): takes the mean of the window.
bilateral_blur(): averages instead of selecting, with weights that keep an edge.
get_binary_kernel2d(): the kernel that stacks each window for the median.

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='reflect', mode='nearest')[source]#

Blur an image along a line at a given angle, as camera or object motion does.

Try in browser

out = motion_blur(input, kernel_size, angle, direction) correlates each channel of a (B, C, H, W) image with the streak kernel of get_motion_kernel2d() and returns an image of the same shape.

Convention:

The kernel is get_motion_kernel2d()’s, correlated with the image by filter2d(); their Convention blocks cover angle, direction (including the side on which the streak of a bright point is heaviest), mode, the tensor shapes and the border modes.

Parameters:

input (Tensor) – image with shape (B, C, H, W).
kernel_size (int) – width and height of the kernel, an odd integer of at least 3.
angle (float | Tensor) – angle of the streak in degrees, anti-clockwise. A float, or a (B,) tensor.
direction (float | Tensor) – weighting of the streak in [-1, 1]: 0 is uniform, 1 and -1 are heaviest at opposite ends. A float, or a (B,) tensor. angle and direction need the same length, a float counting as 1.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. The default 'reflect' leaves a constant image constant. 'constant' zero-pads, so pixels whose kernel reaches past an edge, at most kernel_size // 2 from it, are pulled toward 0. Default: "reflect"
mode (str, optional) – interpolation of the rotated kernel, 'bilinear' or 'nearest'. Default: "nearest"

Return type:

Tensor

Returns:

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

See also

MotionBlur: the module form.
motion_blur3d(): the same for volumes.
get_motion_kernel2d(): the kernel this blur applies.

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.motion_blur3d(input, kernel_size, angle, direction, border_type='replicate', mode='nearest')[source]#

Blur a volume along a line at a given 3D angle, as camera or object motion does.

Try in browser

out = motion_blur3d(input, kernel_size, angle, direction) correlates each channel of a (B, C, D, H, W) volume with the streak kernel of get_motion_kernel3d() and returns a volume of the same shape.

Convention:

The kernel is get_motion_kernel3d()’s, correlated with the volume by filter3d(); their Convention blocks cover angle, direction, mode and the border modes. With direction=1 and a zero angle the streak of a bright voxel is heaviest toward increasing W; a positive roll alone turns it toward increasing H, and a positive pitch alone toward decreasing D.

Parameters:

input (Tensor) – volume with shape (B, C, D, H, W).
kernel_size (int) – width, height and depth of the kernel, an odd integer of at least 3.
angle (tuple[float, float, float] | Tensor) – (yaw, pitch, roll), one Rodrigues axis-angle vector (rx, ry, rz) in degrees, not Euler angles; see get_motion_kernel3d(). A sequence of three floats, or a (B, 3) tensor.
direction (float | Tensor) – weighting of the streak in [-1, 1]: 0 is uniform, 1 and -1 are heaviest at opposite ends. A float, or a (B,) tensor. The first dimension of angle and direction must match, a float counting as 1.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. The default 'replicate' leaves a constant volume constant at any size, including D = 1. 'reflect' and 'circular' follow filter2d() along each axis. 'constant' zero-pads, so voxels whose kernel reaches past a face, at most kernel_size // 2 from it, are pulled toward 0. Default: "replicate"
mode (str, optional) – interpolation of the rotated kernel, 'bilinear' or 'nearest'. Default: "nearest"

Return type:

Tensor

Returns:

the blurred volume with shape (B, C, D, H, W).

See also

MotionBlur3D: the module form.
motion_blur(): the same for images.
get_motion_kernel3d(): the kernel this blur applies.

Example

>>> input = torch.randn(1, 3, 120, 80, 90).repeat(2, 1, 1, 1, 1)
>>> # perform exact motion blur across the batch
>>> out_1 = motion_blur3d(input, 5, (0., 90., 90.), 1)
>>> torch.allclose(out_1[0], out_1[1])
True
>>> # perform element-wise motion blur across the batch
>>> out_1 = motion_blur3d(input, 5, torch.tensor([[0., 90., 90.], [90., 180., 0.]]), 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]#

Sharpen an image by adding back the detail that a Gaussian blur removes.

Try in browser

out = unsharp_mask(input, kernel_size, sigma) returns 2 * input - gaussian_blur2d(input, kernel_size, sigma) for a (B, C, H, W) image, an image of the same shape.

Convention:

The blur takes kernel_size, sigma and border_type as gaussian_blur2d() does, and the detail it removes is added back with a fixed gain of 1. See its Convention block for the argument order.
The output is not clamped: next to an edge it overshoots on both sides, so a step from 0 to 1 comes back below 0 and above 1. Filtering maps the call onto scikit-image.
An integer or bool image is filtered in float32 and the result is float32 on its own scale, like gaussian_blur2d(); a floating image keeps its dtype.
Under torch.autocast the blur runs in the autocast dtype, as in gaussian_blur2d() (autocast leaves a float64 image alone), and the result keeps the image’s dtype, as for sharpness().

Parameters:

input (Tensor) – image with shape (B, C, H, W).
kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both; each a positive odd integer.
sigma (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) in pixels, as a tuple or a tensor.
border_type (str, optional) – padding mode, 'constant', 'reflect', 'replicate' or 'circular'. Default: "reflect"

Return type:

Tensor

Returns:

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

See also

UnsharpMask: the module form.
gaussian_blur2d(): the blur alone.
sharpness(): blends the image with a blurred copy by a factor you choose.

Example

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

Smooth an image, keeping its strong edges, with stored bilateral parameters (module form).

Try in browser

blur = BilateralBlur(kernel_size, sigma_color, sigma_space) stores its arguments, and out = blur(input) is bilateral_blur() on a (B, C, H, W) image.

Convention:: See the Convention block on bilateral_blur().

Parameters:

kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
sigma_color (float | Tensor) – standard deviation of the colour weight, as in bilateral_blur().
sigma_space (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) of the spatial weight in pixels.
border_type (str, optional) – padding mode, as in bilateral_blur(). Default: "reflect"
color_distance_type (str, optional) – 'l1' or 'l2' colour distance. Default: "l1"

Shape:

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

Raises:

BaseError – if an entry of kernel_size is even or not positive; raised from the constructor.
BaseError – if sigma_color is not positive; raised from forward.
BaseError – if the batch of a tensor sigma_color or sigma_space is neither 1 nor the input batch; raised from forward.

See also

bilateral_blur(): the one-call form.
JointBilateralBlur: the colour distance comes from a second image.

Example

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

Blur a feature map and downsample it by a stored stride (module form).

Try in browser

pool = BlurPool2D(kernel_size, stride) stores stride and the normalized binomial kernel as the buffer kernel, which is not in the state dict. out = pool(input) is blur_pool2d() on a (B, C, H, W) map.

Convention:: See the Convention block on blur_pool2d().

Parameters:

kernel_size (tuple[int, int] | int) – size of the square binomial blur kernel, k or (k, k).
stride (int, optional) – step between the kept pixels. Default: 2

Shape:

Input: (B, C, H, W) or (C, H, W)
Output: (B, C, H_out, W_out), or (C, H_out, W_out) for a (C, H, W) input, with H_out and W_out as in blur_pool2d().

See also

blur_pool2d(): the one-call form.
MaxBlurPool2D: takes a local maximum before the blur.

Example

>>> 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=True)[source]#

Blur an image with a stored kernel_size mean window (module form).

Try in browser

blur = BoxBlur(kernel_size) stores its arguments, and out = blur(input) is box_blur() on a (B, C, H, W) image.

Convention:: See the Convention block on box_blur().

Parameters:

kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
border_type (str, optional) – padding mode, as in box_blur(). Default: "reflect"
separable (bool, optional) – True applies two 1D passes, False one 2D kernel. Default: True

Shape:

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

Raises:: BaseError – if an entry of kernel_size is not positive; raised from the constructor.

See also

box_blur(): the one-call form, with the roundoff limit of separable.
GaussianBlur2d: weights the window by a Gaussian.

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.EdgeAwareBlurPool2D(kernel_size, edge_threshold=1.25, edge_dilation_kernel_size=3)[source]#

Blur a feature map at its size and keep the pixels on edges (module form).

Try in browser

blur = EdgeAwareBlurPool2D(kernel_size) stores its arguments, and out = blur(input) is edge_aware_blur_pool2d() on a (B, C, H, W) map.

Convention:: See the Convention block on edge_aware_blur_pool2d().

Parameters:

kernel_size (tuple[int, int] | int) – size of the square binomial blur kernel, k or (k, k).
edge_threshold (float, optional) – intensity ratio between pixels 4 apart above which a pixel counts as an edge and keeps its value. It must be greater than 1. Default: 1.25
edge_dilation_kernel_size (int, optional) – kernel size for dilating the edge map. It must be an odd positive integer. Default: 3

Shape:

Input: (B, C, H, W) or (C, H, W)
Output: the shape of the input

See also

edge_aware_blur_pool2d(): the one-call form.
BlurPool2D: blurs everywhere and downsamples.

Example

>>> input = torch.rand(1, 2, 8, 8)
>>> EdgeAwareBlurPool2D(3)(input).shape
torch.Size([1, 2, 8, 8])

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

Max-pool a feature map, then blur and downsample it (module form).

Try in browser

pool = MaxBlurPool2D(kernel_size, stride, max_pool_size) stores its arguments and the binomial kernel buffer kernel of BlurPool2D. out = pool(input) is max_blur_pool2d() on a (B, C, H, W) map, and equals nn.Sequential(nn.MaxPool2d(max_pool_size, stride=1), BlurPool2D(kernel_size, stride)).

Convention:: See the Convention block on max_blur_pool2d().

Parameters:

kernel_size (tuple[int, int] | int) – size of the square binomial blur kernel, k or (k, k).
stride (int, optional) – step between the kept pixels of the blur. Default: 2
max_pool_size (int, optional) – size of the max-pooling window. Default: 2
ceil_mode (bool | None, optional) – deprecated, has no effect. The max pool runs at stride 1, where floor and ceil rounding give the same size, and the strided blur has no rounding mode. Passing it emits a DeprecationWarning; it will be removed in a future release. Default: None

Shape:

Input: (B, C, H, W) or (C, H, W)
Output: (B, C, H_out, W_out), or (C, H_out, W_out) for a (C, H, W) input, with H_out and W_out as in max_blur_pool2d().

See also

max_blur_pool2d(): the one-call form.
BlurPool2D: blurs without the max pool.

Example

>>> 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)
>>> 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, border_type='reflect')[source]#

Blur an image with a stored kernel_size median window (module form).

Try in browser

blur = MedianBlur(kernel_size) stores its arguments, and out = blur(input) is median_blur() on a (B, C, H, W) image.

Convention:: See the Convention block on median_blur().

Parameters:

kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
border_type (str, optional) – padding mode, as in median_blur(). Default: "reflect"

Shape:

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

See also

median_blur(): the one-call form.
BoxBlur: takes the mean of the window.

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

Blur an image with a stored Gaussian kernel size and sigma (module form).

Try in browser

blur = GaussianBlur2d(kernel_size, sigma) stores its arguments, and out = blur(input) is gaussian_blur2d() on a (B, C, H, W) image.

Convention:: See the Convention block on gaussian_blur2d().

Parameters:

kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
sigma (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) in pixels, as a tuple or a tensor.
border_type (str, optional) – padding mode, as in gaussian_blur2d(). Default: "reflect"
separable (bool, optional) – True applies two 1D passes, False one 2D kernel. Default: True

Shape:

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

See also

gaussian_blur2d(): the one-call form.
BoxBlur: a uniform average, with no sigma.

Example

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

Smooth an image with a stored guided filter (module form).

Try in browser

blur = GuidedBlur(kernel_size, eps) stores its arguments, and out = blur(guidance, input) is guided_blur() on a (B, C_g, H, W) guidance and a (B, C_i, H, W) image.

Convention:: See the Convention block on guided_blur().

Parameters:

kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
eps (float) – regularization of the local variance, as in guided_blur().
border_type (str, optional) – padding mode, as in guided_blur(). Default: "reflect"
subsample (int, optional) – subsampling factor of the fast guided filter, a positive integer; 1 means none. Default: 1
separable (bool, optional) – True applies the window means as two 1D passes. Default: False

Raises:

TypeCheckError – if subsample is not an integer (NumPy integers are accepted).
BaseError – if subsample is not positive, or is a bool. Both are raised by the constructor.

Shape:

Input: (B, C_g, H, W), (B, C_i, H, W)
Output: (B, C_i, H, W)

See also

guided_blur(): the one-call form.
JointBilateralBlur: another filter that follows a guidance image, with the input first.

Example

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

Smooth an image, keeping the edges found in a second image (module form).

Try in browser

blur = JointBilateralBlur(kernel_size, sigma_color, sigma_space) stores its arguments, and out = blur(input, guidance) is joint_bilateral_blur() on a (B, C, H, W) image and a (B, C_g, H, W) guidance.

Convention:: See the Convention block on joint_bilateral_blur().

Parameters:

kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
sigma_color (float | Tensor) – standard deviation of the colour weight, as in bilateral_blur().
sigma_space (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) of the spatial weight in pixels.
border_type (str, optional) – padding mode, as in bilateral_blur(). Default: "reflect"
color_distance_type (str, optional) – 'l1' or 'l2' colour distance. Default: "l1"

Shape:

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

Raises:

BaseError – if an entry of kernel_size is even or not positive; raised from the constructor.
BaseError – if sigma_color is not positive; raised from forward.
BaseError – if the batch of a tensor sigma_color or sigma_space is neither 1 nor the input batch; raised from forward.

See also

joint_bilateral_blur(): the one-call form.
BilateralBlur: the colour distance comes from the input itself.

Example

>>> 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='reflect', mode='nearest')[source]#

Blur an image along a stored motion angle and direction (module form).

Try in browser

blur = MotionBlur(kernel_size, angle, direction) stores its arguments, and out = blur(input) is motion_blur() on a (B, C, H, W) image.

Convention:: See the Convention block on motion_blur().

Parameters:

kernel_size (int) – width and height of the kernel, an odd integer of at least 3.
angle (float) – angle of the streak in degrees, anti-clockwise.
direction (float) – weighting of the streak in [-1, 1], as in motion_blur().
border_type (str, optional) – padding mode, as in motion_blur(). Default: "reflect"
mode (str, optional) – interpolation of the rotated kernel, 'bilinear' or 'nearest'. Default: "nearest"

Shape:

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

See also

motion_blur(): the one-call form.
MotionBlur3D: the same for volumes.

Example

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

class kornia.filters.MotionBlur3D(kernel_size, angle, direction, border_type='replicate', mode='nearest')[source]#

Blur a volume along a stored motion angle and direction (module form).

Try in browser

blur = MotionBlur3D(kernel_size, angle, direction) stores its arguments, and out = blur(input) is motion_blur3d() on a (B, C, D, H, W) volume. A scalar angle is stored as that value for all three components.

Convention:: See the Convention block on motion_blur3d().

Parameters:

kernel_size (int) – width, height and depth of the kernel, an odd integer of at least 3.
angle (float | tuple[float, float, float] | list[float] | Tensor) – one axis-angle vector (rx, ry, rz) in degrees, as in motion_blur3d(). A float, a sequence of three floats, or a (B, 3) tensor.
direction (float | Tensor) – weighting of the streak in [-1, 1], as in motion_blur3d().
border_type (str, optional) – padding mode, as in motion_blur3d(). Default: "replicate"
mode (str, optional) – interpolation of the rotated kernel, 'bilinear' or 'nearest'. Default: "nearest"

Shape:

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

See also

motion_blur3d(): the one-call form.
MotionBlur: the same for images.

Example

>>> input = torch.rand(2, 4, 5, 7, 9)
>>> motion_blur = MotionBlur3D(3, 35., 0.5)
>>> output = motion_blur(input)  # 2x4x5x7x9

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

Sharpen an image with a stored Gaussian kernel size and sigma (module form).

Try in browser

sharpen = UnsharpMask(kernel_size, sigma) stores its arguments, and out = sharpen(input) is unsharp_mask() on a (B, C, H, W) image.

Convention:: See the Convention block on unsharp_mask().

Parameters:

kernel_size (tuple[int, int] | int) – window (kH, kW) in pixels, or one integer for both.
sigma (tuple[float, float] | Tensor) – standard deviation (sigma_y, sigma_x) in pixels, as a tuple or a tensor.
border_type (str, optional) – padding mode, as in unsharp_mask(). Default: "reflect"

Shape:

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

Note

See a working example here.

See also

unsharp_mask(): the one-call form.
GaussianBlur2d: the blur alone.

Example

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

Dissolving#

class kornia.filters.StableDiffusionDissolving(version='1.5', **kwargs)[source]#

Dissolve an image with one reverse-diffusion step of a Stable Diffusion model.

dissolved = StableDiffusionDissolving(version)(input, step_number) encodes a (B, 3, H, W) image with the model’s VAE, takes one reverse-diffusion step at step_number, an index into the model’s 1000-step schedule from 0 to 999, and decodes the result [SZZ+24]. It needs the optional diffusers package, and the constructor loads the checkpoint with from_pretrained.

SD 1.4	SD 1.5	SD XL
		SD XL example image pending — see #4601.

Convention:

input is an image in \([0, 1]\), rescaled to \([-1, 1]\) before encoding and not clamped; the result is clamped to \([0, 1]\).
The model runs under torch.no_grad(): the result has no gradient, and it lives on the model’s device in the VAE’s dtype.
The latent is sampled, so two calls on the same input differ.

Parameters:

version (str, optional) – the version of the stable diffusion model, "1.4", "1.5" or "xl". SD 1.x removes more detail than SD XL. Default: "1.5"
**kwargs (Any) – additional arguments for from_pretrained.

Raises:

NotImplementedError – if version is none of the three above.

See also

RandomDissolving: clamps the input and applies it to a batch with a sampled step and a probability.