Implementation:Kornia Kornia Xyz Conversion

Knowledge Sources	Kornia
Domains	Vision, Color_Processing
Last Updated	2026-02-09 15:00 GMT

Overview

This module provides differentiable conversion between RGB and CIE XYZ color space using the D65 white point, with device-aware optimization.

Description

xyz.py is a module in the Kornia library's color subpackage implementing bidirectional RGB-to-XYZ color space conversion. It uses the standard CIE RGB-to-XYZ transformation matrices for the D65 white point. The module includes an optimized _apply_linear_transformation helper function that selects between torch.einsum (faster on CPU) and F.conv2d (faster on GPU/CUDA) based on the device, ensuring optimal performance across hardware. The rgb_to_xyz function converts RGB to XYZ, and xyz_to_rgb converts XYZ back to RGB. Each has a corresponding nn.Module wrapper (RgbToXyz and XyzToRgb). This module is a core building block used by lab.py and luv.py for their intermediate XYZ representations.

Usage

Import this module when you need CIE XYZ tristimulus values from RGB images, as a preprocessing step for Lab/Luv conversions, or for custom colorimetric computations.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/color/xyz.py
• Lines: 1-195

Signature

def rgb_to_xyz(image: torch.Tensor) -> torch.Tensor: ...
def xyz_to_rgb(image: torch.Tensor) -> torch.Tensor: ...

def _apply_linear_transformation(image: torch.Tensor, kernel: torch.Tensor) -> torch.Tensor: ...

class RgbToXyz(nn.Module):
    def forward(self, image: torch.Tensor) -> torch.Tensor: ...

class XyzToRgb(nn.Module):
    def forward(self, image: torch.Tensor) -> torch.Tensor: ...

Import

from kornia.color import rgb_to_xyz, xyz_to_rgb
from kornia.color import RgbToXyz, XyzToRgb

I/O Contract

Inputs

Name	Type	Required	Description
image (rgb_to_xyz)	torch.Tensor	Yes	RGB image with shape (*, 3, H, W).
image (xyz_to_rgb)	torch.Tensor	Yes	XYZ image with shape (*, 3, H, W).

Outputs

Name	Type	Description
rgb_to_xyz return	torch.Tensor	XYZ image with shape (*, 3, H, W). CIE XYZ tristimulus values.
xyz_to_rgb return	torch.Tensor	RGB image with shape (*, 3, H, W).

Implementation Details

The _apply_linear_transformation function provides a performance-optimized linear color transformation:

• CPU path: Uses torch.einsum("...chw,oc->...ohw", image, kernel) for better CPU performance.
• GPU path: Reshes the image to (B, 3, H, W), the kernel to (3, 3, 1, 1), and applies F.conv2d for GPU-optimized throughput.

The CIE RGB-to-XYZ matrix (D65):

[[0.412453, 0.357580, 0.180423],
 [0.212671, 0.715160, 0.072169],
 [0.019334, 0.119193, 0.950227]]

Usage Examples

Basic Usage

import torch
from kornia.color import rgb_to_xyz, xyz_to_rgb

# Convert RGB to XYZ
rgb = torch.rand(1, 3, 128, 128)
xyz = rgb_to_xyz(rgb)
print(xyz.shape)  # torch.Size([1, 3, 128, 128])

# Convert XYZ back to RGB
rgb_back = xyz_to_rgb(xyz)
print(rgb_back.shape)  # torch.Size([1, 3, 128, 128])

# Using nn.Module wrappers
from kornia.color import RgbToXyz, XyzToRgb
to_xyz = RgbToXyz()
to_rgb = XyzToRgb()
xyz_out = to_xyz(rgb)
rgb_out = to_rgb(xyz_out)

Related Pages

• Principle:Kornia_Kornia_XYZ_Color_Space