kornia.color

The functions in this section perform various color space conversions and intensity transformations.

Color Space Conversions

rgb_to_bgr(image: torch.Tensor) → torch.Tensor[source]

Convert a RGB image to BGR.

See RgbToBgr for details.

Parameters

image (torch.Tensor) – RGB Image to be converted to BGR.

Returns

BGR version of the image.

Return type

torch.Tensor

rgb_to_grayscale(input: torch.Tensor) → torch.Tensor[source]

Convert a RGB image to grayscale.

See RgbToGrayscale for details.

Parameters

input (torch.Tensor) – RGB image to be converted to grayscale.

Returns

Grayscale version of the image.

Return type

torch.Tensor

rgb_to_hsv(image: torch.Tensor) → torch.Tensor[source]

Convert an RGB image to HSV.

Parameters

input (torch.Tensor) – RGB Image to be converted to HSV.

Returns

HSV version of the image.

Return type

torch.Tensor

rgb_to_hls(image: torch.Tensor) → torch.Tensor[source]

Convert an RGB image to HLS The image data is assumed to be in the range of (0, 1).

Parameters

input (torch.Tensor) – RGB Image to be converted to HLS.

Returns

HLS version of the image.

Return type

torch.Tensor

rgb_to_luv(image: torch.Tensor, eps: float = 1e-12) → torch.Tensor[source]

Converts a RGB image to Luv.

See RgbToLuv for details.

Parameters
  • image (torch.Tensor) – RGB image

  • eps (float) – for numerically stability when dividing. Default: 1e-8.

Returns

Luv image

Return type

torch.Tensor

rgb_to_rgba(image: torch.Tensor, alpha_val: Union[float, torch.Tensor]) → torch.Tensor[source]

Convert image from RGB to RGBA.

See RgbToRgba for details.

Parameters
Returns

RGBA version of the image.

Return type

torch.Tensor

rgb_to_xyz(image: torch.Tensor) → torch.Tensor[source]

Converts a RGB image to XYZ.

See RgbToXyz for details.

Parameters

image (torch.Tensor) – RGB Image to be converted to XYZ.

Returns

XYZ version of the image.

Return type

torch.Tensor

rgb_to_ycbcr(image: torch.Tensor) → torch.Tensor[source]

Convert an RGB image to YCbCr.

Parameters

image (torch.Tensor) – RGB Image to be converted to YCbCr.

Returns

YCbCr version of the image.

Return type

torch.Tensor

rgb_to_yuv(input: torch.Tensor) → torch.Tensor[source]

Convert an RGB image to YUV The image data is assumed to be in the range of (0, 1).

Parameters

input (torch.Tensor) – RGB Image to be converted to YUV.

Returns

YUV version of the image.

Return type

torch.Tensor

See RgbToYuv for details.

rgba_to_rgb(image: torch.Tensor) → torch.Tensor[source]

Convert image from RGBA to RGB.

See RgbaToRgb for details.

Parameters

image (torch.Tensor) – RGBA Image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

rgba_to_bgr(image: torch.Tensor) → torch.Tensor[source]

Convert image from RGBA to BGR.

See RgbaToBgr for details.

Parameters

image (torch.Tensor) – RGBA Image to be converted to BGR.

Returns

BGR version of the image.

Return type

torch.Tensor

bgr_to_grayscale(input: torch.Tensor) → torch.Tensor[source]

Convert a BGR image to grayscale.

See BgrToGrayscale for details.

Parameters

input (torch.Tensor) – BGR image to be converted to grayscale.

Returns

Grayscale version of the image.

Return type

torch.Tensor

bgr_to_rgb(image: torch.Tensor) → torch.Tensor[source]

Convert a BGR image to RGB.

See BgrToRgb for details.

Parameters

image (torch.Tensor) – BGR Image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

bgr_to_rgba(image: torch.Tensor, alpha_val: Union[float, torch.Tensor]) → torch.Tensor[source]

Convert image from BGR to RGBA.

See BgrToRgba for details.

Parameters
Returns

RGBA version of the image.

Return type

