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
advanced-features.mddocs/
Advanced Features
Specialized capabilities including spectral recovery, colour blindness simulation, colour temperature calculations, volume and gamut analysis, optical phenomena modeling, camera characterization, and multi-spectral processing.
Capabilities
Spectral Recovery Functions
Recover spectral distributions from tristimulus values using various computational methods.
def XYZ_to_sd(
XYZ: ArrayLike,
method: Literal[
"Jakob 2019",
"Mallett 2019",
"Meng 2015",
"Otsu 2018",
"Smits 1999"
] = "Meng 2015",
**kwargs: Any
) -> SpectralDistribution:
"""
Recover spectral distribution from CIE XYZ tristimulus values.
Parameters:
- XYZ: CIE XYZ tristimulus values to recover from
- method: Computation method for spectral recovery
- additional_data: (Jakob 2019) Return error alongside sd if True
- basis_functions: (Mallett 2019) Basis functions for the method
- clip: (Otsu 2018) Clip values below zero and above unity
- cmfs: Standard observer colour matching functions
- colourspace: (Jakob 2019) RGB colourspace of target colour
- dataset: (Otsu 2018) Dataset for reconstruction
- illuminant: Illuminant spectral distribution (default D65)
- interval: (Meng 2015) Wavelength range interval in nm
- optimisation_kwargs: Parameters for optimization algorithms
Returns:
- Recovered spectral distribution
"""
def XYZ_to_sd_Jakob2019(
XYZ: ArrayLike,
cmfs: MultiSpectralDistributions = None,
illuminant: SpectralDistribution = None,
optimisation_kwargs: dict = None
) -> SpectralDistribution:
"""
Recover spectral distribution using Jakob and Hanika (2019) method.
Parameters:
- XYZ: CIE XYZ tristimulus values
- cmfs: Standard observer colour matching functions
- illuminant: Illuminant spectral distribution
- optimisation_kwargs: Optimization algorithm parameters
Returns:
- Recovered spectral distribution using low-dimensional function space
"""
def XYZ_to_sd_Meng2015(
XYZ: ArrayLike,
cmfs: MultiSpectralDistributions = None,
illuminant: SpectralDistribution = None,
interval: float = 5,
optimisation_kwargs: dict = None
) -> SpectralDistribution:
"""
Recover spectral distribution using Meng et al. (2015) method.
Parameters:
- XYZ: CIE XYZ tristimulus values
- cmfs: Standard observer colour matching functions
- illuminant: Illuminant spectral distribution
- interval: Wavelength range interval in nm
- optimisation_kwargs: Optimization algorithm parameters
Returns:
- Recovered spectral distribution using tristimulus colour rendering
"""
def XYZ_to_sd_Otsu2018(
XYZ: ArrayLike,
cmfs: MultiSpectralDistributions = None,
illuminant: SpectralDistribution = None,
dataset: Dataset_Otsu2018 = None,
clip: bool = True
) -> SpectralDistribution:
"""
Recover spectral distribution using Otsu et al. (2018) method.
Parameters:
- XYZ: CIE XYZ tristimulus values
- cmfs: Standard observer colour matching functions
- illuminant: Illuminant spectral distribution
- dataset: Dataset for reconstruction
- clip: Clip values to maintain physical realizability
Returns:
- Recovered spectral distribution using machine learning approach
"""
def RGB_to_sd_Smits1999(RGB: ArrayLike) -> SpectralDistribution:
"""
Convert RGB values to spectral distribution using Smits (1999) method.
Parameters:
- RGB: RGB values to convert
Returns:
- Spectral distribution representation of RGB values
"""
def RGB_to_sd_Mallett2019(
RGB: ArrayLike,
basis_functions: MultiSpectralDistributions = None
) -> SpectralDistribution:
"""
Convert RGB to spectral distribution using Mallett and Yuksel (2019) method.
Parameters:
- RGB: RGB values to convert
- basis_functions: Spectral basis functions (default sRGB basis)
Returns:
- Spectral distribution using spectral primary decomposition
"""Colour Blindness Simulation
Simulate various types of colour vision deficiency using physiologically-based models.
def msds_cmfs_anomalous_trichromacy_Machado2009(
cmfs: LMS_ConeFundamentals,
d_LMS: ArrayLike
) -> LMS_ConeFundamentals:
"""
Generate colour matching functions for anomalous trichromacy.
Parameters:
- cmfs: LMS cone fundamentals colour matching functions
- d_LMS: Peak wavelength shift for L, M, S cones
Returns:
- Modified colour matching functions for anomalous trichromacy
"""
def matrix_anomalous_trichromacy_Machado2009(
cmfs: LMS_ConeFundamentals,
primaries: RGB_DisplayPrimaries,
d_LMS: ArrayLike
) -> NDArrayFloat:
"""
Compute transformation matrix for anomalous trichromacy simulation.
Parameters:
- cmfs: LMS cone fundamentals colour matching functions
- primaries: RGB display primaries tri-spectral distributions
- d_LMS: Peak wavelength shift for L, M, S cones
Returns:
- Transformation matrix for anomalous trichromacy
"""
def matrix_cvd_Machado2009(
deficiency: Literal["Protanomaly", "Deuteranomaly", "Tritanomaly"],
severity: float
) -> NDArrayFloat:
"""
Generate colour vision deficiency simulation matrix using Machado et al. (2009).
Parameters:
- deficiency: Type of colour vision deficiency
- severity: Severity of the deficiency (0.0 to 1.0)
Returns:
- CVD simulation transformation matrix
"""Colour Temperature Calculations
Comprehensive correlated colour temperature (CCT) calculations between various coordinate systems.
def xy_to_CCT(
xy: ArrayLike,
method: Literal[
"CIE Illuminant D Series",
"Kang 2002",
"Hernandez 1999",
"McCamy 1992"
] = "CIE Illuminant D Series"
) -> NDArrayFloat:
"""
Convert CIE xy chromaticity coordinates to correlated colour temperature.
Parameters:
- xy: CIE xy chromaticity coordinates
- method: Computation method
- optimisation_kwargs: Parameters for scipy.optimize.minimize
Returns:
- Correlated colour temperature in Kelvin
"""
def CCT_to_xy(
CCT: ArrayLike,
method: Literal[
"CIE Illuminant D Series",
"Kang 2002",
"Hernandez 1999",
"McCamy 1992"
] = "CIE Illuminant D Series"
) -> NDArrayFloat:
"""
Convert correlated colour temperature to CIE xy chromaticity coordinates.
Parameters:
- CCT: Correlated colour temperature in Kelvin
- method: Computation method
- optimisation_kwargs: Parameters for scipy.optimize.minimize
Returns:
- CIE xy chromaticity coordinates
"""
def uv_to_CCT(
uv: ArrayLike,
method: Literal[
"Krystek 1985",
"Ohno 2013",
"Planck 1900",
"Robertson 1968"
] = "Ohno 2013"
) -> NDArrayFloat:
"""
Convert CIE UCS uv chromaticity coordinates to CCT and Duv.
Parameters:
- uv: CIE UCS colourspace uv chromaticity coordinates
- method: Computation method
- cmfs: Standard observer colour matching functions
- count: (Ohno 2013) Temperature count in planckian tables
- start/end: (Ohno 2013) Temperature range in Kelvin
- iterations: (Ohno 2013) Number of planckian tables to generate
- optimisation_kwargs: Parameters for optimization
Returns:
- Correlated colour temperature and delta uv [CCT, Duv]
"""
def CCT_to_uv(
CCT_D_uv: ArrayLike,
method: Literal[
"Krystek 1985",
"Ohno 2013",
"Planck 1900",
"Robertson 1968"
] = "Ohno 2013"
) -> NDArrayFloat:
"""
Convert correlated colour temperature and Duv to CIE UCS uv coordinates.
Parameters:
- CCT_D_uv: Correlated colour temperature and delta uv [CCT, Duv]
- method: Computation method
- cmfs: Standard observer colour matching functions
Returns:
- CIE UCS colourspace uv chromaticity coordinates
"""
def CCT_to_mired(CCT: ArrayLike) -> NDArrayFloat:
"""Convert correlated colour temperature to mired scale."""
def mired_to_CCT(mired: ArrayLike) -> NDArrayFloat:
"""Convert mired scale to correlated colour temperature."""Volume and Gamut Analysis
Analyze colour gamut volumes, coverage, and boundary conditions for various colour spaces.
def RGB_colourspace_volume_MonteCarlo(
colourspace: RGB_Colourspace,
samples: int = 1000000,
limits: ArrayLike = None,
illuminant_RGB: ArrayLike = None,
illuminant_XYZ: ArrayLike = None,
chromatic_adaptation_transform: str = None
) -> float:
"""
Compute RGB colourspace volume using Monte Carlo sampling.
Parameters:
- colourspace: RGB colourspace to analyze
- samples: Number of Monte Carlo samples
- limits: RGB colourspace limits
- illuminant_RGB: RGB colourspace illuminant
- illuminant_XYZ: Target illuminant for adaptation
- chromatic_adaptation_transform: Adaptation method
Returns:
- Colourspace volume in cubic units
"""
def RGB_colourspace_limits(
colourspace: RGB_Colourspace,
illuminant: ArrayLike = None
) -> NDArrayFloat:
"""
Compute RGB colourspace limits in CIE XYZ tristimulus values.
Parameters:
- colourspace: RGB colourspace to analyze
- illuminant: Illuminant chromaticity coordinates
Returns:
- RGB colourspace limits as min/max XYZ values
"""
def RGB_colourspace_pointer_gamut_coverage_MonteCarlo(
colourspace: RGB_Colourspace,
samples: int = 1000000
) -> float:
"""
Compute RGB colourspace coverage of Pointer's gamut using Monte Carlo.
Parameters:
- colourspace: RGB colourspace to analyze
- samples: Number of Monte Carlo samples
Returns:
- Coverage percentage of Pointer's gamut [0-1]
"""
def RGB_colourspace_visible_spectrum_coverage_MonteCarlo(
colourspace: RGB_Colourspace,
samples: int = 1000000
) -> float:
"""
Compute RGB colourspace coverage of visible spectrum using Monte Carlo.
Parameters:
- colourspace: RGB colourspace to analyze
- samples: Number of Monte Carlo samples
Returns:
- Coverage percentage of visible spectrum [0-1]
"""
def is_within_macadam_limits(
XYZ: ArrayLike,
illuminant: ArrayLike = None
) -> NDArrayFloat:
"""
Test whether XYZ tristimulus values are within MacAdam limits.
Parameters:
- XYZ: CIE XYZ tristimulus values to test
- illuminant: Illuminant chromaticity coordinates
Returns:
- Boolean array indicating values within MacAdam limits
"""
def is_within_pointer_gamut(XYZ: ArrayLike) -> NDArrayFloat:
"""
Test whether XYZ values are within Pointer's gamut.
Parameters:
- XYZ: CIE XYZ tristimulus values to test
Returns:
- Boolean array indicating values within Pointer's gamut
"""
def is_within_visible_spectrum(
XYZ: ArrayLike,
cmfs: MultiSpectralDistributions = None,
illuminant: SpectralDistribution = None
) -> NDArrayFloat:
"""
Test whether XYZ values are within visible spectrum limits.
Parameters:
- XYZ: CIE XYZ tristimulus values to test
- cmfs: Standard observer colour matching functions
- illuminant: Illuminant spectral distribution
Returns:
- Boolean array indicating values within visible spectrum
"""
def is_within_mesh_volume(
points: ArrayLike,
mesh: ArrayLike,
tolerance: float = 1e-10
) -> NDArrayFloat:
"""
Test whether points are within given mesh volume.
Parameters:
- points: Points to test
- mesh: Mesh vertices defining volume boundary
- tolerance: Computation tolerance
Returns:
- Boolean array indicating points within mesh volume
"""Optical Phenomena Modeling
Model atmospheric optical phenomena including Rayleigh scattering.
def rayleigh_scattering(
wavelength: ArrayLike,
CO2_concentration: float = 300,
temperature: float = 288.15,
pressure: float = 101325,
latitude: float = 0,
altitude: float = 0
) -> NDArrayFloat:
"""
Compute Rayleigh scattering cross-section.
Parameters:
- wavelength: Wavelength values in nanometers
- CO2_concentration: CO2 concentration in parts per million
- temperature: Air temperature in Kelvin
- pressure: Air pressure in Pascal
- latitude: Latitude in degrees
- altitude: Altitude in meters
Returns:
- Rayleigh scattering cross-section values
"""
def scattering_cross_section(
wavelength: ArrayLike,
CO2_concentration: float = 300,
temperature: float = 288.15,
pressure: float = 101325,
latitude: float = 0,
altitude: float = 0
) -> NDArrayFloat:
"""
Compute scattering cross-section for given atmospheric conditions.
Parameters:
- wavelength: Wavelength values in nanometers
- CO2_concentration: CO2 concentration in parts per million
- temperature: Air temperature in Kelvin
- pressure: Air pressure in Pascal
- latitude: Latitude in degrees
- altitude: Altitude in meters
Returns:
- Scattering cross-section values per unit volume
"""
def rayleigh_optical_depth(
wavelength: ArrayLike,
CO2_concentration: float = 300,
temperature: float = 288.15,
pressure: float = 101325,
latitude: float = 0,
altitude: float = 0
) -> NDArrayFloat:
"""
Compute Rayleigh optical depth in atmosphere.
Parameters:
- wavelength: Wavelength values in nanometers
- CO2_concentration: CO2 concentration in parts per million
- temperature: Air temperature in Kelvin
- pressure: Air pressure in Pascal
- latitude: Latitude in degrees
- altitude: Altitude in meters
Returns:
- Rayleigh optical depth values
"""
def sd_rayleigh_scattering(
shape: SpectralShape = None,
CO2_concentration: float = 300,
temperature: float = 288.15,
pressure: float = 101325,
latitude: float = 0,
altitude: float = 0
) -> SpectralDistribution:
"""
Generate Rayleigh scattering spectral distribution.
Parameters:
- shape: Spectral shape for the distribution
- CO2_concentration: CO2 concentration in parts per million
- temperature: Air temperature in Kelvin
- pressure: Air pressure in Pascal
- latitude: Latitude in degrees
- altitude: Altitude in meters
Returns:
- Rayleigh scattering spectral distribution
"""Camera Characterization Functions
Characterize camera sensors and display devices for accurate colour reproduction.
def matrix_colour_correction(
M1: ArrayLike,
M2: ArrayLike,
method: Literal[
"Cheung 2004",
"Finlayson 2015",
"Vandermonde"
] = "Cheung 2004"
) -> NDArrayFloat:
"""
Compute colour correction matrix between two sets of colours.
Parameters:
- M1: Reference colours
- M2: Test colours
- method: Matrix computation method
Returns:
- Colour correction transformation matrix
"""
def colour_correction(
RGB: ArrayLike,
M_T: ArrayLike,
M_R: ArrayLike,
method: Literal[
"Cheung 2004",
"Finlayson 2015",
"Vandermonde"
] = "Cheung 2004"
) -> NDArrayFloat:
"""
Perform colour correction on RGB data.
Parameters:
- RGB: RGB values to correct
- M_T: Test colours matrix
- M_R: Reference colours matrix
- method: Correction method
Returns:
- Colour corrected RGB values
"""
def matrix_idt(
sensitivities: RGB_CameraSensitivities,
illuminant: SpectralDistribution,
training_data: MultiSpectralDistributions = None,
cmfs: MultiSpectralDistributions = None,
optimisation_factory: Callable = None,
optimisation_kwargs: dict = None
) -> NDArrayFloat:
"""
Compute Input Device Transform (IDT) matrix for camera characterization.
Parameters:
- sensitivities: Camera RGB sensitivities
- illuminant: Scene illuminant spectral distribution
- training_data: Training spectral reflectances
- cmfs: Standard observer colour matching functions
- optimisation_factory: Optimization method factory
- optimisation_kwargs: Optimization parameters
Returns:
- IDT transformation matrix from camera RGB to ACES
"""
def camera_RGB_to_ACES2065_1(
RGB: ArrayLike,
matrix_idt: ArrayLike
) -> NDArrayFloat:
"""
Convert camera RGB to ACES2065-1 colourspace.
Parameters:
- RGB: Camera RGB values
- matrix_idt: Input Device Transform matrix
Returns:
- ACES2065-1 RGB values
"""
def sd_to_aces_relative_exposure_values(
sd: SpectralDistribution,
illuminant: SpectralDistribution,
sensitivities: RGB_CameraSensitivities,
ISO: float = 100
) -> NDArrayFloat:
"""
Convert spectral distribution to ACES relative exposure values.
Parameters:
- sd: Spectral distribution of target
- illuminant: Scene illuminant spectral distribution
- sensitivities: Camera RGB sensitivities
- ISO: ISO speed rating
Returns:
- ACES relative exposure values
"""Color Correction and Matrix Generation
Advanced colour correction techniques for device characterization and calibration.
def polynomial_expansion(
RGB: ArrayLike,
method: Literal[
"Cheung 2004",
"Finlayson 2015",
"Vandermonde"
] = "Cheung 2004",
degree: int = 1
) -> NDArrayFloat:
"""
Expand RGB values using polynomial basis functions.
Parameters:
- RGB: RGB values to expand
- method: Polynomial expansion method
- degree: Polynomial degree for expansion
Returns:
- Expanded RGB values with polynomial terms
"""
def matrix_augmented_Cheung2004(RGB: ArrayLike) -> NDArrayFloat:
"""
Augment RGB matrix using Cheung et al. (2004) method.
Parameters:
- RGB: RGB values to augment
Returns:
- Augmented matrix with cross-channel terms
"""
def whitepoint_preserving_matrix(
XYZ_w: ArrayLike,
RGB_w: ArrayLike,
XYZ: ArrayLike,
RGB: ArrayLike
) -> NDArrayFloat:
"""
Compute whitepoint preserving transformation matrix.
Parameters:
- XYZ_w: Reference whitepoint in XYZ
- RGB_w: Camera whitepoint in RGB
- XYZ: Reference colour patches in XYZ
- RGB: Camera colour patches in RGB
Returns:
- Whitepoint preserving transformation matrix
"""
def white_balance_multipliers(
sensitivities: RGB_CameraSensitivities,
illuminant: SpectralDistribution
) -> NDArrayFloat:
"""
Compute white balance multipliers for camera sensitivities.
Parameters:
- sensitivities: Camera RGB sensitivities
- illuminant: Scene illuminant spectral distribution
Returns:
- White balance multiplier values for R, G, B channels
"""
def best_illuminant(
reflectances: MultiSpectralDistributions,
sensitivities: RGB_CameraSensitivities,
illuminants: dict
) -> str:
"""
Find best matching illuminant for given scene conditions.
Parameters:
- reflectances: Scene reflectance spectra
- sensitivities: Camera RGB sensitivities
- illuminants: Dictionary of candidate illuminants
Returns:
- Name of best matching illuminant
"""Multi-Spectral Image Processing
Process multi-spectral and hyperspectral imaging data.
class MultiSpectralDistributions:
"""
Represents multiple aligned spectral power distributions.
Parameters:
- data: Dictionary mapping names to spectral data or 2D array
- 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: SpectralDistribution) -> None: ...
@property
def wavelengths(self) -> NDArray: ...
@property
def values(self) -> NDArray: ...
@property
def shape(self) -> SpectralShape: ...
def align(self, shape: SpectralShape) -> "MultiSpectralDistributions": ...
def trim(self, shape: SpectralShape) -> "MultiSpectralDistributions": ...
def interpolate(self, shape: SpectralShape, method: str = None) -> "MultiSpectralDistributions": ...
def msds_to_XYZ(
msds: MultiSpectralDistributions,
cmfs: MultiSpectralDistributions,
illuminant: SpectralDistribution,
k: float = None,
shape: SpectralShape = None
) -> NDArrayFloat:
"""
Convert multiple spectral distributions to CIE XYZ tristimulus values.
Parameters:
- msds: Multiple spectral distributions to convert
- cmfs: Standard observer colour matching functions
- illuminant: Illuminant spectral distribution
- k: Normalisation constant
- shape: Spectral shape for computation
Returns:
- CIE XYZ tristimulus values for each distribution
"""
def RGB_to_msds_camera_sensitivities_Jiang2013(
RGB: ArrayLike,
basis_functions: MultiSpectralDistributions,
mean_stds: MultiSpectralDistributions = None
) -> MultiSpectralDistributions:
"""
Recover multiple spectral distributions from RGB using camera sensitivities.
Parameters:
- RGB: Camera RGB values
- basis_functions: Spectral basis functions for reconstruction
- mean_stds: Mean spectral distributions for basis
Returns:
- Reconstructed multiple spectral distributions
"""
def PCA_Jiang2013(
reflectances: MultiSpectralDistributions,
illuminants: MultiSpectralDistributions,
sensitivities: RGB_CameraSensitivities
) -> dict:
"""
Perform PCA analysis for spectral reconstruction using Jiang et al. (2013).
Parameters:
- reflectances: Training reflectance spectra
- illuminants: Training illuminant spectra
- sensitivities: Camera RGB sensitivities
Returns:
- Dictionary containing PCA basis functions and statistics
"""Biochemical Modeling
Model biochemical processes relevant to vision and colour perception.
def reaction_rate_MichaelisMenten(
S: ArrayLike,
V_max: ArrayLike,
K_m: ArrayLike,
method: Literal[
"Michaelis 1913",
"Abebe 2017",
"Henri 1903"
] = "Michaelis 1913"
) -> NDArrayFloat:
"""
Compute Michaelis-Menten reaction rate.
Parameters:
- S: Substrate concentration
- V_max: Maximum reaction velocity
- K_m: Michaelis constant
- method: Computation method
Returns:
- Reaction rate values
"""
def substrate_concentration_MichaelisMenten(
v: ArrayLike,
V_max: ArrayLike,
K_m: ArrayLike,
method: Literal[
"Michaelis 1913",
"Abebe 2017"
] = "Michaelis 1913"
) -> NDArrayFloat:
"""
Compute substrate concentration from reaction rate using Michaelis-Menten.
Parameters:
- v: Reaction rate
- V_max: Maximum reaction velocity
- K_m: Michaelis constant
- method: Computation method
Returns:
- Substrate concentration values
"""Usage Examples
Advanced Spectral Recovery
import colour
import numpy as np
# Recover spectral distribution from XYZ using different methods
XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
# Jakob 2019 method - Low-dimensional function space
sd_jakob = colour.XYZ_to_sd(XYZ, method="Jakob 2019")
# Meng 2015 method - Optimization-based approach
sd_meng = colour.XYZ_to_sd(XYZ, method="Meng 2015", interval=10)
# Otsu 2018 method - Machine learning approach
sd_otsu = colour.XYZ_to_sd(XYZ, method="Otsu 2018", clip=True)
# RGB to spectral using Smits 1999
RGB = np.array([0.8, 0.4, 0.2])
sd_smits = colour.RGB_to_sd_Smits1999(RGB)Colour Vision Deficiency Simulation
# Simulate different types of colour blindness
import colour
# Generate CVD simulation matrix
matrix_protanomaly = colour.matrix_cvd_Machado2009("Protanomaly", 0.8)
matrix_deuteranomaly = colour.matrix_cvd_Machado2009("Deuteranomaly", 0.6)
matrix_tritanomaly = colour.matrix_cvd_Machado2009("Tritanomaly", 0.4)
# Apply CVD simulation to RGB image
RGB_image = np.random.random((100, 100, 3))
RGB_protanomaly = np.dot(RGB_image, matrix_protanomaly.T)Colour Temperature Analysis
# Convert between chromaticity coordinates and CCT
xy = np.array([0.31270, 0.32900])
# Get CCT using different methods
CCT_cie = colour.xy_to_CCT(xy, method="CIE Illuminant D Series")
CCT_mccamy = colour.xy_to_CCT(xy, method="McCamy 1992")
# Convert back to chromaticity coordinates
xy_recovered = colour.CCT_to_xy(CCT_cie)
# Work with uv coordinates and Duv
uv = np.array([0.1978, 0.3122])
CCT_Duv = colour.uv_to_CCT(uv, method="Ohno 2013")
CCT, Duv = CCT_Duv[0], CCT_Duv[1]Gamut Analysis and Volume Calculations
# Analyze RGB colourspace properties
colourspace = colour.RGB_COLOURSPACES["sRGB"]
# Compute colourspace volume
volume = colour.RGB_colourspace_volume_MonteCarlo(colourspace, samples=1000000)
# Calculate coverage of standard gamuts
pointer_coverage = colour.RGB_colourspace_pointer_gamut_coverage_MonteCarlo(colourspace)
spectrum_coverage = colour.RGB_colourspace_visible_spectrum_coverage_MonteCarlo(colourspace)
# Test if XYZ values are within various limits
XYZ_test = np.array([0.3, 0.3, 0.3])
within_macadam = colour.is_within_macadam_limits(XYZ_test)
within_pointer = colour.is_within_pointer_gamut(XYZ_test)
within_spectrum = colour.is_within_visible_spectrum(XYZ_test)Atmospheric Phenomena Modeling
# Model Rayleigh scattering in atmosphere
wavelengths = np.linspace(380, 780, 41)
# Standard atmosphere conditions
scattering = colour.rayleigh_scattering(
wavelengths,
CO2_concentration=400, # ppm
temperature=288.15, # K (15°C)
pressure=101325, # Pa (sea level)
latitude=45, # degrees
altitude=0 # meters
)
# Generate spectral distribution
sd_rayleigh = colour.sd_rayleigh_scattering(
shape=colour.SpectralShape(380, 780, 10),
CO2_concentration=400,
temperature=288.15
)
# Compute optical depth
optical_depth = colour.rayleigh_optical_depth(wavelengths)Camera Characterization Workflow
# Complete camera characterization pipeline
from colour.characterisation import MSDS_CAMERA_SENSITIVITIES
# Load camera sensitivities
camera_sensitivities = MSDS_CAMERA_SENSITIVITIES["Nikon D850"]
# Define scene illuminant
illuminant = colour.SDS_ILLUMINANTS["D65"]
# Compute IDT matrix
idt_matrix = colour.matrix_idt(
sensitivities=camera_sensitivities,
illuminant=illuminant,
optimisation_factory=colour.optimisation_factory_rawtoaces_v1
)
# Convert camera RGB to ACES
camera_RGB = np.array([0.8, 0.6, 0.4])
aces_RGB = colour.camera_RGB_to_ACES2065_1(camera_RGB, idt_matrix)
# Calculate white balance multipliers
wb_multipliers = colour.white_balance_multipliers(
camera_sensitivities,
illuminant
)Volume and Gamut Analysis
Functions for analyzing colourspace volumes, gamut coverage, and spectrum analysis for color reproduction assessment.
def RGB_colourspace_limits(colourspace: RGB_Colourspace, resolution: int = 64) -> NDArray:
"""
Calculate RGB colourspace limits using Monte Carlo sampling.
Parameters:
- colourspace: RGB colourspace to analyze
- resolution: sampling resolution for calculation
Returns:
Colourspace boundary limits in Lab space
"""
def RGB_colourspace_volume_MonteCarlo(colourspace: RGB_Colourspace, samples: int = 1000000, random_state: RandomState = None) -> float:
"""
Calculate colourspace volume using Monte Carlo sampling method.
Parameters:
- colourspace: RGB colourspace to analyze
- samples: number of Monte Carlo samples
- random_state: random number generator state
Returns:
Colourspace volume in cubic Lab units
"""
def RGB_colourspace_coverage_MonteCarlo(colourspace: RGB_Colourspace, coverage_sampler: Callable = None, samples: int = 1000000) -> float:
"""
Calculate coverage of a colourspace using Monte Carlo sampling.
Parameters:
- colourspace: RGB colourspace to analyze
- coverage_sampler: sampling function for coverage analysis
- samples: number of Monte Carlo samples
Returns:
Coverage percentage (0-1)
"""
def RGB_colourspace_pointer_gamut_coverage_MonteCarlo(colourspace: RGB_Colourspace, samples: int = 1000000) -> float:
"""
Calculate Pointer's gamut coverage using Monte Carlo sampling.
Parameters:
- colourspace: RGB colourspace to analyze
- samples: number of Monte Carlo samples
Returns:
Pointer's gamut coverage percentage (0-1)
"""
def is_within_macadam_limits(XYZ: ArrayLike, illuminant: ArrayLike = None) -> NDArray:
"""
Check if XYZ values are within MacAdam limits.
Parameters:
- XYZ: CIE XYZ tristimulus values
- illuminant: reference illuminant
Returns:
Boolean array indicating values within limits
"""
def is_within_pointer_gamut(XYZ: ArrayLike, illuminant: ArrayLike = None) -> NDArray:
"""
Check if XYZ values are within Pointer's gamut.
Parameters:
- XYZ: CIE XYZ tristimulus values
- illuminant: reference illuminant
Returns:
Boolean array indicating values within Pointer's gamut
"""
def is_within_visible_spectrum(XYZ: ArrayLike, illuminant: ArrayLike = None, tolerance: float = None) -> NDArray:
"""
Check if XYZ values represent physically realizable colours.
Parameters:
- XYZ: CIE XYZ tristimulus values
- illuminant: reference illuminant
- tolerance: tolerance for boundary checking
Returns:
Boolean array indicating physically realizable colours
"""
# Method collections
RGB_COLOURSPACE_VOLUME_METHODS: Dict[str, Callable]Biochemistry and Kinetics
Biochemical computation functions including enzyme kinetics modeling for biological color processes.
def reaction_rate_MichaelisMenten(S: ArrayLike, V_max: float, K_m: float, method: str = "Michaelis 1913") -> NDArray:
"""
Calculate enzyme reaction rate using Michaelis-Menten kinetics.
Parameters:
- S: substrate concentration array
- V_max: maximum reaction velocity
- K_m: Michaelis constant (substrate concentration at half V_max)
- method: kinetic model method
Returns:
Reaction rate values
"""
def substrate_concentration_MichaelisMenten(r: ArrayLike, V_max: float, K_m: float, method: str = "Michaelis 1913") -> NDArray:
"""
Calculate substrate concentration from reaction rate using Michaelis-Menten kinetics.
Parameters:
- r: reaction rate values
- V_max: maximum reaction velocity
- K_m: Michaelis constant
- method: kinetic model method
Returns:
Substrate concentration values
"""
# Method collections
REACTION_RATE_MICHAELISMENTEN_METHODS: Dict[str, Callable]
SUBSTRATE_CONCENTRATION_MICHAELISMENTEN_METHODS: Dict[str, Callable]Contrast Sensitivity Functions
Contrast sensitivity modeling for human visual system analysis.
def contrast_sensitivity_function(method: str = "Barten 1999", **kwargs) -> NDArray:
"""
Calculate contrast sensitivity function using specified method.
Parameters:
- method: contrast sensitivity model method
- "Barten 1999": Barten (1999) model
- **kwargs: method-specific parameters
Returns:
Contrast sensitivity values
"""
def contrast_sensitivity_function_Barten1999(u: ArrayLike, sigma: float = 0, k: float = 3, T: float = 0.1) -> NDArray:
"""
Calculate contrast sensitivity using Barten (1999) model.
Parameters:
- u: spatial frequency values in cycles per degree
- sigma: standard deviation of optical modulation transfer function
- k: signal-to-noise ratio constant
- T: integration time in seconds
Returns:
Contrast sensitivity values
"""
# Method collections
CONTRAST_SENSITIVITY_METHODS: Dict[str, Callable]Corresponding Chromaticities
Corresponding chromaticities prediction models for cross-media color reproduction.
def corresponding_chromaticities_prediction(experiment: int, model: str = "CIE 1994", **kwargs) -> CorrespondingChromaticitiesPrediction:
"""
Predict corresponding chromaticities using specified model.
Parameters:
- experiment: experiment number from Breneman datasets
- model: prediction model
- "CIE 1994": CIE 1994 corresponding chromaticities model
- "CMCCAT2000": CMCCAT2000 model
- "Fairchild 1990": Fairchild (1990) model
- "Von Kries": Von Kries chromatic adaptation model
- "Zhai 2018": Zhai and Luo (2018) model
Returns:
Corresponding chromaticities prediction specification
"""
class CorrespondingChromaticitiesPrediction:
"""
Specification class for corresponding chromaticities prediction results.
Attributes:
- name: prediction model name
- XYZ_t: test chromaticities
- XYZ_m: match chromaticities
- Y_t: test luminance values
- Y_m: match luminance values
"""
name: str
XYZ_t: NDArray
XYZ_m: NDArray
Y_t: NDArray
Y_m: NDArray
# Method collections and datasets
CORRESPONDING_CHROMATICITIES_PREDICTION_MODELS: Dict[str, Callable]
BRENEMAN_EXPERIMENTS: Dict[int, CorrespondingColourDataset]Additional Usage Examples
Volume Analysis
import colour
import numpy as np
# Analyze sRGB colourspace volume
srgb = colour.RGB_COLOURSPACES["sRGB"]
volume = colour.RGB_colourspace_volume_MonteCarlo(srgb, samples=100000)
print(f"sRGB volume: {volume:.2f} cubic Lab units")
# Calculate Pointer's gamut coverage
pointer_coverage = colour.RGB_colourspace_pointer_gamut_coverage_MonteCarlo(srgb)
print(f"sRGB covers {pointer_coverage*100:.1f}% of Pointer's gamut")
# Check if colors are within visible spectrum
XYZ_test = np.array([[95.047, 100.0, 108.883], # D65 white
[0, 0, 0], # Black
[200, 150, 50]]) # Invalid color
within_spectrum = colour.is_within_visible_spectrum(XYZ_test)
print(f"Within visible spectrum: {within_spectrum}")Biochemistry Modeling
import colour
import numpy as np
# Model enzyme kinetics
substrate_conc = np.linspace(0, 10, 100) # mM
V_max = 2.5 # μmol/min
K_m = 1.2 # mM
reaction_rates = colour.reaction_rate_MichaelisMenten(
substrate_conc, V_max, K_m, method="Michaelis 1913"
)
# Calculate substrate concentration from reaction rate
target_rate = 1.0 # μmol/min
required_substrate = colour.substrate_concentration_MichaelisMenten(
target_rate, V_max, K_m
)
print(f"Substrate needed for {target_rate} μmol/min: {required_substrate:.2f} mM")Contrast Sensitivity
import colour
import numpy as np
# Calculate contrast sensitivity function
spatial_freq = np.logspace(-1, 2, 50) # 0.1 to 100 cycles/degree
# Standard viewing conditions
csf = colour.contrast_sensitivity_function_Barten1999(
spatial_freq,
sigma=0.5, # optical blur
k=3.0, # SNR constant
T=0.1 # integration time
)
print(f"Peak sensitivity at {spatial_freq[np.argmax(csf)]:.1f} cycles/degree")
print(f"Peak sensitivity: {np.max(csf):.1f}")Additional Imports
# Volume and gamut analysis
from colour.volume import (
RGB_colourspace_volume_MonteCarlo, RGB_colourspace_coverage_MonteCarlo,
RGB_colourspace_pointer_gamut_coverage_MonteCarlo,
is_within_macadam_limits, is_within_pointer_gamut, is_within_visible_spectrum
)
# Biochemistry
from colour.biochemistry import (
reaction_rate_MichaelisMenten, substrate_concentration_MichaelisMenten,
REACTION_RATE_MICHAELISMENTEN_METHODS
)
# Contrast sensitivity
from colour.contrast import (
contrast_sensitivity_function, contrast_sensitivity_function_Barten1999,
CONTRAST_SENSITIVITY_METHODS
)
# Corresponding chromaticities
from colour.corresponding import (
corresponding_chromaticities_prediction,
CORRESPONDING_CHROMATICITIES_PREDICTION_MODELS, BRENEMAN_EXPERIMENTS
)Install with Tessl CLI
npx tessl i tessl/pypi-colour-science