Adjust to changes in lighting conditions to maintain consistent color perception despite variations in light sources. More...

#include <peak_ipl/algorithm/peak_ipl_chromatic_adaption.hpp>

Public Types
enum class	ColorSpace { SRGB_D50 = PEAK_IPL_CHROMATIC_ADAPTER_COLOR_SPACE_SRGB_D50 , SRGB_D65 = PEAK_IPL_CHROMATIC_ADAPTER_COLOR_SPACE_SRGB_D65 , CIE_RGB_E = PEAK_IPL_CHROMATIC_ADAPTER_COLOR_SPACE_CIE_RGB_E , ECI_RGB_D50 = PEAK_IPL_CHROMATIC_ADAPTER_COLOR_SPACE_ECI_RGB_D50 , Adobe_RGB_D65 = PEAK_IPL_CHROMATIC_ADAPTER_COLOR_SPACE_ADOBE_RGB_D65 }
	Enumeration that defines the available color spaces. More...

enum class	Algorithm { Legacy = PEAK_IPL_CHROMATIC_ADAPTER_ALGORITHM_LEGACY , Bradford = PEAK_IPL_CHROMATIC_ADAPTER_ALGORITHM_BRADFORD }
	Enumeration that defines the available chromatic adaption algorithms. More...

Public Member Functions
	ChromaticAdapter ()
	Constructor for a new Chromatic Adapter instance.

	~ChromaticAdapter ()
	Destructor for the Chromatic Adapter.

	ChromaticAdapter (const ChromaticAdapter &other)
	Copy Constructor for a new Chromatic Adapter instance.

ChromaticAdapter &	operator= (const ChromaticAdapter &other)
	Copy assigment for Chromatic Adapter instance.

	ChromaticAdapter (ChromaticAdapter &&other) noexcept
	Move constructor for Chromatic Adapter instance.

ChromaticAdapter &	operator= (ChromaticAdapter &&other) noexcept
	Move assignment for Chromatic Adapter instance.

ColorSpace	TargetColorSpace () const
	Get the target color space.

void	SetTargetColorSpace (ColorSpace colorSpace)
	Set the target color space.

Algorithm	AdaptionAlgorithm () const
	Get the current algorithm used for chromatic adaption.

void	SetAdaptionAlgorithm (Algorithm algorithm)
	Set the algorithm used for chromatic adaption.

Range< uint32_t >	TemperatureRange () const
	Returns the allowed temperature range for the current combination of color space and algorithm.

ColorCorrectionFactors	CalculateColorCorrectionMatrix (uint32_t colorTemperature, const ColorCorrectionFactors &correctionFactors=ColorCorrectionFactors::Identity()) const
	Calculate the color correction factors for colorTemperature using the current algorithm and color space.

Detailed Description

Adjust to changes in lighting conditions to maintain consistent color perception despite variations in light sources.

In industrial imaging, white balance can fail due to the lack of a neutral reference in the image, such as when the scene contains no gray or white areas, or when the colors are unevenly distributed (as in images dominated by a single color). In these cases, traditional white balance algorithms, like the gray world method, may fail to produce accurate color corrections.

Chromatic adaptation provides an alternative solution by adjusting the image’s colors based on the known or estimated correlated color temperature of the light source.

Note: If chromatic adaption is used in combination with white balance, the result is indefinite.

Usage

Recommended Image Processing Pipeline

To ensure proper functioning of chromatic adaptation, it is crucial that the image processing pipeline is designed correctly. Chromatic adaptation should be performed on an image with linear color values, meaning it must occur before gamma correction. However, standardized color spaces require gamma-corrected color values for accurate color reproduction. Furthermore, most cameras require color correction for proper color representation.

As a result, the following image processing pipeline is recommended:

Debayer using the peak::ipl::ImageConverter class.
Color correct with a Color Correction Matrix, modified by the Chromatic Adapter, considering the correlated light temperature of the light source.
Gamma correct with the factor for the target color space

Image Processing Pipeline

Configuration

The image pipeline can be configured before image processing begins. The sample code below shows how the necessary modules are set up to process images for the target color space sRGB D65, where the scene is illuminated by a light source with a correlated color temperature of 3600 K.

A gamma corrector is configured with a value of 2.2, which is appropriate for the target color space (sRGB).

The chromatic adapter is set to use the Bradford transform as its algorithm.

The color corrector is initialized with a custom color correction matrix, such as the HQ matrix for the camera's filter glass. Following this, the chromatic adaptation is applied to the matrix using the chromatic adapter and the light source's correlated color temperature of 3600 K.

// prepare the gamma corrector
peak::ipl::GammaCorrector gammaCorrector{};
gammaCorrector.SetGammaCorrectionValue(2.2f);
 