torch.Tensor

hls_to_rgb(image: torch.Tensor) → torch.Tensor[source]

Convert an HLS image to RGB The image data is assumed to be in the range of (0, 1).

Parameters

input (torch.Tensor) – HLS Image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

hsv_to_rgb(image: torch.Tensor) → torch.Tensor[source]

Convert an HSV image to RGB The image data is assumed to be in the range of (0, 1).

Parameters

input (torch.Tensor) – HSV Image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

luv_to_rgb(image: torch.Tensor, eps: float = 1e-12) → torch.Tensor[source]

Converts a Luv image to RGB.

See LuvToRgb for details.

Parameters
  • image (torch.Tensor) – Luv image

  • eps (float) – for numerically stability when dividing. Default: 1e-8.

Returns

RGB image

Return type

torch.Tensor

ycbcr_to_rgb(image: torch.Tensor) → torch.Tensor[source]

Convert an YCbCr image to RGB The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – YCbCr Image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

yuv_to_rgb(input: torch.Tensor) → torch.Tensor[source]

Convert an YUV image to RGB The image data is assumed to be in the range of (0, 1).

Parameters

input (torch.Tensor) – YUV Image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

See YuvToRgb for details.

xyz_to_rgb(image: torch.Tensor) → torch.Tensor[source]

Converts a XYZ image to RGB.

See XyzToRgb for details.

Parameters

image (torch.Tensor) – XYZ Image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

Intensity Transformations

adjust_brightness(input: torch.Tensor, brightness_factor: Union[float, torch.Tensor]) → torch.Tensor[source]

Adjust Brightness of an image.

See AdjustBrightness for details.

adjust_contrast(input: torch.Tensor, contrast_factor: Union[float, torch.Tensor]) → torch.Tensor[source]

Adjust Contrast of an image.

See AdjustContrast for details.

adjust_gamma(input: torch.Tensor, gamma: Union[float, torch.Tensor], gain: Union[float, torch.Tensor] = 1.0) → torch.Tensor[source]

Perform gamma correction on an image.

See AdjustGamma for details.

adjust_hue(input: torch.Tensor, hue_factor: Union[float, torch.Tensor]) → torch.Tensor[source]

Adjust hue of an image.

See AdjustHue for details.

adjust_saturation(input: torch.Tensor, saturation_factor: Union[float, torch.Tensor]) → torch.Tensor[source]

Adjust color saturation of an image.

See AdjustSaturation for details.

add_weighted(src1: torch.Tensor, alpha: float, src2: torch.Tensor, beta: float, gamma: float) → torch.Tensor[source]

Blend two Tensors.

See AddWeighted for details.

normalize(data: torch.Tensor, mean: Union[torch.Tensor, float], std: Union[torch.Tensor, float]) → torch.Tensor[source]

Normalise the image with channel-wise mean and standard deviation.

See Normalize for details.

Parameters
Returns

The normalised image tensor.

Return type

torch.Tensor

denormalize(data: torch.Tensor, mean: Union[torch.Tensor, float], std: Union[torch.Tensor, float]) → torch.Tensor[source]

Denormalize the image given channel-wise mean and standard deviation.

See Normalize for details.

Parameters
Returns

The normalised image tensor.

Return type

torch.Tensor

zca_mean(inp: torch.Tensor, dim: int = 0, unbiased: bool = True, eps: float = 1e-06, return_inverse: bool = False) → Tuple[torch.Tensor, torch.Tensor, Optional[torch.Tensor]][source]

Computes the ZCA whitening matrix and mean vector. The output can be used with linear_transform()

See ZCAWhitening for details.

Parameters
  • inp (torch.Tensor) – input data tensor

  • dim (int) – Specifies the dimension that serves as the samples dimension. Default = 0

  • unbiased (bool) – Whether to use the unbiased estimate of the covariance matrix. Default = True

  • eps (float) – a small number used for numerical stability. Default = 0

  • return_inverse (bool) – Whether to return the inverse ZCA transform.

