Kernels#

Kernel generators, useful with the Filtering API or to inspect what a filter applies.

kornia.filters.gaussian(window_size, sigma, *, mean=None, device=None, dtype=None)[source]#

Compute the gaussian values based on the window and sigma values.

Convention:: See the Convention block on get_gaussian_kernel1d(), which validates the size and calls this function; gaussian does not validate it. In a floating dtype, for an even window_size the Gaussian is centred at mean - 0.5: the default mean centres the kernel on the middle of the window, halfway between the two middle samples, and an explicit mean=m centres it at m - 0.5.

Parameters:

window_size (int) – the size which drives the filter amount.
sigma (Tensor | float) – gaussian standard deviation. If a tensor, should be in a shape \((B, 1)\).
mean (Union[float, Tensor, None], optional) – Mean of the Gaussian function (center); see the Convention block for an even window_size. If not provided, it defaults to window_size // 2. A Python int is treated as its float. If a tensor, should be in a shape \((B, 1)\). Default: None
device (Optional[device], optional) – This value will be used if sigma is an int or float. Device desired to compute. Default: None
dtype (Optional[dtype], optional) – This value will be used if sigma is an int or float. Dtype desired for compute. Default: None

Return type:

Tensor

Returns:

A tensor with shape \((B, \text{kernel_size})\), with Gaussian values.

Note

A sigma of zero – and any sigma too small for the window to hold a representable weight – returns the unit-impulse limit of the kernel: all the mass on the sample nearest the mean, split evenly between the two centre taps when window_size is even. The gradient with respect to sigma is zero there, matching the continuous limit.

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

Return Gaussian filter coefficients.

Convention:

