or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdchromatic-adaptation.mdcolorimetry.mdcolour-appearance.mdcolour-difference.mdcolour-models.mdconstants.mdgeometry.mdindex.mdinput-output.mdmath-utilities.mdnotation.mdplotting.mdquality-assessment.mdtemperature.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/colour-science@0.4.x

To install, run

npx @tessl/cli install tessl/pypi-colour-science@0.4.0

index.mddocs/

Colour Science

A comprehensive Python library providing algorithms and datasets for colour science computations. The package offers extensive functionality for chromatic adaptation, colour appearance modeling, colorimetry, colour difference calculations, spectral analysis, and color space conversions across multiple colour spaces and illuminants, with built-in plotting capabilities and integration with the scientific Python ecosystem.

Package Information

  • Package Name: colour-science
  • Language: Python
  • Installation: pip install colour-science

Core Imports

import colour

Common import patterns for specific functionality:

# Colorimetry and spectral functions
from colour import SpectralDistribution, sd_to_XYZ, MSDS_CMFS

# Colour space conversions
from colour import XYZ_to_Lab, Lab_to_XYZ, XYZ_to_sRGB, sRGB_to_XYZ

# Chromatic adaptation
from colour import chromatic_adaptation, CHROMATIC_ADAPTATION_METHODS

# Color difference calculations
from colour import delta_E, DELTA_E_METHODS

# Graph and automatic conversions
from colour import convert, describe_conversion_path

# Temperature and CCT calculations
from colour import xy_to_CCT, CCT_to_xy, uv_to_CCT, CCT_to_uv

# Notation systems
from colour import munsell_colour_to_xyY, RGB_to_HEX, keyword_to_RGB_CSSColor3

# Constants and tolerances
from colour.constants import CONSTANT_K_M, EPSILON, TOLERANCE_ABSOLUTE_DEFAULT

# Plotting functionality
import colour.plotting as colour_plotting

Basic Usage

import colour
import numpy as np

# Create a spectral distribution
wavelengths = np.linspace(380, 780, 41)
values = np.sin((wavelengths - 550) / 50) ** 2
sd = colour.SpectralDistribution(dict(zip(wavelengths, values)))

# Convert to CIE XYZ tristimulus values
XYZ = colour.sd_to_XYZ(sd)

# Convert XYZ to Lab color space
Lab = colour.XYZ_to_Lab(XYZ)

# Calculate color difference between two Lab values
Lab1 = [50, 20, -10]
Lab2 = [55, 25, -5]
deltaE = colour.delta_E(Lab1, Lab2)

print(f"XYZ: {XYZ}")
print(f"Lab: {Lab}")
print(f"Delta E: {deltaE}")

Architecture

The colour-science package is organized into modular subpackages that can be used independently or together:

  • Core Data Types: SpectralDistribution, MultiSpectralDistributions, RGB_Colourspace classes provide structured data representation
  • Method Collections: *_METHODS dictionaries enable polymorphic dispatch with standardized method selection
  • Transformation Functions: Consistent {source}_to_{target}() naming pattern for all color space conversions
  • Constants and Datasets: Extensive collections of standard illuminants, color matching functions, and reference data
  • Plotting Integration: Built-in visualization capabilities through the plotting submodule

Capabilities

Colorimetry and Spectral Analysis

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

class SpectralDistribution:
    def __init__(self, data: dict, name: str = None): ...

def sd_to_XYZ(sd: SpectralDistribution, cmfs: XYZ_ColourMatchingFunctions = None, illuminant: SpectralDistribution = None) -> NDArray: ...

def sd_blackbody(temperature: float, shape: SpectralShape = None) -> SpectralDistribution: ...

def luminous_flux(sd: SpectralDistribution, lef: SpectralDistribution = None, K_m: float = None) -> float: ...

def dominant_wavelength(xy: ArrayLike, xy_n: ArrayLike) -> Tuple[float, float, bool]: ...

Colorimetry

Colour Space Conversions

Comprehensive colour space transformation functions supporting CIE spaces (XYZ, Lab, Luv, xyY), RGB models (sRGB, Adobe RGB, Rec. 2020), advanced models (CAM16, Jzazbz, Oklab), and polar coordinate representations.

