0
# Colour Appearance Models
1

2
Comprehensive colour appearance modeling functionality implementing multiple industry-standard models for predicting colour appearance under various viewing conditions and adaptation states. These models account for perceptual effects like chromatic adaptation, brightness perception, and colour constancy.
3

4
## Capabilities
5

6
### CIECAM02 Colour Appearance Model
7

8
The CIE recommended CIECAM02 model for predicting colour appearance under different viewing conditions.
9

10
#### Forward Transform
11

12
```python { .api }
13
def XYZ_to_CIECAM02(
14
    XYZ: ArrayLike,
15
    XYZ_w: ArrayLike,
16
    L_A: ArrayLike,
17
    Y_b: ArrayLike,
18
    surround: InductionFactors_CIECAM02 = VIEWING_CONDITIONS_CIECAM02["Average"],
19
    discount_illuminant: bool = False,
20
    compute_H: bool = True,
21
) -> CAM_Specification_CIECAM02:
22
    """
23
    Compute CIECAM02 colour appearance model correlates from CIE XYZ tristimulus values.
24

25
    Parameters:
26
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
27
    - XYZ_w: CIE XYZ tristimulus values of reference white
28
    - L_A: adapting field luminance in cd/m² (often 20% of white object luminance)
29
    - Y_b: luminous factor of background (Y_b = 100 × L_b / L_w)
30
    - surround: surround viewing conditions induction factors
31
    - discount_illuminant: whether to discount the illuminant
32
    - compute_H: whether to compute hue quadrature H
33

34
    Returns:
35
    CAM_Specification_CIECAM02 object containing appearance correlates:
36
    - J: lightness correlate
37
    - C: chroma correlate  
38
    - h: hue angle in degrees
39
    - s: saturation correlate
40
    - Q: brightness correlate
41
    - M: colourfulness correlate
42
    - H: hue quadrature
43
    - HC: hue composition
44

45
    Domain/Range: [0, 1] for XYZ parameters in Scale - 1 mode
46
    """
47
```
48

49
#### Inverse Transform
50

51
```python { .api }
52
def CIECAM02_to_XYZ(
53
    specification: CAM_Specification_CIECAM02,
54
    XYZ_w: ArrayLike,
55
    L_A: ArrayLike,
56
    Y_b: ArrayLike,
57
    surround: InductionFactors_CIECAM02 = VIEWING_CONDITIONS_CIECAM02["Average"],
58
    discount_illuminant: bool = False,
59
) -> NDArrayFloat:
60
    """
61
    Convert CIECAM02 colour appearance specification to CIE XYZ tristimulus values.
62

63
    Parameters:
64
    - specification: CIECAM02 colour appearance specification
65
    - XYZ_w: CIE XYZ tristimulus values of reference white
66
    - L_A: adapting field luminance in cd/m²
67
    - Y_b: luminous factor of background
68
    - surround: surround viewing conditions induction factors
69
    - discount_illuminant: whether to discount the illuminant
70

71
    Returns:
72
    CIE XYZ tristimulus values
73

74
    Notes:
75
    - Requires at least one of J (lightness) or Q (brightness) to be specified
76
    - Requires at least one of C (chroma), M (colourfulness), or s (saturation)
77
    - Requires h (hue angle) for chromatic colours
78
    """
79
```
80

81
#### CIECAM02 Specification Class
82

83
```python { .api }
84
@dataclass
85
class CAM_Specification_CIECAM02:
86
    """
87
    CIECAM02 colour appearance model specification.
88

89
    Attributes:
90
    - J: correlate of lightness
91
    - C: correlate of chroma
92
    - h: hue angle in degrees
93
    - s: correlate of saturation
94
    - Q: correlate of brightness
95
    - M: correlate of colourfulness
96
    - H: hue quadrature
97
    - HC: hue composition
98

99
    All attributes are optional and can be None, float, or NDArrayFloat
100
    """
101
```
102

103
#### CIECAM02 Induction Factors and Viewing Conditions
104

105
```python { .api }
106
class InductionFactors_CIECAM02:
107
    """
108
    CIECAM02 colour appearance model induction factors.
109

110
    Parameters:
111
    - F: maximum degree of adaptation
112
    - c: exponential non-linearity
113
    - N_c: chromatic induction factor
114

115
    Standard conditions:
116
    - Average: F=1, c=0.69, N_c=1 (typical viewing)
117
    - Dim: F=0.9, c=0.59, N_c=0.9 (dim surrounds)
118
    - Dark: F=0.8, c=0.525, N_c=0.8 (dark surrounds)
119
    """
120

121
# Pre-defined viewing conditions
122
VIEWING_CONDITIONS_CIECAM02 = {
123
    "Average": InductionFactors_CIECAM02(1, 0.69, 1),
124
    "Dim": InductionFactors_CIECAM02(0.9, 0.59, 0.9),
125
    "Dark": InductionFactors_CIECAM02(0.8, 0.525, 0.8),
126
}
127
```
128

