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

colour-appearance.mddocs/

Colour Appearance Models

Comprehensive colour appearance modeling functionality implementing multiple industry-standard models for predicting colour appearance under various viewing conditions and adaptation states. These models account for perceptual effects like chromatic adaptation, brightness perception, and colour constancy.

Capabilities

CIECAM02 Colour Appearance Model

The CIE recommended CIECAM02 model for predicting colour appearance under different viewing conditions.

Forward Transform

def XYZ_to_CIECAM02(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_CIECAM02 = VIEWING_CONDITIONS_CIECAM02["Average"],
    discount_illuminant: bool = False,
    compute_H: bool = True,
) -> CAM_Specification_CIECAM02:
    """
    Compute CIECAM02 colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m² (often 20% of white object luminance)
    - Y_b: luminous factor of background (Y_b = 100 × L_b / L_w)
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant
    - compute_H: whether to compute hue quadrature H

    Returns:
    CAM_Specification_CIECAM02 object containing appearance correlates:
    - J: lightness correlate
    - C: chroma correlate  
    - h: hue angle in degrees
    - s: saturation correlate
    - Q: brightness correlate
    - M: colourfulness correlate
    - H: hue quadrature
    - HC: hue composition

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

Inverse Transform

def CIECAM02_to_XYZ(
    specification: CAM_Specification_CIECAM02,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_CIECAM02 = VIEWING_CONDITIONS_CIECAM02["Average"],
    discount_illuminant: bool = False,
) -> NDArrayFloat:
    """
    Convert CIECAM02 colour appearance specification to CIE XYZ tristimulus values.

    Parameters:
    - specification: CIECAM02 colour appearance specification
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m²
    - Y_b: luminous factor of background
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CIE XYZ tristimulus values

    Notes:
    - Requires at least one of J (lightness) or Q (brightness) to be specified
    - Requires at least one of C (chroma), M (colourfulness), or s (saturation)
    - Requires h (hue angle) for chromatic colours
    """

CIECAM02 Specification Class

@dataclass
class CAM_Specification_CIECAM02:
    """
    CIECAM02 colour appearance model specification.

    Attributes:
    - J: correlate of lightness
    - C: correlate of chroma
    - h: hue angle in degrees
    - s: correlate of saturation
    - Q: correlate of brightness
    - M: correlate of colourfulness
    - H: hue quadrature
    - HC: hue composition

    All attributes are optional and can be None, float, or NDArrayFloat
    """

CIECAM02 Induction Factors and Viewing Conditions

class InductionFactors_CIECAM02:
    """
    CIECAM02 colour appearance model induction factors.

    Parameters:
    - F: maximum degree of adaptation
    - c: exponential non-linearity
    - N_c: chromatic induction factor

    Standard conditions:
    - Average: F=1, c=0.69, N_c=1 (typical viewing)
    - Dim: F=0.9, c=0.59, N_c=0.9 (dim surrounds)
    - Dark: F=0.8, c=0.525, N_c=0.8 (dark surrounds)
    """

# Pre-defined viewing conditions
VIEWING_CONDITIONS_CIECAM02 = {
    "Average": InductionFactors_CIECAM02(1, 0.69, 1),
    "Dim": InductionFactors_CIECAM02(0.9, 0.59, 0.9),
    "Dark": InductionFactors_CIECAM02(0.8, 0.525, 0.8),
}

CAM16 Colour Appearance Model

The CAM16 model, an evolution of CIECAM02 with improved predictions.

Forward Transform

def XYZ_to_CAM16(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_CAM16 = VIEWING_CONDITIONS_CAM16["Average"],
    discount_illuminant: bool = False,
) -> CAM_Specification_CAM16:
    """
    Compute CAM16 colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m²
    - Y_b: luminous factor of background
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CAM_Specification_CAM16 object containing appearance correlates:
    - J: lightness correlate
    - C: chroma correlate
    - h: hue angle in degrees
    - s: saturation correlate
    - Q: brightness correlate
    - M: colourfulness correlate
    - H: hue quadrature
    - HC: hue composition

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

