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

quality-assessment.mddocs/

Quality Assessment

Comprehensive colour quality assessment functions for evaluating illumination source quality, colour fidelity, and spectral similarity. These functions implement industry-standard metrics including CRI, CQS, CFI, and advanced assessment methods for professional lighting evaluation and colour science applications.

Capabilities

Main Quality Assessment Functions

Primary entry points for colour quality calculations with automatic method selection and comprehensive result specifications.

def colour_rendering_index(sd_test: SpectralDistribution, additional_data: bool = False) -> float | ColourRendering_Specification_CRI:
    """
    Calculate Colour Rendering Index (CRI) Ra of given test spectral distribution.
    
    Parameters:
    - sd_test: test illuminant spectral distribution
    - additional_data: whether to output detailed specification with individual sample data
    
    Returns:
    Float CRI Ra value (0-100) or detailed ColourRendering_Specification_CRI
    
    Notes:
    - Based on CIE 13.3-1995 standard using 8 test colour samples (TCS01-TCS08)
    - Uses CIE 1931 2° Standard Observer and CIE 1960 UCS colour space
    - Reference illuminant: blackbody radiator (CCT < 5000K) or CIE Illuminant D (CCT ≥ 5000K)
    - Individual sample indexes available with additional_data=True
    - Values: 100 = perfect colour rendering, lower values indicate poorer rendering
    """

def colour_quality_scale(sd_test: SpectralDistribution, additional_data: bool = False, method: str = "NIST CQS 9.0") -> float | ColourRendering_Specification_CQS:
    """
    Calculate Colour Quality Scale (CQS) of given test spectral distribution.
    
    Parameters:
    - sd_test: test illuminant spectral distribution
    - additional_data: whether to output detailed specification
    - method: computation method:
        * "NIST CQS 9.0": latest CQS method (default)
        * "NIST CQS 7.4": legacy CQS method with preference metrics
    
    Returns:
    Float CQS Qa value (0-100) or detailed ColourRendering_Specification_CQS
    
    Notes:
    - Uses 15 virtual test samples (VS) covering wider gamut than CRI
    - Employs CIE L*a*b* colour space with chromatic adaptation
    - Includes colour fidelity (Qf), preference (Qp), and gamut (Qg) metrics
    - More comprehensive than CRI, especially for LED and novel light sources
    - Values: 100 = excellent quality, 0 = poor quality
    """

def colour_fidelity_index(sd_test: SpectralDistribution, additional_data: bool = False, method: str = "CIE 2017") -> float | ColourRendering_Specification_CIE2017 | ColourQuality_Specification_ANSIIESTM3018:
    """
    Calculate Colour Fidelity Index (CFI) Rf of given test spectral distribution.
    
    Parameters:
    - sd_test: test illuminant spectral distribution
    - additional_data: whether to output detailed specification
    - method: computation method:
        * "CIE 2017": CIE 2017 Colour Fidelity Index (default)
        * "ANSI/IES TM-30-18": IES TM-30-18 method with gamut index
    
    Returns:
    Float CFI Rf value (0-100) or detailed specification object
    
    Notes:
    - Uses 99 test colour samples for comprehensive evaluation
    - Based on CAM02-UCS uniform colour space for improved accuracy
    - CIE 1964 10° Standard Observer for better correlation with visual assessment
    - TM-30-18 method includes gamut index Rg and local metrics
    - Superior to CRI for modern light sources and critical applications
    """

def spectral_similarity_index(sd_test: SpectralDistribution, sd_reference: SpectralDistribution, round_result: bool = True) -> NDArray:
    """
    Calculate Academy Spectral Similarity Index (SSI) between test and reference spectra.
    
    Parameters:
    - sd_test: test spectral distribution
    - sd_reference: reference spectral distribution  
    - round_result: whether to round result to integer (default True)
    
    Returns:
    SSI value (0-100), where 100 indicates perfect spectral match
    
    Notes:
    - Developed by Academy of Motion Picture Arts and Sciences
    - Evaluates spectral similarity rather than colour rendering
    - Uses 375-675nm range with 1nm resolution and specialized weighting
    - Ideal for comparing LED sources to reference illuminants
    - Does not require colour space transformations
    """