129
### CAM16 Colour Appearance Model
130

131
The CAM16 model, an evolution of CIECAM02 with improved predictions.
132

133
#### Forward Transform
134

135
```python { .api }
136
def XYZ_to_CAM16(
137
    XYZ: ArrayLike,
138
    XYZ_w: ArrayLike,
139
    L_A: ArrayLike,
140
    Y_b: ArrayLike,
141
    surround: InductionFactors_CAM16 = VIEWING_CONDITIONS_CAM16["Average"],
142
    discount_illuminant: bool = False,
143
) -> CAM_Specification_CAM16:
144
    """
145
    Compute CAM16 colour appearance model correlates from CIE XYZ tristimulus values.
146

147
    Parameters:
148
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
149
    - XYZ_w: CIE XYZ tristimulus values of reference white
150
    - L_A: adapting field luminance in cd/m²
151
    - Y_b: luminous factor of background
152
    - surround: surround viewing conditions induction factors
153
    - discount_illuminant: whether to discount the illuminant
154

155
    Returns:
156
    CAM_Specification_CAM16 object containing appearance correlates:
157
    - J: lightness correlate
158
    - C: chroma correlate
159
    - h: hue angle in degrees
160
    - s: saturation correlate
161
    - Q: brightness correlate
162
    - M: colourfulness correlate
163
    - H: hue quadrature
164
    - HC: hue composition
165

166
    Domain/Range: [0, 1] for XYZ parameters in Scale - 1 mode
167
    """
168
```
169

170
#### Inverse Transform
171

172
```python { .api }
173
def CAM16_to_XYZ(
174
    specification: CAM_Specification_CAM16,
175
    XYZ_w: ArrayLike,
176
    L_A: ArrayLike,
177
    Y_b: ArrayLike,
178
    surround: InductionFactors_CAM16 = VIEWING_CONDITIONS_CAM16["Average"],
179
    discount_illuminant: bool = False,
180
) -> NDArrayFloat:
181
    """
182
    Convert CAM16 colour appearance specification to CIE XYZ tristimulus values.
183

184
    Parameters:
185
    - specification: CAM16 colour appearance specification
186
    - XYZ_w: CIE XYZ tristimulus values of reference white
187
    - L_A: adapting field luminance in cd/m²
188
    - Y_b: luminous factor of background
189
    - surround: surround viewing conditions induction factors
190
    - discount_illuminant: whether to discount the illuminant
191

192
    Returns:
193
    CIE XYZ tristimulus values
194

195
    Notes:
196
    - Uses improved CAM16 chromatic adaptation transform (CAT16)
197
    - More accurate than CIECAM02 for certain viewing conditions
198
    """
199
```
200

201
#### CAM16 Specification and Viewing Conditions
202

203
```python { .api }
204
@dataclass
205
class CAM_Specification_CAM16:
206
    """
207
    CAM16 colour appearance model specification.
208
    
209
    Same structure as CIECAM02 specification with identical attributes.
210
    """
211

212
class InductionFactors_CAM16:
213
    """
214
    CAM16 colour appearance model induction factors.
215
    
216
    Same structure as CIECAM02 induction factors:
217
    - F: maximum degree of adaptation
218
    - c: exponential non-linearity  
219
    - N_c: chromatic induction factor
220
    """
221

222
# Inherits CIECAM02 viewing conditions
223
VIEWING_CONDITIONS_CAM16 = VIEWING_CONDITIONS_CIECAM02
224
```
225

226
### Hunt Colour Appearance Model
227

228
The Hunt model providing detailed colour appearance predictions with comprehensive adaptation mechanisms.
229

230
#### Forward Transform
231