// configure the chromatic adapter
peak::ipl::ChromaticAdapter chromaticAdapter{};
chromaticAdapter.SetTargetColorSpace(peak::ipl::ChromaticAdapter::ColorSpace::SRGB_D65);
chromaticAdapter.SetAdaptionAlgorithm(peak::ipl::ChromaticAdapter::Algorithm::Bradford);
 
// configure the color corrector
peak::ipl::ColorCorrector colorCorrector{};
colorCorrector.SetColorCorrectionFactors(ccm);
 
// apply chromatic adaption
colorCorrector.ApplyChromaticAdaption(chromaticAdapter, 3600);

Alternatively, the adapted color correction matrix can be calculated and applied in two steps. In this case, the second parameter is optional. If not provided, the resulting matrix will be the direct chromatic adaptation matrix.

// apply chromatic adaption
const auto adaptedCcm = chromaticAdapter.CalculateColorCorrectionMatrix(3600, ccm);
colorCorrector.SetColorCorrectionFactors(adaptedCcm);

Image Processing

Each image must be processed following the previously configured image pipeline and in the correct order. It can be processed in-place or by creating a new image, depending on the specific use case.

// 1. debayering
auto image = sourceImage.ConvertTo(peak::ipl::PixelFormatName::RGB8);
 
// 2. color correction with chromatic adaption
colorCorrector.ProcessInPlace(image);
 
// 3. gamma correction
gammaCorrector.ProcessInPlace(image);

The following images demonstrate a setting, where an image with incandescent light is adapted to sRGB D65 color space using a correlated color temperature of 3600 K:

Without chromatic adaption

With chromatic adaption

Terms and Definitions

Color Constancy and Chromatic Adaption

Color constancy is the ability of the human visual system to perceive an object's color consistently, regardless of changes in lighting.

In computer vision, a Chromatic Adaptation Transform (CAT) is a mathematical transformation applied to an image to simulate this perceptual adjustment, ensuring color constancy under varying lighting.

Several algorithms are used to perform CAT, with the Bradford transform being among the most widely used algorithms for this adjustment.

Color Temperature

The correlated color temperature (CCT) describes the color of a visible light source by comparing it to the light emitted by an ideal black body at a specific surface temperature, measured in Kelvin (K).

The following table provides example values:

Light source	Color temperature
Light bulb (100 W)	2700 - 2800 K
Halogen lamp	3000 - 3500 K
Daylight (midday sun)	5000 - 6500 K
Cloudy sky	6500 - 7500 K

For artificial light sources, a "white tone" is often specified, which refers to the perceived warmth or coolness of the light. This is opposite to the actual correlated color temperature. Warm light (reddish) has a lower color temperature, while cold light (bluish) has a higher color temperature.

White tone	Correlated color temperature
Warm white	2700 - 3500 K
Neutral white	4000 - 5000 K
Cool white	5000 - 6500 K

Member Enumeration Documentation

◆ Algorithm

enum class peak::ipl::ChromaticAdapter::Algorithm

strong

Enumeration that defines the available chromatic adaption algorithms.

The algorithms use a CAT (chromatic adaptation transform) matrix for chromatic adaption. There are various available CATs describing the transformation.

Enumerator
Legacy	The legacy algorithm
Bradford	The Bradford CAT matrix algorithm. This is the default.

◆ ColorSpace

enum class peak::ipl::ChromaticAdapter::ColorSpace

strong

Enumeration that defines the available color spaces.

A color space is a specific implementation of a color model, mapping colors to a defined range of values. For example, sRGB is a standardized color space based on the RGB color model, but it also defines color primaries, the white point, and gamma to ensure consistent color representation across various platforms and devices.

Enumerator
SRGB_D50	sRGB (standard RGB): standard illuminant D50 (5000 K), gamma 2.2.
SRGB_D65	sRGB (standard RGB): standard illuminant D65 (6500 K), gamma 2.2.
CIE_RGB_E	CIE-RGB: standard illuminant E (equal energy distribution), gamma 2.2.
ECI_RGB_D50	ECI-RGB: standard illuminant D50 (5000 K), gamma 1.8.
Adobe_RGB_D65	Adobe RGB: standard illuminant D65 (6500 K), gamma 2.2.

Constructor & Destructor Documentation

◆ ChromaticAdapter() [1/3]

peak::ipl::ChromaticAdapter::ChromaticAdapter ( )

inline

Constructor for a new Chromatic Adapter instance.

Since: 1.16

◆ ~ChromaticAdapter()

peak::ipl::ChromaticAdapter::~ChromaticAdapter ( )

inline

Destructor for the Chromatic Adapter.

Since: 1.16

◆ ChromaticAdapter() [2/3]

peak::ipl::ChromaticAdapter::ChromaticAdapter ( const ChromaticAdapter & other )

inline

