Blurring

Functions

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

Blur a torch.Tensor using a Bilateral filter.

Try in browser

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.

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.

Parameters:

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

• kernel_size (tuple[int, int] | int) – the size of the kernel. Each entry must be a positive odd integer.

• sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges. It must be positive. A float is shared by the batch; a torch.Tensor has shape \((1,)\), shared by the batch, or \((B,)\), one value per sample.

• sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d(). A tuple of two floats is shared by the batch; a torch.Tensor has shape \((1, 2)\), shared by the batch, or \((B, 2)\), one row per sample.

• 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. Default: 'l1'.

Return type:

Tensor

Returns:

the blurred torch.Tensor 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.

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)

Compute blurs and downsample a given feature map.

Try in browser

See BlurPool2D for details.

See [Zha19] for more details.

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

Parameters:

• input (Tensor) – torch.Tensor to apply operation to.

• kernel_size (tuple[int, int] | int) – the size of the square binomial blur kernel.

• stride (int, optional) – stride for pooling. Default: 2

Shape:

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

• Output: \((B, C, H_{out}, W_{out})\), 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 transformed torch.Tensor.

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=True)

Blur an image using the box filter.

Try in browser

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

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) – 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) – use two one-dimensional passes (the default), reducing work for larger kernels. The two implementations 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 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.edge_aware_blur_pool2d(input, kernel_size, edge_threshold=1.25, edge_dilation_kernel_size=3, epsilon=1e-6)

Blur the input torch.Tensor while maintaining its edges.

Try in browser

Convention:

• Nothing is downsampled: the output has the input’s shape.

• 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) – the input image to blur with shape \((B, C, H, W)\).

• kernel_size (tuple[int, int] | int) – the size of the square binomial blur kernel.

• 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) – the kernel size for dilating the edges. It must be an odd positive integer. Default: 3

• epsilon (float, optional) – for numerical stability. Default: 1e-6

Return type:

Tensor

Returns:

The blurred torch.Tensor of shape \((B, C, H, W)\).

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

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

Try in browser

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

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) – 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 \((1, 2)\), shared by the batch, or \((B, 2)\), one row per sample. 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', case-insensitive. 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:

• TypeCheckError – if input is not a torch.Tensor.

• ShapeError – if input is not 4D.

• BaseError – if sigma values are 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

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)

Blur a torch.Tensor using a Guided filter.

Try in browser

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

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) – the guidance torch.Tensor with shape \((B,C_g,H,W)\).

• input (Tensor) – the input torch.Tensor with shape \((B,C_i,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, a positive integer (a bool is rejected). Guidance and input are subsampled by nearest neighbour to max(H // subsample, 1) rows and max(W // subsample, 1) columns: every subsample-th pixel when H is a multiple of subsample (likewise W), and otherwise, for row i, the pixel nearest to (i + 0.5) * H / rows - subsample / 2 (a tie rounds up), which keeps the subsampled grid aligned with the bilinear upsample of the coefficient maps as it is on a multiple; a single pixel, the first, on an axis shorter than subsample. H and W need not be multiples of it: the coefficient maps are resized back to the size of the input. Default: 1 (no subsampling)

• separable (bool, optional) – use two one-dimensional box-filter passes, reducing work for large windows. Default: False

Return type:

Tensor

Returns:

the blurred torch.Tensor with same shape as input \((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.

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

Blur a torch.Tensor using a Joint Bilateral filter.

Try in browser

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.

Convention:

• See the Convention block on bilateral_blur(); the colour distances are taken in guidance, and input is what gets averaged.

• 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) – the input torch.Tensor with shape \((B,C,H,W)\).

• guidance (Tensor) – the guidance torch.Tensor with shape \((B,C_g,H,W)\).

• kernel_size (tuple[int, int] | int) – the size of the kernel. Each entry must be a positive odd integer.

• sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges. It must be positive. A float is shared by the batch; a torch.Tensor has shape \((1,)\), shared by the batch, or \((B,)\), one value per sample.

• sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d(). A tuple of two floats is shared by the batch; a torch.Tensor has shape \((1, 2)\), shared by the batch, or \((B, 2)\), one row per sample.

• 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. Default: 'l1'.

Return type:

Tensor

Returns:

the blurred torch.Tensor 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.

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=None)

Compute pools and blurs and downsample a given feature map.

Try in browser

See MaxBlurPool2D for details.

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 and the border.

Parameters:

• input (Tensor) – torch.Tensor to apply operation to.

• kernel_size (tuple[int, int] | int) – the size of the square binomial blur kernel.

• stride (int, optional) – stride of the blur step. Default: 2

• max_pool_size (int, optional) – the kernel size for max pooling. 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

Return type:

Tensor

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, border_type='reflect')

Blur an image using the median filter.

Try in browser

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) – the input image with shape \((B,C,H,W)\).

• kernel_size (tuple[int, int] | int) – the blurring kernel size. Each entry must be a positive odd integer.

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

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='reflect', mode='nearest')