In a floating dtype the kernel samples \(\exp(-n^2 / 2\sigma^2)\) at the offsets \(n\) of its taps from its centre, integers for an odd size and half-integers for an even one, and is normalized to sum 1; Filtering names the matching scipy and OpenCV kernels. get_gaussian_erf_kernel1d() integrates the Gaussian over each pixel instead, and get_gaussian_discrete_kernel1d() is the discrete Gaussian.
force_even=True also accepts an even kernel_size, and in a floating dtype the kernel is then symmetric about the middle of the window, (kernel_size - 1) / 2.
A tensor sigma of shape \((B, 1)\) gives one kernel per row.
A Python integer sigma is treated as its floating-point equivalent. With dtype=None, both use the default floating-point dtype.
An integer or bool dtype raises: the taps are fractional, and an integer dtype would also truncate a fractional sigma (#5155).

Parameters:

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

Return type:

Tensor

Returns:

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

Examples

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

A sigma of zero, or one too small for the window to hold a representable weight, returns the unit impulse rather than a kernel of NaN:

>>> get_gaussian_kernel1d(5, 0.0)
tensor([[0., 0., 1., 0., 0.]])
>>> get_gaussian_kernel1d(4, 0.0, force_even=True)
tensor([[0.0000, 0.5000, 0.5000, 0.0000]])

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

Return Gaussian filter coefficients by interpolating the error function.

Adapted from: Project-MONAI/MONAI.

Convention:

See the Convention block on get_gaussian_kernel1d(). In a floating dtype this kernel integrates the Gaussian over each pixel, \(\Phi((n + 1/2) / \sigma) - \Phi((n - 1/2) / \sigma)\) with \(\Phi\) the normal CDF, so it blurs more than the sampled kernel: for \(\sigma\) of about 1 or more, on a window wide enough for the tails, its variance is \(\sigma^2 + 1/12\).
With force_even=True an even kernel is symmetric about the middle of the window, (kernel_size - 1) / 2, as the sampled kernel is.

Parameters:

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

Return type:

Tensor

Returns:

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

Examples

>>> get_gaussian_erf_kernel1d(3, 2.0)
tensor([[0.3195, 0.3611, 0.3195]])
>>> get_gaussian_erf_kernel1d(5, 1.5)
tensor([[0.1226, 0.2331, 0.2887, 0.2331, 0.1226]])
>>> get_gaussian_erf_kernel1d(5, torch.tensor([[1.5], [2.1]]))
tensor([[0.1226, 0.2331, 0.2887, 0.2331, 0.1226],
        [0.1574, 0.2198, 0.2456, 0.2198, 0.1574]])

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

Return Gaussian filter coefficients based on the modified Bessel functions.

Adapted from: Project-MONAI/MONAI.

Convention:

See the Convention block on get_gaussian_kernel1d(). In a floating dtype this kernel is Lindeberg’s discrete Gaussian \(e^{-\sigma^2} I_{|n|}(\sigma^2)\), with \(I_n\) the modified Bessel function of the first kind, normalized over the window: the smoothing kernel of discrete scale space. A float16 or bfloat16 kernel is computed in float32 and rounded to its dtype.
The kernel has kernel_size taps, and kernel_size=1 is the single tap [1.0]. The discrete Gaussian is defined at integer offsets from the centre tap, so there is no even window: an even kernel_size raises with and without force_even.

Parameters:

kernel_size (int) – filter size. It should be odd and positive.
sigma (float | Tensor) – gaussian standard deviation. If a tensor, should be in a shape \((B, 1)\)
force_even (bool, optional) – accepted for parity with the other Gaussian builders. The discrete Gaussian needs an odd kernel_size either way. Default: False
device (Optional[device], optional) – This value will be used if sigma is an int or float. Device desired to compute. Default: None
dtype (Optional[dtype], optional) – This value will be used if sigma is an int or float. Dtype desired for compute. Default: None

Return type:

Tensor

Returns:

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

Examples

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

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

Return Gaussian filter matrix coefficients.

Convention:: See the Convention block on get_gaussian_kernel1d(). kernel_size is (k_y, k_x) and sigma is \((\sigma_y, \sigma_x)\), y first as in the output \((B, k_y, k_x)\), which is the outer product of the two 1d kernels. A tensor sigma of shape \((B, 2)\) gives one kernel per row.

Parameters:

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

Return type:

Tensor

Returns:

2D tensor with gaussian filter matrix coefficients.

Shape:

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

Examples

>>> get_gaussian_kernel2d((5, 5), (1.5, 1.5))
tensor([[[0.0144, 0.0281, 0.0351, 0.0281, 0.0144],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0351, 0.0683, 0.0853, 0.0683, 0.0351],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0144, 0.0281, 0.0351, 0.0281, 0.0144]]])
>>> get_gaussian_kernel2d((3, 5), (1.5, 1.5))
tensor([[[0.0370, 0.0720, 0.0899, 0.0720, 0.0370],
         [0.0462, 0.0899, 0.1123, 0.0899, 0.0462],
         [0.0370, 0.0720, 0.0899, 0.0720, 0.0370]]])
>>> get_gaussian_kernel2d((5, 5), torch.tensor([[1.5, 1.5]]))
tensor([[[0.0144, 0.0281, 0.0351, 0.0281, 0.0144],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0351, 0.0683, 0.0853, 0.0683, 0.0351],
         [0.0281, 0.0547, 0.0683, 0.0547, 0.0281],
         [0.0144, 0.0281, 0.0351, 0.0281, 0.0144]]])

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

Return Gaussian filter matrix coefficients.

Convention:: See the Convention block on get_gaussian_kernel1d(). kernel_size is (k_z, k_y, k_x) and sigma is \((\sigma_z, \sigma_y, \sigma_x)\), z first as in the output \((B, k_z, k_y, k_x)\), which is the outer product of the three 1d kernels. A tensor sigma of shape \((B, 3)\) gives one kernel per row.

Parameters:

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

Return type:

Tensor

Returns:

3D tensor with gaussian filter matrix coefficients.

Shape:

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

Examples