# Available methods for each quality metric
COLOUR_FIDELITY_INDEX_METHODS = {
    "CIE 2017": colour_fidelity_index_CIE2017,
    "ANSI/IES TM-30-18": colour_fidelity_index_ANSIIESTM3018
}

COLOUR_QUALITY_SCALE_METHODS = ("NIST CQS 7.4", "NIST CQS 9.0")

CIE Colour Rendering Index (CRI) Functions

Traditional colour rendering evaluation based on CIE 13.3-1995 standard.

def colour_rendering_index(sd_test: SpectralDistribution, additional_data: bool = False) -> float | ColourRendering_Specification_CRI:
    """
    Calculate CRI Ra using 8 standard test colour samples.
    
    Algorithm:
    1. Determine CCT of test source using Robertson's method
    2. Select reference illuminant (blackbody < 5000K, CIE D-series ≥ 5000K)
    3. Calculate tristimulus values for test samples under both illuminants
    4. Apply chromatic adaptation using CIE 1960 UCS
    5. Compute individual rendering indexes Ri for each sample
    6. Calculate general rendering index Ra as average of R1-R8
    
    Test Colour Samples:
    - TCS01: Light greyish red
    - TCS02: Dark greyish yellow  
    - TCS03: Strong yellow green
    - TCS04: Moderate yellowish green
    - TCS05: Light bluish green
    - TCS06: Light blue
    - TCS07: Light violet
    - TCS08: Light reddish purple
    - TCS09-TCS14: Special samples (not included in Ra)
    """

def tcs_colorimetry_data(sd_t: SpectralDistribution, sd_r: SpectralDistribution, sds_tcs: dict, cmfs: MultiSpectralDistributions, chromatic_adaptation: bool = False) -> tuple:
    """
    Calculate colorimetry data for test colour samples under test and reference illuminants.
    
    Parameters:
    - sd_t: test spectral distribution
    - sd_r: reference spectral distribution
    - sds_tcs: test colour sample spectral reflectance distributions
    - cmfs: colour matching functions
    - chromatic_adaptation: apply von Kries chromatic adaptation
    
    Returns:
    Tuple of DataColorimetry_TCS objects containing XYZ, uv, UVW data
    """

def colour_rendering_indexes(test_data: tuple, reference_data: tuple) -> dict:
    """
    Calculate individual colour rendering indexes for each test sample.
    
    Parameters:
    - test_data: colorimetry data under test illuminant
    - reference_data: colorimetry data under reference illuminant
    
    Returns:
    Dictionary mapping sample number to DataColourQualityScale_TCS
    
    Formula: Ri = 100 - 4.6 * ΔE*uv
    """

Colour Quality Scale (CQS) Functions

Advanced quality assessment using virtual test samples and improved colour space.

def colour_quality_scale(sd_test: SpectralDistribution, additional_data: bool = False, method: str = "NIST CQS 9.0") -> float | ColourRendering_Specification_CQS:
    """
    Calculate CQS using 15 virtual samples with comprehensive quality metrics.
    
    Quality Metrics:
    - Qa: Overall colour quality scale
    - Qf: Colour fidelity scale (similar to CRI)
    - Qp: Colour preference scale (rewards increased chroma)
    - Qg: Gamut area scale (relative gamut size)
    - Qd: Relative gamut area scale (deprecated in CQS 9.0)
    
    Virtual Samples (VS):
    - 15 synthetic reflectance spectra covering extended colour gamut
    - More saturated colours than CRI test samples
    - Better representation of real-world object colours
    """

def gamut_area(Lab: ArrayLike) -> float:
    """
    Calculate gamut area covered by given L*a*b* coordinates using triangulation.
    
    Parameters:
    - Lab: L*a*b* colourspace matrices for samples
    
    Returns:
    Gamut area G using Heron's formula for triangular areas
    """

def vs_colorimetry_data(sd_test: SpectralDistribution, sd_reference: SpectralDistribution, sds_vs: dict, cmfs: MultiSpectralDistributions, chromatic_adaptation: bool = False) -> tuple:
    """
    Calculate colorimetry data for virtual samples under test and reference illuminants.
    
    Uses von Kries chromatic adaptation with CMCCAT2000 transform
    when chromatic_adaptation=True for improved accuracy.
    """