Perform motion blur on torch.Tensor images.

Try in browser

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

• kernel_size (int) – motion kernel width and height, an odd integer of at least 3.

• 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: 'reflect', which leaves a constant image constant like box_blur() and gaussian_blur2d(), but needs each spatial axis longer than kernel_size // 2. 'constant' zero-pads, so pixels whose kernel reaches past an edge (at most kernel_size // 2 from it) are pulled toward 0.

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

Perform motion blur on 3D volumes (5D torch.Tensor).

Try in browser

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) – the input torch.Tensor with shape \((B, C, D, H, W)\).

• kernel_size (int) – motion kernel width, height and depth, 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(). If torch.Tensor, it must be \((B, 3)\).

• 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: 'replicate', which leaves a constant volume constant like filter3d(), at any volume size ('reflect' needs each axis longer than kernel_size // 2, so it raises on a thin volume such as D = 1). 'constant' zero-pads, so voxels whose kernel reaches past a face (at most kernel_size // 2 from it) are pulled toward 0.

• 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, D, H, W)\).

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

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

Try in browser

Convention:

• The blur in the formula above is gaussian_blur2d() with the same kernel_size, sigma and border_type, and the detail it removes is added back with a fixed gain of 1. See the Convention block on gaussian_blur2d() 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) – 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 sharpened 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')

Blur a torch.Tensor using a Bilateral filter.

Try in browser

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.

Convention:

See the Convention block on bilateral_blur().

Parameters:

• kernel_size (tuple[int, int] | int) – the size of the kernel. Each entry must be a positive odd integer.

• sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges. It must be positive. A float is shared by the batch; a torch.Tensor has shape \((1,)\), shared by the batch, or \((B,)\), one value per sample.

• sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d(). A tuple of two floats is shared by the batch; a torch.Tensor has shape \((1, 2)\), shared by the batch, or \((B, 2)\), one row per sample.

• 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. Default: 'l1'.

Returns:

the blurred input torch.Tensor.

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.

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)

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

Try in browser

See [Zha19] for more details.

Convention:

See the Convention block on blur_pool2d().

Parameters:

• kernel_size (tuple[int, int] | int) – the size of the square binomial blur kernel.

• stride (int, optional) – stride for pooling. Default: 2

Shape:

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

• Output: \((B, C, H_{out}, W_{out})\), where

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

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=True)

Blur an image using the box filter.

Try in browser

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

Convention:

See the Convention block on box_blur().

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) – use two one-dimensional passes (the default), reducing work for larger kernels. The two implementations 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

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

Apply an edge-aware anti-aliasing blur that keeps the input size.

Try in browser

This module blurs while preserving edges by using an edge-intensity threshold.

Convention:

See the Convention block on edge_aware_blur_pool2d().

Parameters:

• kernel_size (tuple[int, int] | int) – The size of the square binomial blur kernel.

• edge_threshold (float, optional) – The 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) – The kernel size for dilating the edge map. It must be an odd positive integer. Default: 3.

class kornia.filters.MaxBlurPool2D(kernel_size, stride=2, max_pool_size=2, ceil_mode=None)

Compute pools and blurs and downsample a given feature map.

Try in browser

Equivalent to nn.Sequential(nn.MaxPool2d(max_pool_size, stride=1), BlurPool2D(kernel_size, stride)).

See [Zha19] for more details.

Convention:

See the Convention block on max_blur_pool2d().

Parameters:

• kernel_size (tuple[int, int] | int) – the size of the square binomial blur kernel.

• stride (int, optional) – stride of the blur step. Default: 2

• max_pool_size (int, optional) – the kernel size for max pooling. 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)\)

• Output: \((B, C, H_{out}, W_{out})\), 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\]

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

Blur an image using the median filter.

Try in browser

Convention:

See the Convention block on median_blur().

Parameters:

• kernel_size (tuple[int, int] | int) – the blurring kernel size.

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

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)

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