Inverse Transform

def CAM16_to_XYZ(
    specification: CAM_Specification_CAM16,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_CAM16 = VIEWING_CONDITIONS_CAM16["Average"],
    discount_illuminant: bool = False,
) -> NDArrayFloat:
    """
    Convert CAM16 colour appearance specification to CIE XYZ tristimulus values.

    Parameters:
    - specification: CAM16 colour appearance specification
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m²
    - Y_b: luminous factor of background
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CIE XYZ tristimulus values

    Notes:
    - Uses improved CAM16 chromatic adaptation transform (CAT16)
    - More accurate than CIECAM02 for certain viewing conditions
    """

CAM16 Specification and Viewing Conditions

@dataclass
class CAM_Specification_CAM16:
    """
    CAM16 colour appearance model specification.
    
    Same structure as CIECAM02 specification with identical attributes.
    """

class InductionFactors_CAM16:
    """
    CAM16 colour appearance model induction factors.
    
    Same structure as CIECAM02 induction factors:
    - F: maximum degree of adaptation
    - c: exponential non-linearity  
    - N_c: chromatic induction factor
    """

# Inherits CIECAM02 viewing conditions
VIEWING_CONDITIONS_CAM16 = VIEWING_CONDITIONS_CIECAM02

Hunt Colour Appearance Model

The Hunt model providing detailed colour appearance predictions with comprehensive adaptation mechanisms.

Forward Transform

def XYZ_to_Hunt(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    XYZ_b: ArrayLike,
    L_A: ArrayLike,
    surround: InductionFactors_Hunt = VIEWING_CONDITIONS_HUNT["Normal Scenes"],
    L_AS: ArrayLike | None = None,
    CCT_w: ArrayLike | None = None,
    XYZ_p: ArrayLike | None = None,
    p: ArrayLike | None = None,
    S: ArrayLike | None = None,
    S_w: ArrayLike | None = None,
    helson_judd_effect: bool = False,
    discount_illuminant: bool = False,
) -> CAM_Specification_Hunt:
    """
    Compute Hunt colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - XYZ_b: CIE XYZ tristimulus values of background
    - L_A: adapting field luminance in cd/m²
    - surround: surround viewing conditions induction factors
    - L_AS: scotopic luminance of adapting field (optional)
    - CCT_w: correlated colour temperature of illuminant (optional)
    - XYZ_p: CIE XYZ tristimulus values of proximate field (optional)
    - p: simultaneous contrast/assimilation parameter (optional)
    - S: scotopic response (optional)
    - S_w: scotopic response for reference white (optional)
    - helson_judd_effect: whether to account for Helson-Judd effect
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CAM_Specification_Hunt object containing appearance correlates:
    - J: lightness correlate
    - C: chroma correlate
    - h: hue angle in degrees
    - s: saturation correlate
    - Q: brightness correlate
    - M: colourfulness correlate
    - H: hue quadrature
    - HC: hue composition

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

Hunt Specification and Induction Factors

@dataclass
class CAM_Specification_Hunt:
    """
    Hunt colour appearance model specification.

    Attributes:
    - J: correlate of lightness
    - C: correlate of chroma
    - h: hue angle in degrees
    - s: correlate of saturation
    - Q: correlate of brightness
    - M: correlate of colourfulness
    - H: hue quadrature
    - HC: hue composition
    """

class InductionFactors_Hunt:
    """
    Hunt colour appearance model induction factors.

    Parameters:
    - N_c: chromatic induction factor
    - N_b: brightness induction factor
    - N_cb: chromatic brightness induction factor (optional)
    - N_bb: brightness induction factor for background (optional)
    """

# Pre-defined viewing conditions for Hunt model
VIEWING_CONDITIONS_HUNT = {
    "Small Areas, Uniform Background & Surrounds": InductionFactors_Hunt(1, 300),
    "Normal Scenes": InductionFactors_Hunt(1, 75),
    "Television & CRT, Dim Surrounds": InductionFactors_Hunt(1, 25),
    "Large Transparencies On Light Boxes": InductionFactors_Hunt(0.7, 25),
    "Projected Transparencies, Dark Surrounds": InductionFactors_Hunt(0.7, 10),
}

RLAB Colour Appearance Model

The RLAB model providing simplified colour appearance predictions with emphasis on cross-media reproduction.

Forward Transform

def XYZ_to_RLAB(
    XYZ: ArrayLike,
    XYZ_n: ArrayLike,
    Y_n: ArrayLike,
    sigma: ArrayLike = VIEWING_CONDITIONS_RLAB["Average"],
    D: ArrayLike = D_FACTOR_RLAB["Hard Copy Images"],
) -> CAM_Specification_RLAB:
    """
    Compute RLAB colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_n: CIE XYZ tristimulus values of reference white
    - Y_n: luminance factor of reference white
    - sigma: surround relative luminance
    - D: degree of adaptation

    Returns:
    CAM_Specification_RLAB object containing appearance correlates:
    - J: lightness correlate
    - C: chroma correlate
    - h: hue angle in degrees
    - s: saturation correlate
    - HC: hue composition

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