shapes:
  • inp: \((D_0,...,D_{\text{dim}},...,D_N)\) is a batch of N-D tensors.

  • transform_matrix: \((\Pi_{d=0,d\neq \text{dim}}^N D_d, \Pi_{d=0,d\neq \text{dim}}^N D_d)\)

  • mean_vector: \((1, \Pi_{d=0,d\neq \text{dim}}^N D_d)\)

  • inv_transform: same shape as the transform matrix

Returns

A tuple containing the ZCA matrix and the mean vector. If return_inverse is set to True, then it returns the inverse ZCA matrix, otherwise it returns None.

Return type

Tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Examples

>>> from kornia.color import zca_mean
>>> x = torch.tensor([[0,1],[1,0],[-1,0],[0,-1]], dtype = torch.float32)
>>> transform_matrix, mean_vector,_ = zca_mean(x) # Returns transformation matrix and data mean
>>> x = torch.rand(3,20,2,2)
>>> transform_matrix, mean_vector, inv_transform = zca_mean(x, dim = 1, return_inverse = True)
>>> # transform_matrix.size() equals (12,12) and the mean vector.size equal (1,12)
zca_whiten(inp: torch.Tensor, dim: int = 0, unbiased: bool = True, eps: float = 1e-06) → torch.Tensor[source]

Applies ZCA whitening transform.

See ZCAWhitening for details.

Parameters
  • inp (torch.Tensor) – input data tensor

  • dim (int) – Specifies the dimension that serves as the samples dimension. Default = 0

  • unbiased (bool) – Whether to use the unbiased estimate of the covariance matrix. Default = True

  • eps (float) – a small number used for numerial stablility. Default = 0

Returns

Whiten Input data

Return type

torch.Tensor

Examples

>>> import torch
>>> import kornia
>>> x = torch.tensor([[0,1],[1,0],[-1,0]], dtype = torch.float32)
>>> x_whiten = kornia.color.zca_whiten(x)
linear_transform(inp: torch.Tensor, transform_matrix: torch.Tensor, mean_vector: torch.Tensor, dim: int = 0) → torch.Tensor[source]

Given a transformation matrix and a mean vector, this function will flatten the input tensor along the given dimension and subtract the mean vector from it. Then the dot product with the transformation matrix will be computed and then the resulting tensor is reshaped to the original input shape.

\[\mathbf{X}_{T} = (\mathbf{X - \mu})(T)\]
Parameters
shapes:
  • inp: \((D_0,...,D_{\text{dim}},...,D_N)\) is a batch of N-D tensors.

  • transform_matrix: \((\Pi_{d=0,d\neq \text{dim}}^N D_d, \Pi_{d=0,d\neq \text{dim}}^N D_d)\)

  • mean_vector: \((1, \Pi_{d=0,d\neq \text{dim}}^N D_d)\)

Returns

Transformed data

Return type

torch.Tensor

Example

>>> # Example where dim = 3
>>> inp = torch.ones((10,3,4,5))
>>> transform_mat = torch.ones((10*3*4,10*3*4))
>>> mean = 2*torch.ones((1,10*3*4))
>>> out = kornia.color.linear_transform(inp, transform_mat, mean, 3)
>>> print(out) # Should a be (10,3,4,5) tensor of -120s
>>> # Example where dim = 0
>>> inp = torch.ones((10,2))
>>> transform_mat = torch.ones((2,2))
>>> mean = torch.zeros((1,2))
>>> out = kornia.color.linear_transform(inp, transform_mat, mean)
>>> print(out) # Should a be (10,3,4,5) tensor of 2s
histogram(x: torch.Tensor, bins: torch.Tensor, bandwidth: torch.Tensor, epsilon: float = 1e-10) → torch.Tensor[source]

Function that estimates the histogram of the input tensor. The calculation uses kernel density estimation which requires a bandwidth (smoothing) parameter. :param x: (torch.Tensor), shape [BxN] :param bins: (torch.Tensor), shape [NUM_BINS] :param bandwidth: (torch.Tensor), shape [1], gaussian smoothing factor :param epsilon: (float), scalar, for numerical stability

Returns

