Equalization and histograms#

Equalization#

kornia.enhance.equalize(input)[source]#

Apply equalize on the input torch.Tensor.

Implements Equalize function from PIL using PyTorch ops based on uint8 format: tensorflow/tpu

Parameters:: input (Tensor) – image torch.Tensor to equalize with shape \((*, C, H, W)\).
Return type:: Tensor
Returns:: Equalized image torch.Tensor with shape \((*, C, H, W)\).

Example

>>> x = torch.rand(1, 2, 3, 3)
>>> equalize(x).shape
torch.Size([1, 2, 3, 3])

kornia.enhance.equalize_clahe(input, clip_limit=40.0, grid_size=(8, 8), slow_and_differentiable=False)[source]#

Apply clahe equalization on the input tensor.

NOTE: Lut computation uses the same approach as in OpenCV, in next versions this can change.

Parameters:

input (Tensor) – images tensor to equalize with values in the range [0, 1] and shape \((*, C, H, W)\).
clip_limit (float, optional) – threshold value for contrast limiting. If 0 clipping is disabled. Default: 40.0
grid_size (Tuple[int, int], optional) – number of tiles to be cropped in each direction (GH, GW). Default: (8, 8)
slow_and_differentiable (bool, optional) – flag to select implementation Default: False

Return type:

Tensor

Returns:

Equalized image or images with shape as the input.

Examples

>>> img = torch.rand(1, 10, 20)
>>> res = equalize_clahe(img)
>>> res.shape
torch.Size([1, 10, 20])

>>> img = torch.rand(2, 3, 10, 20)
>>> res = equalize_clahe(img)
>>> res.shape
torch.Size([2, 3, 10, 20])

kornia.enhance.equalize3d(input)[source]#

Equalize the values for a 3D volumetric torch.Tensor.

Implements Equalize function for a sequence of images using PyTorch ops based on uint8 format: tensorflow/tpu

Parameters:: input (Tensor) – image torch.Tensor with shape \((*, C, D, H, W)\) to equalize.
Return type:: Tensor
Returns:: Equalized volume with shape \((B, C, D, H, W)\).

Histograms#

kornia.enhance.histogram(x, bins, bandwidth, epsilon=1e-10)[source]#

Estimate the histogram of the input torch.Tensor.

The calculation uses kernel density estimation which requires a bandwidth (smoothing) parameter.

Parameters:

x (Tensor) – Input torch.Tensor to compute the histogram with shape \((B, D)\).
bins (Tensor) – The number of bins to use the histogram \((N_{bins})\).
bandwidth (Tensor) – Gaussian smoothing factor with shape shape [1].
epsilon (float, optional) – A scalar, for numerical stability. Default: 1e-10

Return type:

Tensor

Returns:

Computed histogram of shape \((B, N_{bins})\).

Examples

>>> x = torch.rand(1, 10)
>>> bins = torch.torch.linspace(0, 255, 128)
>>> hist = histogram(x, bins, bandwidth=torch.tensor(0.9))
>>> hist.shape
torch.Size([1, 128])

kornia.enhance.histogram2d(x1, x2, bins, bandwidth, epsilon=1e-10)[source]#

Estimate the 2d histogram of the input torch.Tensor.

The calculation uses kernel density estimation which requires a bandwidth (smoothing) parameter.

Parameters:

x1 (Tensor) – Input torch.Tensor to compute the histogram with shape \((B, D1)\).
x2 (Tensor) – Input torch.Tensor to compute the histogram with shape \((B, D2)\).
bins (Tensor) – The number of bins to use the histogram \((N_{bins})\).
bandwidth (Tensor) – Gaussian smoothing factor with shape shape [1].
epsilon (float, optional) – A scalar, for numerical stability. Default: 1e-10.

Return type:

Tensor

Returns:

Computed histogram of shape \((B, N_{bins}), N_{bins})\).

Examples

>>> x1 = torch.rand(2, 32)
>>> x2 = torch.rand(2, 32)
>>> bins = torch.torch.linspace(0, 255, 128)
>>> hist = histogram2d(x1, x2, bins, bandwidth=torch.tensor(0.9))
>>> hist.shape
torch.Size([2, 128, 128])

kornia.enhance.image_histogram2d(image, min=0.0, max=255.0, n_bins=256, bandwidth=None, centers=None, return_pdf=False, kernel='triangular', eps=1e-10)[source]#

Estimate the histogram of the input image(s).

The calculation uses triangular kernel density estimation.

Parameters:

image (Tensor) – Input torch.Tensor to compute the histogram with shape \((H, W)\), \((C, H, W)\) or \((B, C, H, W)\).
min (float, optional) – Lower end of the interval (inclusive). Default: 0.0
max (float, optional) – Upper end of the interval (inclusive). Ignored when centers is specified. Default: 255.0
n_bins (int, optional) – The number of histogram bins. Ignored when centers is specified. Default: 256
bandwidth (Optional[float], optional) – Smoothing factor. If not specified or equal to -1, \((bandwidth = (max - min) / n_bins)\). Default: None
centers (Optional[Tensor], optional) – Centers of the bins with shape \((n_bins,)\). If not specified or empty, it is calculated as centers of equal width bins of [min, max] range. Default: None
return_pdf (bool, optional) – If True, also return probability densities for each bin. Default: False
kernel (str, optional) – kernel to perform kernel density estimation (`triangular`, `gaussian`, `uniform`, `epanechnikov`). Default: "triangular"
eps (float, optional) – epsilon for numerical stability. Default: 1e-10

Return type:

Tuple[Tensor, Tensor]

Returns:

Computed histogram of shape \((bins)\), \((C, bins)\),: \((B, C, bins)\).
Computed probability densities of shape \((bins)\), \((C, bins)\),: \((B, C, bins)\), if return_pdf is True. torch.Tensor of torch.zeros with shape of the histogram otherwise.