RLAB Specification and Viewing Conditions

@dataclass
class CAM_Specification_RLAB:
    """
    RLAB colour appearance model specification.

    Attributes:
    - J: correlate of lightness
    - C: correlate of chroma
    - h: hue angle in degrees
    - s: correlate of saturation
    - HC: hue composition
    """

# RLAB viewing conditions and adaptation factors
VIEWING_CONDITIONS_RLAB = {
    "Average": 0.2,     # Average surround
    "Dim": 0.1,         # Dim surround  
    "Dark": 0.0,        # Dark surround
}

D_FACTOR_RLAB = {
    "Hard Copy Images": 1.0,           # Complete adaptation
    "Soft Copy Images": 0.7,           # Partial adaptation
    "Projected Transparencies": 0.5,    # Limited adaptation
}

ZCAM Colour Appearance Model

The ZCAM model designed for high dynamic range and wide colour gamut imaging applications.

Forward Transform

def XYZ_to_ZCAM(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_ZCAM = VIEWING_CONDITIONS_ZCAM["Average"],
    discount_illuminant: bool = False,
) -> CAM_Specification_ZCAM:
    """
    Compute ZCAM colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m²
    - Y_b: luminous factor of background
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CAM_Specification_ZCAM object containing appearance correlates:
    - J: lightness correlate
    - C: chroma correlate
    - h: hue angle in degrees
    - s: saturation correlate
    - Q: brightness correlate
    - M: colourfulness correlate
    - H: hue quadrature
    - HC: hue composition
    - V: vividness correlate
    - K: blackness correlate
    - W: whiteness correlate

    Optimized for HDR and wide gamut applications
    Domain/Range: [0, 1] for XYZ parameters in Scale - 1 mode
    """

Inverse Transform

def ZCAM_to_XYZ(
    specification: CAM_Specification_ZCAM,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_ZCAM = VIEWING_CONDITIONS_ZCAM["Average"],
    discount_illuminant: bool = False,
) -> NDArrayFloat:
    """
    Convert ZCAM colour appearance specification to CIE XYZ tristimulus values.

    Parameters:
    - specification: ZCAM colour appearance specification
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m²
    - Y_b: luminous factor of background
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CIE XYZ tristimulus values

    Notes:
    - Designed for HDR and wide colour gamut imaging
    - Enhanced predictions for extreme luminance levels
    """

ZCAM Specification and Induction Factors