(torch.Tensor), shape [BxNUM_BINS]

Return type

pdf

histogram2d(x1: torch.Tensor, x2: torch.Tensor, bins: torch.Tensor, bandwidth: torch.Tensor, epsilon: float = 1e-10) → torch.Tensor[source]

Function that estimates the histogram of the input tensor. The calculation uses kernel density estimation which requires a bandwidth (smoothing) parameter. :param x1: (torch.Tensor), shape [BxN1] :param x2: (torch.Tensor), shape [BxN2] :param bins: (torch.Tensor), shape [NUM_BINS] :param bandwidth: (torch.Tensor), scalar, gaussian smoothing factor :param epsilon: (float), scalar, for numerical stability

Returns

(torch.Tensor), shape [BxNUM_BINSxNUM_BINS]

Return type

pdf

Modules

class RgbToGrayscale[source]

convert RGB image to grayscale version of image.

the image data is assumed to be in the range of (0, 1).

Parameters

input (torch.Tensor) – RGB image to be converted to grayscale.

Returns

grayscale version of the image.

Return type

torch.Tensor

shape:
  • input: \((*, 3, H, W)\)

  • output: \((*, 1, H, W)\)

reference:

https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> gray = kornia.color.RgbToGrayscale()
>>> output = gray(input)  # 2x1x4x5
class BgrToGrayscale[source]

convert BGR image to grayscale version of image.

the image data is assumed to be in the range of (0, 1).

Parameters

input (torch.Tensor) – BGR image to be converted to grayscale.

Returns

grayscale version of the image.

Return type

torch.Tensor

shape:
  • input: \((*, 3, H, W)\)

  • output: \((*, 1, H, W)\)

reference:

https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> gray = kornia.color.BgrToGrayscale()
>>> output = gray(input)  # 2x1x4x5
class RgbToHsv[source]

Convert image from RGB to HSV.

The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – RGB image to be converted to HSV.

Returns

HSV version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> hsv = kornia.color.RgbToHsv()
>>> output = hsv(input)  # 2x3x4x5
class HsvToRgb[source]

Convert image from HSV to Rgb The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – HSV image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> rgb = kornia.color.HsvToRgb()
>>> output = rgb(input)  # 2x3x4x5
class RgbToHls[source]

Convert image from RGB to HLS The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – RGB image to be converted to HLS.

Returns

HLS version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> hls = kornia.color.RgbToHls()
>>> output = hls(input)  # 2x3x4x5
class HlsToRgb[source]

Convert image from HLS to Rgb The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – HLS image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

reference:

https://en.wikipedia.org/wiki/HSL_and_HSV

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> rgb = kornia.color.HlsToRgb()
>>> output = rgb(input)  # 2x3x4x5
class RgbToBgr[source]

Convert image from RGB to BGR.

The image data is assumed to be in the range of (0, 1).

Returns

BGR version of the image.

Return type

torch.Tensor

Shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> bgr = kornia.color.RgbToBgr()
>>> output = bgr(input)  # 2x3x4x5
class BgrToRgb[source]

Convert image from BGR to RGB.

The image data is assumed to be in the range of (0, 1).

Returns

RGB version of the image.

Return type

torch.Tensor

Shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> rgb = kornia.color.BgrToRgb()
>>> output = rgb(input)  # 2x3x4x5
class RgbToYuv[source]

Convert image from RGB to YUV The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – RGB image to be converted to YUV.

Returns

YUV version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples::
>>> input = torch.rand(2, 3, 4, 5)
>>> yuv = kornia.color.RgbToYuv()
>>> output = yuv(input)  # 2x3x4x5
Reference::

[1] https://es.wikipedia.org/wiki/YUV#RGB_a_Y’UV

class YuvToRgb[source]

Convert image from YUV to RGB The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – YUV image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples::
>>> input = torch.rand(2, 3, 4, 5)
>>> rgb = kornia.color.YuvToRgb()
>>> output = rgb(input)  # 2x3x4x5
class RgbToRgba(alpha_val: Union[float, torch.Tensor])[source]