232
```python { .api }
233
def XYZ_to_Hunt(
234
    XYZ: ArrayLike,
235
    XYZ_w: ArrayLike,
236
    XYZ_b: ArrayLike,
237
    L_A: ArrayLike,
238
    surround: InductionFactors_Hunt = VIEWING_CONDITIONS_HUNT["Normal Scenes"],
239
    L_AS: ArrayLike | None = None,
240
    CCT_w: ArrayLike | None = None,
241
    XYZ_p: ArrayLike | None = None,
242
    p: ArrayLike | None = None,
243
    S: ArrayLike | None = None,
244
    S_w: ArrayLike | None = None,
245
    helson_judd_effect: bool = False,
246
    discount_illuminant: bool = False,
247
) -> CAM_Specification_Hunt:
248
    """
249
    Compute Hunt colour appearance model correlates from CIE XYZ tristimulus values.
250

251
    Parameters:
252
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
253
    - XYZ_w: CIE XYZ tristimulus values of reference white
254
    - XYZ_b: CIE XYZ tristimulus values of background
255
    - L_A: adapting field luminance in cd/m²
256
    - surround: surround viewing conditions induction factors
257
    - L_AS: scotopic luminance of adapting field (optional)
258
    - CCT_w: correlated colour temperature of illuminant (optional)
259
    - XYZ_p: CIE XYZ tristimulus values of proximate field (optional)
260
    - p: simultaneous contrast/assimilation parameter (optional)
261
    - S: scotopic response (optional)
262
    - S_w: scotopic response for reference white (optional)
263
    - helson_judd_effect: whether to account for Helson-Judd effect
264
    - discount_illuminant: whether to discount the illuminant
265

266
    Returns:
267
    CAM_Specification_Hunt object containing appearance correlates:
268
    - J: lightness correlate
269
    - C: chroma correlate
270
    - h: hue angle in degrees
271
    - s: saturation correlate
272
    - Q: brightness correlate
273
    - M: colourfulness correlate
274
    - H: hue quadrature
275
    - HC: hue composition
276

277
    Domain/Range: [0, 1] for XYZ parameters in Scale - 1 mode
278
    """
279
```
280

281
#### Hunt Specification and Induction Factors
282

283
```python { .api }
284
@dataclass
285
class CAM_Specification_Hunt:
286
    """
287
    Hunt colour appearance model specification.
288

289
    Attributes:
290
    - J: correlate of lightness
291
    - C: correlate of chroma
292
    - h: hue angle in degrees
293
    - s: correlate of saturation
294
    - Q: correlate of brightness
295
    - M: correlate of colourfulness
296
    - H: hue quadrature
297
    - HC: hue composition
298
    """
299

300
class InductionFactors_Hunt:
301
    """
302
    Hunt colour appearance model induction factors.
303

304
    Parameters:
305
    - N_c: chromatic induction factor
306
    - N_b: brightness induction factor
307
    - N_cb: chromatic brightness induction factor (optional)
308
    - N_bb: brightness induction factor for background (optional)
309
    """
310

311
# Pre-defined viewing conditions for Hunt model
312
VIEWING_CONDITIONS_HUNT = {
313
    "Small Areas, Uniform Background & Surrounds": InductionFactors_Hunt(1, 300),
314
    "Normal Scenes": InductionFactors_Hunt(1, 75),
315
    "Television & CRT, Dim Surrounds": InductionFactors_Hunt(1, 25),
316
    "Large Transparencies On Light Boxes": InductionFactors_Hunt(0.7, 25),
317
    "Projected Transparencies, Dark Surrounds": InductionFactors_Hunt(0.7, 10),
318
}
319
```
320

321
### RLAB Colour Appearance Model
322

323
The RLAB model providing simplified colour appearance predictions with emphasis on cross-media reproduction.
324

325
#### Forward Transform
326

327
```python { .api }
328
def XYZ_to_RLAB(
329
    XYZ: ArrayLike,
330
    XYZ_n: ArrayLike,
331
    Y_n: ArrayLike,
332
    sigma: ArrayLike = VIEWING_CONDITIONS_RLAB["Average"],
333
    D: ArrayLike = D_FACTOR_RLAB["Hard Copy Images"],
334
) -> CAM_Specification_RLAB:
335
    """
336
    Compute RLAB colour appearance model correlates from CIE XYZ tristimulus values.
337

338
    Parameters:
339
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
340
    - XYZ_n: CIE XYZ tristimulus values of reference white
341
    - Y_n: luminance factor of reference white
342
    - sigma: surround relative luminance
343
    - D: degree of adaptation
344

345
    Returns:
346
    CAM_Specification_RLAB object containing appearance correlates:
347
    - J: lightness correlate
348
    - C: chroma correlate
349
    - h: hue angle in degrees
350
    - s: saturation correlate
351
    - HC: hue composition
352

353
    Domain/Range: [0, 1] for XYZ parameters in Scale - 1 mode
354
    """
355
```
356

357
#### RLAB Specification and Viewing Conditions
358