@dataclass
class CAM_Specification_ZCAM:
    """
    ZCAM colour appearance model specification.

    Attributes:
    - J: correlate of lightness
    - C: correlate of chroma
    - h: hue angle in degrees
    - s: correlate of saturation
    - Q: correlate of brightness
    - M: correlate of colourfulness
    - H: hue quadrature
    - HC: hue composition
    - V: correlate of vividness
    - K: correlate of blackness
    - W: correlate of whiteness
    """

class InductionFactors_ZCAM:
    """
    ZCAM colour appearance model induction factors.

    Parameters:
    - F_s: surround impact factor
    - F: maximum degree of adaptation
    - c: exponential non-linearity
    - N_c: chromatic induction factor
    """

# Pre-defined ZCAM viewing conditions
VIEWING_CONDITIONS_ZCAM = {
    "Average": InductionFactors_ZCAM(0.69, 1, 0.69, 1),
    "Dim": InductionFactors_ZCAM(0.59, 0.9, 0.59, 0.9),
    "Dark": InductionFactors_ZCAM(0.525, 0.8, 0.525, 0.8),
}

LLAB Colour Appearance Model

The LLAB(l:c) model providing appearance predictions with emphasis on luminance-chroma interactions.

Forward Transform

def XYZ_to_LLAB(
    XYZ: ArrayLike,
    XYZ_0: ArrayLike,
    Y_b: ArrayLike,
    L: ArrayLike,
    surround: InductionFactors_LLAB = VIEWING_CONDITIONS_LLAB["Reference"],
) -> CAM_Specification_LLAB:
    """
    Compute LLAB colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_0: CIE XYZ tristimulus values of reference white
    - Y_b: luminance factor of background
    - L: absolute luminance of reference white in cd/m²
    - surround: surround viewing conditions induction factors

    Returns:
    CAM_Specification_LLAB object containing appearance correlates:
    - J: lightness correlate
    - C: chroma correlate
    - h: hue angle in degrees
    - s: saturation correlate
    - HC: hue composition

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

LLAB Specification and Viewing Conditions

@dataclass
class CAM_Specification_LLAB:
    """
    LLAB colour appearance model specification.

    Attributes:
    - J: correlate of lightness
    - C: correlate of chroma
    - h: hue angle in degrees
    - s: correlate of saturation
    - HC: hue composition
    """

class InductionFactors_LLAB:
    """
    LLAB colour appearance model induction factors.

    Parameters for LLAB(l:c) model configuration.
    """

VIEWING_CONDITIONS_LLAB = {
    "Reference": InductionFactors_LLAB(...),  # Standard reference conditions
}

Additional Appearance Models

ATD95 Model

def XYZ_to_ATD95(
    XYZ: ArrayLike,
    XYZ_0: ArrayLike,
    Y_0: ArrayLike,
    k_1: ArrayLike,
    k_2: ArrayLike,
    sigma: ArrayLike = 300,
) -> CAM_Specification_ATD95:
    """
    Compute ATD95 colour vision model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_0: CIE XYZ tristimulus values of reference white
    - Y_0: luminance factor of reference white
    - k_1: first-order luminance adaptation factor
    - k_2: second-order luminance adaptation factor
    - sigma: sigma factor (default: 300)

    Returns:
    CAM_Specification_ATD95 object containing appearance correlates

    Based on ATD (1995) colour vision model
    """

@dataclass
class CAM_Specification_ATD95:
    """ATD95 colour vision model specification."""

Nayatani95 Model

def XYZ_to_Nayatani95(
    XYZ: ArrayLike,
    XYZ_n: ArrayLike,
    Y_o: ArrayLike,
    E_o: ArrayLike,
    E_or: ArrayLike,
    n: ArrayLike = 1,
) -> CAM_Specification_Nayatani95:
    """
    Compute Nayatani95 colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus  
    - XYZ_n: CIE XYZ tristimulus values of reference white
    - Y_o: luminance factor of achromatic background
    - E_o: illuminance of the background in lux
    - E_or: reference illuminance in lux
    - n: noise component factor

    Returns:
    CAM_Specification_Nayatani95 object containing appearance correlates

    Based on Nayatani (1995) colour appearance model
    """

@dataclass
class CAM_Specification_Nayatani95:
    """Nayatani95 colour appearance model specification."""

Kim2009 Model

def XYZ_to_Kim2009(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    media: MediaParameters_Kim2009 = MEDIA_PARAMETERS_KIM2009["CRT Displays"],
) -> CAM_Specification_Kim2009:
    """
    Compute Kim2009 colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m²
    - media: media viewing parameters for specific display types

    Returns:
    CAM_Specification_Kim2009 object containing appearance correlates

    Optimized for cross-media colour reproduction
    """

def Kim2009_to_XYZ(
    specification: CAM_Specification_Kim2009,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    media: MediaParameters_Kim2009 = MEDIA_PARAMETERS_KIM2009["CRT Displays"],
) -> NDArrayFloat:
    """Convert Kim2009 colour appearance specification to CIE XYZ tristimulus values."""

@dataclass
class CAM_Specification_Kim2009:
    """Kim2009 colour appearance model specification."""

class MediaParameters_Kim2009:
    """Kim2009 media parameters for different display types."""

MEDIA_PARAMETERS_KIM2009 = {
    "CRT Displays": MediaParameters_Kim2009(...),
    "LCD Displays": MediaParameters_Kim2009(...),
    "Printed Images": MediaParameters_Kim2009(...),
}

Hellwig2022 Model

def XYZ_to_Hellwig2022(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_Hellwig2022 = VIEWING_CONDITIONS_HELLWIG2022["Average"],
    discount_illuminant: bool = False,
) -> CAM_Specification_Hellwig2022:
    """
    Compute Hellwig2022 colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_w: CIE XYZ tristimulus values of reference white
    - L_A: adapting field luminance in cd/m²
    - Y_b: luminous factor of background
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CAM_Specification_Hellwig2022 object containing appearance correlates

    Latest evolution of CIECAM02 with improved predictions
    """

def Hellwig2022_to_XYZ(
    specification: CAM_Specification_Hellwig2022,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_Hellwig2022 = VIEWING_CONDITIONS_HELLWIG2022["Average"],
    discount_illuminant: bool = False,
) -> NDArrayFloat:
    """Convert Hellwig2022 colour appearance specification to CIE XYZ tristimulus values."""

@dataclass
class CAM_Specification_Hellwig2022:
    """Hellwig2022 colour appearance model specification."""

class InductionFactors_Hellwig2022:
    """Hellwig2022 colour appearance model induction factors."""

VIEWING_CONDITIONS_HELLWIG2022 = {
    "Average": InductionFactors_Hellwig2022(...),
    "Dim": InductionFactors_Hellwig2022(...),
    "Dark": InductionFactors_Hellwig2022(...),
}

CIECAM16 Model

def XYZ_to_CIECAM16(
    XYZ: ArrayLike,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_CIECAM16 = VIEWING_CONDITIONS_CIECAM16["Average"],
    discount_illuminant: bool = False,
) -> CAM_Specification_CIECAM16:
    """
    Compute CIECAM16 colour appearance model correlates from CIE XYZ tristimulus values.

    Parameters:
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
    - XYZ_w: CIE XYZ tristimulus values of reference white  
    - L_A: adapting field luminance in cd/m²
    - Y_b: luminous factor of background
    - surround: surround viewing conditions induction factors
    - discount_illuminant: whether to discount the illuminant

    Returns:
    CAM_Specification_CIECAM16 object containing appearance correlates

    Alternative formulation of CIECAM02 with different constants
    """

def CIECAM16_to_XYZ(
    specification: CAM_Specification_CIECAM16,
    XYZ_w: ArrayLike,
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: InductionFactors_CIECAM16 = VIEWING_CONDITIONS_CIECAM16["Average"],
    discount_illuminant: bool = False,
) -> NDArrayFloat:
    """Convert CIECAM16 colour appearance specification to CIE XYZ tristimulus values."""

@dataclass
class CAM_Specification_CIECAM16:
    """CIECAM16 colour appearance model specification."""

class InductionFactors_CIECAM16:
    """CIECAM16 colour appearance model induction factors."""

VIEWING_CONDITIONS_CIECAM16 = {
    "Average": InductionFactors_CIECAM16(...),
    "Dim": InductionFactors_CIECAM16(...),
    "Dark": InductionFactors_CIECAM16(...),
}

Helmholtz-Kohlrausch Effect

Functions for computing the Helmholtz-Kohlrausch effect, which describes the increase in perceived brightness of chromatic stimuli compared to achromatic stimuli of equal luminance.

HKE for Object Colours

def HelmholtzKohlrausch_effect_object_Nayatani1997(
    uv: ArrayLike,
    uv_c: ArrayLike,
    L_a: ArrayLike,
    method: Literal["VAC", "VCC"] = "VCC",
) -> NDArrayFloat:
    """
    Compute HKE value for object colours using Nayatani (1997) method.

    Parameters:
    - uv: CIE uv chromaticity coordinates of samples
    - uv_c: CIE uv chromaticity coordinates of reference white
    - L_a: adapting luminance in cd/m²
    - method: estimation method ("VCC" or "VAC")
        - "VCC": Variable Chromatic Colour method
        - "VAC": Variable Achromatic Colour method

    Returns:
    Luminance factor (Γ) values computed with Nayatani object colour estimation

    The HKE quantifies how chromatic colours appear brighter than 
    achromatic colours at the same luminance level.
    """

HKE for Luminous Colours

def HelmholtzKohlrausch_effect_luminous_Nayatani1997(
    uv: ArrayLike,
    uv_c: ArrayLike,
    L_a: ArrayLike,
) -> NDArrayFloat:
    """
    Compute HKE value for luminous colours using Nayatani (1997) method.

    Parameters:
    - uv: CIE uv chromaticity coordinates of samples
    - uv_c: CIE uv chromaticity coordinates of reference white
    - L_a: adapting luminance in cd/m²

    Returns:
    Luminance factor values for luminous colour HKE estimation

    Specialized for self-luminous stimuli like displays and light sources.
    """

HKE Coefficient Functions

def coefficient_q_Nayatani1997(
    uv: ArrayLike,
    uv_c: ArrayLike,
) -> NDArrayFloat:
    """
    Calculate q coefficient for Nayatani 1997 HKE estimation.

    Parameters:
    - uv: CIE uv chromaticity coordinates of samples
    - uv_c: CIE uv chromaticity coordinates of reference white

    Returns:
    q coefficient values used in HKE calculations
    """

def coefficient_K_Br_Nayatani1997(
    uv: ArrayLike,
    uv_c: ArrayLike,
    method: Literal["VAC", "VCC"] = "VCC",
) -> NDArrayFloat:
    """
    Calculate K_Br coefficient for Nayatani 1997 HKE estimation.

    Parameters:
    - uv: CIE uv chromaticity coordinates of samples
    - uv_c: CIE uv chromaticity coordinates of reference white
    - method: estimation method ("VCC" or "VAC")

    Returns:
    K_Br coefficient values used in HKE calculations
    """

# HKE method constants
HKE_NAYATANI1997_METHODS = {
    "VAC": -0.1340,  # Variable Achromatic Colour
    "VCC": -0.8660,  # Variable Chromatic Colour
}

Usage Examples

Basic CIECAM02 Usage

import numpy as np
import colour

# Test sample (sRGB red converted to XYZ)
XYZ = np.array([0.20654008, 0.12197225, 0.01136952])
# D65 whitepoint
XYZ_w = colour.CCS_ILLUMINANTS['CIE 1931 2 Degree Standard Observer']['D65']
# Typical viewing conditions
L_A = 318.31  # cd/m²
Y_b = 20.0    # %

# Compute appearance correlates
specification = colour.XYZ_to_CIECAM02(XYZ, XYZ_w, L_A, Y_b)
print(f"Lightness: {specification.J:.2f}")
print(f"Chroma: {specification.C:.2f}")  
print(f"Hue: {specification.h:.2f}°")

# Convert back to XYZ
XYZ_recovered = colour.CIECAM02_to_XYZ(specification, XYZ_w, L_A, Y_b)

Comparing Multiple Appearance Models

# Compare predictions across models
models = {
    'CIECAM02': colour.XYZ_to_CIECAM02,
    'CAM16': colour.XYZ_to_CAM16,
    'Hunt': lambda XYZ, XYZ_w, L_A, Y_b: colour.XYZ_to_Hunt(
        XYZ, XYZ_w, XYZ_w * 0.2, L_A  # Assuming background = 20% of white
    ),
    'ZCAM': colour.XYZ_to_ZCAM,
}

for name, func in models.items():
    try:
        spec = func(XYZ, XYZ_w, L_A, Y_b)
        print(f"{name}: J={spec.J:.1f}, C={spec.C:.1f}, h={spec.h:.1f}")
    except Exception as e:
        print(f"{name}: Error - {e}")

HKE Effect Demonstration

# Demonstrate Helmholtz-Kohlrausch effect
uv_red = np.array([0.4507, 0.5229])  # Red chromaticity
uv_white = np.array([0.1978, 0.4683])  # White chromaticity  
L_a = 100  # cd/m²

# Compare VCC and VAC methods
hke_vcc = colour.HelmholtzKohlrausch_effect_object_Nayatani1997(
    uv_red, uv_white, L_a, method="VCC"
)
hke_vac = colour.HelmholtzKohlrausch_effect_object_Nayatani1997(
    uv_red, uv_white, L_a, method="VAC"
)

print(f"HKE (VCC method): {hke_vcc:.3f}")
print(f"HKE (VAC method): {hke_vac:.3f}")

Custom Viewing Conditions

# Define custom viewing conditions
from colour.appearance import InductionFactors_CIECAM02

custom_surround = InductionFactors_CIECAM02(
    F=0.95,   # Slightly reduced adaptation
    c=0.65,   # Modified exponential non-linearity
    N_c=0.95  # Reduced chromatic induction
)

# Use custom conditions
specification = colour.XYZ_to_CIECAM02(
    XYZ, XYZ_w, L_A, Y_b, 
    surround=custom_surround,
    discount_illuminant=True
)

Key Concepts

Viewing Conditions

  • Adapting Luminance (L_A): Environmental luminance affecting adaptation state
  • Background Factor (Y_b): Relative luminance of the immediate background
  • Surround Conditions: Environmental factors affecting appearance perception

Appearance Correlates

  • Lightness (J): Perceived lightness relative to white
  • Brightness (Q): Absolute brightness perception
  • Chroma (C): Colorfulness relative to brightness of white
  • Colourfulness (M): Absolute colorfulness perception
  • Saturation (s): Colorfulness relative to brightness of stimulus
  • Hue Angle (h): Angular position in colour space
  • Hue Quadrature (H): Perceptual hue categories (Red, Yellow, Green, Blue)

Model Selection Guidelines

  • CIECAM02: Industry standard, well-validated, recommended for most applications
  • CAM16: Improved version of CIECAM02, better for certain conditions
  • Hunt: Most comprehensive model, includes many perceptual effects
  • ZCAM: Optimized for HDR and wide gamut applications
  • RLAB: Simplified model for cross-media applications
  • LLAB: Specialized for luminance-chroma interactions

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