CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-colour-science

Comprehensive Python library providing algorithms and datasets for colour science computations, including chromatic adaptation, colour appearance models, colorimetry, and spectral analysis.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

chromatic-adaptation.mddocs/

Chromatic Adaptation

Comprehensive chromatic adaptation functionality for adapting stimuli between different viewing conditions and illuminants using various chromatic adaptation models and transforms.

Capabilities

Main Chromatic Adaptation Function

The primary function for chromatic adaptation with multiple method support.

def chromatic_adaptation(
    XYZ: ArrayLike, 
    XYZ_w: ArrayLike, 
    XYZ_wr: ArrayLike, 
    method: Literal["CIE 1994", "CMCCAT2000", "Fairchild 1990", "Von Kries", "Zhai 2018", "vK20"] = "Von Kries",
    **kwargs: Any
) -> NDArrayFloat:
    """
    Adapt given stimulus from test viewing conditions to reference viewing conditions.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of stimulus to adapt
    - XYZ_w: test viewing condition CIE XYZ tristimulus values of the whitepoint
    - XYZ_wr: reference viewing condition CIE XYZ tristimulus values of the whitepoint
    - method: chromatic adaptation method to use
    - **kwargs: method-specific parameters (see individual methods for details)

    Returns:
    CIE XYZ_c tristimulus values of the stimulus corresponding colour

    Supported Methods:
    - "Von Kries": Classical Von Kries chromatic adaptation
    - "CIE 1994": CIE 1994 chromatic adaptation model 
    - "CMCCAT2000": CMC CAT2000 chromatic adaptation transform
    - "Fairchild 1990": Fairchild's 1990 incomplete chromatic adaptation model
    - "Zhai 2018": Zhai and Luo 2018 two-step chromatic adaptation
    - "vK20": Von Kries 2020 evolution with degree of adaptation

    Domain/Range: [0, 1] for all XYZ parameters in Scale - 1 mode
    """

Von Kries Chromatic Adaptation

Classical Von Kries chromatic adaptation model implementation.

def matrix_chromatic_adaptation_VonKries(
    XYZ_w: ArrayLike,
    XYZ_wr: ArrayLike, 
    transform: LiteralChromaticAdaptationTransform = "CAT02"
) -> NDArrayFloat:
    """
    Compute the chromatic adaptation matrix from test viewing conditions to reference viewing conditions.

    Parameters:
    - XYZ_w: test viewing conditions CIE XYZ tristimulus values of whitepoint
    - XYZ_wr: reference viewing conditions CIE XYZ tristimulus values of whitepoint
    - transform: chromatic adaptation transform matrix to use

    Returns:
    Chromatic adaptation matrix M_cat

    Available transforms: "XYZ Scaling", "Von Kries", "Bradford", "Sharp", 
    "Fairchild", "CMCCAT97", "CMCCAT2000", "CAT02", "CAT02 Brill 2008", 
    "CAT16", "Bianco 2010", "Bianco PC 2010"
    """

def chromatic_adaptation_VonKries(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    XYZ_wr: ArrayLike,
    transform: LiteralChromaticAdaptationTransform = "CAT02"
) -> NDArrayFloat:
    """
    Adapt given stimulus CIE XYZ tristimulus values from test viewing conditions 
    to reference viewing conditions using Von Kries chromatic adaptation model.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of stimulus to adapt
    - XYZ_w: test viewing condition CIE XYZ tristimulus values of whitepoint
    - XYZ_wr: reference viewing condition CIE XYZ tristimulus values of whitepoint  
    - transform: chromatic adaptation transform matrix to use

    Returns:
    CIE XYZ_c tristimulus values of the stimulus corresponding colour
    """

CMCCAT2000 Chromatic Adaptation

CMC CAT2000 chromatic adaptation transform with viewing condition support.

class InductionFactors_CMCCAT2000:
    """
    CMCCAT2000 chromatic adaptation model induction factors.
    
    Attributes:
    - F: surround condition factor
    """
    F: float

