Kernels

Kernel builders, to see what a filter applies or to filter with a Filtering API function. filter2d(), its 2D variants and fft_conv() take a (1, kH, kW) kernel: add a leading axis to a (kH, kW) one, and pass a stacked derivative kernel such as get_sobel_kernel2d() one kernel at a time, since a (2, 3, 3) stack is read as one kernel per sample. filter2d_separable() takes two (1, k) kernels and filter3d() a (1, kD, kH, kW) one, the shapes the 1D and 3D builders return.

Which Gaussian to use:

• get_gaussian_kernel1d() samples the Gaussian at the taps. It is the kernel gaussian_blur2d() applies, and get_gaussian_kernel2d() and get_gaussian_kernel3d() are its outer products.

• get_gaussian_erf_kernel1d() integrates the Gaussian over each pixel, for a tap that models a pixel’s area. It blurs more.

• get_gaussian_discrete_kernel1d() is Lindeberg’s discrete Gaussian, for discrete scale space.

• gaussian() samples like get_gaussian_kernel1d(), takes a mean and does not check the size.

kornia.filters.gaussian(window_size, sigma, *, mean=None, device=None, dtype=None)

Sample a Gaussian on any window around a chosen mean, summing to 1.

kernel = gaussian(window_size, sigma) returns the Gaussian of standard deviation sigma sampled at the window_size taps, as a (B, window_size) tensor. Use it for an off-centre mean; get_gaussian_kernel1d() is the checked call for a centred kernel.

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) – number of taps.

• sigma (Tensor | float) – non-negative standard deviation in taps, a float or a (B, 1) tensor.

• mean (Union[Tensor, float, None], optional) – centre in taps, a float or a (B, 1) tensor with the B of sigma; window_size // 2 by default. See the Convention block for an even window_size. Default: None

• device (Optional[device], optional) – device of the kernel when sigma is a Python number. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel when sigma is a Python number. Default: None

Return type:

Tensor

Returns:

the kernels, each summing to 1, with shape (B, window_size).

Note

Float16 and bfloat16 kernels are computed in float32 and rounded once at return.

A sigma of zero, or one too small for the window to hold a representable weight, puts all the mass on the sample nearest the mean: the unit impulse. With an even window_size the default centre falls between two samples, so a small sigma splits the mass between them, and a sigma of zero is not defined.

See also

• get_gaussian_kernel1d(): the checked call.

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

Return a 1D Gaussian kernel sampled at the taps, summing to 1.

kernel = get_gaussian_kernel1d(kernel_size, sigma) returns the Gaussian of standard deviation sigma sampled at the kernel_size taps, as a (B, kernel_size) tensor. It is the usual Gaussian kernel, the one gaussian_blur2d() applies.

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.

• 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. No tap sits on that middle, so a sigma of zero is not defined for an even kernel_size.

• 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) – number of taps, odd and positive.

• sigma (float | Tensor) – non-negative standard deviation in taps, a float or a (B, 1) tensor.

• force_even (bool, optional) – whether to accept an even kernel_size. Default: False

• device (Optional[device], optional) – device of the kernel when sigma is a Python number. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel when sigma is a Python number. Default: None

Return type:

Tensor

Returns:

the kernels, with shape (B, kernel_size).

See also

• get_gaussian_erf_kernel1d(): integrates the Gaussian over each pixel, so it blurs more.

• get_gaussian_discrete_kernel1d(): Lindeberg’s discrete Gaussian, for discrete scale space.

• gaussian(): the same samples around a chosen mean, without the size check.

• get_gaussian_kernel2d(): the outer product of two of these kernels.

• gaussian_blur2d(): the blur that applies it along each axis.

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 returns the unit impulse:

>>> get_gaussian_kernel1d(5, 0.0)
tensor([[0., 0., 1., 0., 0.]])

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

Return a 1D Gaussian kernel integrated per pixel with the error function.