def XYZ_to_Lab(XYZ: ArrayLike, illuminant: ArrayLike = None) -> NDArray: ...

def Lab_to_XYZ(Lab: ArrayLike, illuminant: ArrayLike = None) -> NDArray: ...

def XYZ_to_sRGB(XYZ: ArrayLike, illuminant: ArrayLike = None, chromatic_adaptation_transform: str = None) -> NDArray: ...

def RGB_to_HSV(RGB: ArrayLike) -> NDArray: ...

def XYZ_to_Jzazbz(XYZ: ArrayLike) -> NDArray: ...

def convert(a: ArrayLike, source: str, target: str, **kwargs) -> NDArray: ...

Colour Models

Chromatic Adaptation

Chromatic adaptation models and transformations for adjusting colors between different viewing conditions and illuminants.

def chromatic_adaptation(XYZ: ArrayLike, XYZ_w: ArrayLike, XYZ_wr: ArrayLike, method: str = None, **kwargs) -> NDArray: ...

CHROMATIC_ADAPTATION_METHODS: Dict[str, Callable]
CHROMATIC_ADAPTATION_TRANSFORMS: Dict[str, NDArray]

Chromatic Adaptation

Colour Appearance Models

Advanced colour appearance models including CIECAM02, CAM16, Hunt, and other perceptual color models that account for viewing conditions and human visual perception.

def XYZ_to_CIECAM02(XYZ: ArrayLike, XYZ_w: ArrayLike, L_A: float, Y_b: float, surround: InductionFactors_CIECAM02 = None) -> CAM_Specification_CIECAM02: ...

def XYZ_to_CAM16(XYZ: ArrayLike, XYZ_w: ArrayLike, L_A: float, Y_b: float, surround: InductionFactors_CAM16 = None) -> CAM_Specification_CAM16: ...

class CAM_Specification_CIECAM02:
    J: float  # Lightness
    C: float  # Chroma
    h: float  # Hue angle
    # ... additional attributes

Colour Appearance

Colour Difference Calculations

Comprehensive color difference metrics including CIE Delta E variants, CAM-based differences, and perceptual uniformity measures.

def delta_E(Lab1: ArrayLike, Lab2: ArrayLike, method: str = None, **kwargs) -> NDArray: ...

def delta_E_CIE2000(Lab1: ArrayLike, Lab2: ArrayLike, textiles: bool = False) -> NDArray: ...

def delta_E_CAM16UCS(CAM1: CAM_Specification_CAM16, CAM2: CAM_Specification_CAM16) -> float: ...

DELTA_E_METHODS: Dict[str, Callable]

Colour Difference

Input/Output Operations

File format support for images, lookup tables (LUTs), spectral data, and various color science data formats including CSV, X-Rite, IES TM-27-14, and more.

def read_image(path: str, method: str = None, **kwargs) -> NDArray: ...

def write_image(image: ArrayLike, path: str, method: str = None, **kwargs) -> bool: ...

def read_LUT(path: str, method: str = None, **kwargs) -> Union[LUT1D, LUT3x1D, LUT3D]: ...

def read_sds_from_csv_file(path: str, **kwargs) -> Dict[str, SpectralDistribution]: ...

class LUT3D:
    def __init__(self, table: ArrayLike, name: str = None, domain: ArrayLike = None): ...
    def apply(self, RGB: ArrayLike) -> NDArray: ...

Input/Output

Quality Assessment

Colour quality and rendering assessment including colour rendering index (CRI), colour quality scale (CQS), colour fidelity index, and spectral similarity metrics.

def colour_rendering_index(sd_test: SpectralDistribution, additional_data: bool = False) -> Union[float, ColourRendering_Specification_CRI]: ...

def colour_quality_scale(sd_test: SpectralDistribution, additional_data: bool = False) -> Union[float, ColourRendering_Specification_CQS]: ...

def colour_fidelity_index(sd_test: SpectralDistribution, method: str = None) -> float: ...

class ColourRendering_Specification_CRI:
    Q_a: float  # General colour rendering index
    Q_as: List[float]  # Special colour rendering indices
    # ... additional attributes

Quality Assessment