def chromatic_adaptation_CMCCAT2000(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    XYZ_wr: ArrayLike,
    L_A1: ArrayLike,
    L_A2: ArrayLike,
    surround: InductionFactors_CMCCAT2000 = None,
    direction: Literal["Forward", "Inverse"] = "Forward"
) -> NDArrayFloat:
    """
    Adapt given stimulus CIE XYZ tristimulus values from test viewing conditions 
    to reference viewing conditions using CMCCAT2000 chromatic adaptation model.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of the stimulus to adapt
    - XYZ_w: test viewing condition CIE XYZ tristimulus values of whitepoint
    - XYZ_wr: reference viewing condition CIE XYZ tristimulus values of whitepoint
    - L_A1: luminance of test adapting field in cd/m²
    - L_A2: luminance of reference adapting field in cd/m²
    - surround: surround viewing conditions induction factors
    - direction: chromatic adaptation direction ("Forward" or "Inverse")

    Returns:
    CIE XYZ_c tristimulus values of the stimulus corresponding colour

    Domain/Range: [0, 100] for XYZ in reference scale, [0, 1] in scale-1 mode
    """

def chromatic_adaptation_forward_CMCCAT2000(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    XYZ_wr: ArrayLike,
    L_A1: ArrayLike,
    L_A2: ArrayLike,
    surround: InductionFactors_CMCCAT2000 = None
) -> NDArrayFloat:
    """
    Forward CMCCAT2000 chromatic adaptation from test to reference conditions.
    
    Parameters same as chromatic_adaptation_CMCCAT2000 with direction="Forward"
    """

def chromatic_adaptation_inverse_CMCCAT2000(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    XYZ_wr: ArrayLike,
    L_A1: ArrayLike,
    L_A2: ArrayLike,
    surround: InductionFactors_CMCCAT2000 = None
) -> NDArrayFloat:
    """
    Inverse CMCCAT2000 chromatic adaptation from reference to test conditions.
    
    Parameters same as chromatic_adaptation_CMCCAT2000 with direction="Inverse"
    """

CIE 1994 Chromatic Adaptation

CIE 1994 chromatic adaptation model with illuminance considerations.

def chromatic_adaptation_CIE1994(
    XYZ_1: ArrayLike,
    xy_o1: ArrayLike,
    xy_o2: ArrayLike,
    Y_o: ArrayLike,
    E_o1: ArrayLike,
    E_o2: ArrayLike,
    n: ArrayLike = 1
) -> NDArrayFloat:
    """
    Adapt given stimulus CIE XYZ tristimulus values from test viewing conditions 
    to reference viewing conditions using CIE 1994 chromatic adaptation model.

    Parameters:
    - XYZ_1: CIE XYZ tristimulus values of test sample/stimulus
    - xy_o1: chromaticity coordinates of test illuminant and background
    - xy_o2: chromaticity coordinates of reference illuminant and background
    - Y_o: luminance factor of achromatic background as percentage [18, 100]
    - E_o1: test illuminance in cd/m²
    - E_o2: reference illuminance in cd/m²
    - n: noise component in fundamental primary system

    Returns:
    Adapted CIE XYZ tristimulus values of stimulus

    Domain/Range: [0, 100] for XYZ and Y_o in reference scale
    """

Fairchild 1990 Chromatic Adaptation

Fairchild's 1990 incomplete chromatic adaptation model.

def chromatic_adaptation_Fairchild1990(
    XYZ_1: ArrayLike,
    XYZ_n: ArrayLike,
    XYZ_r: ArrayLike,
    Y_n: ArrayLike,
    discount_illuminant: bool = False
) -> NDArrayFloat:
    """
    Adapt given stimulus CIE XYZ tristimulus values from test viewing conditions 
    to reference viewing conditions using Fairchild (1990) chromatic adaptation model.

    Parameters:
    - XYZ_1: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_n: test viewing condition CIE XYZ tristimulus values of whitepoint
    - XYZ_r: reference viewing condition CIE XYZ tristimulus values of whitepoint
    - Y_n: luminance of test adapting stimulus in cd/m²
    - discount_illuminant: whether the illuminant should be discounted

    Returns:
    Adapted CIE XYZ tristimulus values of stimulus

    Domain/Range: [0, 100] for XYZ in reference scale, [0, 1] in scale-1 mode
    """

Von Kries 2020 (vK20) Chromatic Adaptation

Modern evolution of Von Kries adaptation with degree of adaptation coefficients.

class Coefficients_DegreeOfAdaptation_vK20:
    """
    Von Kries 2020 (vK20) degree of adaptation coefficients.
    
    Attributes:
    - D_n: degree of adaptation for the adapting illuminant
    - D_r: degree of adaptation for the reference illuminant  
    - D_p: degree of adaptation for the previous illuminant
    """
    D_n: float
    D_r: float
    D_p: float