def CCT_factor(reference_data: tuple, XYZ_r: ArrayLike) -> float:
    """
    Calculate correlated colour temperature factor penalizing extremely low CCT lamps.
    
    Returns factor ≤ 1.0 that reduces quality scores for sources with
    very low CCT that compress the reference gamut.
    """

def scale_conversion(D_E_ab: float, CCT_f: float, scaling_f: float) -> float:
    """
    Convert ΔE*ab value to CQS scale using logarithmic transformation.
    
    Formula: Qa = 10 * log(1 + exp((100 - scaling_f * ΔE*ab) / 10)) * CCT_f
    """

def delta_E_RMS(CQS_data: dict, attribute: str) -> float:
    """
    Calculate root-mean-square average for CQS data attributes.
    
    Used to compute RMS values for ΔE*ab, ΔE'*ab, and ΔC*ab.
    """

def colour_quality_scales(test_data: tuple, reference_data: tuple, scaling_f: float, CCT_f: float) -> dict:
    """
    Calculate individual quality scales for each virtual sample.
    
    Computes chroma shift ΔC*ab, colour difference ΔE*ab,
    and colour preference difference ΔE'*ab for each sample.
    """

# CQS reference gamut area constant
GAMUT_AREA_D65 = 8210  # Gamut area for CIE Illuminant D65

CIE 2017 Colour Fidelity Index Functions

State-of-the-art colour fidelity assessment using 99 test samples and CAM02-UCS colour space.

def colour_fidelity_index_CIE2017(sd_test: SpectralDistribution, additional_data: bool = False) -> float | ColourRendering_Specification_CIE2017:
    """
    Calculate CIE 2017 Colour Fidelity Index using 99 test colour samples.
    
    Technical Requirements:
    - Spectral range: 380-780nm (recommended)
    - Maximum interval: 5nm
    - Observer: CIE 1964 10° Standard Observer
    - Colour space: CAM02-UCS for uniform colour differences
    - Missing values filled with zeros per standard
    
    Test Colour Samples:
    - 99 samples covering comprehensive colour space
    - Real reflectance spectra from natural and artificial materials
    - Superior coverage compared to CRI's 8 or 14 samples
    """

def load_TCS_CIE2017(shape: SpectralShape) -> MultiSpectralDistributions:
    """
    Load CIE 2017 test colour samples dataset for given spectral shape.
    
    Parameters:
    - shape: spectral shape of tested illuminant
    
    Returns:
    MultiSpectralDistributions containing 99 test samples
    
    Notes:
    - Supports 1nm and 5nm intervals
    - Cached for performance on subsequent calls
    - Labels: TCS0-TCS98 (CIE 2017)
    """

def CCT_reference_illuminant(sd: SpectralDistribution) -> NDArray:
    """
    Determine reference illuminant CCT and Δuv using Ohno 2013 method.
    
    Uses optimized temperature range 1000K-25000K for performance.
    Returns CCT and distance from Planckian locus.
    """

def sd_reference_illuminant(CCT: float, shape: SpectralShape) -> SpectralDistribution:
    """
    Generate reference illuminant for given CCT following CIE 2017 standard.
    
    Reference Selection:
    - CCT < 4000K: Planckian radiator only
    - 4000K ≤ CCT ≤ 5000K: Weighted mixture of Planckian and CIE D-series
    - CCT > 5000K: CIE D-series illuminant only
    
    Mixture ensures smooth transition between reference types.
    """

def tcs_colorimetry_data(sd_irradiance: SpectralDistribution | list, sds_tcs: MultiSpectralDistributions, cmfs: MultiSpectralDistributions) -> tuple:
    """
    Calculate test colour sample colorimetry under CIE 2017 viewing conditions.
    
    Viewing Conditions:
    - Adapting luminance LA: 100 cd/m²
    - Background luminance Yb: 20% of white
    - Surround: Average (CIECAM02)
    - Discount illuminant: True
    """

