0
# Advanced Features
1
2
Specialized capabilities including spectral recovery, colour blindness simulation, colour temperature calculations, volume and gamut analysis, optical phenomena modeling, camera characterization, and multi-spectral processing.
3
4
## Capabilities
5
6
### Spectral Recovery Functions
7
8
Recover spectral distributions from tristimulus values using various computational methods.
9
10
```python { .api }
11
def XYZ_to_sd(
12
XYZ: ArrayLike,
13
method: Literal[
14
"Jakob 2019",
15
"Mallett 2019",
16
"Meng 2015",
17
"Otsu 2018",
18
"Smits 1999"
19
] = "Meng 2015",
20
**kwargs: Any
21
) -> SpectralDistribution:
22
"""
23
Recover spectral distribution from CIE XYZ tristimulus values.
24
25
Parameters:
26
- XYZ: CIE XYZ tristimulus values to recover from
27
- method: Computation method for spectral recovery
28
- additional_data: (Jakob 2019) Return error alongside sd if True
29
- basis_functions: (Mallett 2019) Basis functions for the method
30
- clip: (Otsu 2018) Clip values below zero and above unity
31
- cmfs: Standard observer colour matching functions
32
- colourspace: (Jakob 2019) RGB colourspace of target colour
33
- dataset: (Otsu 2018) Dataset for reconstruction
34
- illuminant: Illuminant spectral distribution (default D65)
35
- interval: (Meng 2015) Wavelength range interval in nm
36
- optimisation_kwargs: Parameters for optimization algorithms
37
38
Returns:
39
- Recovered spectral distribution
40
"""
41
42
def XYZ_to_sd_Jakob2019(
43
XYZ: ArrayLike,
44
cmfs: MultiSpectralDistributions = None,
45
illuminant: SpectralDistribution = None,
46
optimisation_kwargs: dict = None
47
) -> SpectralDistribution:
48
"""
49
Recover spectral distribution using Jakob and Hanika (2019) method.
50
51
Parameters:
52
- XYZ: CIE XYZ tristimulus values
53
- cmfs: Standard observer colour matching functions
54
- illuminant: Illuminant spectral distribution
55
- optimisation_kwargs: Optimization algorithm parameters
56
57
Returns:
58
- Recovered spectral distribution using low-dimensional function space
59
"""
60
61
def XYZ_to_sd_Meng2015(
62
XYZ: ArrayLike,
63
cmfs: MultiSpectralDistributions = None,
64
illuminant: SpectralDistribution = None,
65
interval: float = 5,
66
optimisation_kwargs: dict = None
67
) -> SpectralDistribution:
68
"""
69
Recover spectral distribution using Meng et al. (2015) method.
70
71
Parameters:
72
- XYZ: CIE XYZ tristimulus values
73
- cmfs: Standard observer colour matching functions
74
- illuminant: Illuminant spectral distribution
75
- interval: Wavelength range interval in nm
76
- optimisation_kwargs: Optimization algorithm parameters
77
78
Returns:
79
- Recovered spectral distribution using tristimulus colour rendering
80
"""
81
82
def XYZ_to_sd_Otsu2018(
83
XYZ: ArrayLike,
84
cmfs: MultiSpectralDistributions = None,
85
illuminant: SpectralDistribution = None,
86
dataset: Dataset_Otsu2018 = None,
87
clip: bool = True
88
) -> SpectralDistribution:
89
"""
90
Recover spectral distribution using Otsu et al. (2018) method.
91
92
Parameters:
93
- XYZ: CIE XYZ tristimulus values
94
- cmfs: Standard observer colour matching functions
95
- illuminant: Illuminant spectral distribution
96
- dataset: Dataset for reconstruction
97
- clip: Clip values to maintain physical realizability
98
99
Returns:
100
- Recovered spectral distribution using machine learning approach
101
"""
102
103
def RGB_to_sd_Smits1999(RGB: ArrayLike) -> SpectralDistribution:
104
"""
105
Convert RGB values to spectral distribution using Smits (1999) method.
106
107
Parameters:
108
- RGB: RGB values to convert
109
110
Returns:
111
- Spectral distribution representation of RGB values
112
"""
113
114
def RGB_to_sd_Mallett2019(
115
RGB: ArrayLike,
116
basis_functions: MultiSpectralDistributions = None
117
) -> SpectralDistribution:
118
"""
119
Convert RGB to spectral distribution using Mallett and Yuksel (2019) method.
120
121
Parameters:
122
- RGB: RGB values to convert
123
- basis_functions: Spectral basis functions (default sRGB basis)
124
125
Returns:
126
- Spectral distribution using spectral primary decomposition
127
"""
128
```
129
130
### Colour Blindness Simulation
131
132
Simulate various types of colour vision deficiency using physiologically-based models.
133
134
```python { .api }
135
def msds_cmfs_anomalous_trichromacy_Machado2009(
136
cmfs: LMS_ConeFundamentals,
137
d_LMS: ArrayLike
138
) -> LMS_ConeFundamentals:
139
"""
140
Generate colour matching functions for anomalous trichromacy.
141
142
Parameters:
143
- cmfs: LMS cone fundamentals colour matching functions
144
- d_LMS: Peak wavelength shift for L, M, S cones
145
146
Returns:
147
- Modified colour matching functions for anomalous trichromacy
148
"""
149
150
def matrix_anomalous_trichromacy_Machado2009(
151
cmfs: LMS_ConeFundamentals,
152
primaries: RGB_DisplayPrimaries,
153
d_LMS: ArrayLike
154
) -> NDArrayFloat:
155
"""
156
Compute transformation matrix for anomalous trichromacy simulation.
157
158
Parameters:
159
- cmfs: LMS cone fundamentals colour matching functions
160
- primaries: RGB display primaries tri-spectral distributions
161
- d_LMS: Peak wavelength shift for L, M, S cones
162
163
Returns:
164
- Transformation matrix for anomalous trichromacy
165
"""
166
167
def matrix_cvd_Machado2009(
168
deficiency: Literal["Protanomaly", "Deuteranomaly", "Tritanomaly"],
169
severity: float
170
) -> NDArrayFloat:
171
"""
172
Generate colour vision deficiency simulation matrix using Machado et al. (2009).
173
174
Parameters:
175
- deficiency: Type of colour vision deficiency
176
- severity: Severity of the deficiency (0.0 to 1.0)
177
178
Returns:
179
- CVD simulation transformation matrix
180
"""
181
```
182
183
### Colour Temperature Calculations
184
185
Comprehensive correlated colour temperature (CCT) calculations between various coordinate systems.
186
187
```python { .api }
188
def xy_to_CCT(
189
xy: ArrayLike,
190
method: Literal[
191
"CIE Illuminant D Series",
192
"Kang 2002",
193
"Hernandez 1999",
194
"McCamy 1992"
195
] = "CIE Illuminant D Series"
196
) -> NDArrayFloat:
197
"""
198
Convert CIE xy chromaticity coordinates to correlated colour temperature.
199
200
Parameters:
201
- xy: CIE xy chromaticity coordinates
202
- method: Computation method
203
- optimisation_kwargs: Parameters for scipy.optimize.minimize
204
205
Returns:
206
- Correlated colour temperature in Kelvin
207
"""
208
209
def CCT_to_xy(
210
CCT: ArrayLike,
211
method: Literal[
212
"CIE Illuminant D Series",
213
"Kang 2002",
214
"Hernandez 1999",
215
"McCamy 1992"
216
] = "CIE Illuminant D Series"
217
) -> NDArrayFloat:
218
"""
219
Convert correlated colour temperature to CIE xy chromaticity coordinates.
220
221
Parameters:
222
- CCT: Correlated colour temperature in Kelvin
223
- method: Computation method
224
- optimisation_kwargs: Parameters for scipy.optimize.minimize
225
226
Returns:
227
- CIE xy chromaticity coordinates
228
"""
229
230
def uv_to_CCT(
231
uv: ArrayLike,
232
method: Literal[
233
"Krystek 1985",
234
"Ohno 2013",
235
"Planck 1900",
236
"Robertson 1968"
237
] = "Ohno 2013"
238
) -> NDArrayFloat:
239
"""
240
Convert CIE UCS uv chromaticity coordinates to CCT and Duv.
241
242
Parameters:
243
- uv: CIE UCS colourspace uv chromaticity coordinates
244
- method: Computation method
245
- cmfs: Standard observer colour matching functions
246
- count: (Ohno 2013) Temperature count in planckian tables
247
- start/end: (Ohno 2013) Temperature range in Kelvin
248
- iterations: (Ohno 2013) Number of planckian tables to generate
249
- optimisation_kwargs: Parameters for optimization
250
251
Returns:
252
- Correlated colour temperature and delta uv [CCT, Duv]
253
"""
254
255
def CCT_to_uv(
256
CCT_D_uv: ArrayLike,
257
method: Literal[
258
"Krystek 1985",
259
"Ohno 2013",
260
"Planck 1900",
261
"Robertson 1968"
262
] = "Ohno 2013"
263
) -> NDArrayFloat:
264
"""
265
Convert correlated colour temperature and Duv to CIE UCS uv coordinates.
266
267
Parameters:
268
- CCT_D_uv: Correlated colour temperature and delta uv [CCT, Duv]
269
- method: Computation method
270
- cmfs: Standard observer colour matching functions
271
272
Returns:
273
- CIE UCS colourspace uv chromaticity coordinates
274
"""
275
276
def CCT_to_mired(CCT: ArrayLike) -> NDArrayFloat:
277
"""Convert correlated colour temperature to mired scale."""
278
279
def mired_to_CCT(mired: ArrayLike) -> NDArrayFloat:
280
"""Convert mired scale to correlated colour temperature."""
281
```
282
283
### Volume and Gamut Analysis
284
285
Analyze colour gamut volumes, coverage, and boundary conditions for various colour spaces.
286
287
```python { .api }
288
def RGB_colourspace_volume_MonteCarlo(
289
colourspace: RGB_Colourspace,
290
samples: int = 1000000,
291
limits: ArrayLike = None,
292
illuminant_RGB: ArrayLike = None,
293
illuminant_XYZ: ArrayLike = None,
294
chromatic_adaptation_transform: str = None
295
) -> float:
296
"""
297
Compute RGB colourspace volume using Monte Carlo sampling.
298
299
Parameters:
300
- colourspace: RGB colourspace to analyze
301
- samples: Number of Monte Carlo samples
302
- limits: RGB colourspace limits
303
- illuminant_RGB: RGB colourspace illuminant
304
- illuminant_XYZ: Target illuminant for adaptation
305
- chromatic_adaptation_transform: Adaptation method
306
307
Returns:
308
- Colourspace volume in cubic units
309
"""
310
311
def RGB_colourspace_limits(
312
colourspace: RGB_Colourspace,
313
illuminant: ArrayLike = None
314
) -> NDArrayFloat:
315
"""
316
Compute RGB colourspace limits in CIE XYZ tristimulus values.
317
318
Parameters:
319
- colourspace: RGB colourspace to analyze
320
- illuminant: Illuminant chromaticity coordinates
321
322
Returns:
323
- RGB colourspace limits as min/max XYZ values
324
"""
325
326
def RGB_colourspace_pointer_gamut_coverage_MonteCarlo(
327
colourspace: RGB_Colourspace,
328
samples: int = 1000000
329
) -> float:
330
"""
331
Compute RGB colourspace coverage of Pointer's gamut using Monte Carlo.
332
333
Parameters:
334
- colourspace: RGB colourspace to analyze
335
- samples: Number of Monte Carlo samples
336
337
Returns:
338
- Coverage percentage of Pointer's gamut [0-1]
339
"""
340
341
def RGB_colourspace_visible_spectrum_coverage_MonteCarlo(
342
colourspace: RGB_Colourspace,
343
samples: int = 1000000
344
) -> float:
345
"""
346
Compute RGB colourspace coverage of visible spectrum using Monte Carlo.
347
348
Parameters:
349
- colourspace: RGB colourspace to analyze
350
- samples: Number of Monte Carlo samples
351
352
Returns:
353
- Coverage percentage of visible spectrum [0-1]
354
"""
355
356
def is_within_macadam_limits(
357
XYZ: ArrayLike,
358
illuminant: ArrayLike = None
359
) -> NDArrayFloat:
360
"""
361
Test whether XYZ tristimulus values are within MacAdam limits.
362
363
Parameters:
364
- XYZ: CIE XYZ tristimulus values to test
365
- illuminant: Illuminant chromaticity coordinates
366
367
Returns:
368
- Boolean array indicating values within MacAdam limits
369
"""
370
371
def is_within_pointer_gamut(XYZ: ArrayLike) -> NDArrayFloat:
372
"""
373
Test whether XYZ values are within Pointer's gamut.
374
375
Parameters:
376
- XYZ: CIE XYZ tristimulus values to test
377
378
Returns:
379
- Boolean array indicating values within Pointer's gamut
380
"""
381
382
def is_within_visible_spectrum(
383
XYZ: ArrayLike,
384
cmfs: MultiSpectralDistributions = None,
385
illuminant: SpectralDistribution = None
386
) -> NDArrayFloat:
387
"""
388
Test whether XYZ values are within visible spectrum limits.
389
390
Parameters:
391
- XYZ: CIE XYZ tristimulus values to test
392
- cmfs: Standard observer colour matching functions
393
- illuminant: Illuminant spectral distribution
394
395
Returns:
396
- Boolean array indicating values within visible spectrum
397
"""
398
399
def is_within_mesh_volume(
400
points: ArrayLike,
401
mesh: ArrayLike,
402
tolerance: float = 1e-10
403
) -> NDArrayFloat:
404
"""
405
Test whether points are within given mesh volume.
406
407
Parameters:
408
- points: Points to test
409
- mesh: Mesh vertices defining volume boundary
410
- tolerance: Computation tolerance
411
412
Returns:
413
- Boolean array indicating points within mesh volume
414
"""
415
```
416
417
### Optical Phenomena Modeling
418
419
Model atmospheric optical phenomena including Rayleigh scattering.
420
421
```python { .api }
422
def rayleigh_scattering(
423
wavelength: ArrayLike,
424
CO2_concentration: float = 300,
425
temperature: float = 288.15,
426
pressure: float = 101325,
427
latitude: float = 0,
428
altitude: float = 0
429
) -> NDArrayFloat:
430
"""
431
Compute Rayleigh scattering cross-section.
432
433
Parameters:
434
- wavelength: Wavelength values in nanometers
435
- CO2_concentration: CO2 concentration in parts per million
436
- temperature: Air temperature in Kelvin
437
- pressure: Air pressure in Pascal
438
- latitude: Latitude in degrees
439
- altitude: Altitude in meters
440
441
Returns:
442
- Rayleigh scattering cross-section values
443
"""
444
445
def scattering_cross_section(
446
wavelength: ArrayLike,
447
CO2_concentration: float = 300,
448
temperature: float = 288.15,
449
pressure: float = 101325,
450
latitude: float = 0,
451
altitude: float = 0
452
) -> NDArrayFloat:
453
"""
454
Compute scattering cross-section for given atmospheric conditions.
455
456
Parameters:
457
- wavelength: Wavelength values in nanometers
458
- CO2_concentration: CO2 concentration in parts per million
459
- temperature: Air temperature in Kelvin
460
- pressure: Air pressure in Pascal
461
- latitude: Latitude in degrees
462
- altitude: Altitude in meters
463
464
Returns:
465
- Scattering cross-section values per unit volume
466
"""
467
468
def rayleigh_optical_depth(
469
wavelength: ArrayLike,
470
CO2_concentration: float = 300,
471
temperature: float = 288.15,
472
pressure: float = 101325,
473
latitude: float = 0,
474
altitude: float = 0
475
) -> NDArrayFloat:
476
"""
477
Compute Rayleigh optical depth in atmosphere.
478
479
Parameters:
480
- wavelength: Wavelength values in nanometers
481
- CO2_concentration: CO2 concentration in parts per million
482
- temperature: Air temperature in Kelvin
483
- pressure: Air pressure in Pascal
484
- latitude: Latitude in degrees
485
- altitude: Altitude in meters
486
487
Returns:
488
- Rayleigh optical depth values
489
"""
490
491
def sd_rayleigh_scattering(
492
shape: SpectralShape = None,
493
CO2_concentration: float = 300,
494
temperature: float = 288.15,
495
pressure: float = 101325,
496
latitude: float = 0,
497
altitude: float = 0
498
) -> SpectralDistribution:
499
"""
500
Generate Rayleigh scattering spectral distribution.
501
502
Parameters:
503
- shape: Spectral shape for the distribution
504
- CO2_concentration: CO2 concentration in parts per million
505
- temperature: Air temperature in Kelvin
506
- pressure: Air pressure in Pascal
507
- latitude: Latitude in degrees
508
- altitude: Altitude in meters
509
510
Returns:
511
- Rayleigh scattering spectral distribution
512
"""
513
```
514
515
### Camera Characterization Functions
516
517
Characterize camera sensors and display devices for accurate colour reproduction.
518
519
```python { .api }
520
def matrix_colour_correction(
521
M1: ArrayLike,
522
M2: ArrayLike,
523
method: Literal[
524
"Cheung 2004",
525
"Finlayson 2015",
526
"Vandermonde"
527
] = "Cheung 2004"
528
) -> NDArrayFloat:
529
"""
530
Compute colour correction matrix between two sets of colours.
531
532
Parameters:
533
- M1: Reference colours
534
- M2: Test colours
535
- method: Matrix computation method
536
537
Returns:
538
- Colour correction transformation matrix
539
"""
540
541
def colour_correction(
542
RGB: ArrayLike,
543
M_T: ArrayLike,
544
M_R: ArrayLike,
545
method: Literal[
546
"Cheung 2004",
547
"Finlayson 2015",
548
"Vandermonde"
549
] = "Cheung 2004"
550
) -> NDArrayFloat:
551
"""
552
Perform colour correction on RGB data.
553
554
Parameters:
555
- RGB: RGB values to correct
556
- M_T: Test colours matrix
557
- M_R: Reference colours matrix
558
- method: Correction method
559
560
Returns:
561
- Colour corrected RGB values
562
"""
563
564
def matrix_idt(
565
sensitivities: RGB_CameraSensitivities,
566
illuminant: SpectralDistribution,
567
training_data: MultiSpectralDistributions = None,
568
cmfs: MultiSpectralDistributions = None,
569
optimisation_factory: Callable = None,
570
optimisation_kwargs: dict = None
571
) -> NDArrayFloat:
572
"""
573
Compute Input Device Transform (IDT) matrix for camera characterization.
574
575
Parameters:
576
- sensitivities: Camera RGB sensitivities
577
- illuminant: Scene illuminant spectral distribution
578
- training_data: Training spectral reflectances
579
- cmfs: Standard observer colour matching functions
580
- optimisation_factory: Optimization method factory
581
- optimisation_kwargs: Optimization parameters
582
583
Returns:
584
- IDT transformation matrix from camera RGB to ACES
585
"""
586
587
def camera_RGB_to_ACES2065_1(
588
RGB: ArrayLike,
589
matrix_idt: ArrayLike
590
) -> NDArrayFloat:
591
"""
592
Convert camera RGB to ACES2065-1 colourspace.
593
594
Parameters:
595
- RGB: Camera RGB values
596
- matrix_idt: Input Device Transform matrix
597
598
Returns:
599
- ACES2065-1 RGB values
600
"""
601
602
def sd_to_aces_relative_exposure_values(
603
sd: SpectralDistribution,
604
illuminant: SpectralDistribution,
605
sensitivities: RGB_CameraSensitivities,
606
ISO: float = 100
607
) -> NDArrayFloat:
608
"""
609
Convert spectral distribution to ACES relative exposure values.
610
611
Parameters:
612
- sd: Spectral distribution of target
613
- illuminant: Scene illuminant spectral distribution
614
- sensitivities: Camera RGB sensitivities
615
- ISO: ISO speed rating
616
617
Returns:
618
- ACES relative exposure values
619
"""
620
```
621
622
### Color Correction and Matrix Generation
623
624
Advanced colour correction techniques for device characterization and calibration.
625
626
```python { .api }
627
def polynomial_expansion(
628
RGB: ArrayLike,
629
method: Literal[
630
"Cheung 2004",
631
"Finlayson 2015",
632
"Vandermonde"
633
] = "Cheung 2004",
634
degree: int = 1
635
) -> NDArrayFloat:
636
"""
637
Expand RGB values using polynomial basis functions.
638
639
Parameters:
640
- RGB: RGB values to expand
641
- method: Polynomial expansion method
642
- degree: Polynomial degree for expansion
643
644
Returns:
645
- Expanded RGB values with polynomial terms
646
"""
647
648
def matrix_augmented_Cheung2004(RGB: ArrayLike) -> NDArrayFloat:
649
"""
650
Augment RGB matrix using Cheung et al. (2004) method.
651
652
Parameters:
653
- RGB: RGB values to augment
654
655
Returns:
656
- Augmented matrix with cross-channel terms
657
"""
658
659
def whitepoint_preserving_matrix(
660
XYZ_w: ArrayLike,
661
RGB_w: ArrayLike,
662
XYZ: ArrayLike,
663
RGB: ArrayLike
664
) -> NDArrayFloat:
665
"""
666
Compute whitepoint preserving transformation matrix.
667
668
Parameters:
669
- XYZ_w: Reference whitepoint in XYZ
670
- RGB_w: Camera whitepoint in RGB
671
- XYZ: Reference colour patches in XYZ
672
- RGB: Camera colour patches in RGB
673
674
Returns:
675
- Whitepoint preserving transformation matrix
676
"""
677
678
def white_balance_multipliers(
679
sensitivities: RGB_CameraSensitivities,
680
illuminant: SpectralDistribution
681
) -> NDArrayFloat:
682
"""
683
Compute white balance multipliers for camera sensitivities.
684
685
Parameters:
686
- sensitivities: Camera RGB sensitivities
687
- illuminant: Scene illuminant spectral distribution
688
689
Returns:
690
- White balance multiplier values for R, G, B channels
691
"""
692
693
def best_illuminant(
694
reflectances: MultiSpectralDistributions,
695
sensitivities: RGB_CameraSensitivities,
696
illuminants: dict
697
) -> str:
698
"""
699
Find best matching illuminant for given scene conditions.
700
701
Parameters:
702
- reflectances: Scene reflectance spectra
703
- sensitivities: Camera RGB sensitivities
704
- illuminants: Dictionary of candidate illuminants
705
706
Returns:
707
- Name of best matching illuminant
708
"""
709
```
710
711
### Multi-Spectral Image Processing
712
713
Process multi-spectral and hyperspectral imaging data.
714
715
```python { .api }
716
class MultiSpectralDistributions:
717
"""
718
Represents multiple aligned spectral power distributions.
719
720
Parameters:
721
- data: Dictionary mapping names to spectral data or 2D array
722
- domain: Array-like of wavelengths
723
- labels: Names for each distribution if data is array
724
"""
725
726
def __init__(
727
self,
728
data: Union[dict, ArrayLike],
729
domain: ArrayLike = None,
730
labels: List[str] = None
731
): ...
732
733
def __getitem__(self, item: Union[str, int]) -> SpectralDistribution: ...
734
def __setitem__(self, item: Union[str, int], value: SpectralDistribution) -> None: ...
735
736
@property
737
def wavelengths(self) -> NDArray: ...
738
@property
739
def values(self) -> NDArray: ...
740
@property
741
def shape(self) -> SpectralShape: ...
742
743
def align(self, shape: SpectralShape) -> "MultiSpectralDistributions": ...
744
def trim(self, shape: SpectralShape) -> "MultiSpectralDistributions": ...
745
def interpolate(self, shape: SpectralShape, method: str = None) -> "MultiSpectralDistributions": ...
746
747
def msds_to_XYZ(
748
msds: MultiSpectralDistributions,
749
cmfs: MultiSpectralDistributions,
750
illuminant: SpectralDistribution,
751
k: float = None,
752
shape: SpectralShape = None
753
) -> NDArrayFloat:
754
"""
755
Convert multiple spectral distributions to CIE XYZ tristimulus values.
756
757
Parameters:
758
- msds: Multiple spectral distributions to convert
759
- cmfs: Standard observer colour matching functions
760
- illuminant: Illuminant spectral distribution
761
- k: Normalisation constant
762
- shape: Spectral shape for computation
763
764
Returns:
765
- CIE XYZ tristimulus values for each distribution
766
"""
767
768
def RGB_to_msds_camera_sensitivities_Jiang2013(
769
RGB: ArrayLike,
770
basis_functions: MultiSpectralDistributions,
771
mean_stds: MultiSpectralDistributions = None
772
) -> MultiSpectralDistributions:
773
"""
774
Recover multiple spectral distributions from RGB using camera sensitivities.
775
776
Parameters:
777
- RGB: Camera RGB values
778
- basis_functions: Spectral basis functions for reconstruction
779
- mean_stds: Mean spectral distributions for basis
780
781
Returns:
782
- Reconstructed multiple spectral distributions
783
"""
784
785
def PCA_Jiang2013(
786
reflectances: MultiSpectralDistributions,
787
illuminants: MultiSpectralDistributions,
788
sensitivities: RGB_CameraSensitivities
789
) -> dict:
790
"""
791
Perform PCA analysis for spectral reconstruction using Jiang et al. (2013).
792
793
Parameters:
794
- reflectances: Training reflectance spectra
795
- illuminants: Training illuminant spectra
796
- sensitivities: Camera RGB sensitivities
797
798
Returns:
799
- Dictionary containing PCA basis functions and statistics
800
"""
801
```
802
803
### Biochemical Modeling
804
805
Model biochemical processes relevant to vision and colour perception.
806
807
```python { .api }
808
def reaction_rate_MichaelisMenten(
809
S: ArrayLike,
810
V_max: ArrayLike,
811
K_m: ArrayLike,
812
method: Literal[
813
"Michaelis 1913",
814
"Abebe 2017",
815
"Henri 1903"
816
] = "Michaelis 1913"
817
) -> NDArrayFloat:
818
"""
819
Compute Michaelis-Menten reaction rate.
820
821
Parameters:
822
- S: Substrate concentration
823
- V_max: Maximum reaction velocity
824
- K_m: Michaelis constant
825
- method: Computation method
826
827
Returns:
828
- Reaction rate values
829
"""
830
831
def substrate_concentration_MichaelisMenten(
832
v: ArrayLike,
833
V_max: ArrayLike,
834
K_m: ArrayLike,
835
method: Literal[
836
"Michaelis 1913",
837
"Abebe 2017"
838
] = "Michaelis 1913"
839
) -> NDArrayFloat:
840
"""
841
Compute substrate concentration from reaction rate using Michaelis-Menten.
842
843
Parameters:
844
- v: Reaction rate
845
- V_max: Maximum reaction velocity
846
- K_m: Michaelis constant
847
- method: Computation method
848
849
Returns:
850
- Substrate concentration values
851
"""
852
```
853
854
## Usage Examples
855
856
### Advanced Spectral Recovery
857
858
```python
859
import colour
860
import numpy as np
861
862
# Recover spectral distribution from XYZ using different methods
863
XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
864
865
# Jakob 2019 method - Low-dimensional function space
866
sd_jakob = colour.XYZ_to_sd(XYZ, method="Jakob 2019")
867
868
# Meng 2015 method - Optimization-based approach
869
sd_meng = colour.XYZ_to_sd(XYZ, method="Meng 2015", interval=10)
870
871
# Otsu 2018 method - Machine learning approach
872
sd_otsu = colour.XYZ_to_sd(XYZ, method="Otsu 2018", clip=True)
873
874
# RGB to spectral using Smits 1999
875
RGB = np.array([0.8, 0.4, 0.2])
876
sd_smits = colour.RGB_to_sd_Smits1999(RGB)
877
```
878
879
### Colour Vision Deficiency Simulation
880
881
```python
882
# Simulate different types of colour blindness
883
import colour
884
885
# Generate CVD simulation matrix
886
matrix_protanomaly = colour.matrix_cvd_Machado2009("Protanomaly", 0.8)
887
matrix_deuteranomaly = colour.matrix_cvd_Machado2009("Deuteranomaly", 0.6)
888
matrix_tritanomaly = colour.matrix_cvd_Machado2009("Tritanomaly", 0.4)
889
890
# Apply CVD simulation to RGB image
891
RGB_image = np.random.random((100, 100, 3))
892
RGB_protanomaly = np.dot(RGB_image, matrix_protanomaly.T)
893
```
894
895
### Colour Temperature Analysis
896
897
```python
898
# Convert between chromaticity coordinates and CCT
899
xy = np.array([0.31270, 0.32900])
900
901
# Get CCT using different methods
902
CCT_cie = colour.xy_to_CCT(xy, method="CIE Illuminant D Series")
903
CCT_mccamy = colour.xy_to_CCT(xy, method="McCamy 1992")
904
905
# Convert back to chromaticity coordinates
906
xy_recovered = colour.CCT_to_xy(CCT_cie)
907
908
# Work with uv coordinates and Duv
909
uv = np.array([0.1978, 0.3122])
910
CCT_Duv = colour.uv_to_CCT(uv, method="Ohno 2013")
911
CCT, Duv = CCT_Duv[0], CCT_Duv[1]
912
```
913
914
### Gamut Analysis and Volume Calculations
915
916
```python
917
# Analyze RGB colourspace properties
918
colourspace = colour.RGB_COLOURSPACES["sRGB"]
919
920
# Compute colourspace volume
921
volume = colour.RGB_colourspace_volume_MonteCarlo(colourspace, samples=1000000)
922
923
# Calculate coverage of standard gamuts
924
pointer_coverage = colour.RGB_colourspace_pointer_gamut_coverage_MonteCarlo(colourspace)
925
spectrum_coverage = colour.RGB_colourspace_visible_spectrum_coverage_MonteCarlo(colourspace)
926
927
# Test if XYZ values are within various limits
928
XYZ_test = np.array([0.3, 0.3, 0.3])
929
within_macadam = colour.is_within_macadam_limits(XYZ_test)
930
within_pointer = colour.is_within_pointer_gamut(XYZ_test)
931
within_spectrum = colour.is_within_visible_spectrum(XYZ_test)
932
```
933
934
### Atmospheric Phenomena Modeling
935
936
```python
937
# Model Rayleigh scattering in atmosphere
938
wavelengths = np.linspace(380, 780, 41)
939
940
# Standard atmosphere conditions
941
scattering = colour.rayleigh_scattering(
942
wavelengths,
943
CO2_concentration=400, # ppm
944
temperature=288.15, # K (15°C)
945
pressure=101325, # Pa (sea level)
946
latitude=45, # degrees
947
altitude=0 # meters
948
)
949
950
# Generate spectral distribution
951
sd_rayleigh = colour.sd_rayleigh_scattering(
952
shape=colour.SpectralShape(380, 780, 10),
953
CO2_concentration=400,
954
temperature=288.15
955
)
956
957
# Compute optical depth
958
optical_depth = colour.rayleigh_optical_depth(wavelengths)
959
```
960
961
### Camera Characterization Workflow
962
963
```python
964
# Complete camera characterization pipeline
965
from colour.characterisation import MSDS_CAMERA_SENSITIVITIES
966
967
# Load camera sensitivities
968
camera_sensitivities = MSDS_CAMERA_SENSITIVITIES["Nikon D850"]
969
970
# Define scene illuminant
971
illuminant = colour.SDS_ILLUMINANTS["D65"]
972
973
# Compute IDT matrix
974
idt_matrix = colour.matrix_idt(
975
sensitivities=camera_sensitivities,
976
illuminant=illuminant,
977
optimisation_factory=colour.optimisation_factory_rawtoaces_v1
978
)
979
980
# Convert camera RGB to ACES
981
camera_RGB = np.array([0.8, 0.6, 0.4])
982
aces_RGB = colour.camera_RGB_to_ACES2065_1(camera_RGB, idt_matrix)
983
984
# Calculate white balance multipliers
985
wb_multipliers = colour.white_balance_multipliers(
986
camera_sensitivities,
987
illuminant
988
)
989
```
990
991
### Volume and Gamut Analysis
992
993
Functions for analyzing colourspace volumes, gamut coverage, and spectrum analysis for color reproduction assessment.
994
995
```python { .api }
996
def RGB_colourspace_limits(colourspace: RGB_Colourspace, resolution: int = 64) -> NDArray:
997
"""
998
Calculate RGB colourspace limits using Monte Carlo sampling.
999
1000
Parameters:
1001
- colourspace: RGB colourspace to analyze
1002
- resolution: sampling resolution for calculation
1003
1004
Returns:
1005
Colourspace boundary limits in Lab space
1006
"""
1007
1008
def RGB_colourspace_volume_MonteCarlo(colourspace: RGB_Colourspace, samples: int = 1000000, random_state: RandomState = None) -> float:
1009
"""
1010
Calculate colourspace volume using Monte Carlo sampling method.
1011
1012
Parameters:
1013
- colourspace: RGB colourspace to analyze
1014
- samples: number of Monte Carlo samples
1015
- random_state: random number generator state
1016
1017
Returns:
1018
Colourspace volume in cubic Lab units
1019
"""
1020
1021
def RGB_colourspace_coverage_MonteCarlo(colourspace: RGB_Colourspace, coverage_sampler: Callable = None, samples: int = 1000000) -> float:
1022
"""
1023
Calculate coverage of a colourspace using Monte Carlo sampling.
1024
1025
Parameters:
1026
- colourspace: RGB colourspace to analyze
1027
- coverage_sampler: sampling function for coverage analysis
1028
- samples: number of Monte Carlo samples
1029
1030
Returns:
1031
Coverage percentage (0-1)
1032
"""
1033
1034
def RGB_colourspace_pointer_gamut_coverage_MonteCarlo(colourspace: RGB_Colourspace, samples: int = 1000000) -> float:
1035
"""
1036
Calculate Pointer's gamut coverage using Monte Carlo sampling.
1037
1038
Parameters:
1039
- colourspace: RGB colourspace to analyze
1040
- samples: number of Monte Carlo samples
1041
1042
Returns:
1043
Pointer's gamut coverage percentage (0-1)
1044
"""
1045
1046
def is_within_macadam_limits(XYZ: ArrayLike, illuminant: ArrayLike = None) -> NDArray:
1047
"""
1048
Check if XYZ values are within MacAdam limits.
1049
1050
Parameters:
1051
- XYZ: CIE XYZ tristimulus values
1052
- illuminant: reference illuminant
1053
1054
Returns:
1055
Boolean array indicating values within limits
1056
"""
1057
1058
def is_within_pointer_gamut(XYZ: ArrayLike, illuminant: ArrayLike = None) -> NDArray:
1059
"""
1060
Check if XYZ values are within Pointer's gamut.
1061
1062
Parameters:
1063
- XYZ: CIE XYZ tristimulus values
1064
- illuminant: reference illuminant
1065
1066
Returns:
1067
Boolean array indicating values within Pointer's gamut
1068
"""
1069
1070
def is_within_visible_spectrum(XYZ: ArrayLike, illuminant: ArrayLike = None, tolerance: float = None) -> NDArray:
1071
"""
1072
Check if XYZ values represent physically realizable colours.
1073
1074
Parameters:
1075
- XYZ: CIE XYZ tristimulus values
1076
- illuminant: reference illuminant
1077
- tolerance: tolerance for boundary checking
1078
1079
Returns:
1080
Boolean array indicating physically realizable colours
1081
"""
1082
1083
# Method collections
1084
RGB_COLOURSPACE_VOLUME_METHODS: Dict[str, Callable]
1085
```
1086
1087
### Biochemistry and Kinetics
1088
1089
Biochemical computation functions including enzyme kinetics modeling for biological color processes.
1090
1091
```python { .api }
1092
def reaction_rate_MichaelisMenten(S: ArrayLike, V_max: float, K_m: float, method: str = "Michaelis 1913") -> NDArray:
1093
"""
1094
Calculate enzyme reaction rate using Michaelis-Menten kinetics.
1095
1096
Parameters:
1097
- S: substrate concentration array
1098
- V_max: maximum reaction velocity
1099
- K_m: Michaelis constant (substrate concentration at half V_max)
1100
- method: kinetic model method
1101
1102
Returns:
1103
Reaction rate values
1104
"""
1105
1106
def substrate_concentration_MichaelisMenten(r: ArrayLike, V_max: float, K_m: float, method: str = "Michaelis 1913") -> NDArray:
1107
"""
1108
Calculate substrate concentration from reaction rate using Michaelis-Menten kinetics.
1109
1110
Parameters:
1111
- r: reaction rate values
1112
- V_max: maximum reaction velocity
1113
- K_m: Michaelis constant
1114
- method: kinetic model method
1115
1116
Returns:
1117
Substrate concentration values
1118
"""
1119
1120
# Method collections
1121
REACTION_RATE_MICHAELISMENTEN_METHODS: Dict[str, Callable]
1122
SUBSTRATE_CONCENTRATION_MICHAELISMENTEN_METHODS: Dict[str, Callable]
1123
```
1124
1125
### Contrast Sensitivity Functions
1126
1127
Contrast sensitivity modeling for human visual system analysis.
1128
1129
```python { .api }
1130
def contrast_sensitivity_function(method: str = "Barten 1999", **kwargs) -> NDArray:
1131
"""
1132
Calculate contrast sensitivity function using specified method.
1133
1134
Parameters:
1135
- method: contrast sensitivity model method
1136
- "Barten 1999": Barten (1999) model
1137
- **kwargs: method-specific parameters
1138
1139
Returns:
1140
Contrast sensitivity values
1141
"""
1142
1143
def contrast_sensitivity_function_Barten1999(u: ArrayLike, sigma: float = 0, k: float = 3, T: float = 0.1) -> NDArray:
1144
"""
1145
Calculate contrast sensitivity using Barten (1999) model.
1146
1147
Parameters:
1148
- u: spatial frequency values in cycles per degree
1149
- sigma: standard deviation of optical modulation transfer function
1150
- k: signal-to-noise ratio constant
1151
- T: integration time in seconds
1152
1153
Returns:
1154
Contrast sensitivity values
1155
"""
1156
1157
# Method collections
1158
CONTRAST_SENSITIVITY_METHODS: Dict[str, Callable]
1159
```
1160
1161
### Corresponding Chromaticities
1162
1163
Corresponding chromaticities prediction models for cross-media color reproduction.
1164
1165
```python { .api }
1166
def corresponding_chromaticities_prediction(experiment: int, model: str = "CIE 1994", **kwargs) -> CorrespondingChromaticitiesPrediction:
1167
"""
1168
Predict corresponding chromaticities using specified model.
1169
1170
Parameters:
1171
- experiment: experiment number from Breneman datasets
1172
- model: prediction model
1173
- "CIE 1994": CIE 1994 corresponding chromaticities model
1174
- "CMCCAT2000": CMCCAT2000 model
1175
- "Fairchild 1990": Fairchild (1990) model
1176
- "Von Kries": Von Kries chromatic adaptation model
1177
- "Zhai 2018": Zhai and Luo (2018) model
1178
1179
Returns:
1180
Corresponding chromaticities prediction specification
1181
"""
1182
1183
class CorrespondingChromaticitiesPrediction:
1184
"""
1185
Specification class for corresponding chromaticities prediction results.
1186
1187
Attributes:
1188
- name: prediction model name
1189
- XYZ_t: test chromaticities
1190
- XYZ_m: match chromaticities
1191
- Y_t: test luminance values
1192
- Y_m: match luminance values
1193
"""
1194
name: str
1195
XYZ_t: NDArray
1196
XYZ_m: NDArray
1197
Y_t: NDArray
1198
Y_m: NDArray
1199
1200
# Method collections and datasets
1201
CORRESPONDING_CHROMATICITIES_PREDICTION_MODELS: Dict[str, Callable]
1202
BRENEMAN_EXPERIMENTS: Dict[int, CorrespondingColourDataset]
1203
```
1204
1205
## Additional Usage Examples
1206
1207
### Volume Analysis
1208
1209
```python
1210
import colour
1211
import numpy as np
1212
1213
# Analyze sRGB colourspace volume
1214
srgb = colour.RGB_COLOURSPACES["sRGB"]
1215
volume = colour.RGB_colourspace_volume_MonteCarlo(srgb, samples=100000)
1216
print(f"sRGB volume: {volume:.2f} cubic Lab units")
1217
1218
# Calculate Pointer's gamut coverage
1219
pointer_coverage = colour.RGB_colourspace_pointer_gamut_coverage_MonteCarlo(srgb)
1220
print(f"sRGB covers {pointer_coverage*100:.1f}% of Pointer's gamut")
1221
1222
# Check if colors are within visible spectrum
1223
XYZ_test = np.array([[95.047, 100.0, 108.883], # D65 white
1224
[0, 0, 0], # Black
1225
[200, 150, 50]]) # Invalid color
1226
within_spectrum = colour.is_within_visible_spectrum(XYZ_test)
1227
print(f"Within visible spectrum: {within_spectrum}")
1228
```
1229
1230
### Biochemistry Modeling
1231
1232
```python
1233
import colour
1234
import numpy as np
1235
1236
# Model enzyme kinetics
1237
substrate_conc = np.linspace(0, 10, 100) # mM
1238
V_max = 2.5 # μmol/min
1239
K_m = 1.2 # mM
1240
1241
reaction_rates = colour.reaction_rate_MichaelisMenten(
1242
substrate_conc, V_max, K_m, method="Michaelis 1913"
1243
)
1244
1245
# Calculate substrate concentration from reaction rate
1246
target_rate = 1.0 # μmol/min
1247
required_substrate = colour.substrate_concentration_MichaelisMenten(
1248
target_rate, V_max, K_m
1249
)
1250
print(f"Substrate needed for {target_rate} μmol/min: {required_substrate:.2f} mM")
1251
```
1252
1253
### Contrast Sensitivity
1254
1255
```python
1256
import colour
1257
import numpy as np
1258
1259
# Calculate contrast sensitivity function
1260
spatial_freq = np.logspace(-1, 2, 50) # 0.1 to 100 cycles/degree
1261
1262
# Standard viewing conditions
1263
csf = colour.contrast_sensitivity_function_Barten1999(
1264
spatial_freq,
1265
sigma=0.5, # optical blur
1266
k=3.0, # SNR constant
1267
T=0.1 # integration time
1268
)
1269
1270
print(f"Peak sensitivity at {spatial_freq[np.argmax(csf)]:.1f} cycles/degree")
1271
print(f"Peak sensitivity: {np.max(csf):.1f}")
1272
```
1273
1274
## Additional Imports
1275
1276
```python
1277
# Volume and gamut analysis
1278
from colour.volume import (
1279
RGB_colourspace_volume_MonteCarlo, RGB_colourspace_coverage_MonteCarlo,
1280
RGB_colourspace_pointer_gamut_coverage_MonteCarlo,
1281
is_within_macadam_limits, is_within_pointer_gamut, is_within_visible_spectrum
1282
)
1283
1284
# Biochemistry
1285
from colour.biochemistry import (
1286
reaction_rate_MichaelisMenten, substrate_concentration_MichaelisMenten,
1287
REACTION_RATE_MICHAELISMENTEN_METHODS
1288
)
1289
1290
# Contrast sensitivity
1291
from colour.contrast import (
1292
contrast_sensitivity_function, contrast_sensitivity_function_Barten1999,
1293
CONTRAST_SENSITIVITY_METHODS
1294
)
1295
1296
# Corresponding chromaticities
1297
from colour.corresponding import (
1298
corresponding_chromaticities_prediction,
1299
CORRESPONDING_CHROMATICITIES_PREDICTION_MODELS, BRENEMAN_EXPERIMENTS
1300
)
1301
```