def matrix_chromatic_adaptation_vk20(
    XYZ_p: ArrayLike,
    XYZ_n: ArrayLike,
    XYZ_r: ArrayLike = None,
    coefficients: Coefficients_DegreeOfAdaptation_vK20 = None,
    transform: LiteralChromaticAdaptationTransform = "CAT02"
) -> NDArrayFloat:
    """
    Compute the vK20 chromatic adaptation matrix.

    Parameters:
    - XYZ_p: previous/test viewing conditions XYZ tristimulus values of whitepoint
    - XYZ_n: current viewing conditions XYZ tristimulus values of whitepoint
    - XYZ_r: reference viewing conditions XYZ tristimulus values of whitepoint
    - coefficients: vK20 degree of adaptation coefficients
    - transform: chromatic adaptation transform matrix to use

    Returns:
    vK20 chromatic adaptation matrix
    """

def chromatic_adaptation_vK20(
    XYZ: ArrayLike,
    XYZ_p: ArrayLike,
    XYZ_n: ArrayLike,
    XYZ_r: ArrayLike = None,
    coefficients: Coefficients_DegreeOfAdaptation_vK20 = None,
    transform: LiteralChromaticAdaptationTransform = "CAT02"
) -> NDArrayFloat:
    """
    Adapt given stimulus CIE XYZ tristimulus values using Von Kries 2020 (vK20) 
    chromatic adaptation model.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of stimulus to adapt
    - XYZ_p: previous/test viewing conditions XYZ tristimulus values of whitepoint
    - XYZ_n: current viewing conditions XYZ tristimulus values of whitepoint
    - XYZ_r: reference viewing conditions XYZ tristimulus values of whitepoint
    - coefficients: vK20 degree of adaptation coefficients
    - transform: chromatic adaptation transform matrix to use

    Returns:
    CIE XYZ_c tristimulus values of the stimulus corresponding colour
    """

Zhai and Luo 2018 Chromatic Adaptation

Two-step chromatic adaptation model with baseline illuminant concept.

def chromatic_adaptation_Zhai2018(
    XYZ_b: ArrayLike,
    XYZ_wb: ArrayLike,
    XYZ_wd: ArrayLike,
    D_b: ArrayLike = 1,
    D_d: ArrayLike = 1,
    XYZ_wo: ArrayLike = None,
    transform: Literal["CAT02", "CAT16"] = "CAT02"
) -> NDArrayFloat:
    """
    Adapt given sample colour from input viewing conditions to output viewing conditions 
    using Zhai and Luo (2018) two-step chromatic adaptation model.

    This model uses a baseline illuminant (BI) concept where adaptation is calculated
    relative to an intrinsic property of the human vision system, allowing for 
    incomplete-to-incomplete adaptation scenarios.

    Parameters:
    - XYZ_b: sample colour under input illuminant β
    - XYZ_wb: input illuminant β tristimulus values
    - XYZ_wd: output illuminant δ tristimulus values  
    - D_b: degree of adaptation of input illuminant β
    - D_d: degree of adaptation of output illuminant δ
    - XYZ_wo: baseline illuminant (BI) tristimulus values
    - transform: chromatic adaptation transform ("CAT02" or "CAT16")

    Returns:
    Sample corresponding colour XYZ tristimulus values under output illuminant

    Domain/Range: [0, 100] for XYZ in reference scale, [0, 1] in scale-1 mode
    """

Chromatic Adaptation Transform Matrices

Pre-defined chromatic adaptation transform matrices for various CAT models.

# Primary CAT Matrices (3x3 NDArrayFloat)
CAT_XYZ_SCALING: NDArrayFloat
"""XYZ Scaling chromatic adaptation transform (identity matrix)."""

CAT_VON_KRIES: NDArrayFloat  
"""Von Kries chromatic adaptation transform."""

CAT_BRADFORD: NDArrayFloat
"""Bradford chromatic adaptation transform."""

CAT_SHARP: NDArrayFloat
"""Sharp chromatic adaptation transform."""

CAT_FAIRCHILD: NDArrayFloat
"""Fairchild chromatic adaptation transform."""

CAT_CMCCAT97: NDArrayFloat
"""CMCCAT97 chromatic adaptation transform."""

CAT_CMCCAT2000: NDArrayFloat
"""CMCCAT2000 chromatic adaptation transform."""

CAT_CAT02: NDArrayFloat
"""CAT02 chromatic adaptation transform."""

CAT_CAT02_BRILL2008: NDArrayFloat
"""Brill and Susstrunk (2008) corrected CAT02 chromatic adaptation transform."""

CAT_CAT16: NDArrayFloat
"""CAT16 chromatic adaptation transform."""

CAT_BIANCO2010: NDArrayFloat
"""Bianco and Schettini (2010) chromatic adaptation transform."""