def delta_E_to_R_f(delta_E: ArrayLike) -> NDArray:
    """
    Convert CAM02-UCS colour difference to CIE 2017 fidelity index.
    
    Formula: Rf = 10 * log(1 + exp((100 - 6.73 * ΔE) / 10))
    
    Where ΔE is Euclidean distance in CAM02-UCS colour space.
    """

# CIE 2017 constants
SPECTRAL_SHAPE_CIE2017 = SpectralShape(380, 780, 1)  # Standard spectral shape
ROOT_RESOURCES_CIE2017 = "datasets/"  # TCS data directory

ANSI/IES TM-30-18 Functions

Extended colour fidelity assessment with gamut index and local colour fidelity metrics.

def colour_fidelity_index_ANSIIESTM3018(sd_test: SpectralDistribution, additional_data: bool = False) -> float | ColourQuality_Specification_ANSIIESTM3018:
    """
    Calculate ANSI/IES TM-30-18 Colour Fidelity Index with comprehensive metrics.
    
    Based on CIE 2017 CFI with additional TM-30-18 specific metrics:
    - Rf: Colour fidelity index (same as CIE 2017)
    - Rg: Gamut index (relative gamut area)
    - Rfs: 16 local colour fidelity indexes per hue bin
    - Rcs: 16 local chromaticity shifts (%)  
    - Rhs: 16 local hue shifts
    
    Hue Binning:
    - 16 equal hue bins of 22.5° each in CAM02-UCS a'b' plane
    - Bin assignment based on reference sample hue angles
    - Local metrics provide detailed spectral performance analysis
    """

def averages_area(averages: ArrayLike) -> float:
    """
    Calculate area of polygon formed by hue bin averages using shoelace formula.
    
    Used for computing gamut index Rg = 100 * (test_area / reference_area).
    """

# TM-30-18 hue bin configuration
# 16 bins × 22.5° = 360° coverage
# Bin centers: 11.25°, 33.75°, ..., 348.75°

Academy Spectral Similarity Index Functions

Direct spectral comparison without colour space transformations.

def spectral_similarity_index(sd_test: SpectralDistribution, sd_reference: SpectralDistribution, round_result: bool = True) -> NDArray:
    """
    Calculate Academy Spectral Similarity Index for direct spectral comparison.
    
    Algorithm:
    1. Normalize spectra to 375-675nm at 1nm resolution
    2. Integrate using weighted trapezoidal rule over 10nm bands
    3. Calculate relative differences with reference offset
    4. Apply wavelength-dependent weighting (higher weight 500-600nm)
    5. Convolve with smoothing kernel [0.22, 0.56, 0.22]
    6. Compute SSI = 100 - 32 * √(Σ(weighted_differences²))
    
    Spectral Requirements:
    - Range: 375-675nm (extrapolated with zeros outside)
    - Resolution: 1nm (interpolated from input)
    - Normalization: area under curve = 1.0
    
    Weighting Function:
    - 375-425nm: 4/15 to 22/45 (low weight, blue)
    - 425-575nm: 32/45 to 1.0 (high weight, visible)
    - 575-625nm: 1.0 (maximum weight, yellow-green)
    - 625-675nm: 11/15 to 3/15 (decreasing weight, red)
    
    Applications:
    - LED source matching to reference illuminants
    - Spectral metameric evaluation
    - Light source development and quality control
    """

# SSI constants
SPECTRAL_SHAPE_SSI = SpectralShape(375, 675, 1)  # Required spectral shape

Specification Classes

Comprehensive data classes for structured quality assessment results.

class ColourRendering_Specification_CRI:
    """
    CRI computation results with detailed sample-by-sample data.
    
    Attributes:
    - name: test illuminant name
    - Q_a: general colour rendering index Ra (0-100)
    - Q_as: individual sample rendering indexes R1-R14
    - colorimetry_data: test and reference colorimetry computations
    
    Individual Sample Data (DataColourQualityScale_TCS):
    - name: sample name (e.g., "TCS01")
    - Q_a: individual rendering index Ri
    """