359
```python { .api }
360
@dataclass
361
class CAM_Specification_RLAB:
362
    """
363
    RLAB colour appearance model specification.
364

365
    Attributes:
366
    - J: correlate of lightness
367
    - C: correlate of chroma
368
    - h: hue angle in degrees
369
    - s: correlate of saturation
370
    - HC: hue composition
371
    """
372

373
# RLAB viewing conditions and adaptation factors
374
VIEWING_CONDITIONS_RLAB = {
375
    "Average": 0.2,     # Average surround
376
    "Dim": 0.1,         # Dim surround  
377
    "Dark": 0.0,        # Dark surround
378
}
379

380
D_FACTOR_RLAB = {
381
    "Hard Copy Images": 1.0,           # Complete adaptation
382
    "Soft Copy Images": 0.7,           # Partial adaptation
383
    "Projected Transparencies": 0.5,    # Limited adaptation
384
}
385
```
386

387
### ZCAM Colour Appearance Model
388

389
The ZCAM model designed for high dynamic range and wide colour gamut imaging applications.
390

391
#### Forward Transform
392

393
```python { .api }
394
def XYZ_to_ZCAM(
395
    XYZ: ArrayLike,
396
    XYZ_w: ArrayLike,
397
    L_A: ArrayLike,
398
    Y_b: ArrayLike,
399
    surround: InductionFactors_ZCAM = VIEWING_CONDITIONS_ZCAM["Average"],
400
    discount_illuminant: bool = False,
401
) -> CAM_Specification_ZCAM:
402
    """
403
    Compute ZCAM colour appearance model correlates from CIE XYZ tristimulus values.
404

405
    Parameters:
406
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
407
    - XYZ_w: CIE XYZ tristimulus values of reference white
408
    - L_A: adapting field luminance in cd/m²
409
    - Y_b: luminous factor of background
410
    - surround: surround viewing conditions induction factors
411
    - discount_illuminant: whether to discount the illuminant
412

413
    Returns:
414
    CAM_Specification_ZCAM object containing appearance correlates:
415
    - J: lightness correlate
416
    - C: chroma correlate
417
    - h: hue angle in degrees
418
    - s: saturation correlate
419
    - Q: brightness correlate
420
    - M: colourfulness correlate
421
    - H: hue quadrature
422
    - HC: hue composition
423
    - V: vividness correlate
424
    - K: blackness correlate
425
    - W: whiteness correlate
426

427
    Optimized for HDR and wide gamut applications
428
    Domain/Range: [0, 1] for XYZ parameters in Scale - 1 mode
429
    """
430
```
431

432
#### Inverse Transform
433

434
```python { .api }
435
def ZCAM_to_XYZ(
436
    specification: CAM_Specification_ZCAM,
437
    XYZ_w: ArrayLike,
438
    L_A: ArrayLike,
439
    Y_b: ArrayLike,
440
    surround: InductionFactors_ZCAM = VIEWING_CONDITIONS_ZCAM["Average"],
441
    discount_illuminant: bool = False,
442
) -> NDArrayFloat:
443
    """
444
    Convert ZCAM colour appearance specification to CIE XYZ tristimulus values.
445

446
    Parameters:
447
    - specification: ZCAM colour appearance specification
448
    - XYZ_w: CIE XYZ tristimulus values of reference white
449
    - L_A: adapting field luminance in cd/m²
450
    - Y_b: luminous factor of background
451
    - surround: surround viewing conditions induction factors
452
    - discount_illuminant: whether to discount the illuminant
453

454
    Returns:
455
    CIE XYZ tristimulus values
456

457
    Notes:
458
    - Designed for HDR and wide colour gamut imaging
459
    - Enhanced predictions for extreme luminance levels
460
    """
461
```
462

463
#### ZCAM Specification and Induction Factors
464

465
```python { .api }
466
@dataclass
467
class CAM_Specification_ZCAM:
468
    """
469
    ZCAM colour appearance model specification.
470

471
    Attributes:
472
    - J: correlate of lightness
473
    - C: correlate of chroma
474
    - h: hue angle in degrees
475
    - s: correlate of saturation
476
    - Q: correlate of brightness
477
    - M: correlate of colourfulness
478
    - H: hue quadrature
479
    - HC: hue composition
480
    - V: correlate of vividness
481
    - K: correlate of blackness
482
    - W: correlate of whiteness
483
    """
484

485
class InductionFactors_ZCAM:
486
    """
487
    ZCAM colour appearance model induction factors.
488

489
    Parameters:
490
    - F_s: surround impact factor
491
    - F: maximum degree of adaptation
492
    - c: exponential non-linearity
493
    - N_c: chromatic induction factor
494
    """
495

496
# Pre-defined ZCAM viewing conditions
497
VIEWING_CONDITIONS_ZCAM = {
498
    "Average": InductionFactors_ZCAM(0.69, 1, 0.69, 1),
499
    "Dim": InductionFactors_ZCAM(0.59, 0.9, 0.59, 0.9),
500
    "Dark": InductionFactors_ZCAM(0.525, 0.8, 0.525, 0.8),
501
}
502
```
503

504
### LLAB Colour Appearance Model
505

