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

Colorimetry and Spectral Analysis

Name: tessl/pypi-colour-science
Author: tessl

Core colorimetric computations including spectral distribution manipulation, tristimulus value calculations, illuminant and color matching function handling, photometric calculations, and colorimetric properties analysis.

Capabilities

Spectral Distribution Classes

Core classes for representing and manipulating spectral data.

class SpectralDistribution:
    """
    Represents a spectral power distribution.
    
    Parameters:
    - data: dict mapping wavelengths to values, or array-like paired data
    - domain: array-like of wavelengths (if data is array-like values)
    - name: optional name for the distribution
    """
    def __init__(self, data: Union[dict, ArrayLike], domain: ArrayLike = None, name: str = None): ...
    
    def __getitem__(self, wavelength: float) -> float: ...
    def __setitem__(self, wavelength: float, value: float) -> None: ...
    
    @property
    def domain(self) -> NDArray: ...
    @property
    def range(self) -> NDArray: ...
    @property
    def shape(self) -> SpectralShape: ...
    
    def align(self, shape: SpectralShape) -> "SpectralDistribution": ...
    def interpolate(self, shape: SpectralShape, method: str = None) -> "SpectralDistribution": ...
    def extrapolate(self, shape: SpectralShape, method: str = None) -> "SpectralDistribution": ...
    def trim(self, shape: SpectralShape) -> "SpectralDistribution": ...
    def normalise(self, factor: float = 1) -> "SpectralDistribution": ...

class MultiSpectralDistributions:
    """
    Represents multiple spectral power distributions with aligned wavelengths.
    
    Parameters:
    - data: dict mapping names to spectral data, or 2D array with labels
    - domain: array-like of wavelengths
    - labels: names for each distribution (if data is array)
    """
    def __init__(self, data: Union[dict, ArrayLike], domain: ArrayLike = None, labels: List[str] = None): ...
    
    def __getitem__(self, item: Union[str, int]) -> SpectralDistribution: ...
    def __setitem__(self, item: Union[str, int], value: Union[SpectralDistribution, ArrayLike]) -> None: ...
    
    @property
    def domain(self) -> NDArray: ...
    @property
    def range(self) -> NDArray: ...
    @property
    def shape(self) -> SpectralShape: ...

class SpectralShape:
    """
    Defines the spectral range and sampling for spectral distributions.
    
    Parameters:
    - start: starting wavelength
    - end: ending wavelength  
    - interval: wavelength interval
    """
    def __init__(self, start: float, end: float, interval: float = 1): ...
    
    @property
    def start(self) -> float: ...
    @property  
    def end(self) -> float: ...
    @property
    def interval(self) -> float: ...
    @property
    def size(self) -> int: ...
    @property
    def range(self) -> NDArray: ...

Tristimulus Value Calculations

Functions for converting spectral data to CIE XYZ tristimulus values.

def sd_to_XYZ(sd: SpectralDistribution, cmfs: XYZ_ColourMatchingFunctions = None, illuminant: SpectralDistribution = None, k: float = None) -> NDArray:
    """
    Convert spectral distribution to CIE XYZ tristimulus values.
    
    Parameters:
    - sd: spectral distribution to convert
    - cmfs: colour matching functions (defaults to CIE 1931 2° Standard Observer)
    - illuminant: illuminant spectral distribution (defaults to CIE Standard Illuminant D65)
    - k: normalization constant (computed automatically if None)
    
    Returns:
    CIE XYZ tristimulus values as ndarray shape (3,)
    """

def msds_to_XYZ(msds: MultiSpectralDistributions, cmfs: XYZ_ColourMatchingFunctions = None, illuminant: SpectralDistribution = None, k: float = None, method: str = None) -> NDArray:
    """
    Convert multiple spectral distributions to CIE XYZ tristimulus values.
    
    Parameters:
    - msds: multiple spectral distributions
    - cmfs: colour matching functions
    - illuminant: illuminant spectral distribution
    - k: normalization constant
    - method: computation method
    
    Returns:
    CIE XYZ tristimulus values as ndarray shape (n, 3)
    """