kernel = get_gaussian_erf_kernel1d(kernel_size, sigma) takes the arguments of get_gaussian_kernel1d() and returns the Gaussian integrated over the unit-wide interval of each tap, as a (B, kernel_size) tensor.

Convention:

• See the Convention block on get_gaussian_kernel1d(). In a floating dtype the kernel is \(\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) – number of taps, odd and positive.

• sigma (float | Tensor) – non-negative standard deviation in taps, a float or a (B, 1) tensor. Zero is not defined for an even kernel_size.

• force_even (bool, optional) – whether to accept an even kernel_size. Default: False

• device (Optional[device], optional) – device of the kernel when sigma is a Python number. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel when sigma is a Python number. Default: None

Return type:

Tensor

Returns:

the kernels, with shape (B, kernel_size).

See also

• get_gaussian_kernel1d(): samples the Gaussian at the taps, the usual choice.

• get_gaussian_discrete_kernel1d(): Lindeberg’s discrete Gaussian.

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)

Return a 1D discrete Gaussian kernel from modified Bessel functions, summing to 1.

kernel = get_gaussian_discrete_kernel1d(kernel_size, sigma) takes the arguments of get_gaussian_kernel1d() and returns Lindeberg’s discrete Gaussian, the smoothing kernel of discrete scale space, as a (B, kernel_size) tensor.

Convention:

• See the Convention block on get_gaussian_kernel1d(). In a floating dtype the kernel is \(e^{-\sigma^2} I_{|n|}(\sigma^2)\), with \(I_n\) the modified Bessel function of the first kind, normalized over the window. A float16 or bfloat16 kernel is computed in float32 and rounded to its dtype.

• 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) – number of taps, odd and positive.

• sigma (float | Tensor) – non-negative standard deviation in taps, a float or a (B, 1) tensor.

• force_even (bool, optional) – accepted for parity with the other Gaussian builders, and ignored. Default: False

• device (Optional[device], optional) – device of the kernel when sigma is a Python number. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel when sigma is a Python number. Default: None

Return type:

Tensor

Returns:

the kernels, with shape (B, kernel_size).

See also

• get_gaussian_kernel1d(): samples the Gaussian, the usual choice, and takes an even size.

• get_gaussian_erf_kernel1d(): integrates the Gaussian over each pixel.

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)

Return a 2D Gaussian kernel as the outer product of two 1D kernels, summing to 1.

kernel = get_gaussian_kernel2d(kernel_size, sigma) multiplies the get_gaussian_kernel1d() kernels of kernel_size=(k_y, k_x) and sigma=(sigma_y, sigma_x), y first, and returns a (B, k_y, k_x) tensor.

Convention:

See the Convention block on get_gaussian_kernel1d(). A tensor sigma of shape (B, 2) gives one kernel per row.

Parameters:

• kernel_size (tuple[int, int] | int) – size (k_y, k_x), or one integer for both; odd and positive.

• sigma (tuple[float, float] | Tensor) – non-negative standard deviations (sigma_y, sigma_x), or a (B, 2) tensor.

• force_even (bool, optional) – whether to accept an even size. Default: False

• device (Optional[device], optional) – device of the kernel when sigma is a tuple. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel when sigma is a tuple. Default: None

Return type:

Tensor

Returns:

the kernels, with shape (B, k_y, k_x).

See also

• get_gaussian_kernel1d(): the 1D kernel.

• get_gaussian_kernel3d(): the 3D kernel.

• gaussian_blur2d(): the blur that applies it.

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)

Return a 3D Gaussian kernel as the outer product of three 1D kernels, summing to 1.

kernel = get_gaussian_kernel3d(kernel_size, sigma) multiplies the get_gaussian_kernel1d() kernels of kernel_size=(k_z, k_y, k_x) and sigma=(sigma_z, sigma_y, sigma_x), z first, and returns a (B, k_z, k_y, k_x) tensor.

Convention:

See the Convention block on get_gaussian_kernel1d(). A tensor sigma of shape (B, 3) gives one kernel per row.

Parameters:

