Thresholding#

Simple intensity-based segmentation: keep the pixels inside a value range, or split an image at Otsu’s threshold.

kornia.filters.in_range(input, lower, upper, return_mask=False)[source]#

Create a mask indicating whether elements of the input torch.Tensor are within the specified range.

The formula applied for single-channel torch.Tensor is:

\[\text{out}(I) = \text{lower}(I) \leq \text{input}(I) \geq \text{upper}(I)\]

The formula applied for multi-channel torch.Tensor is:

\[\text{out}(I) = \bigwedge_{c=0}^{C} \left( \text{lower}_c(I) \leq \text{input}_c(I) \geq \text{upper}_c(I) \right)\]

where C is the number of channels.

Parameters:

input (Tensor) – The input torch.Tensor to be filtered in the shape of \((*, *, H, W)\).
lower (Union[tuple[Any, ...], Tensor]) – The lower bounds of the filter (inclusive).
upper (Union[tuple[Any, ...], Tensor]) – The upper bounds of the filter (inclusive).
return_mask (bool, optional) – If is true, the filtered mask is returned, otherwise the filtered input image. Default: False

Return type:

Tensor

Returns:

A binary mask \((*, 1, H, W)\) of input indicating whether elements are within the range or filtered input image \((*, *, H, W)\).

Raises:

ValueError – If the shape of lower, upper, and input image channels do not match.

Note

Clarification of lower and upper:

If provided as a tuple, it should have the same number of elements as the channels in the input torch.Tensor. This bound is then applied uniformly across all batches.
When provided as a torch.Tensor, it allows for different bounds to be applied to each batch. The torch.Tensor shape should be (B, C, 1, 1), where B is the batch size and C is the number of channels.
If the torch.Tensor has a 1-D shape, same bound will be applied across all batches.

Examples

>>> rng = torch.manual_seed(1)
>>> input = torch.rand(1, 3, 3, 3)
>>> lower = (0.2, 0.3, 0.4)
>>> upper = (0.8, 0.9, 1.0)
>>> mask = in_range(input, lower, upper, return_mask=True)
>>> mask
tensor([[[[1., 1., 0.],
          [0., 0., 0.],
          [0., 1., 1.]]]])
>>> mask.shape
torch.Size([1, 1, 3, 3])

Apply different bounds (lower and upper) for each batch:

>>> rng = torch.manual_seed(1)
>>> input_tensor = torch.rand((2, 3, 3, 3))
>>> input_shape = input_tensor.shape
>>> lower = torch.tensor([[0.2, 0.2, 0.2], [0.2, 0.2, 0.2]]).reshape(input_shape[0], input_shape[1], 1, 1)
>>> upper = torch.tensor([[0.6, 0.6, 0.6], [0.8, 0.8, 0.8]]).reshape(input_shape[0], input_shape[1], 1, 1)
>>> mask = in_range(input_tensor, lower, upper, return_mask=True)
>>> mask
tensor([[[[0., 0., 1.],
          [0., 0., 0.],
          [1., 0., 0.]]],


        [[[0., 0., 0.],
          [1., 0., 0.],
          [0., 0., 1.]]]])

class kornia.filters.InRange(lower, upper, return_mask=False)[source]#

Create a module for applying lower and upper bounds to input tensors.

Parameters:

input – The input torch.Tensor to be filtered.
lower (Union[tuple[Any, ...], Tensor]) – The lower bounds of the filter (inclusive).
upper (Union[tuple[Any, ...], Tensor]) – The upper bounds of the filter (inclusive).
return_mask (bool, optional) – If is true, the filtered mask is returned, otherwise the filtered input image. Default: False

Returns:

A binary mask \((*, 1, H, W)\) of input indicating whether elements are within the range or filtered input image \((*, *, H, W)\).

Note

View complete documentation in kornia.filters.in_range().

Examples

>>> rng = torch.manual_seed(1)
>>> input = torch.rand(1, 3, 3, 3)
>>> lower = (0.2, 0.3, 0.4)
>>> upper = (0.8, 0.9, 1.0)
>>> mask = InRange(lower, upper, return_mask=True)(input)
>>> mask
tensor([[[[1., 1., 0.],
          [0., 0., 0.],
          [0., 1., 1.]]]])

kornia.filters.otsu_threshold(x, nbins=256, slow_and_differentiable=False, return_mask=False)[source]#

Apply automatic image thresholding using Otsu algorithm to the input tensor.

Parameters:

x (Tensor) – Input tensor (image or batch of images).
nbins (int) – Number of bins for histogram computation, default is 256. Default: 256
slow_and_differentiable (bool) – If True, use a differentiable histogram computation. Default is False. Default: False
return_mask (bool) – If True, return a binary mask indicating the thresholded pixels. If False, return the thresholded image. Default: False

Returns:

Thresholded tensor and the computed threshold values.

Return type:

Tuple[torch.Tensor, torch.Tensor]

Raises:

ValueError – If the input tensor has unsupported dimensionality or dtype.

Note

The input tensor can be of various types, but float types are preferred for accuracy in histogram computation, especially on CPU. Integer types will be cast to float.
If use_thresh is True, the threshold must have been computed previously and set in the module.
If threshold is provided, it overrides the computed threshold.

Note

You may found more information about the Otsu algorithm here: https://en.wikipedia.org/wiki/Otsu’s_method

Example

>>> import torch
>>> from kornia.filters.otsu_thresholding import otsu_threshold
>>> x = torch.tensor([[10, 20, 30], [40, 50, 60], [70, 80, 90]])
>>> x
tensor([[10, 20, 30],
        [40, 50, 60],
        [70, 80, 90]])
>>> otsu_threshold(x)
(tensor([[ 0,  0,  0],
        [ 0, 50, 60],
        [70, 80, 90]]), tensor([40]))

class kornia.filters.OtsuThreshold[source]#: Otsu thresholding module for PyTorch tensors.