0
# Colour Science
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: colour-science
7
- **Language**: Python
8
- **Installation**: `pip install colour-science`
9

10
## Core Imports
11

12
```python
13
import colour
14
```
15

16
Common import patterns for specific functionality:
17

18
```python
19
# Colorimetry and spectral functions
20
from colour import SpectralDistribution, sd_to_XYZ, MSDS_CMFS
21

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

25
# Chromatic adaptation
26
from colour import chromatic_adaptation, CHROMATIC_ADAPTATION_METHODS
27

28
# Color difference calculations
29
from colour import delta_E, DELTA_E_METHODS
30

31
# Graph and automatic conversions
32
from colour import convert, describe_conversion_path
33

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

37
# Notation systems
38
from colour import munsell_colour_to_xyY, RGB_to_HEX, keyword_to_RGB_CSSColor3
39

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

43
# Plotting functionality
44
import colour.plotting as colour_plotting
45
```
46

47
## Basic Usage
48

49
```python
50
import colour
51
import numpy as np
52

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

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

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

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

69
print(f"XYZ: {XYZ}")
70
print(f"Lab: {Lab}")
71
print(f"Delta E: {deltaE}")
72
```
73

74
## Architecture
75

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

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

84
## Capabilities
85

86
### Colorimetry and Spectral Analysis
87

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

90
```python { .api }
91
class SpectralDistribution:
92
    def __init__(self, data: dict, name: str = None): ...
93

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

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

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

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

103
[Colorimetry](./colorimetry.md)
104

105
### Colour Space Conversions
106

107
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.
108

109
```python { .api }
110
def XYZ_to_Lab(XYZ: ArrayLike, illuminant: ArrayLike = None) -> NDArray: ...
111

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

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

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

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

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

123
[Colour Models](./colour-models.md)
124

125
### Chromatic Adaptation
126

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

129
```python { .api }
130
def chromatic_adaptation(XYZ: ArrayLike, XYZ_w: ArrayLike, XYZ_wr: ArrayLike, method: str = None, **kwargs) -> NDArray: ...
131

132
CHROMATIC_ADAPTATION_METHODS: Dict[str, Callable]
133
CHROMATIC_ADAPTATION_TRANSFORMS: Dict[str, NDArray]
134
```
135

136
[Chromatic Adaptation](./chromatic-adaptation.md)
137

138
### Colour Appearance Models
139

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

142
```python { .api }
143
def XYZ_to_CIECAM02(XYZ: ArrayLike, XYZ_w: ArrayLike, L_A: float, Y_b: float, surround: InductionFactors_CIECAM02 = None) -> CAM_Specification_CIECAM02: ...
144

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

147
class CAM_Specification_CIECAM02:
148
    J: float  # Lightness
149
    C: float  # Chroma
150
    h: float  # Hue angle
151
    # ... additional attributes
152
```
153

154
[Colour Appearance](./colour-appearance.md)
155

156
### Colour Difference Calculations
157

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

160
```python { .api }
161
def delta_E(Lab1: ArrayLike, Lab2: ArrayLike, method: str = None, **kwargs) -> NDArray: ...
162

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

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

167
DELTA_E_METHODS: Dict[str, Callable]
168
```
169

170
[Colour Difference](./colour-difference.md)
171

172
### Input/Output Operations
173

174
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.
175

176
```python { .api }
177
def read_image(path: str, method: str = None, **kwargs) -> NDArray: ...
178

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

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

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

185
class LUT3D:
186
    def __init__(self, table: ArrayLike, name: str = None, domain: ArrayLike = None): ...
187
    def apply(self, RGB: ArrayLike) -> NDArray: ...
188
```
189

190
[Input/Output](./input-output.md)
191

192
### Quality Assessment
193

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

196
```python { .api }
197
def colour_rendering_index(sd_test: SpectralDistribution, additional_data: bool = False) -> Union[float, ColourRendering_Specification_CRI]: ...
198

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

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

203
class ColourRendering_Specification_CRI:
204
    Q_a: float  # General colour rendering index
205
    Q_as: List[float]  # Special colour rendering indices
206
    # ... additional attributes
207
```
208

209
[Quality Assessment](./quality-assessment.md)
210

211
### Plotting and Visualization
212

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

215
```python { .api }
216
def plot_single_sd(sd: SpectralDistribution, **kwargs) -> Tuple[Figure, Axes]: ...
217

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

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

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

224
class ColourSwatch:
225
    def __init__(self, RGB: ArrayLike, name: str = None): ...
226
```
227

228
[Plotting](./plotting.md)
229

230
### Mathematical Utilities
231

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

234
```python { .api }
235
def table_interpolation(x: float, xp: ArrayLike, fp: ArrayLike, method: str = None, **kwargs) -> float: ...
236

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

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

243
def euclidean_distance(a: ArrayLike, b: ArrayLike) -> float: ...
244
```
245

246
[Mathematical Utilities](./math-utilities.md)
247

248
### Advanced Features
249

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

252
```python { .api }
253
def XYZ_to_sd(XYZ: ArrayLike, method: str = None, **kwargs) -> SpectralDistribution: ...
254

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

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

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

261
def rayleigh_scattering(wavelength: ArrayLike) -> NDArray: ...
262
```
263

264
[Advanced Features](./advanced-features.md)
265

266
### Constants and Physical Values
267

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

270
```python { .api }
271
CONSTANT_K_M: float  # 683 lm/W - Maximum photopic luminous efficacy
272
CONSTANT_PLANCK: float  # 6.62607e-34 J⋅s - Planck constant
273
EPSILON: float  # Machine epsilon for floating point comparisons
274
TOLERANCE_ABSOLUTE_DEFAULT: float  # Default absolute tolerance
275
```
276

277
[Constants](./constants.md)
278

279
### Colour Notation Systems
280

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

283
```python { .api }
284
def munsell_colour_to_xyY(specification: str) -> NDArray: ...
285
def RGB_to_HEX(RGB: ArrayLike) -> str: ...
286
def keyword_to_RGB_CSSColor3(keyword: str) -> NDArray: ...
287
MUNSELL_COLOURS: Dict[str, NDArray]
288
CSS_COLOR_3: Dict[str, NDArray]
289
```
290

291
[Notation Systems](./notation.md)
292

293
### Colour Temperature and CCT
294

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

297
```python { .api }
298
def xy_to_CCT(xy: ArrayLike, method: str = None) -> NDArray: ...
299
def CCT_to_xy(CCT: ArrayLike, method: str = None) -> NDArray: ...
300
def uv_to_CCT(uv: ArrayLike, method: str = None) -> NDArray: ...
301
XY_TO_CCT_METHODS: Dict[str, Callable]
302
UV_TO_CCT_METHODS: Dict[str, Callable]
303
```
304

305
[Temperature and CCT](./temperature.md)
306

307
### Geometric Computations
308

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

311
```python { .api }
312
def ellipse_fitting(coefficients: ArrayLike, method: str = None) -> NDArray: ...
313
def intersect_line_segments(l_1: ArrayLike, l_2: ArrayLike) -> LineSegmentsIntersections_Specification: ...
314
def primitive(method: str = "cube", **kwargs) -> NDArray: ...
315
def hull_section(points: ArrayLike, axis: str = "z") -> NDArray: ...
316
```
317

318
[Geometry](./geometry.md)