• kernel_size (tuple[int, int, int] | int) – size (k_z, k_y, k_x), or one integer for all three; odd and positive.

• sigma (tuple[float, float, float] | Tensor) – non-negative standard deviations (sigma_z, sigma_y, sigma_x), or a (B, 3) tensor.

• force_even (bool, optional) – whether to accept an even size. Default: False

• device (Optional[device], optional) – device of the kernel when sigma is a tuple. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel when sigma is a tuple. Default: None

Return type:

Tensor

Returns:

the kernels, with shape (B, k_z, k_y, k_x).

See also

• get_gaussian_kernel2d(): the 2D kernel.

• filter3d(): filters a volume with it.

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)

Return a 1D box kernel: equal taps summing to 1.

kernel = get_box_kernel1d(kernel_size) returns the averaging kernel of kernel_size taps, as a (1, kernel_size) tensor.

Convention:

• 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) – number of taps.

• device (Optional[device], optional) – device of the kernel. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel. Default: None

Return type:

Tensor

Returns:

the kernel, every tap \(1 / \text{kernel\_size}\).

See also

• get_box_kernel2d(): the 2D kernel.

• box_blur(): the blur that applies it.

kornia.filters.get_box_kernel2d(kernel_size, *, device=None, dtype=None)

Return a 2D box kernel: equal taps summing to 1.

kernel = get_box_kernel2d(kernel_size) returns the averaging kernel of (k_y, k_x) taps, as a (1, k_y, k_x) tensor.

Convention:

See the Convention block on get_box_kernel1d().

Parameters:

• kernel_size (tuple[int, int] | int) – size (k_y, k_x), or one integer for both.

• device (Optional[device], optional) – device of the kernel. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel. Default: None

Return type:

Tensor

Returns:

the kernel, every tap \(1 / (k_y k_x)\).

See also

• get_box_kernel1d(): the 1D kernel.

• box_blur(): the blur that applies it.

kornia.filters.get_binary_kernel2d(window_size, *, device=None, dtype=torch.float32)

Return one-hot kernels that pick out every pixel of a window.

kernels = get_binary_kernel2d(window_size) returns one kernel per position of a (k_y, k_x) window, as a (k_y * k_x, 1, k_y, k_x) tensor. torch.nn.functional.conv2d() with them on a one-channel image stacks each pixel’s neighbourhood along the channel axis.

Convention:

Channel i is one-hot at (i // k_x, i % k_x), in row-major order, the layout median_blur() builds on.

Parameters:

• window_size (tuple[int, int] | int) – size (k_y, k_x), or one integer for both.

• device (Optional[device], optional) – device of the kernel. Default: None

• dtype (dtype, optional) – dtype of the kernel. Default: torch.float32

Return type:

Tensor

Returns:

the kernels, with shape (k_y * k_x, 1, k_y, k_x).

See also

• median_blur(): takes the median over the stacked neighbourhood.

kornia.filters.get_hanning_kernel1d(kernel_size, device=None, dtype=None)

Return a symmetric 1D Hanning (Hann) window.

window = get_hanning_kernel1d(kernel_size) returns the window of \(M\) = kernel_size taps, as a (kernel_size,) tensor:

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

Convention:

Both end taps are 0, so only \(M - 2\) samples carry weight, and the window 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) – number of taps, an integer greater than 2.

• device (Optional[device], optional) – device of the kernel. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel. Default: None

Return type:

Tensor

Returns:

the window, with shape (kernel_size,).

See also

• get_hanning_kernel2d(): the 2D window.

Examples

>>> get_hanning_kernel1d(4).round(decimals=4)
tensor([0.0000, 0.7500, 0.7500, 0.0000])

kornia.filters.get_hanning_kernel2d(kernel_size, device=None, dtype=None)

Return a 2D Hanning (Hann) window as the outer product of two 1D windows.

window = get_hanning_kernel2d(kernel_size) multiplies the get_hanning_kernel1d() windows of kernel_size=(k_y, k_x), along H and W, and returns a (k_y, k_x) tensor.