class ColourRendering_Specification_CQS:
    """
    CQS computation results with comprehensive quality metrics.
    
    Attributes:
    - name: test illuminant name
    - Q_a: overall colour quality scale (0-100)
    - Q_f: colour fidelity scale (0-100)
    - Q_p: colour preference scale (0-100, None in CQS 9.0)
    - Q_g: gamut area scale (relative to D65)
    - Q_d: relative gamut area scale (None in CQS 9.0)
    - Q_as: individual sample quality data
    - colorimetry_data: detailed colorimetric computations
    
    Sample Data (DataColourQualityScale_VS):
    - name: virtual sample name
    - Q_a: sample quality scale
    - D_C_ab: chroma difference ΔC*ab
    - D_E_ab: colour difference ΔE*ab
    - D_Ep_ab: preference-weighted colour difference
    """

class ColourRendering_Specification_CIE2017:
    """
    CIE 2017 CFI results with advanced colorimetric data.
    
    Attributes:
    - name: test illuminant name
    - sd_reference: reference illuminant spectrum
    - R_f: colour fidelity index (0-100)
    - R_s: individual sample fidelity indexes (99 values)
    - CCT: correlated colour temperature (K)
    - D_uv: distance from Planckian locus
    - colorimetry_data: CAM02-UCS based computations
    - delta_E_s: colour shifts in CAM02-UCS space
    
    Colorimetry Data (DataColorimetry_TCS_CIE2017):
    - name: sample names (99 TCS labels)
    - XYZ: CIE XYZ tristimulus values
    - CAM: CIECAM02 appearance specification
    - JMh: lightness-chroma-hue coordinates
    - Jpapbp: CAM02-UCS uniform colour coordinates
    """

class ColourQuality_Specification_ANSIIESTM3018:
    """
    TM-30-18 extended colour quality specification with local metrics.
    
    Extends CIE 2017 specification with:
    - R_g: gamut index (relative gamut area)
    - bins: hue bin assignments for 99 samples
    - averages_test: test hue bin average coordinates
    - averages_reference: reference hue bin averages  
    - average_norms: reference coordinate magnitudes
    - R_fs: local fidelity indexes (16 hue bins)
    - R_cs: local chromaticity shifts (16 values, %)
    - R_hs: local hue shifts (16 values)
    
    Local Metrics Applications:
    - Identify specific hue regions with poor performance
    - Evaluate gamut compression/expansion patterns
    - Optimize LED spectra for targeted applications
    """

# Supporting data classes
class DataColorimetry_TCS:
    """CRI test colour sample colorimetry data."""
    # name: sample name, XYZ: tristimulus, uv: chromaticity, UVW: uniform coordinates

class DataColourQualityScale_TCS:
    """CRI sample quality scale data."""  
    # name: sample name, Q_a: rendering index

class DataColorimetry_VS:
    """CQS virtual sample colorimetry data."""
    # name: sample name, XYZ: tristimulus, Lab: L*a*b*, C: chroma

class DataColourQualityScale_VS:
    """CQS sample quality scale data."""
    # name: sample name, Q_a: quality, D_C_ab: chroma shift, D_E_ab: colour shift, D_Ep_ab: preference shift

class DataColorimetry_TCS_CIE2017:
    """CIE 2017 test sample colorimetry data."""
    # name: sample names, XYZ: tristimulus, CAM: appearance, JMh: appearance coordinates, Jpapbp: uniform coordinates

Constants and Datasets

Essential constants and datasets for quality assessment computations.

# Test colour sample datasets
SDS_TCS = {
    # CRI test colour samples (TCS01-TCS14)
    "TCS01": SpectralDistribution,  # Light greyish red
    "TCS02": SpectralDistribution,  # Dark greyish yellow
    "TCS03": SpectralDistribution,  # Strong yellow green
    "TCS04": SpectralDistribution,  # Moderate yellowish green
    "TCS05": SpectralDistribution,  # Light bluish green
    "TCS06": SpectralDistribution,  # Light blue
    "TCS07": SpectralDistribution,  # Light violet
    "TCS08": SpectralDistribution,  # Light reddish purple
    "TCS09": SpectralDistribution,  # Strong red
    "TCS10": SpectralDistribution,  # Strong yellow
    "TCS11": SpectralDistribution,  # Strong green
    "TCS12": SpectralDistribution,  # Strong blue
    "TCS13": SpectralDistribution,  # Light yellowish pink (Caucasian skin)
    "TCS14": SpectralDistribution   # Moderate olive green (leaf)
}