>>> get_gaussian_kernel3d((3, 3, 3), (1.5, 1.5, 1.5))
tensor([[[[0.0292, 0.0364, 0.0292],
          [0.0364, 0.0455, 0.0364],
          [0.0292, 0.0364, 0.0292]],

         [[0.0364, 0.0455, 0.0364],
          [0.0455, 0.0568, 0.0455],
          [0.0364, 0.0455, 0.0364]],

         [[0.0292, 0.0364, 0.0292],
          [0.0364, 0.0455, 0.0364],
          [0.0292, 0.0364, 0.0292]]]])
>>> torch.allclose(get_gaussian_kernel3d((3, 3, 3), (1.5, 1.5, 1.5)).sum(), torch.tensor(1.0))
True
>>> get_gaussian_kernel3d((3, 3, 3), (1.5, 1.5, 1.5)).shape
torch.Size([1, 3, 3, 3])
>>> get_gaussian_kernel3d((3, 7, 5), torch.tensor([[1.5, 1.5, 1.5]])).shape
torch.Size([1, 3, 7, 5])

kornia.filters.get_box_kernel1d(kernel_size, *, device=None, dtype=None)[source]#

Return a 1-D box filter.

Convention:

For a floating dtype every tap is 1 / kernel_size; an even kernel_size is accepted.
The kernel is a contiguous tensor, so an in-place edit changes only the taps it addresses.
An integer or bool dtype raises: it would truncate 1 / kernel_size to 0 (#5155).

Parameters:

kernel_size (int) – the size of the kernel.
device (Optional[device], optional) – the desired device of returned tensor. Default: None
dtype (Optional[dtype], optional) – the desired data type of returned tensor. Default: None

Return type:

Tensor

Returns:

A tensor with shape \((1, \text{kernel\_size})\), filled with the value \(\frac{1}{\text{kernel\_size}}\) for a floating dtype.

kornia.filters.get_box_kernel2d(kernel_size, *, device=None, dtype=None)[source]#

Return a 2-D box filter.

Convention:: See the Convention block on get_box_kernel1d(); kernel_size is (k_y, k_x).

Parameters:

kernel_size (tuple[int, int] | int) – the size of the kernel, an integer or (k_y, k_x).
device (Optional[device], optional) – the desired device of returned tensor. Default: None
dtype (Optional[dtype], optional) – the desired data type of returned tensor. Default: None

Return type:

Tensor

Returns:

A tensor with shape \((1, \text{kernel\_size}[0], \text{kernel\_size}[1])\), filled with the value \(\frac{1}{\text{kernel\_size}[0] \times \text{kernel\_size}[1]}\) for a floating dtype.

kornia.filters.get_binary_kernel2d(window_size, *, device=None, dtype=torch.float32)[source]#

Create a binary kernel to extract the patches.

If the window size is HxW will create a (H*W)x1xHxW kernel.

Convention:: Channel i is one-hot at (i // k_x, i % k_x) for window_size=(k_y, k_x), in row-major order, so torch.nn.functional.conv2d() of an image with the kernel stacks each pixel’s neighbourhood in that order, the layout median_blur() builds on.

Parameters:

window_size (tuple[int, int] | int) – the window size, an integer or (k_y, k_x).
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (dtype, optional) – tensor dtype desired to create the kernel Default: torch.float32

Return type:

Tensor

Returns:

the kernel with shape \((k_y k_x, 1, k_y, k_x)\).

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

Return Hanning (also known as Hann) kernel.

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

Convention:: This is the symmetric window of size \(M\): both end taps are 0, so only \(M - 2\) samples carry weight, and it is not normalized, its taps summing to \((M - 1) / 2\). An even size is accepted and is symmetric about \((M - 1) / 2\). Filtering names the matching numpy and torch windows.

Parameters:

kernel_size (int) – The size of the kernel, an integer greater than 2.
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (Optional[dtype], optional) – tensor dtype desired to create the kernel Default: None

Return type:

Tensor

Returns:

1D tensor with Hanning filter coefficients. Shape \((\text{kernel_size})\).

Examples

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

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

Return 2d Hanning kernel.

Convention:: See the Convention block on get_hanning_kernel1d(). For kernel_size=(k_y, k_x) the kernel is the outer product of the 1d windows of sizes k_y (along H) and k_x (along W).

Parameters:

kernel_size (tuple[int, int] | int) – The size of the kernel for the filter, an integer or (k_y, k_x), each greater than 2.
device (Union[str, device, None], optional) – tensor device desired to create the kernel Default: None
dtype (Optional[dtype], optional) – tensor dtype desired to create the kernel Default: None

Return type:

Tensor

Returns:

2D tensor with Hanning filter coefficients. Shape \((k_y, k_x)\).

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

Return the coefficients of a 1D Laplacian filter.

Convention:

In a floating dtype, or a signed integer one wide enough to hold 1 - kernel_size, the kernel is all ones with the centre tap set to 1 - kernel_size, so it sums to 0. Size 3 is the second difference [1, -2, 1]; a larger size is not a wider second difference, and size 5 answers 5 to a unit second derivative.
The negative centre makes the response positive where the values curve upwards.
An integer or bool dtype that cannot hold 1 - kernel_size raises, so uint8 and bool always do, rather than wrap the centre (to 252 for size 5 in uint8) (#5155).

Parameters:

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

Return type:

Tensor

Returns:

1D tensor with laplacian filter coefficients.

Raises:

BaseError – if kernel_size is even, not positive, or 1: a single tap is the all-zero kernel.

Shape:

Output: \((\text{kernel_size})\)

Examples

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

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

Return Laplacian filter matrix coefficients.

Convention:: See the Convention block on get_laplacian_kernel1d(): in a floating dtype, or a signed integer one wide enough to hold \(1 - k_y k_x\), all ones with the centre set to \(1 - k_y k_x\) for kernel_size=(k_y, k_x). Size 3 is the 8-neighbour stencil, which answers 3 to a unit \(\partial_{xx}\) or \(\partial_{yy}\), so it estimates \(3 \nabla^2\); size 5 estimates \(25 \nabla^2\). Filtering compares it with the scipy, OpenCV and scikit-image Laplacians.

Parameters:

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

Return type:

Tensor

Returns:

2D tensor with laplacian filter matrix coefficients.

Raises:

BaseError – if a size is even or not positive, if kernel_size is a sequence of other than 2 sizes, or if it is 1 or (1, 1): a \(1 \times 1\) kernel is the all-zero kernel.

Shape:

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

Examples

>>> get_laplacian_kernel2d(3)
tensor([[ 1.,  1.,  1.],
        [ 1., -8.,  1.],
        [ 1.,  1.,  1.]])
>>> get_laplacian_kernel2d(5)
tensor([[  1.,   1.,   1.,   1.,   1.],
        [  1.,   1.,   1.,   1.,   1.],
        [  1.,   1., -24.,   1.,   1.],
        [  1.,   1.,   1.,   1.,   1.],
        [  1.,   1.,   1.,   1.,   1.]])

kornia.filters.laplacian_1d(window_size, *, device=None, dtype=torch.float32)[source]#

Return the 1D Laplacian kernel of get_laplacian_kernel1d() without checking the size.

Convention:: See the Convention block on get_laplacian_kernel1d(), which validates the size and calls this function. laplacian_1d accepts any positive size; an even one puts the negative tap at window_size // 2, off the middle of the kernel.

Parameters:

window_size (int) – the number of taps.
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (dtype, optional) – tensor dtype desired to create the kernel Default: torch.float32

Return type:

Tensor

Returns:

1D tensor with shape \((\text{window_size},)\).

kornia.filters.get_spatial_gradient_kernel2d(mode, order, *, device=None, dtype=None)[source]#

Return kernel for 1st or 2nd order image gradients.

Uses one of the following operators: sobel, diff.

Convention:

order=1 stacks \((\partial_x, \partial_y)\) along the first axis and order=2 stacks \((\partial_{xx}, \partial_{xy}, \partial_{yy})\). Correlated with an image, as filter2d() does, an order=1 channel is positive where the values increase with the column (x) or the row (y), and an order=2 channel is positive on \(x^2\), \(xy\) and \(y^2\) respectively.
The kernels are raw integer stencils, not derivative estimates. Per unit slope Sobel answers 8 and 'diff' answers 2; per unit second derivative Sobel answers 64 on all three channels, while 'diff' answers 1 on \(\partial_{xx}\) and \(\partial_{yy}\) and 4 on \(\partial_{xy}\).
mode is case-insensitive: 'Sobel' is 'sobel'.

Parameters:

mode (str) – 'sobel' or 'diff'.
order (int) – the derivative order, 1 or 2.
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (Optional[dtype], optional) – tensor dtype desired to create the kernel Default: None

Return type:

Tensor

Returns:

the kernels with shape \((2, 3, 3)\) for order=1, and \((3, 5, 5)\) (Sobel) or \((3, 3, 3)\) (diff) for order=2.

kornia.filters.get_spatial_gradient_kernel3d(mode, order, device=None, dtype=None)[source]#

Return kernel for 1st or 2nd order gradients of a volume.

Convention:

Only mode='diff' exists; 'sobel' passes the mode check and raises NotImplementedError.
order=1 stacks \((\partial_x, \partial_y, \partial_z)\) and order=2 stacks \((\partial_{xx}, \partial_{yy}, \partial_{zz}, \partial_{xy}, \partial_{yz}, \partial_{xz})\), an order that differs from the 2d \((\partial_{xx}, \partial_{xy}, \partial_{yy})\). The stack has a singleton second axis that get_spatial_gradient_kernel2d() lacks.
In a floating dtype every channel is in derivative units: it answers 1 to a unit slope or a unit second derivative, unlike the raw 2d stencils.
mode is case-insensitive: 'Diff' is 'diff'.
An integer or bool dtype raises: it would truncate the half and quarter taps to 0, leaving the first-order channels and the mixed second-order ones all zero (#5155).

Parameters:

mode (str) – 'diff'.
order (int) – the derivative order, 1 or 2.
device (Optional[device], optional) – tensor device desired to create the kernel Default: None
dtype (Optional[dtype], optional) – tensor dtype desired to create the kernel Default: None

Return type:

Tensor

Returns:

the kernels with shape \((3, 1, 3, 3, 3)\) for order=1 and \((6, 1, 3, 3, 3)\) for order=2.

kornia.filters.get_sobel_kernel2d(*, device=None, dtype=None)[source]#

Return 1st order gradient for sobel operator.

Return type:: Tensor

Convention:: See the Convention block on get_spatial_gradient_kernel2d(); this is get_spatial_gradient_kernel2d('sobel', 1), of shape \((2, 3, 3)\).

kornia.filters.get_diff_kernel2d(*, device=None, dtype=None)[source]#

Return 1st order gradient for diff operator.

Return type:: Tensor

Convention:: See the Convention block on get_spatial_gradient_kernel2d(); this is get_spatial_gradient_kernel2d('diff', 1), of shape \((2, 3, 3)\).

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

Return 2D motion blur filter.

Convention:

direction is clamped to [-1, 1] and weighs the line linearly before it is rotated: 1 gives [0.4, 0.3, 0.2, 0.1, 0] along the middle row of a size-5 kernel, heavy at the left end and 0 at the right, so only kernel_size - 1 taps carry weight; -1 mirrors it and 0 is uniform.
angle is in degrees and turns the line counter-clockwise as displayed (row 0 at the top), as rotate() does: at 90 the heavy end moves from the left to the bottom.
Because filter2d() correlates, the streak that the kernel draws from a bright point is heaviest on the side opposite the kernel’s heavy end: to the point’s right at angle=0, direction=1.
The rotation resamples the line with mode: 'nearest' copies each pixel from the nearest tap, so the number of taps changes with the angle (3 at 45 degrees, 7 at 25 for a size-5 line), and 'bilinear' spreads the weight off the line.
A floating tensor angle of shape \((B,)\) gives \((B, k, k)\) in its dtype. A tensor direction must match it in length, dtype and device; a float direction is not broadcast, so it raises for B > 1.
With 'nearest', each pixel copies the tap nearest to its source under the inverse rotation, picked with exact arithmetic: where the source falls exactly between two taps, such as at 30 or 120 degrees, the tie goes to the even coordinate, as torch.nn.functional.grid_sample breaks it. The kernel is the same on every device and dtype, for every full turn added to the angle, and with torch.compile.

Parameters:

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

Return type:

Tensor

Returns:

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

Examples

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

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

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

Return 3D motion blur filter.

Convention:: See the Convention block on get_motion_kernel2d() for direction and mode. angle is a Rodrigues axis-angle vector (rx, ry, rz) in degrees, as applied by rotate3d(): its direction is the rotation axis and its norm is the rotation angle. rotate3d() and the 3D motion blurs call the components yaw, pitch and roll, but they are not composed Euler rotations. The unrotated line lies along x, so with the default mode='nearest' yaw alone leaves the kernel unchanged ('bilinear' resamples it off the line); a positive pitch alone turns the line’s -x end, the heavy end for a positive direction, towards +z, and a positive roll alone turns the line clockwise as displayed, the opposite of the 2d angle. With 'nearest', each voxel copies the tap nearest to its source under the inverse rotation, picked with exact arithmetic: where the source falls exactly between two taps, such as at a pitch or roll of 30 or 120 degrees, the tie goes to the even coordinate, as torch.nn.functional.grid_sample breaks it. The kernel is the same on every device and dtype and with torch.compile.

Parameters:

kernel_size (int) – motion kernel width, height and depth, an odd integer of at least 3.
angle (Tensor | tuple[float, float, float]) – Rodrigues axis-angle vector (rx, ry, rz) in degrees, not Euler angles. If tensor, it must be \((B, 3)\). If tuple, it must be (rx, ry, rz).
direction (Tensor | float, optional) – forward/backward direction of the motion blur. Lower values towards -1.0 will point the motion blur towards the back (with angle provided via angle), while higher values towards 1.0 will point the motion blur forward. A value of 0.0 leads to a uniformly (but still angled) motion blur. Default: 0.0
mode (str, optional) – interpolation mode for rotating the kernel. 'bilinear' or 'nearest'. Default: "nearest"

Return type:

Tensor

Returns:

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

Examples

>>> get_motion_kernel3d(3, (0., 0., 0.), 0.)
tensor([[[[0.0000, 0.0000, 0.0000],
          [0.0000, 0.0000, 0.0000],
          [0.0000, 0.0000, 0.0000]],

         [[0.0000, 0.0000, 0.0000],
          [0.3333, 0.3333, 0.3333],
          [0.0000, 0.0000, 0.0000]],

         [[0.0000, 0.0000, 0.0000],
          [0.0000, 0.0000, 0.0000],
          [0.0000, 0.0000, 0.0000]]]])

>>> get_motion_kernel3d(3, (90., 90., 0.), -0.5)
tensor([[[[0.0000, 0.0000, 0.0000],
          [0.0000, 0.0000, 0.0000],
          [0.0000, 0.5000, 0.0000]],

         [[0.0000, 0.0000, 0.0000],
          [0.0000, 0.3333, 0.0000],
          [0.0000, 0.0000, 0.0000]],

         [[0.0000, 0.1667, 0.0000],
          [0.0000, 0.0000, 0.0000],
          [0.0000, 0.0000, 0.0000]]]])