506
The LLAB(l:c) model providing appearance predictions with emphasis on luminance-chroma interactions.
507

508
#### Forward Transform
509

510
```python { .api }
511
def XYZ_to_LLAB(
512
    XYZ: ArrayLike,
513
    XYZ_0: ArrayLike,
514
    Y_b: ArrayLike,
515
    L: ArrayLike,
516
    surround: InductionFactors_LLAB = VIEWING_CONDITIONS_LLAB["Reference"],
517
) -> CAM_Specification_LLAB:
518
    """
519
    Compute LLAB colour appearance model correlates from CIE XYZ tristimulus values.
520

521
    Parameters:
522
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
523
    - XYZ_0: CIE XYZ tristimulus values of reference white
524
    - Y_b: luminance factor of background
525
    - L: absolute luminance of reference white in cd/m²
526
    - surround: surround viewing conditions induction factors
527

528
    Returns:
529
    CAM_Specification_LLAB object containing appearance correlates:
530
    - J: lightness correlate
531
    - C: chroma correlate
532
    - h: hue angle in degrees
533
    - s: saturation correlate
534
    - HC: hue composition
535

536
    Domain/Range: [0, 1] for XYZ parameters in Scale - 1 mode
537
    """
538
```
539

540
#### LLAB Specification and Viewing Conditions
541

542
```python { .api }
543
@dataclass
544
class CAM_Specification_LLAB:
545
    """
546
    LLAB colour appearance model specification.
547

548
    Attributes:
549
    - J: correlate of lightness
550
    - C: correlate of chroma
551
    - h: hue angle in degrees
552
    - s: correlate of saturation
553
    - HC: hue composition
554
    """
555

556
class InductionFactors_LLAB:
557
    """
558
    LLAB colour appearance model induction factors.
559

560
    Parameters for LLAB(l:c) model configuration.
561
    """
562

563
VIEWING_CONDITIONS_LLAB = {
564
    "Reference": InductionFactors_LLAB(...),  # Standard reference conditions
565
}
566
```
567

568
### Additional Appearance Models
569

570
#### ATD95 Model
571

572
```python { .api }
573
def XYZ_to_ATD95(
574
    XYZ: ArrayLike,
575
    XYZ_0: ArrayLike,
576
    Y_0: ArrayLike,
577
    k_1: ArrayLike,
578
    k_2: ArrayLike,
579
    sigma: ArrayLike = 300,
580
) -> CAM_Specification_ATD95:
581
    """
582
    Compute ATD95 colour vision model correlates from CIE XYZ tristimulus values.
583

584
    Parameters:
585
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
586
    - XYZ_0: CIE XYZ tristimulus values of reference white
587
    - Y_0: luminance factor of reference white
588
    - k_1: first-order luminance adaptation factor
589
    - k_2: second-order luminance adaptation factor
590
    - sigma: sigma factor (default: 300)
591

592
    Returns:
593
    CAM_Specification_ATD95 object containing appearance correlates
594

595
    Based on ATD (1995) colour vision model
596
    """
597

598
@dataclass
599
class CAM_Specification_ATD95:
600
    """ATD95 colour vision model specification."""
601
```
602

603
#### Nayatani95 Model
604

605
```python { .api }
606
def XYZ_to_Nayatani95(
607
    XYZ: ArrayLike,
608
    XYZ_n: ArrayLike,
609
    Y_o: ArrayLike,
610
    E_o: ArrayLike,
611
    E_or: ArrayLike,
612
    n: ArrayLike = 1,
613
) -> CAM_Specification_Nayatani95:
614
    """
615
    Compute Nayatani95 colour appearance model correlates from CIE XYZ tristimulus values.
616

617
    Parameters:
618
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus  
619
    - XYZ_n: CIE XYZ tristimulus values of reference white
620
    - Y_o: luminance factor of achromatic background
621
    - E_o: illuminance of the background in lux
622
    - E_or: reference illuminance in lux
623
    - n: noise component factor
624

625
    Returns:
626
    CAM_Specification_Nayatani95 object containing appearance correlates
627

628
    Based on Nayatani (1995) colour appearance model
629
    """
630

631
@dataclass
632
class CAM_Specification_Nayatani95:
633
    """Nayatani95 colour appearance model specification."""
634
```
635

636
#### Kim2009 Model
637

