0
# Colorimetry and Spectral Analysis
1

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

4
## Capabilities
5

6
### Spectral Distribution Classes
7

8
Core classes for representing and manipulating spectral data.
9

10
```python { .api }
11
class SpectralDistribution:
12
    """
13
    Represents a spectral power distribution.
14
    
15
    Parameters:
16
    - data: dict mapping wavelengths to values, or array-like paired data
17
    - domain: array-like of wavelengths (if data is array-like values)
18
    - name: optional name for the distribution
19
    """
20
    def __init__(self, data: Union[dict, ArrayLike], domain: ArrayLike = None, name: str = None): ...
21
    
22
    def __getitem__(self, wavelength: float) -> float: ...
23
    def __setitem__(self, wavelength: float, value: float) -> None: ...
24
    
25
    @property
26
    def domain(self) -> NDArray: ...
27
    @property
28
    def range(self) -> NDArray: ...
29
    @property
30
    def shape(self) -> SpectralShape: ...
31
    
32
    def align(self, shape: SpectralShape) -> "SpectralDistribution": ...
33
    def interpolate(self, shape: SpectralShape, method: str = None) -> "SpectralDistribution": ...
34
    def extrapolate(self, shape: SpectralShape, method: str = None) -> "SpectralDistribution": ...
35
    def trim(self, shape: SpectralShape) -> "SpectralDistribution": ...
36
    def normalise(self, factor: float = 1) -> "SpectralDistribution": ...
37

38
class MultiSpectralDistributions:
39
    """
40
    Represents multiple spectral power distributions with aligned wavelengths.
41
    
42
    Parameters:
43
    - data: dict mapping names to spectral data, or 2D array with labels
44
    - domain: array-like of wavelengths
45
    - labels: names for each distribution (if data is array)
46
    """
47
    def __init__(self, data: Union[dict, ArrayLike], domain: ArrayLike = None, labels: List[str] = None): ...
48
    
49
    def __getitem__(self, item: Union[str, int]) -> SpectralDistribution: ...
50
    def __setitem__(self, item: Union[str, int], value: Union[SpectralDistribution, ArrayLike]) -> None: ...
51
    
52
    @property
53
    def domain(self) -> NDArray: ...
54
    @property
55
    def range(self) -> NDArray: ...
56
    @property
57
    def shape(self) -> SpectralShape: ...
58

59
class SpectralShape:
60
    """
61
    Defines the spectral range and sampling for spectral distributions.
62
    
63
    Parameters:
64
    - start: starting wavelength
65
    - end: ending wavelength  
66
    - interval: wavelength interval
67
    """
68
    def __init__(self, start: float, end: float, interval: float = 1): ...
69
    
70
    @property
71
    def start(self) -> float: ...
72
    @property  
73
    def end(self) -> float: ...
74
    @property
75
    def interval(self) -> float: ...
76
    @property
77
    def size(self) -> int: ...
78
    @property
79
    def range(self) -> NDArray: ...
80
```
81

82
### Tristimulus Value Calculations
83

84
Functions for converting spectral data to CIE XYZ tristimulus values.
85

86
```python { .api }
87
def sd_to_XYZ(sd: SpectralDistribution, cmfs: XYZ_ColourMatchingFunctions = None, illuminant: SpectralDistribution = None, k: float = None) -> NDArray:
88
    """
89
    Convert spectral distribution to CIE XYZ tristimulus values.
90
    
91
    Parameters:
92
    - sd: spectral distribution to convert
93
    - cmfs: colour matching functions (defaults to CIE 1931 2° Standard Observer)
94
    - illuminant: illuminant spectral distribution (defaults to CIE Standard Illuminant D65)
95
    - k: normalization constant (computed automatically if None)
96
    
97
    Returns:
98
    CIE XYZ tristimulus values as ndarray shape (3,)
99
    """
100

101
def msds_to_XYZ(msds: MultiSpectralDistributions, cmfs: XYZ_ColourMatchingFunctions = None, illuminant: SpectralDistribution = None, k: float = None, method: str = None) -> NDArray:
102
    """
103
    Convert multiple spectral distributions to CIE XYZ tristimulus values.
104
    
105
    Parameters:
106
    - msds: multiple spectral distributions
107
    - cmfs: colour matching functions
108
    - illuminant: illuminant spectral distribution
109
    - k: normalization constant
110
    - method: computation method
111
    
112
    Returns:
113
    CIE XYZ tristimulus values as ndarray shape (n, 3)
114
    """
115

116
def wavelength_to_XYZ(wavelength: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> NDArray:
117
    """
118
    Convert wavelength(s) to CIE XYZ tristimulus values of monochromatic stimuli.
119
    
120
    Parameters:
121
    - wavelength: wavelength(s) in nanometers
122
    - cmfs: colour matching functions
123
    
124
    Returns:
125
    CIE XYZ tristimulus values
126
    """
127
```
128

