Edge detection#

Functions#

kornia.filters.canny(input, low_threshold=0.1, high_threshold=0.2, kernel_size=(5, 5), sigma=(1, 1), hysteresis=True, eps=1e-6)[source]#

Find edges of the input image and filters them using the Canny algorithm.

Parameters:

input (Tensor) – input image torch.Tensor with shape \((B,C,H,W)\).
low_threshold (float, optional) – lower threshold for the hysteresis procedure. Default: 0.1
high_threshold (float, optional) – upper threshold for the hysteresis procedure. Default: 0.2
kernel_size (tuple[int, int] | int, optional) – the size of the kernel for the gaussian blur. Default: (5, 5)
sigma (tuple[float, float] | Tensor, optional) – the standard deviation of the kernel for the gaussian blur. Default: (1, 1)
hysteresis (bool, optional) – if True, applies the hysteresis edge tracking. Otherwise, the edges are divided between weak (0.5) and strong (1) edges. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Return type:

tuple[Tensor, Tensor]

Returns:

the canny edge magnitudes map, shape of \((B,1,H,W)\).
the canny edge detection filtered by thresholds and hysteresis, shape of \((B,1,H,W)\).

Note

See a working example here.

Example

>>> input = torch.rand(5, 3, 4, 4)
>>> magnitude, edges = canny(input)  # 5x3x4x4
>>> magnitude.shape
torch.Size([5, 1, 4, 4])
>>> edges.shape
torch.Size([5, 1, 4, 4])

kornia.filters.laplacian(input, kernel_size, border_type='reflect', normalized=True)[source]#

Create an operator that returns a tensor using a Laplacian filter.

The operator smooths the given tensor with a laplacian kernel by convolving it to each channel. It supports batched operation.

Parameters:

input (Tensor) – the input image tensor with shape \((B, C, H, W)\).
kernel_size (tuple[int, int] | int) – the size 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"
normalized (bool, optional) – if True, L1 norm of the kernel is set to 1. Default: True

Return type:

Tensor

Returns:

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

Note

See a working example here.

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> output = laplacian(input, 3)
>>> output.shape
torch.Size([2, 4, 5, 5])

kornia.filters.sobel(input, normalized=True, eps=1e-6)[source]#

Compute the Sobel operator and returns the magnitude per channel.

Parameters:

input (Tensor) – the input image with shape \((B,C,H,W)\).
normalized (bool, optional) – if True, L1 norm of the kernel is set to 1. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Return type:

Tensor

Returns:

the sobel edge gradient magnitudes map with shape \((B,C,H,W)\).

Note

See a working example here.

Example

>>> input = torch.rand(1, 3, 4, 4)
>>> output = sobel(input)  # 1x3x4x4
>>> output.shape
torch.Size([1, 3, 4, 4])

kornia.filters.spatial_gradient(input, mode='sobel', order=1, normalized=True)[source]#

Compute the first order image derivative in both x and y using a Sobel operator.

Parameters:

input (Tensor) – input image torch.Tensor with shape \((B, C, H, W)\).
mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "sobel"
order (int, optional) – the order of the derivatives. Default: 1
normalized (bool, optional) – whether the output is normalized. Default: True

Return type:

Tensor

Returns:

the derivatives of the input feature map. with shape \((B, C, 2, H, W)\).

Note

See a working example here.

Examples

>>> input = torch.rand(1, 3, 4, 4)
>>> output = spatial_gradient(input)  # 1x3x2x4x4
>>> output.shape
torch.Size([1, 3, 2, 4, 4])

kornia.filters.spatial_gradient3d(input, mode='diff', order=1)[source]#

Compute the first and second order volume derivative in x, y and d using a diff operator.

Parameters:

input (Tensor) – input features torch.Tensor with shape \((B, C, D, H, W)\).
mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "diff"
order (int, optional) – the order of the derivatives. Default: 1

Returns:

(B, C, 3, D, H, W) or \((B, C, 6, D, H, W)\).

Return type:

the spatial gradients of the input feature map with shape math

Examples