SDS_VS = {
    "NIST CQS 7.4": {
        # 15 virtual samples for CQS 7.4
    },
    "NIST CQS 9.0": {
        # 15 virtual samples for CQS 9.0  
    }
}

# Sample index mappings
INDEXES_TO_NAMES_TCS = {
    1: "TCS01", 2: "TCS02", 3: "TCS03", 4: "TCS04",
    5: "TCS05", 6: "TCS06", 7: "TCS07", 8: "TCS08", 
    9: "TCS09", 10: "TCS10", 11: "TCS11", 12: "TCS12",
    13: "TCS13", 14: "TCS14"
}

INDEXES_TO_NAMES_VS = {
    # Virtual sample index to name mapping
}

# Reference gamut area
GAMUT_AREA_D65 = 8210  # CIE Illuminant D65 gamut area for CQS normalization

# Spectral shapes
SPECTRAL_SHAPE_CIE2017 = SpectralShape(380, 780, 1)  # CIE 2017 standard shape
SPECTRAL_SHAPE_SSI = SpectralShape(375, 675, 1)      # SSI computation shape

Usage Examples

Practical examples demonstrating quality assessment workflows for different applications.

Basic Quality Assessment

from colour import SDS_ILLUMINANTS, SpectralDistribution
from colour.quality import (
    colour_rendering_index, colour_quality_scale, 
    colour_fidelity_index, spectral_similarity_index
)

# Load test illuminant
sd_test = SDS_ILLUMINANTS["FL2"]  # Fluorescent F2

# Basic quality metrics
cri = colour_rendering_index(sd_test)
print(f"CRI Ra: {cri:.1f}")  # CRI Ra: 64.2

cqs = colour_quality_scale(sd_test)  
print(f"CQS Qa: {cqs:.1f}")  # CQS Qa: 64.1

cfi = colour_fidelity_index(sd_test)
print(f"CFI Rf: {cfi:.1f}")  # CFI Rf: 70.1

# Spectral similarity to daylight
sd_d65 = SDS_ILLUMINANTS["D65"]
ssi = spectral_similarity_index(sd_test, sd_d65)
print(f"SSI: {ssi:.0f}")  # SSI: 75

Detailed Assessment with Specifications

# Get detailed CRI specification with individual sample data
cri_spec = colour_rendering_index(sd_test, additional_data=True)
print(f"General CRI: {cri_spec.Q_a:.1f}")
for i, (sample_num, sample_data) in enumerate(cri_spec.Q_as.items(), 1):
    if i <= 8:  # Show first 8 samples used in Ra
        print(f"  R{sample_num} ({sample_data.name}): {sample_data.Q_a:.1f}")

# Detailed CQS with all quality metrics
cqs_spec = colour_quality_scale(sd_test, additional_data=True, method="NIST CQS 9.0")
print(f"CQS Quality Metrics:")
print(f"  Qa (Overall): {cqs_spec.Q_a:.1f}")  
print(f"  Qf (Fidelity): {cqs_spec.Q_f:.1f}")
print(f"  Qg (Gamut): {cqs_spec.Q_g:.1f}")
# Qp and Qd are None in CQS 9.0

# TM-30-18 with local hue metrics
tm30_spec = colour_fidelity_index(sd_test, additional_data=True, method="ANSI/IES TM-30-18")
print(f"TM-30-18 Metrics:")
print(f"  Rf (Fidelity): {tm30_spec.R_f:.1f}")
print(f"  Rg (Gamut): {tm30_spec.R_g:.1f}")
print(f"Local Fidelity by Hue Bin:")
for i, rf_local in enumerate(tm30_spec.R_fs):
    hue_center = 22.5 * i + 11.25  
    print(f"  Bin {i+1} ({hue_center:.1f}°): Rf={rf_local:.1f}")

LED Source Development

# Evaluate custom LED spectrum
led_data = {
    380: 0.001, 385: 0.002, 390: 0.003, 395: 0.005,
    # ... LED spectral data ...
    450: 0.850, 455: 0.900, 460: 0.950,  # Blue peak
    # ...
    550: 0.120, 555: 0.150, 560: 0.180,  # Green component
    # ...
    630: 0.280, 635: 0.300, 640: 0.320   # Red peak
}
sd_led = SpectralDistribution(led_data, name="Custom LED")