638
```python { .api }
639
def XYZ_to_Kim2009(
640
    XYZ: ArrayLike,
641
    XYZ_w: ArrayLike,
642
    L_A: ArrayLike,
643
    media: MediaParameters_Kim2009 = MEDIA_PARAMETERS_KIM2009["CRT Displays"],
644
) -> CAM_Specification_Kim2009:
645
    """
646
    Compute Kim2009 colour appearance model correlates from CIE XYZ tristimulus values.
647

648
    Parameters:
649
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
650
    - XYZ_w: CIE XYZ tristimulus values of reference white
651
    - L_A: adapting field luminance in cd/m²
652
    - media: media viewing parameters for specific display types
653

654
    Returns:
655
    CAM_Specification_Kim2009 object containing appearance correlates
656

657
    Optimized for cross-media colour reproduction
658
    """
659

660
def Kim2009_to_XYZ(
661
    specification: CAM_Specification_Kim2009,
662
    XYZ_w: ArrayLike,
663
    L_A: ArrayLike,
664
    media: MediaParameters_Kim2009 = MEDIA_PARAMETERS_KIM2009["CRT Displays"],
665
) -> NDArrayFloat:
666
    """Convert Kim2009 colour appearance specification to CIE XYZ tristimulus values."""
667

668
@dataclass
669
class CAM_Specification_Kim2009:
670
    """Kim2009 colour appearance model specification."""
671

672
class MediaParameters_Kim2009:
673
    """Kim2009 media parameters for different display types."""
674

675
MEDIA_PARAMETERS_KIM2009 = {
676
    "CRT Displays": MediaParameters_Kim2009(...),
677
    "LCD Displays": MediaParameters_Kim2009(...),
678
    "Printed Images": MediaParameters_Kim2009(...),
679
}
680
```
681

682
#### Hellwig2022 Model
683

684
```python { .api }
685
def XYZ_to_Hellwig2022(
686
    XYZ: ArrayLike,
687
    XYZ_w: ArrayLike,
688
    L_A: ArrayLike,
689
    Y_b: ArrayLike,
690
    surround: InductionFactors_Hellwig2022 = VIEWING_CONDITIONS_HELLWIG2022["Average"],
691
    discount_illuminant: bool = False,
692
) -> CAM_Specification_Hellwig2022:
693
    """
694
    Compute Hellwig2022 colour appearance model correlates from CIE XYZ tristimulus values.
695

696
    Parameters:
697
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
698
    - XYZ_w: CIE XYZ tristimulus values of reference white
699
    - L_A: adapting field luminance in cd/m²
700
    - Y_b: luminous factor of background
701
    - surround: surround viewing conditions induction factors
702
    - discount_illuminant: whether to discount the illuminant
703

704
    Returns:
705
    CAM_Specification_Hellwig2022 object containing appearance correlates
706

707
    Latest evolution of CIECAM02 with improved predictions
708
    """
709

710
def Hellwig2022_to_XYZ(
711
    specification: CAM_Specification_Hellwig2022,
712
    XYZ_w: ArrayLike,
713
    L_A: ArrayLike,
714
    Y_b: ArrayLike,
715
    surround: InductionFactors_Hellwig2022 = VIEWING_CONDITIONS_HELLWIG2022["Average"],
716
    discount_illuminant: bool = False,
717
) -> NDArrayFloat:
718
    """Convert Hellwig2022 colour appearance specification to CIE XYZ tristimulus values."""
719

720
@dataclass
721
class CAM_Specification_Hellwig2022:
722
    """Hellwig2022 colour appearance model specification."""
723

724
class InductionFactors_Hellwig2022:
725
    """Hellwig2022 colour appearance model induction factors."""
726

727
VIEWING_CONDITIONS_HELLWIG2022 = {
728
    "Average": InductionFactors_Hellwig2022(...),
729
    "Dim": InductionFactors_Hellwig2022(...),
730
    "Dark": InductionFactors_Hellwig2022(...),
731
}
732
```
733

734
#### CIECAM16 Model
735