def wavelength_to_XYZ(wavelength: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> NDArray:
    """
    Convert wavelength(s) to CIE XYZ tristimulus values of monochromatic stimuli.
    
    Parameters:
    - wavelength: wavelength(s) in nanometers
    - cmfs: colour matching functions
    
    Returns:
    CIE XYZ tristimulus values
    """

Spectral Distribution Generation

Functions for generating standard spectral distributions.

def sd_blackbody(temperature: float, shape: SpectralShape = None) -> SpectralDistribution:
    """
    Generate blackbody spectral distribution for given temperature.
    
    Parameters:
    - temperature: blackbody temperature in Kelvin
    - shape: spectral shape for the distribution
    
    Returns:
    Blackbody spectral distribution
    """

def sd_gaussian(peak_wavelength: float, fwhm: float, shape: SpectralShape = None, method: str = None) -> SpectralDistribution:
    """
    Generate Gaussian spectral distribution.
    
    Parameters:
    - peak_wavelength: peak wavelength in nanometers
    - fwhm: full width at half maximum
    - shape: spectral shape
    - method: computation method
    
    Returns:
    Gaussian spectral distribution
    """

def sd_single_led(peak_wavelength: float, fwhm: float, shape: SpectralShape = None, method: str = None) -> SpectralDistribution:
    """
    Generate single LED spectral distribution.
    
    Parameters:
    - peak_wavelength: LED peak wavelength
    - fwhm: full width at half maximum
    - shape: spectral shape
    - method: LED model method
    
    Returns:
    LED spectral distribution
    """

def sd_multi_leds(peak_wavelengths: ArrayLike, fwhm: ArrayLike, peak_power_ratios: ArrayLike = None, shape: SpectralShape = None, method: str = None) -> SpectralDistribution:
    """
    Generate multi-LED spectral distribution.
    
    Parameters:
    - peak_wavelengths: array of LED peak wavelengths
    - fwhm: array of full width at half maximum values
    - peak_power_ratios: relative power ratios (defaults to equal)
    - shape: spectral shape
    - method: LED model method
    
    Returns:
    Combined multi-LED spectral distribution
    """

Standard Illuminants

Functions for generating CIE standard illuminants.

def sd_CIE_standard_illuminant_A(shape: SpectralShape = None) -> SpectralDistribution:
    """
    Generate CIE Standard Illuminant A spectral distribution.
    
    Parameters:
    - shape: spectral shape
    
    Returns:
    CIE Standard Illuminant A spectral distribution
    """

def sd_CIE_illuminant_D_series(xy: ArrayLike, shape: SpectralShape = None) -> SpectralDistribution:
    """
    Generate CIE Illuminant D Series spectral distribution.
    
    Parameters:
    - xy: CIE xy chromaticity coordinates
    - shape: spectral shape
    
    Returns:
    CIE Illuminant D Series spectral distribution
    """

def sd_mesopic_luminous_efficiency_function(Lp: float, source: str = None, method: str = None, shape: SpectralShape = None) -> SpectralDistribution:
    """
    Generate mesopic luminous efficiency function.
    
    Parameters:
    - Lp: adaptation luminance in cd/m²
    - source: source of the luminous efficiency function data
    - method: computation method
    - shape: spectral shape
    
    Returns:
    Mesopic luminous efficiency function
    """

Photometric Calculations

Photometric quantity calculations from spectral data.

def luminous_flux(sd: SpectralDistribution, lef: SpectralDistribution = None, K_m: float = None) -> float:
    """
    Calculate luminous flux from spectral distribution.
    
    Parameters:
    - sd: spectral distribution
    - lef: luminous efficiency function
    - K_m: maximum luminous efficacy constant
    
    Returns:
    Luminous flux in lumens
    """

def luminous_efficiency(sd: SpectralDistribution, lef: SpectralDistribution = None) -> float:
    """
    Calculate luminous efficiency from spectral distribution.
    
    Parameters:
    - sd: spectral distribution
    - lef: luminous efficiency function
    
    Returns:
    Luminous efficiency (dimensionless ratio)
    """

def luminous_efficacy(sd: SpectralDistribution, lef: SpectralDistribution = None, K_m: float = None) -> float:
    """
    Calculate luminous efficacy from spectral distribution.
    
    Parameters:
    - sd: spectral distribution  
    - lef: luminous efficiency function
    - K_m: maximum luminous efficacy constant
    
    Returns:
    Luminous efficacy in lm/W
    """

Colorimetric Properties

Functions for calculating colorimetric properties from chromaticity coordinates.

def dominant_wavelength(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None, inverse: bool = False) -> Tuple[float, float, bool]:
    """
    Calculate dominant wavelength and excitation purity.
    
    Parameters:
    - xy: CIE xy chromaticity coordinates of test stimulus
    - xy_n: CIE xy chromaticity coordinates of reference white
    - cmfs: colour matching functions
    - inverse: whether to calculate complementary wavelength if outside spectrum locus
    
    Returns:
    Tuple of (wavelength, purity, is_on_spectrum_locus)
    """

def complementary_wavelength(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> Tuple[float, float]:
    """
    Calculate complementary wavelength and excitation purity.
    
    Parameters:
    - xy: CIE xy chromaticity coordinates
    - xy_n: CIE xy chromaticity coordinates of reference white
    - cmfs: colour matching functions
    
    Returns:
    Tuple of (complementary_wavelength, purity)
    """

def excitation_purity(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> float:
    """
    Calculate excitation purity.
    
    Parameters:
    - xy: CIE xy chromaticity coordinates
    - xy_n: CIE xy chromaticity coordinates of reference white
    - cmfs: colour matching functions
    
    Returns:
    Excitation purity (0-1)
    """

def colorimetric_purity(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> float:
    """
    Calculate colorimetric purity.
    
    Parameters:
    - xy: CIE xy chromaticity coordinates
    - xy_n: CIE xy chromaticity coordinates of reference white
    - cmfs: colour matching functions
    
    Returns:
    Colorimetric purity (0-1)
    """

Lightness and Luminance

Functions for converting between lightness and luminance scales.

def lightness(Y: ArrayLike, method: str = None, **kwargs) -> NDArray:
    """
    Calculate lightness from luminance.
    
    Parameters:
    - Y: relative luminance values
    - method: lightness method ('CIE 1976', 'Glasser 1958', 'Wyszecki 1963')
    - **kwargs: additional method-specific parameters
    
    Returns:
    Lightness values
    """

def luminance(L_star: ArrayLike, method: str = None, **kwargs) -> NDArray:
    """
    Calculate luminance from lightness.
    
    Parameters:
    - L_star: lightness values
    - method: lightness method used
    - **kwargs: additional method-specific parameters
    
    Returns:
    Relative luminance values
    """

Constants and Datasets

Standard datasets and constants for colorimetric calculations.

# Standard spectral shapes
SPECTRAL_SHAPE_DEFAULT: SpectralShape
SPECTRAL_SHAPE_ASTME308: SpectralShape

# Colour matching functions
MSDS_CMFS: Dict[str, XYZ_ColourMatchingFunctions]
MSDS_CMFS_LMS: Dict[str, LMS_ConeFundamentals]

# Standard illuminants  
CCS_ILLUMINANTS: Dict[str, NDArray]  # Chromaticity coordinates
SDS_ILLUMINANTS: Dict[str, SpectralDistribution]  # Spectral distributions
TVS_ILLUMINANTS: Dict[str, NDArray]  # Tristimulus values

# Luminous efficiency functions
SDS_LEFS: Dict[str, SpectralDistribution]
SDS_LEFS_PHOTOPIC: Dict[str, SpectralDistribution]
SDS_LEFS_SCOTOPIC: Dict[str, SpectralDistribution]

# Method collections
SD_TO_XYZ_METHODS: Dict[str, Callable]
MSDS_TO_XYZ_METHODS: Dict[str, Callable]
LIGHTNESS_METHODS: Dict[str, Callable]
LUMINANCE_METHODS: Dict[str, Callable]
SD_GAUSSIAN_METHODS: Dict[str, Callable]
SD_SINGLE_LED_METHODS: Dict[str, Callable]
SD_MULTI_LEDS_METHODS: Dict[str, Callable]

Install with Tessl CLI