>>> input = torch.rand(1, 4, 2, 4, 4)
>>> output = spatial_gradient3d(input)
>>> output.shape
torch.Size([1, 4, 3, 2, 4, 4])

Modules#

class kornia.filters.Laplacian(kernel_size, border_type='reflect', normalized=True)[source]#

Create an operator that returns a tensor using a Laplacian filter.

The operator smooths the given tensor with a laplacian kernel by convolving it to each channel. It supports batched operation.

Parameters:

kernel_size (tuple[int, int] | int) – the size 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"
normalized (bool, optional) – if True, L1 norm of the kernel is set to 1. Default: True

Shape:

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

Examples

>>> input = torch.rand(2, 4, 5, 5)
>>> laplace = Laplacian(5)
>>> output = laplace(input)
>>> output.shape
torch.Size([2, 4, 5, 5])

class kornia.filters.Sobel(normalized=True, eps=1e-6)[source]#

Compute the Sobel operator and returns the magnitude per channel.

Parameters:

normalized (bool, optional) – if True, L1 norm of the kernel is set to 1. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Returns:

the sobel edge gradient magnitudes map.

Shape:

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

Examples

>>> input = torch.rand(1, 3, 4, 4)
>>> output = Sobel()(input)  # 1x3x4x4

class kornia.filters.Canny(low_threshold=0.1, high_threshold=0.2, kernel_size=(5, 5), sigma=(1, 1), hysteresis=True, eps=1e-6)[source]#

nn.Module that finds edges of the input image and filters them using the Canny algorithm.

Parameters:

input – input image torch.Tensor with shape \((B,C,H,W)\).
low_threshold (float, optional) – lower threshold for the hysteresis procedure. Default: 0.1
high_threshold (float, optional) – upper threshold for the hysteresis procedure. Default: 0.2
kernel_size (tuple[int, int] | int, optional) – the size of the kernel for the gaussian blur. Default: (5, 5)
sigma (tuple[float, float] | Tensor, optional) – the standard deviation of the kernel for the gaussian blur. Default: (1, 1)
hysteresis (bool, optional) – if True, applies the hysteresis edge tracking. Otherwise, the edges are divided between weak (0.5) and strong (1) edges. Default: True
eps (float, optional) – regularization number to avoid NaN during backprop. Default: 1e-6

Returns:

the canny edge magnitudes map, shape of \((B,1,H,W)\).
the canny edge detection filtered by thresholds and hysteresis, shape of \((B,1,H,W)\).

Example

>>> input = torch.rand(5, 3, 4, 4)
>>> magnitude, edges = Canny()(input)  # 5x3x4x4
>>> magnitude.shape
torch.Size([5, 1, 4, 4])
>>> edges.shape
torch.Size([5, 1, 4, 4])

class kornia.filters.SpatialGradient(mode='sobel', order=1, normalized=True)[source]#

Compute the first order image derivative in both x and y using a Sobel operator.

Parameters:

mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "sobel"
order (int, optional) – the order of the derivatives. Default: 1
normalized (bool, optional) – whether the output is normalized. Default: True

Returns:

the sobel edges of the input feature map.

Shape:

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

Examples

>>> input = torch.rand(1, 3, 4, 4)
>>> output = SpatialGradient()(input)  # 1x3x2x4x4

class kornia.filters.SpatialGradient3d(mode='diff', order=1)[source]#

Compute the first and second order volume derivative in x, y and d using a diff operator.

Parameters:

mode (str, optional) – derivatives modality, can be: sobel or diff. Default: "diff"
order (int, optional) – the order of the derivatives. Default: 1

Returns:

the spatial gradients of the input feature map.

Shape:

Input: \((B, C, D, H, W)\). D, H, W are spatial dimensions, gradient is calculated w.r.t to them.
Output: \((B, C, 3, D, H, W)\) or \((B, C, 6, D, H, W)\)

Examples

>>> input = torch.rand(1, 4, 2, 4, 4)
>>> output = SpatialGradient3d()(input)
>>> output.shape
torch.Size([1, 4, 3, 2, 4, 4])