Convention:

See the Convention block on get_hanning_kernel1d().

Parameters:

• kernel_size (tuple[int, int] | int) – size (k_y, k_x), or one integer for both; each greater than 2.

• device (Union[str, device, None], optional) – device of the kernel. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernel. Default: None

Return type:

Tensor

Returns:

the window, with shape (k_y, k_x).

See also

• get_hanning_kernel1d(): the 1D window.

kornia.filters.get_laplacian_kernel1d(kernel_size, *, device=None, dtype=torch.float32)

Return a 1D Laplacian kernel: ones with a negative centre, summing to 0.

kernel = get_laplacian_kernel1d(kernel_size) returns kernel_size taps, all ones except the centre tap 1 - kernel_size, as a (kernel_size,) tensor.

Convention:

• 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) – number of taps, odd and at least 3.

• device (Optional[device], optional) – device of the kernel. Default: None

• dtype (dtype, optional) – dtype of the kernel. Default: torch.float32

Return type:

Tensor

Returns:

the kernel, with shape (kernel_size,).

Raises:

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

See also

• get_laplacian_kernel2d(): the 2D kernel.

• laplacian_1d(): the same kernel without the size checks.

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)

Return a 2D Laplacian kernel: ones with a negative centre, summing to 0.

kernel = get_laplacian_kernel2d(kernel_size) returns (k_y, k_x) taps, all ones except the centre tap \(1 - k_y k_x\), as a (k_y, k_x) tensor.

Convention:

See the Convention block on get_laplacian_kernel1d(). 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) – size (k_y, k_x), or one integer for both; odd, and at least 3 along one axis.

• device (Optional[device], optional) – device of the kernel. Default: None

• dtype (dtype, optional) – dtype of the kernel. Default: torch.float32

Return type:

Tensor

Returns:

the kernel, with shape (k_y, k_x).

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.

See also

• get_laplacian_kernel1d(): the 1D kernel.

• laplacian(): the filter that applies it, normalized by default.

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)

Build a 1D Laplacian kernel of any positive size, without validating it.

kernel = laplacian_1d(window_size) returns ones with 1 - window_size at index window_size // 2. Call get_laplacian_kernel1d() instead, which rejects an even size and a single tap.

Convention:

See the Convention block on get_laplacian_kernel1d(). An even size puts the negative tap at window_size // 2, off the middle of the kernel, and size 1 gives [0.].

Parameters:

• window_size (int) – number of taps.

• device (Optional[device], optional) – device of the kernel. Default: None

• dtype (dtype, optional) – dtype of the kernel. Default: torch.float32

Return type:

Tensor

Returns:

the kernel, with shape (window_size,).

See also

• get_laplacian_kernel1d(): the same kernel with its size checked.

kornia.filters.get_spatial_gradient_kernel2d(mode, order, *, device=None, dtype=None)

Return the Sobel or difference kernels of the first or second image derivatives.

kernels = get_spatial_gradient_kernel2d(mode, order) returns the stencils that spatial_gradient() correlates with an image.

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) – derivative order, 1 or 2.

• device (Optional[device], optional) – device of the kernels. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernels. 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.

See also

• get_spatial_gradient_kernel3d(): the 3D kernels, 'diff' only.

• spatial_gradient(): the filter that applies them, normalized by default.

kornia.filters.get_spatial_gradient_kernel3d(mode, order, device=None, dtype=None)

Return the central-difference kernels of the first or second derivatives of a volume.

kernels = get_spatial_gradient_kernel3d(mode, order) returns the (3, 3, 3) stencils that spatial_gradient3d() correlates with 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) – derivative order, 1 or 2.

• device (Optional[device], optional) – device of the kernels. Default: None

• dtype (Optional[dtype], optional) – dtype of the kernels. 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.

See also

• get_spatial_gradient_kernel2d(): the 2D kernels, with the 'sobel' mode.

• spatial_gradient3d(): the filter that applies them.