129
### Spectral Distribution Generation
130

131
Functions for generating standard spectral distributions.
132

133
```python { .api }
134
def sd_blackbody(temperature: float, shape: SpectralShape = None) -> SpectralDistribution:
135
    """
136
    Generate blackbody spectral distribution for given temperature.
137
    
138
    Parameters:
139
    - temperature: blackbody temperature in Kelvin
140
    - shape: spectral shape for the distribution
141
    
142
    Returns:
143
    Blackbody spectral distribution
144
    """
145

146
def sd_gaussian(peak_wavelength: float, fwhm: float, shape: SpectralShape = None, method: str = None) -> SpectralDistribution:
147
    """
148
    Generate Gaussian spectral distribution.
149
    
150
    Parameters:
151
    - peak_wavelength: peak wavelength in nanometers
152
    - fwhm: full width at half maximum
153
    - shape: spectral shape
154
    - method: computation method
155
    
156
    Returns:
157
    Gaussian spectral distribution
158
    """
159

160
def sd_single_led(peak_wavelength: float, fwhm: float, shape: SpectralShape = None, method: str = None) -> SpectralDistribution:
161
    """
162
    Generate single LED spectral distribution.
163
    
164
    Parameters:
165
    - peak_wavelength: LED peak wavelength
166
    - fwhm: full width at half maximum
167
    - shape: spectral shape
168
    - method: LED model method
169
    
170
    Returns:
171
    LED spectral distribution
172
    """
173

174
def sd_multi_leds(peak_wavelengths: ArrayLike, fwhm: ArrayLike, peak_power_ratios: ArrayLike = None, shape: SpectralShape = None, method: str = None) -> SpectralDistribution:
175
    """
176
    Generate multi-LED spectral distribution.
177
    
178
    Parameters:
179
    - peak_wavelengths: array of LED peak wavelengths
180
    - fwhm: array of full width at half maximum values
181
    - peak_power_ratios: relative power ratios (defaults to equal)
182
    - shape: spectral shape
183
    - method: LED model method
184
    
185
    Returns:
186
    Combined multi-LED spectral distribution
187
    """
188
```
189

190
### Standard Illuminants
191

192
Functions for generating CIE standard illuminants.
193

194
```python { .api }
195
def sd_CIE_standard_illuminant_A(shape: SpectralShape = None) -> SpectralDistribution:
196
    """
197
    Generate CIE Standard Illuminant A spectral distribution.
198
    
199
    Parameters:
200
    - shape: spectral shape
201
    
202
    Returns:
203
    CIE Standard Illuminant A spectral distribution
204
    """
205

206
def sd_CIE_illuminant_D_series(xy: ArrayLike, shape: SpectralShape = None) -> SpectralDistribution:
207
    """
208
    Generate CIE Illuminant D Series spectral distribution.
209
    
210
    Parameters:
211
    - xy: CIE xy chromaticity coordinates
212
    - shape: spectral shape
213
    
214
    Returns:
215
    CIE Illuminant D Series spectral distribution
216
    """
217

218
def sd_mesopic_luminous_efficiency_function(Lp: float, source: str = None, method: str = None, shape: SpectralShape = None) -> SpectralDistribution:
219
    """
220
    Generate mesopic luminous efficiency function.
221
    
222
    Parameters:
223
    - Lp: adaptation luminance in cd/m²
224
    - source: source of the luminous efficiency function data
225
    - method: computation method
226
    - shape: spectral shape
227
    
228
    Returns:
229
    Mesopic luminous efficiency function
230
    """
231
```
232

233
### Photometric Calculations
234

235
Photometric quantity calculations from spectral data.
236

237
```python { .api }
238
def luminous_flux(sd: SpectralDistribution, lef: SpectralDistribution = None, K_m: float = None) -> float:
239
    """
240
    Calculate luminous flux from spectral distribution.
241
    
242
    Parameters:
243
    - sd: spectral distribution
244
    - lef: luminous efficiency function
245
    - K_m: maximum luminous efficacy constant
246
    
247
    Returns:
248
    Luminous flux in lumens
249
    """
250

251
def luminous_efficiency(sd: SpectralDistribution, lef: SpectralDistribution = None) -> float:
252
    """
253
    Calculate luminous efficiency from spectral distribution.
254
    
255
    Parameters:
256
    - sd: spectral distribution
257
    - lef: luminous efficiency function
258
    
259
    Returns:
260
    Luminous efficiency (dimensionless ratio)
261
    """
262

263
def luminous_efficacy(sd: SpectralDistribution, lef: SpectralDistribution = None, K_m: float = None) -> float:
264
    """
265
    Calculate luminous efficacy from spectral distribution.
266
    
267
    Parameters:
268
    - sd: spectral distribution  
269
    - lef: luminous efficiency function
270
    - K_m: maximum luminous efficacy constant
271
    
272
    Returns:
273
    Luminous efficacy in lm/W
274
    """
275
```
276