Convert image from RGB to RGBA.

Add an alpha channel to existing RGB image.

Parameters

alpha_val (float, torch.Tensor) – A float number for the alpha value.

Returns

RGBA version of the image.

Return type

torch.Tensor

Shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 4, H, W)\)

Examples:

>>> input = torch.rand(2, 3, 4, 5)
>>> rgba = kornia.color.RgbToRgba(1.)
>>> output = rgba(input)  # 2x4x4x5
class BgrToRgba(alpha_val: Union[float, torch.Tensor])[source]

Convert image from BGR to RGBA.

Add an alpha channel to existing BGR image.

Parameters

alpha_val (float, torch.Tensor) – A float number for the alpha value.

Returns

RGBA version of the image.

Return type

torch.Tensor

Shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 4, H, W)\)

Examples:

>>> input = torch.rand(2, 3, 4, 5)
>>> rgba = kornia.color.BgrToRgba(1.)
>>> output = rgba(input)  # 2x4x4x5
class RgbaToRgb[source]

Convert image from RGBA to RGB.

Remove an alpha channel from RGB image.

Returns

RGB version of the image.

Return type

torch.Tensor

shape:
  • image: \((*, 4, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> input = torch.rand(2, 4, 4, 5)
>>> rgba = kornia.color.RgbaToRgb()
>>> output = rgba(input)  # 2x3x4x5
class RgbaToBgr[source]

Convert image from RGBA to BGR.

Remove an alpha channel from BGR image.

Returns

BGR version of the image.

Return type

torch.Tensor

shape:
  • image: \((*, 4, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> input = torch.rand(2, 4, 4, 5)
>>> rgba = kornia.color.RgbaToBgr()
>>> output = rgba(input)  # 2x3x4x5
class RgbToXyz[source]

Converts an image from RGB to XYZ

The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – RGB image to be converted to XYZ.

Returns

XYZ version of the image.

Return type

torch.Tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples

>>> input = torch.rand(2, 3, 4, 5)
>>> xyz = kornia.color.RgbToXyz()
>>> output = xyz(input)  # 2x3x4x5
Reference:

[1] https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html

class XyzToRgb[source]

Converts an image from XYZ to RGB

Parameters

image (torch.Tensor) – XYZ image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples

>>> input = torch.rand(2, 3, 4, 5)
>>> rgb = kornia.color.XyzToRgb()
>>> output = rgb(input)  # 2x3x4x5
Reference:

[1] https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html

class RgbToLuv[source]

Converts an image from RGB to Luv

The image data is assumed to be in the range of \([0, 1]\). Luv color is computed using the D65 illuminant and Observer 2.

Parameters

image (torch.Tensor) – RGB image to be converted to Luv.

Returns

Luv version of the image.

Return type

torch.Tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples

>>> input = torch.rand(2, 3, 4, 5)
>>> luv = kornia.color.RgbToLuv()
>>> output = luv(input)  # 2x3x4x5
Reference:

[1] https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html

[2] https://www.easyrgb.com/en/math.php

[3] http://www.poynton.com/ColorFAQ.html

class LuvToRgb[source]

Converts an image from Luv to RGB

Parameters

image (torch.Tensor) – Luv image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.Tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples

>>> input = torch.rand(2, 3, 4, 5)
>>> rgb = kornia.color.LuvToRgb()
>>> output = rgb(input)  # 2x3x4x5

References

[1] https://docs.opencv.org/4.0.1/de/d25/imgproc_color_conversions.html

[2] https://www.easyrgb.com/en/math.php

[3] http://www.poynton.com/ColorFAQ.html

class YcbcrToRgb[source]

Convert image from YCbCr to Rgb The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – YCbCr image to be converted to RGB.

Returns

RGB version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> rgb = kornia.color.YcbcrToRgb()
>>> output = rgb(input)  # 2x3x4x5
class RgbToYcbcr[source]

Convert image from RGB to YCbCr The image data is assumed to be in the range of (0, 1).

Parameters

image (torch.Tensor) – RGB image to be converted to YCbCr.

Returns

YCbCr version of the image.

Return type

torch.tensor

shape:
  • image: \((*, 3, H, W)\)

  • output: \((*, 3, H, W)\)

Examples:

>>> import torch
>>> import kornia
>>> input = torch.rand(2, 3, 4, 5)
>>> ycbcr = kornia.color.RgbToYcbcr()
>>> output = ycbcr(input)  # 2x3x4x5
class Normalize(mean: Union[torch.Tensor, float], std: Union[torch.Tensor, float])[source]

Normalize a tensor image or a batch of tensor images with mean and standard deviation.

Input must be a tensor of shape (C, H, W) or a batch of tensors \((*, C, H, W)\).

Given mean: (M1,...,Mn) and std: (S1,..,Sn) for n channels, this transform will normalize each channel of the input torch.Tensor i.e. input[channel] = (input[channel] - mean[channel]) / std[channel]

Parameters
class Denormalize(mean: Union[torch.Tensor, float], std: Union[torch.Tensor, float])[source]

Denormalize a tensor image or a batch of tensor images.

Input must be a tensor of shape (C, H, W) or a batch of tensors \((*, C, H, W)\).

Given mean: (M1,...,Mn) and std: (S1,..,Sn) for n channels, this transform will denormalize each channel of the input torch.Tensor i.e. input[channel] = (input[channel] * std[channel]) + mean[channel]

Parameters
class ZCAWhitening(dim: int = 0, eps: float = 1e-06, unbiased: bool = True, detach_transforms: bool = True, compute_inv: bool = False)[source]

Computes the ZCA whitening matrix transform and the mean vector and applies the transform to the data. The data tensor is flattened, and the mean \(\mathbf{\mu}\) and covariance matrix \(\mathbf{\Sigma}\) are computed from the flattened data \(\mathbf{X} \in \mathbb{R}^{N \times D}\), where \(N\) is the sample size and \(D\) is flattened dimensionality (e.g. for a tensor with size 5x3x2x2 \(N = 5\) and \(D = 12\)). The ZCA whitening transform is given by:

\[\mathbf{X}_{\text{zca}} = (\mathbf{X - \mu})(US^{-\frac{1}{2}}U^T)^T\]

where \(U\) are the eigenvectors of \(\Sigma\) and \(S\) contain the correpsonding eigenvalues of \(\Sigma\). After the transform is applied, the output is reshaped to same shape.

Parameters
  • dim (int) – Determines the dimension that represents the samples axis. Default = 0

  • eps (float) – a small number used for numerial stablility. Default=1e-6

  • unbiased (bool) – Whether to use the biased estimate of the covariance matrix. Default=False

  • compute_inv (bool) – Compute the inverse transform matrix. Default=False

  • detach_transforms (bool) – Detaches gradient from the ZCA fitting. Default=True

shape:
  • x: \((D_0,...,D_{\text{dim}},...,D_N)\) is a batch of N-D tensors.

  • x_whiten: \((D_0,...,D_{\text{dim}},...,D_N)\) same shape as input.

Examples

>>> x = torch.tensor([[0,1],[1,0],[-1,0],[0,-1]], dtype = torch.float32)
>>> zca = kornia.color.ZCAWhitening().fit(x)
>>> x_whiten = zca(x)
>>> zca = kornia.color.ZCAWhitening()
>>> x_whiten = zca(x, include_fit = True) # Includes the fitting step
>>> x_whiten = zca(x) # Can run now without the fitting set
>>> # Enable backprop through ZCA fitting process
>>> zca = kornia.color.ZCAWhitening(detach_transforms = False)
>>> x_whiten = zca(x, include_fit = True) # Includes the fitting step

Note

This implementation uses svd() which yields NaNs in the backwards step if the sigular values are not unique. See here for more information.

References

[1] Stanford PCA & ZCA whitening tutorial

fit(x: torch.Tensor)[source]

Fits ZCA whitening matrices to the data.

Parameters

x (torch.Tensor) – Input data

Returns

returns a fitted ZCAWhiten object instance.

Return type

ZCAWhiten

forward(x: torch.Tensor, include_fit: bool = False) → torch.Tensor[source]

Applies the whitening transform to the data

Parameters
  • x (torch.Tensor) – Input data

  • include_fit (bool) – Indicates whether to fit the data as part of the forward pass

Returns

The transformed data

Return type

torch.Tensor

inverse_transform(x: torch.Tensor) → torch.Tensor[source]

Applies the inverse transform to the whitened data.

Parameters

x (torch.Tensor) – Whitened data

Returns

original data

Return type

torch.Tensor

class AdjustBrightness(brightness_factor: Union[float, torch.Tensor])[source]

Adjust Brightness of an image. This implementation aligns OpenCV, not PIL. Hence, the output differs from TorchVision.

The input image is expected to be in the range of [0, 1].

Parameters
  • input (torch.Tensor) – Image/Input to be adjusted in the shape of (*, N).

  • brightness_factor (Union[float, torch.Tensor]) – Brightness adjust factor per element in the batch. 0 does not modify the input image while any other number modify the brightness.

Returns

Adjusted image.

Return type

torch.Tensor

class AdjustContrast(contrast_factor: Union[float, torch.Tensor])[source]

Adjust Contrast of an image. This implementation aligns OpenCV, not PIL. Hence, the output differs from TorchVision.

The input image is expected to be in the range of [0, 1].

Parameters
  • input (torch.Tensor) – Image to be adjusted in the shape of (*, N).

  • contrast_factor (Union[float, torch.Tensor]) – Contrast adjust factor per element in the batch. 0 generates a compleatly black image, 1 does not modify the input image while any other non-negative number modify the brightness by this factor.

Returns

Adjusted image.

Return type

torch.Tensor

class AdjustSaturation(saturation_factor: Union[float, torch.Tensor])[source]

Adjust color saturation of an image.

The input image is expected to be an RGB image in the range of [0, 1].

Parameters
  • input (torch.Tensor) – Image/Tensor to be adjusted in the shape of (*, N).

  • saturation_factor (float) – How much to adjust the saturation. 0 will give a black

  • white image, 1 will give the original image while 2 will enhance the saturation (and) –

  • a factor of 2. (by) –

Returns

Adjusted image.

Return type

torch.Tensor

class AdjustHue(hue_factor: Union[float, torch.Tensor])[source]

Adjust hue of an image.

The input image is expected to be an RGB image in the range of [0, 1].

Parameters
  • input (torch.Tensor) – Image/Tensor to be adjusted in the shape of (*, N).

  • hue_factor (float) – How much to shift the hue channel. Should be in [-PI, PI]. PI and -PI give complete reversal of hue channel in HSV space in positive and negative direction respectively. 0 means no shift. Therefore, both -PI and PI will give an image with complementary colors while 0 gives the original image.

Returns

Adjusted image.

Return type

torch.Tensor

class AdjustGamma(gamma: Union[float, torch.Tensor], gain: Union[float, torch.Tensor] = 1.0)[source]

Perform gamma correction on an image.

The input image is expected to be in the range of [0, 1].

Parameters
  • input (torch.Tensor) – Image/Tensor to be adjusted in the shape of (*, N).

  • gamma (float) – Non negative real number, same as γgammaγ in the equation. gamma larger than 1 make the shadows darker, while gamma smaller than 1 make dark regions lighter.

  • gain (float, optional) – The constant multiplier. Default 1.

Returns

Adjusted image.

Return type

torch.Tensor

class AddWeighted(alpha: float, beta: float, gamma: float)[source]

Calculates the weighted sum of two Tensors.

The function calculates the weighted sum of two Tensors as follows:

\[out = src1 * alpha + src2 * beta + gamma\]
Parameters
  • src1 (torch.Tensor) – Tensor.

  • alpha (float) – weight of the src1 elements.

  • src2 (torch.Tensor) – Tensor of same size and channel number as src1.

  • beta (float) – weight of the src2 elements.

  • gamma (float) – scalar added to each sum.

Returns

Weighted Tensor.

Return type

torch.Tensor