Plotting and Visualization

Comprehensive plotting capabilities for colour science visualizations including chromaticity diagrams, spectral plots, color swatches, and gamut visualizations.

def plot_single_sd(sd: SpectralDistribution, **kwargs) -> Tuple[Figure, Axes]: ...

def plot_chromaticity_diagram_CIE1931(cmfs: str = None, **kwargs) -> Tuple[Figure, Axes]: ...

def plot_RGB_colourspaces_gamuts(colourspaces: List[str], **kwargs) -> Tuple[Figure, Axes]: ...

def plot_single_colour_swatch(RGB: ArrayLike, **kwargs) -> Tuple[Figure, Axes]: ...

class ColourSwatch:
    def __init__(self, RGB: ArrayLike, name: str = None): ...

Plotting

Mathematical Utilities

Mathematical utilities including interpolation, algebra operations, geometric computations, and array manipulation functions.

def table_interpolation(x: float, xp: ArrayLike, fp: ArrayLike, method: str = None, **kwargs) -> float: ...

class LinearInterpolator:
    def __init__(self, x: ArrayLike, y: ArrayLike): ...
    def __call__(self, xi: ArrayLike) -> NDArray: ...

def normalise_maximum(a: ArrayLike, axis: int = None, factor: float = None) -> NDArray: ...

def euclidean_distance(a: ArrayLike, b: ArrayLike) -> float: ...

Mathematical Utilities

Advanced Features

Specialized functionality including spectral recovery, colour blindness simulation, colour temperature calculations, volume and gamut analysis, and optical phenomena modeling.

def XYZ_to_sd(XYZ: ArrayLike, method: str = None, **kwargs) -> SpectralDistribution: ...

def matrix_cvd_Machado2009(deficiency: str, severity: float) -> NDArray: ...

def xy_to_CCT(xy: ArrayLike, method: str = None, **kwargs) -> float: ...

def RGB_colourspace_volume_MonteCarlo(colourspace: RGB_Colourspace, samples: int = None) -> float: ...

def rayleigh_scattering(wavelength: ArrayLike) -> NDArray: ...

Advanced Features

Constants and Physical Values

Fundamental physical constants, CIE standards, computational tolerances, and data type definitions for accurate colorimetric calculations.

CONSTANT_K_M: float  # 683 lm/W - Maximum photopic luminous efficacy
CONSTANT_PLANCK: float  # 6.62607e-34 J⋅s - Planck constant
EPSILON: float  # Machine epsilon for floating point comparisons
TOLERANCE_ABSOLUTE_DEFAULT: float  # Default absolute tolerance

Constants

Colour Notation Systems

Colour notation systems including Munsell Color System, hexadecimal color codes, and CSS color names with conversion functions.

def munsell_colour_to_xyY(specification: str) -> NDArray: ...
def RGB_to_HEX(RGB: ArrayLike) -> str: ...
def keyword_to_RGB_CSSColor3(keyword: str) -> NDArray: ...
MUNSELL_COLOURS: Dict[str, NDArray]
CSS_COLOR_3: Dict[str, NDArray]

Notation Systems

Colour Temperature and CCT

Comprehensive colour temperature and correlated colour temperature calculations using multiple computational methods.

def xy_to_CCT(xy: ArrayLike, method: str = None) -> NDArray: ...
def CCT_to_xy(CCT: ArrayLike, method: str = None) -> NDArray: ...
def uv_to_CCT(uv: ArrayLike, method: str = None) -> NDArray: ...
XY_TO_CCT_METHODS: Dict[str, Callable]
UV_TO_CCT_METHODS: Dict[str, Callable]

Temperature and CCT

Geometric Computations

Geometric computation functions including ellipse fitting, line intersections, primitive generation, and hull analysis for color space visualization.

def ellipse_fitting(coefficients: ArrayLike, method: str = None) -> NDArray: ...
def intersect_line_segments(l_1: ArrayLike, l_2: ArrayLike) -> LineSegmentsIntersections_Specification: ...
def primitive(method: str = "cube", **kwargs) -> NDArray: ...
def hull_section(points: ArrayLike, axis: str = "z") -> NDArray: ...

Geometry