kornia.filters.get_sobel_kernel2d(*, device=None, dtype=None)

Return the 2D Sobel kernels of the first derivatives (x, y).

kernels = get_sobel_kernel2d() returns the kernels of \((\partial_x, \partial_y)\) stacked as a (2, 3, 3) tensor.

Return type:

Tensor

Convention:

See the Convention block on get_spatial_gradient_kernel2d(); this is get_spatial_gradient_kernel2d('sobel', 1).

See also

• get_diff_kernel2d(): the same stack of central-difference kernels.

• get_spatial_gradient_kernel2d(): also the second order and the 'diff' mode.

kornia.filters.get_diff_kernel2d(*, device=None, dtype=None)

Return the 2D central-difference kernels of the first derivatives (x, y).

kernels = get_diff_kernel2d() returns the kernels of \((\partial_x, \partial_y)\) stacked as a (2, 3, 3) tensor.

Return type:

Tensor

Convention:

See the Convention block on get_spatial_gradient_kernel2d(); this is get_spatial_gradient_kernel2d('diff', 1).

See also

• get_sobel_kernel2d(): the same stack of Sobel kernels.

• get_spatial_gradient_kernel2d(): also the second order and the 'sobel' mode.

kornia.filters.get_motion_kernel2d(kernel_size, angle, direction=0.0, mode='nearest')

Return a 2D motion-blur kernel: a weighted line rotated by an angle.

kernel = get_motion_kernel2d(kernel_size, angle, direction) puts kernel_size taps along the middle row, weights them by direction, rotates them by angle degrees and normalizes the sum to 1. It returns a (B, kernel_size, kernel_size) tensor with one kernel per angle.

Convention:

• direction is clamped to [-1, 1] and weights the line linearly before the rotation: 0 is uniform, 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, and -1 mirrors it.

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

• filter2d() correlates, so 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.

• mode resamples the rotated line. '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 tensor direction must match a tensor angle in length, dtype and device, and a floating one gives the kernel its dtype; a float direction is not broadcast, so it raises for B > 1.

• The 'nearest' kernel is the same on every device and dtype, for every full turn added to the angle, and with torch.compile. Where a 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.

Parameters:

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

• angle (Tensor | float) – angle in degrees, a float or a (B,) tensor.

• direction (Tensor | float, optional) – weighting of the line in [-1, 1], a float or a (B,) tensor; see the Convention block. Default: 0.0

• mode (str, optional) – interpolation of the rotation, 'nearest' or 'bilinear'. Default: "nearest"

Return type:

Tensor

Returns:

the kernels, with shape (B, kernel_size, kernel_size).

See also

• get_motion_kernel3d(): the 3D kernel, rotated by an axis-angle vector.

• motion_blur(): the blur that applies it to an image.

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

Return a 3D motion-blur kernel: a weighted line rotated by an axis-angle vector.

kernel = get_motion_kernel3d(kernel_size, angle, direction) puts kernel_size taps along x through the centre, weights them by direction, rotates them by angle and normalizes the sum to 1. It returns a (B, kernel_size, kernel_size, kernel_size) tensor with one kernel per angle.

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. A positive roll alone turns the line clockwise as displayed, the opposite of the 2D angle.

• The 'nearest' kernel is the same on every device and dtype and with torch.compile.

Parameters:

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

• angle (Tensor | tuple[float, float, float]) – axis-angle vector (rx, ry, rz) in degrees, a tuple or a (B, 3) tensor.

• direction (Tensor | float, optional) – weighting of the line in [-1, 1], a float or a (B,) tensor, as in the 2D kernel. Default: 0.0

• mode (str, optional) – interpolation of the rotation, 'nearest' or 'bilinear'. Default: "nearest"

Return type:

Tensor

Returns:

the kernels, with shape (B, kernel_size, kernel_size, kernel_size).

See also

• get_motion_kernel2d(): the 2D kernel, rotated by an angle.

• motion_blur3d(): the blur that applies it to a volume.

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