CAT_PC_BIANCO2010: NDArrayFloat
"""Bianco and Schettini PC (2010) chromatic adaptation transform (no negative lobes)."""

Viewing Conditions and Constants

Standard viewing conditions and adaptation coefficients for chromatic adaptation models.

# CMCCAT2000 Viewing Conditions
VIEWING_CONDITIONS_CMCCAT2000: Dict[str, InductionFactors_CMCCAT2000]
"""
Reference CMCCAT2000 chromatic adaptation model viewing conditions.

Available conditions:
- "Average": F = 1.0
- "Dim": F = 0.8  
- "Dark": F = 0.8
"""

# vK20 Degree of Adaptation Conditions  
CONDITIONS_DEGREE_OF_ADAPTATION_VK20: Dict[str, Coefficients_DegreeOfAdaptation_vK20]
"""
Conditions for the Von Kries 2020 (vK20) degree of adaptation coefficients.

Available conditions:
- "Fairchild": (D_n=0.7, D_r=0.3, D_p=0)
- "Hands": (D_n=0.95, D_r=0.05, D_p=0)
- "No Hands": (D_n=0.85, D_r=0.15, D_p=0)
- "Ordinal 1st": (D_n=0.9, D_r=0.1, D_p=0)
- "Ordinal 2nd": (D_n=0.8, D_r=0.1, D_p=0.1)
- "Reversibility Trial 1st": (D_n=0.7, D_r=0.3, D_p=0.1)
- "Reversibility Trial 2nd": (D_n=0.6, D_r=0.3, D_p=0.1)
- "Ma et al.": (D_n=1/3, D_r=1/3, D_p=1/3)
- "Hunt & Winter": (D_n=0.6, D_r=0.2, D_p=0.2)  
- "Hurvich & Jameson": (D_n=0.7, D_r=0.3, D_p=0)
- "Simple von Kries": (D_n=1, D_r=0, D_p=0)
"""

TVS_XYZ_R_VK20: NDArrayFloat
"""
Von Kries 2020 (vK20) reference illuminant tristimulus values.
Approximately 15000K sky blue (u'=0.185, v'=0.425).
"""

# Transform Collections
CHROMATIC_ADAPTATION_TRANSFORMS: Dict[str, NDArrayFloat]
"""
Available chromatic adaptation transforms mapping method names to matrices.

Keys: "XYZ Scaling", "Von Kries", "Bradford", "Sharp", "Fairchild", 
"CMCCAT97", "CMCCAT2000", "CAT02", "CAT02 Brill 2008", "CAT16", 
"Bianco 2010", "Bianco PC 2010"
"""

CHROMATIC_ADAPTATION_METHODS: Dict[str, Callable]
"""
Supported chromatic adaptation methods mapping method names to functions.

Keys: "CIE 1994", "CMCCAT2000", "Fairchild 1990", "Von Kries", 
"Zhai 2018", "vK20"
"""

Usage Examples

Basic Von Kries Adaptation

import numpy as np

# Basic Von Kries chromatic adaptation
XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
XYZ_w = np.array([0.95045593, 1.00000000, 1.08905775])  # D65
XYZ_wr = np.array([0.96429568, 1.00000000, 0.82510460])  # D50

# Adapt from D65 to D50 using Von Kries (default)
XYZ_adapted = chromatic_adaptation(XYZ, XYZ_w, XYZ_wr)
# array([0.21638817, 0.1257, 0.03847493])

# Using Bradford transform explicitly
XYZ_adapted_bradford = chromatic_adaptation_VonKries(
    XYZ, XYZ_w, XYZ_wr, transform="Bradford"
)

CMCCAT2000 Adaptation with Viewing Conditions

# CMCCAT2000 adaptation with specific viewing conditions
XYZ = np.array([0.2248, 0.2274, 0.0854])
XYZ_w = np.array([1.1115, 1.0000, 0.3520])
XYZ_wr = np.array([0.9481, 1.0000, 1.0730])
L_A = 200

XYZ_adapted = chromatic_adaptation(
    XYZ, XYZ_w, XYZ_wr, 
    method="CMCCAT2000",
    L_A1=L_A, 
    L_A2=L_A,
    surround=VIEWING_CONDITIONS_CMCCAT2000["Average"]
)

vK20 Adaptation with Custom Coefficients

# Von Kries 2020 adaptation with specific coefficients
XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
XYZ_w = np.array([0.95045593, 1.00000000, 1.08905775])
XYZ_wr = np.array([0.96429568, 1.00000000, 0.82510460])