736
```python { .api }
737
def XYZ_to_CIECAM16(
738
    XYZ: ArrayLike,
739
    XYZ_w: ArrayLike,
740
    L_A: ArrayLike,
741
    Y_b: ArrayLike,
742
    surround: InductionFactors_CIECAM16 = VIEWING_CONDITIONS_CIECAM16["Average"],
743
    discount_illuminant: bool = False,
744
) -> CAM_Specification_CIECAM16:
745
    """
746
    Compute CIECAM16 colour appearance model correlates from CIE XYZ tristimulus values.
747

748
    Parameters:
749
    - XYZ: CIE XYZ tristimulus values of test sample/stimulus
750
    - XYZ_w: CIE XYZ tristimulus values of reference white  
751
    - L_A: adapting field luminance in cd/m²
752
    - Y_b: luminous factor of background
753
    - surround: surround viewing conditions induction factors
754
    - discount_illuminant: whether to discount the illuminant
755

756
    Returns:
757
    CAM_Specification_CIECAM16 object containing appearance correlates
758

759
    Alternative formulation of CIECAM02 with different constants
760
    """
761

762
def CIECAM16_to_XYZ(
763
    specification: CAM_Specification_CIECAM16,
764
    XYZ_w: ArrayLike,
765
    L_A: ArrayLike,
766
    Y_b: ArrayLike,
767
    surround: InductionFactors_CIECAM16 = VIEWING_CONDITIONS_CIECAM16["Average"],
768
    discount_illuminant: bool = False,
769
) -> NDArrayFloat:
770
    """Convert CIECAM16 colour appearance specification to CIE XYZ tristimulus values."""
771

772
@dataclass
773
class CAM_Specification_CIECAM16:
774
    """CIECAM16 colour appearance model specification."""
775

776
class InductionFactors_CIECAM16:
777
    """CIECAM16 colour appearance model induction factors."""
778

779
VIEWING_CONDITIONS_CIECAM16 = {
780
    "Average": InductionFactors_CIECAM16(...),
781
    "Dim": InductionFactors_CIECAM16(...),
782
    "Dark": InductionFactors_CIECAM16(...),
783
}
784
```
785

786
### Helmholtz-Kohlrausch Effect
787

788
Functions for computing the Helmholtz-Kohlrausch effect, which describes the increase in perceived brightness of chromatic stimuli compared to achromatic stimuli of equal luminance.
789

790
#### HKE for Object Colours
791

792
```python { .api }
793
def HelmholtzKohlrausch_effect_object_Nayatani1997(
794
    uv: ArrayLike,
795
    uv_c: ArrayLike,
796
    L_a: ArrayLike,
797
    method: Literal["VAC", "VCC"] = "VCC",
798
) -> NDArrayFloat:
799
    """
800
    Compute HKE value for object colours using Nayatani (1997) method.
801

802
    Parameters:
803
    - uv: CIE uv chromaticity coordinates of samples
804
    - uv_c: CIE uv chromaticity coordinates of reference white
805
    - L_a: adapting luminance in cd/m²
806
    - method: estimation method ("VCC" or "VAC")
807
        - "VCC": Variable Chromatic Colour method
808
        - "VAC": Variable Achromatic Colour method
809

810
    Returns:
811
    Luminance factor (Γ) values computed with Nayatani object colour estimation
812

813
    The HKE quantifies how chromatic colours appear brighter than 
814
    achromatic colours at the same luminance level.
815
    """
816
```
817

818
#### HKE for Luminous Colours
819

820
```python { .api }
821
def HelmholtzKohlrausch_effect_luminous_Nayatani1997(
822
    uv: ArrayLike,
823
    uv_c: ArrayLike,
824
    L_a: ArrayLike,
825
) -> NDArrayFloat:
826
    """
827
    Compute HKE value for luminous colours using Nayatani (1997) method.
828

829
    Parameters:
830
    - uv: CIE uv chromaticity coordinates of samples
831
    - uv_c: CIE uv chromaticity coordinates of reference white
832
    - L_a: adapting luminance in cd/m²
833

834
    Returns:
835
    Luminance factor values for luminous colour HKE estimation
836

837
    Specialized for self-luminous stimuli like displays and light sources.
838
    """
839
```
840

841
#### HKE Coefficient Functions
842

843
```python { .api }
844
def coefficient_q_Nayatani1997(
845
    uv: ArrayLike,
846
    uv_c: ArrayLike,
847
) -> NDArrayFloat:
848
    """
849
    Calculate q coefficient for Nayatani 1997 HKE estimation.
850

851
    Parameters:
852
    - uv: CIE uv chromaticity coordinates of samples
853
    - uv_c: CIE uv chromaticity coordinates of reference white
854

855
    Returns:
856
    q coefficient values used in HKE calculations
857
    """
858

859
def coefficient_K_Br_Nayatani1997(
860
    uv: ArrayLike,
861
    uv_c: ArrayLike,
862
    method: Literal["VAC", "VCC"] = "VCC",
863
) -> NDArrayFloat:
864
    """
865
    Calculate K_Br coefficient for Nayatani 1997 HKE estimation.
866

867
    Parameters:
868
    - uv: CIE uv chromaticity coordinates of samples
869
    - uv_c: CIE uv chromaticity coordinates of reference white
870
    - method: estimation method ("VCC" or "VAC")
871

872
    Returns:
873
    K_Br coefficient values used in HKE calculations
874
    """
875

876
# HKE method constants
877
HKE_NAYATANI1997_METHODS = {
878
    "VAC": -0.1340,  # Variable Achromatic Colour
879
    "VCC": -0.8660,  # Variable Chromatic Colour
880
}
881
```
882

883
## Usage Examples
884

885
### Basic CIECAM02 Usage
886