Copy Constructor for a new Chromatic Adapter instance.

Note: This only creates a shallow copy. See Shallow copy (since 1.8) for a detailed explanation.

Parameters

[in] other The other instance to acquire a reference for.

Since: 1.16

◆ ChromaticAdapter() [3/3]

peak::ipl::ChromaticAdapter::ChromaticAdapter ( ChromaticAdapter && other )

inlinenoexcept

Move constructor for Chromatic Adapter instance.

Moves the instance from other to this, leaving other in an invalid state.

Parameters

[in] other The other instance to move.

Since: 1.16

Member Function Documentation

◆ AdaptionAlgorithm()

ChromaticAdapter::Algorithm peak::ipl::ChromaticAdapter::AdaptionAlgorithm ( ) const

inline

Get the current algorithm used for chromatic adaption.

The implemented algorithms are listed in the enum Algorithm.

Returns: The currently set algorithm.

Since: 1.16

◆ CalculateColorCorrectionMatrix()

ColorCorrectionFactors peak::ipl::ChromaticAdapter::CalculateColorCorrectionMatrix	(	uint32_t	colorTemperature,
		const ColorCorrectionFactors &	correctionFactors = ColorCorrectionFactors::Identity() ) const

inline

Calculate the color correction factors for colorTemperature using the current algorithm and color space.

The optional parameter correctionFactors can be used if the chromatic adaption is to be applied in parallel with another color correction, e.g. the HQ matrix for the camera filter glass. The result will be a matrix multiplication of the initial CCM and the chromatic adaption. It can directly be used. When using the ColorCorrector module, it might be advantageous to adjust an already set CCM using the comfort function ColorCorrector::ApplyChromaticAdaption

Parameters

[in]	colorTemperature	The color temperature in Kelvin for which the factors are be.
[in]	correctionFactors	The input color correction matrix. Default is the identity matrix.

Returns: The calculated color correction factors.

Since: 1.16

◆ operator=() [1/2]

ChromaticAdapter & peak::ipl::ChromaticAdapter::operator= ( ChromaticAdapter && other )

inlinenoexcept

Move assignment for Chromatic Adapter instance.

Moves the instance from other to this, leaving other in an invalid state.

Parameters

[in] other The other instance to move.

Since: 1.16

◆ operator=() [2/2]

ChromaticAdapter & peak::ipl::ChromaticAdapter::operator= ( const ChromaticAdapter & other )

inline

Copy assigment for Chromatic Adapter instance.

Acquires a reference from other to this instance. If this instance already has a reference, it will be destroyed.

Note: See Shallow copy (since 1.8) for a detailed explanation.

Parameters

[in] other The other instance to acquire a reference for.

Since: 1.16

◆ SetAdaptionAlgorithm()

void peak::ipl::ChromaticAdapter::SetAdaptionAlgorithm ( Algorithm algorithm )

inline

Set the algorithm used for chromatic adaption.

The available algorithms are listed in the enum Algorithm.

Parameters

[in] algorithm The algorithm to set.

Since: 1.16

◆ SetTargetColorSpace()

void peak::ipl::ChromaticAdapter::SetTargetColorSpace ( ColorSpace colorSpace )

inline

Set the target color space.

The available color spaces are listed in the enum ColorSpace.

Parameters

[in] colorSpace The color space to set.

Since: 1.16

◆ TargetColorSpace()

ChromaticAdapter::ColorSpace peak::ipl::ChromaticAdapter::TargetColorSpace ( ) const

inline

Get the target color space.

There are many available color spaces. The implemented color spaces are listed in the enum ColorSpace.

Returns: The currently set color space.

Since: 1.16

◆ TemperatureRange()

Range< uint32_t > peak::ipl::ChromaticAdapter::TemperatureRange ( ) const

inline

Returns the allowed temperature range for the current combination of color space and algorithm.

Returns: The allowed temperature range in Kelvin.

Since: 1.16

The documentation for this class was generated from the following file:

peak_ipl/algorithm/peak_ipl_chromatic_adaption.hpp

Public Types

Public Member Functions

Detailed Description

Usage

Recommended Image Processing Pipeline

Configuration

Image Processing

Terms and Definitions

Color Constancy and Chromatic Adaption

Color Temperature

Member Enumeration Documentation

◆ Algorithm

◆ ColorSpace

Constructor & Destructor Documentation

◆ ChromaticAdapter() [1/3]

◆ ~ChromaticAdapter()

◆ ChromaticAdapter() [2/3]

◆ ChromaticAdapter() [3/3]

Member Function Documentation

◆ AdaptionAlgorithm()

◆ CalculateColorCorrectionMatrix()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ SetAdaptionAlgorithm()

◆ SetTargetColorSpace()

◆ TargetColorSpace()

◆ TemperatureRange()