# Using predefined coefficients
XYZ_adapted = chromatic_adaptation(
    XYZ, XYZ_w, XYZ_wr,
    method="vK20",
    coefficients=CONDITIONS_DEGREE_OF_ADAPTATION_VK20["Fairchild"]
)

# Using custom coefficients
custom_coeffs = Coefficients_DegreeOfAdaptation_vK20(D_n=0.8, D_r=0.2, D_p=0)
XYZ_adapted_custom = chromatic_adaptation_vK20(
    XYZ, XYZ_w, XYZ_wr, coefficients=custom_coeffs
)

Two-Step Zhai 2018 Adaptation

# Zhai 2018 two-step adaptation with baseline illuminant
XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
XYZ_wb = np.array([0.95045593, 1.00000000, 1.08905775])  # Input illuminant
XYZ_wd = np.array([0.96429568, 1.00000000, 0.82510460])  # Output illuminant
XYZ_wo = np.array([100, 100, 100])  # Baseline illuminant

XYZ_adapted = chromatic_adaptation(
    XYZ, XYZ_wb, XYZ_wd,
    method="Zhai 2018",
    D_b=0.9,      # Degree of adaptation for input
    D_d=0.95,     # Degree of adaptation for output  
    XYZ_wo=XYZ_wo
)

Computing Adaptation Matrices

# Compute Von Kries adaptation matrix
XYZ_w = np.array([0.95045593, 1.00000000, 1.08905775])
XYZ_wr = np.array([0.96429568, 1.00000000, 0.82510460])

# Using CAT02 transform
M_cat = matrix_chromatic_adaptation_VonKries(XYZ_w, XYZ_wr, transform="CAT02")

# Apply matrix directly to adapt colors
XYZ_adapted_manual = XYZ @ M_cat.T

# vK20 adaptation matrix
M_vk20 = matrix_chromatic_adaptation_vk20(
    XYZ_w, XYZ_wr, 
    coefficients=CONDITIONS_DEGREE_OF_ADAPTATION_VK20["Fairchild"]
)

Type Definitions

from typing import Literal, Union
from numpy.typing import NDArray

# Type aliases for chromatic adaptation
ArrayLike = Union[list, tuple, NDArray]
NDArrayFloat = NDArray[float]

LiteralChromaticAdaptationTransform = Literal[
    "XYZ Scaling", "Von Kries", "Bradford", "Sharp", "Fairchild",
    "CMCCAT97", "CMCCAT2000", "CAT02", "CAT02 Brill 2008", "CAT16", 
    "Bianco 2010", "Bianco PC 2010"
]

LiteralChromaticAdaptationMethod = Literal[
    "CIE 1994", "CMCCAT2000", "Fairchild 1990", 
    "Von Kries", "Zhai 2018", "vK20"
]

Notes

Domain and Range Scaling

Most chromatic adaptation functions support dual domain/range scaling:

  • Reference Scale: XYZ values in [0, 100], Y_o in [0, 100]
  • Scale-1: XYZ values in [0, 1], Y_o in [0, 1]

The scaling mode is controlled by the global domain-range scale setting.

Transform Selection Guidelines

  • CAT02: Default for most applications, good balance of accuracy and stability
  • Bradford: Widely used, excellent for D-series illuminants
  • Von Kries: Classical choice, simple and robust
  • CAT16: Modern choice, designed for CAM16 color appearance model
  • Sharp/Bianco: Optimized transforms for specific applications
  • CMCCAT2000: Specialized for CMCCAT2000 model usage

Method Selection Guidelines

  • Von Kries: Fast, simple, suitable for most applications
  • CMCCAT2000: When viewing conditions (luminance, surround) are important
  • CIE 1994: When illuminance levels affect adaptation
  • Fairchild 1990: For incomplete adaptation scenarios
  • vK20: Modern approach with adaptation history consideration
  • Zhai 2018: For complex incomplete-to-incomplete adaptation scenarios

Performance Considerations

  • Von Kries methods are fastest (simple matrix operations)
  • CMCCAT2000 and CIE 1994 have moderate computational overhead
  • Zhai 2018 is most complex (two-step process with baseline illuminant)
  • Matrix pre-computation recommended for batch processing

Install with Tessl CLI

npx tessl i tessl/pypi-colour-science

docs

advanced-features.md

chromatic-adaptation.md

colorimetry.md

colour-appearance.md

colour-difference.md

colour-models.md

constants.md

geometry.md

index.md

input-output.md

math-utilities.md

notation.md

plotting.md

quality-assessment.md

temperature.md

tile.json