887
```python
888
import numpy as np
889
import colour
890

891
# Test sample (sRGB red converted to XYZ)
892
XYZ = np.array([0.20654008, 0.12197225, 0.01136952])
893
# D65 whitepoint
894
XYZ_w = colour.CCS_ILLUMINANTS['CIE 1931 2 Degree Standard Observer']['D65']
895
# Typical viewing conditions
896
L_A = 318.31  # cd/m²
897
Y_b = 20.0    # %
898

899
# Compute appearance correlates
900
specification = colour.XYZ_to_CIECAM02(XYZ, XYZ_w, L_A, Y_b)
901
print(f"Lightness: {specification.J:.2f}")
902
print(f"Chroma: {specification.C:.2f}")  
903
print(f"Hue: {specification.h:.2f}°")
904

905
# Convert back to XYZ
906
XYZ_recovered = colour.CIECAM02_to_XYZ(specification, XYZ_w, L_A, Y_b)
907
```
908

909
### Comparing Multiple Appearance Models
910

911
```python
912
# Compare predictions across models
913
models = {
914
    'CIECAM02': colour.XYZ_to_CIECAM02,
915
    'CAM16': colour.XYZ_to_CAM16,
916
    'Hunt': lambda XYZ, XYZ_w, L_A, Y_b: colour.XYZ_to_Hunt(
917
        XYZ, XYZ_w, XYZ_w * 0.2, L_A  # Assuming background = 20% of white
918
    ),
919
    'ZCAM': colour.XYZ_to_ZCAM,
920
}
921

922
for name, func in models.items():
923
    try:
924
        spec = func(XYZ, XYZ_w, L_A, Y_b)
925
        print(f"{name}: J={spec.J:.1f}, C={spec.C:.1f}, h={spec.h:.1f}")
926
    except Exception as e:
927
        print(f"{name}: Error - {e}")
928
```
929

930
### HKE Effect Demonstration
931

932
```python
933
# Demonstrate Helmholtz-Kohlrausch effect
934
uv_red = np.array([0.4507, 0.5229])  # Red chromaticity
935
uv_white = np.array([0.1978, 0.4683])  # White chromaticity  
936
L_a = 100  # cd/m²
937

938
# Compare VCC and VAC methods
939
hke_vcc = colour.HelmholtzKohlrausch_effect_object_Nayatani1997(
940
    uv_red, uv_white, L_a, method="VCC"
941
)
942
hke_vac = colour.HelmholtzKohlrausch_effect_object_Nayatani1997(
943
    uv_red, uv_white, L_a, method="VAC"
944
)
945

946
print(f"HKE (VCC method): {hke_vcc:.3f}")
947
print(f"HKE (VAC method): {hke_vac:.3f}")
948
```
949

950
### Custom Viewing Conditions
951

952
```python
953
# Define custom viewing conditions
954
from colour.appearance import InductionFactors_CIECAM02
955

956
custom_surround = InductionFactors_CIECAM02(
957
    F=0.95,   # Slightly reduced adaptation
958
    c=0.65,   # Modified exponential non-linearity
959
    N_c=0.95  # Reduced chromatic induction
960
)
961

962
# Use custom conditions
963
specification = colour.XYZ_to_CIECAM02(
964
    XYZ, XYZ_w, L_A, Y_b, 
965
    surround=custom_surround,
966
    discount_illuminant=True
967
)
968
```
969

970
## Key Concepts
971

972
### Viewing Conditions
973
- **Adapting Luminance (L_A)**: Environmental luminance affecting adaptation state
974
- **Background Factor (Y_b)**: Relative luminance of the immediate background
975
- **Surround Conditions**: Environmental factors affecting appearance perception
976

977
### Appearance Correlates
978
- **Lightness (J)**: Perceived lightness relative to white
979
- **Brightness (Q)**: Absolute brightness perception
980
- **Chroma (C)**: Colorfulness relative to brightness of white
981
- **Colourfulness (M)**: Absolute colorfulness perception
982
- **Saturation (s)**: Colorfulness relative to brightness of stimulus
983
- **Hue Angle (h)**: Angular position in colour space
984
- **Hue Quadrature (H)**: Perceptual hue categories (Red, Yellow, Green, Blue)
985

986
### Model Selection Guidelines
987
- **CIECAM02**: Industry standard, well-validated, recommended for most applications
988
- **CAM16**: Improved version of CIECAM02, better for certain conditions
989
- **Hunt**: Most comprehensive model, includes many perceptual effects
990
- **ZCAM**: Optimized for HDR and wide gamut applications
991
- **RLAB**: Simplified model for cross-media applications
992
- **LLAB**: Specialized for luminance-chroma interactions