Try in browser

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

Convention:

See the Convention block on gaussian_blur2d().

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)

Blur a torch.Tensor using a Guided filter.

Try in browser

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

Convention:

See the Convention block on guided_blur().

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, a positive integer (a bool is rejected). Guidance and input are subsampled by nearest neighbour to max(H // subsample, 1) rows and max(W // subsample, 1) columns: every subsample-th pixel when H is a multiple of subsample (likewise W), and otherwise, for row i, the pixel nearest to (i + 0.5) * H / rows - subsample / 2 (a tie rounds up), which keeps the subsampled grid aligned with the bilinear upsample of the coefficient maps as it is on a multiple; a single pixel, the first, on an axis shorter than subsample. H and W need not be multiples of it: the coefficient maps are resized back to the size of the input. Default: 1 (no subsampling)

• separable (bool, optional) – use two one-dimensional box-filter passes, reducing work for large windows. Default: False

Returns:

the blurred input torch.Tensor.

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

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

Blur a torch.Tensor using a Joint Bilateral filter.

Try in browser

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.

Convention:

See the Convention block on joint_bilateral_blur().

Parameters:

• kernel_size (tuple[int, int] | int) – the size of the kernel. Each entry must be a positive odd integer.

• sigma_color (float | Tensor) – the standard deviation for intensity/color Gaussian kernel. Smaller values preserve more edges. It must be positive. A float is shared by the batch; a torch.Tensor has shape \((1,)\), shared by the batch, or \((B,)\), one value per sample.

• sigma_space (tuple[float, float] | Tensor) – the standard deviation for spatial Gaussian kernel. This is similar to sigma in gaussian_blur2d(). A tuple of two floats is shared by the batch; a torch.Tensor has shape \((1, 2)\), shared by the batch, or \((B, 2)\), one row per sample.

• 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. Default: 'l1'.

Returns:

the blurred input torch.Tensor.

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.

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='reflect', mode='nearest')

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

Try in browser

Convention:

See the Convention block on motion_blur().

Parameters:

• kernel_size (int) – motion kernel width and height, an odd integer of at least 3.

• 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: 'reflect', which leaves a constant image constant like box_blur() and gaussian_blur2d(), but needs each spatial axis longer than kernel_size // 2. 'constant' zero-pads, so pixels whose kernel reaches past an edge (at most kernel_size // 2 from it) are pulled toward 0.

• 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.MotionBlur3D(kernel_size, angle, direction, border_type='replicate', mode='nearest')

Blur 3D volumes (5D torch.Tensor) using the motion filter.

Try in browser

Convention:

See the Convention block on motion_blur3d().

Parameters:

• kernel_size (int) – motion kernel width, height and depth, an odd integer of at least 3.

• angle (float | tuple[float, float, float] | list[float] | Tensor) – Components of one Rodrigues axis-angle vector (rx, ry, rz) in degrees, not Euler angles; see get_motion_kernel3d(). A scalar sets all three components to the same value; a three-element sequence sets each component, and a tensor must have shape \((B, 3)\).

• 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.

• border_type (str, optional) – the padding mode to be applied before convolving. The expected modes are: 'constant', 'reflect', 'replicate' or 'circular'. Default: 'replicate', which leaves a constant volume constant like filter3d(), at any volume size ('reflect' needs each axis longer than kernel_size // 2, so it raises on a thin volume such as D = 1). 'constant' zero-pads, so voxels whose kernel reaches past a face (at most kernel_size // 2 from it) are pulled toward 0.

• mode (str, optional) – interpolation mode for rotating the kernel. 'bilinear' or 'nearest'. Default: "nearest"

Returns:

the blurred input torch.Tensor.

Shape:

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

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

Examples

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

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

Try in browser

Convention:

See the Convention block on unsharp_mask().

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

Dissolving

class kornia.filters.StableDiffusionDissolving(version='1.5', **kwargs)

Perform dissolving transformation using StableDiffusion models.

Based on [SZZ+24], the dissolving transformation is essentially applying one-step reverse diffusion. Our implementation currently supports HuggingFace implementations of SD 1.4, 1.5 and SD XL (replacing the discontinued SD 2.1). SD 1.X tends to remove more details than SD XL.

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

Convention:

See the Convention block on RandomDissolving.

Parameters:

• version (str, optional) – the version of the stable diffusion model. Options: “1.4”, “1.5”, “xl”. Default: "1.5"

• **kwargs (Any) – additional arguments for .from_pretrained.