277
### Colorimetric Properties
278

279
Functions for calculating colorimetric properties from chromaticity coordinates.
280

281
```python { .api }
282
def dominant_wavelength(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None, inverse: bool = False) -> Tuple[float, float, bool]:
283
    """
284
    Calculate dominant wavelength and excitation purity.
285
    
286
    Parameters:
287
    - xy: CIE xy chromaticity coordinates of test stimulus
288
    - xy_n: CIE xy chromaticity coordinates of reference white
289
    - cmfs: colour matching functions
290
    - inverse: whether to calculate complementary wavelength if outside spectrum locus
291
    
292
    Returns:
293
    Tuple of (wavelength, purity, is_on_spectrum_locus)
294
    """
295

296
def complementary_wavelength(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> Tuple[float, float]:
297
    """
298
    Calculate complementary wavelength and excitation purity.
299
    
300
    Parameters:
301
    - xy: CIE xy chromaticity coordinates
302
    - xy_n: CIE xy chromaticity coordinates of reference white
303
    - cmfs: colour matching functions
304
    
305
    Returns:
306
    Tuple of (complementary_wavelength, purity)
307
    """
308

309
def excitation_purity(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> float:
310
    """
311
    Calculate excitation purity.
312
    
313
    Parameters:
314
    - xy: CIE xy chromaticity coordinates
315
    - xy_n: CIE xy chromaticity coordinates of reference white
316
    - cmfs: colour matching functions
317
    
318
    Returns:
319
    Excitation purity (0-1)
320
    """
321

322
def colorimetric_purity(xy: ArrayLike, xy_n: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> float:
323
    """
324
    Calculate colorimetric purity.
325
    
326
    Parameters:
327
    - xy: CIE xy chromaticity coordinates
328
    - xy_n: CIE xy chromaticity coordinates of reference white
329
    - cmfs: colour matching functions
330
    
331
    Returns:
332
    Colorimetric purity (0-1)
333
    """
334
```
335

336
### Lightness and Luminance
337

338
Functions for converting between lightness and luminance scales.
339

340
```python { .api }
341
def lightness(Y: ArrayLike, method: str = None, **kwargs) -> NDArray:
342
    """
343
    Calculate lightness from luminance.
344
    
345
    Parameters:
346
    - Y: relative luminance values
347
    - method: lightness method ('CIE 1976', 'Glasser 1958', 'Wyszecki 1963')
348
    - **kwargs: additional method-specific parameters
349
    
350
    Returns:
351
    Lightness values
352
    """
353

354
def luminance(L_star: ArrayLike, method: str = None, **kwargs) -> NDArray:
355
    """
356
    Calculate luminance from lightness.
357
    
358
    Parameters:
359
    - L_star: lightness values
360
    - method: lightness method used
361
    - **kwargs: additional method-specific parameters
362
    
363
    Returns:
364
    Relative luminance values
365
    """
366
```
367

368
### Constants and Datasets
369

370
Standard datasets and constants for colorimetric calculations.
371

372
```python { .api }
373
# Standard spectral shapes
374
SPECTRAL_SHAPE_DEFAULT: SpectralShape
375
SPECTRAL_SHAPE_ASTME308: SpectralShape
376

377
# Colour matching functions
378
MSDS_CMFS: Dict[str, XYZ_ColourMatchingFunctions]
379
MSDS_CMFS_LMS: Dict[str, LMS_ConeFundamentals]
380

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

386
# Luminous efficiency functions
387
SDS_LEFS: Dict[str, SpectralDistribution]
388
SDS_LEFS_PHOTOPIC: Dict[str, SpectralDistribution]
389
SDS_LEFS_SCOTOPIC: Dict[str, SpectralDistribution]
390

391
# Method collections
392
SD_TO_XYZ_METHODS: Dict[str, Callable]
393
MSDS_TO_XYZ_METHODS: Dict[str, Callable]
394
LIGHTNESS_METHODS: Dict[str, Callable]
395
LUMINANCE_METHODS: Dict[str, Callable]
396
SD_GAUSSIAN_METHODS: Dict[str, Callable]
397
SD_SINGLE_LED_METHODS: Dict[str, Callable]
398
SD_MULTI_LEDS_METHODS: Dict[str, Callable]
399
```