# Comprehensive quality assessment
print("LED Quality Assessment:")
print(f"CRI Ra: {colour_rendering_index(sd_led):.1f}")
print(f"CQS Qa: {colour_quality_scale(sd_led):.1f}")  
print(f"CFI Rf: {colour_fidelity_index(sd_led):.1f}")

# Compare spectral match to target illuminant
target = SDS_ILLUMINANTS["D65"]
ssi_match = spectral_similarity_index(sd_led, target)
print(f"SSI to D65: {ssi_match:.0f}")

# TM-30-18 for detailed analysis
tm30 = colour_fidelity_index(sd_led, additional_data=True, method="ANSI/IES TM-30-18")
print(f"Gamut Index Rg: {tm30.R_g:.1f}")

# Identify weak hue regions
weak_hues = [(i, rf) for i, rf in enumerate(tm30.R_fs) if rf < 80]
if weak_hues:
    print("Weak Performance Hue Regions:")
    for bin_idx, rf_val in weak_hues:
        hue_deg = 22.5 * bin_idx + 11.25
        print(f"  {hue_deg:.0f}° (Rf={rf_val:.1f})")

Method Comparison Study

# Compare all methods for multiple sources
sources = ["A", "D65", "FL2", "FL11"]  # Incandescent, daylight, fluorescent
methods_cfi = ["CIE 2017", "ANSI/IES TM-30-18"] 
methods_cqs = ["NIST CQS 7.4", "NIST CQS 9.0"]

print("Quality Assessment Comparison:")
print("Source    | CRI Ra | CQS 7.4| CQS 9.0| CFI 17 | TM30-18| SSI->D65")
print("-" * 70)

for source in sources:
    sd = SDS_ILLUMINANTS[source]
    
    # Calculate all metrics
    cri = colour_rendering_index(sd)
    cqs_74 = colour_quality_scale(sd, method="NIST CQS 7.4") 
    cqs_90 = colour_quality_scale(sd, method="NIST CQS 9.0")
    cfi_17 = colour_fidelity_index(sd, method="CIE 2017")
    cfi_tm30 = colour_fidelity_index(sd, method="ANSI/IES TM-30-18")
    ssi = spectral_similarity_index(sd, SDS_ILLUMINANTS["D65"])
    
    print(f"{source:9} | {cri:6.1f} | {cqs_74:6.1f} | {cqs_90:6.1f} | "
          f"{cfi_17:6.1f} | {cfi_tm30:7.1f} | {ssi:7.0f}")

Technical Notes

Computational Considerations

  • CRI: Fastest computation, suitable for real-time applications
  • CQS: Moderate complexity, good for general LED evaluation
  • CFI: Most computationally intensive due to 99 samples and CAM02-UCS
  • SSI: Fast spectral-only computation, no colour space transforms

Method Selection Guidelines

  • CRI: Legacy applications, regulatory compliance, basic evaluation
  • CQS: LED development, broader gamut assessment than CRI
  • CIE 2017 CFI: Research applications, most accurate colour fidelity
  • TM-30-18: Comprehensive lighting design, local performance analysis
  • SSI: Spectral matching, metameric source development

Spectral Requirements

  • Range: 380-780nm recommended (CRI/CQS/CFI), 375-675nm (SSI)
  • Resolution: ≤5nm intervals for CFI, 1nm preferred for SSI
  • Extrapolation: Zero-padding for missing spectral regions
  • Normalization: Methods handle relative spectral data appropriately

Accuracy and Limitations

  • All methods assume 2° or 10° standard observer viewing conditions
  • CRI limited by 8 test samples and CIE 1960 UCS colour space
  • CQS virtual samples better represent real object colours than CRI
  • CFI most correlates with visual assessments due to CAM02-UCS uniformity
  • SSI evaluates spectral similarity, not colour rendering quality

The quality assessment module provides comprehensive tools for professional lighting evaluation, supporting both traditional CRI assessment and advanced methods for modern light sources including LEDs, OLEDs, and laser-based systems.

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