0
# Colour Models and Space Conversions
1

2
Comprehensive colour space conversion functions covering CIE standards, RGB models, advanced perceptual models, and automatic conversions between any supported colour spaces.
3

4
## Capabilities
5

6
### Universal Colour Space Conversion
7

8
The main entry point for automatic colour space conversion using an intelligent graph-based system.
9

10
```python { .api }
11
def convert(a: ArrayLike, source: str, target: str, **kwargs) -> NDArray:
12
    """
13
    Convert colour data between any supported colour spaces using automatic path finding.
14
    
15
    Parameters:
16
    - a: colour data array to convert
17
    - source: source colour space (e.g., 'XYZ', 'sRGB', 'Lab', 'Oklab')
18
    - target: target colour space (e.g., 'XYZ', 'sRGB', 'Lab', 'Oklab') 
19
    - **kwargs: additional parameters for specific conversions (illuminant, colourspace, etc.)
20
    
21
    Returns:
22
    Converted colour data in target colour space
23
    
24
    Supported Colour Spaces:
25
    - CIE: XYZ, xyY, Lab, Luv, UCS, UVW
26
    - RGB: sRGB, Adobe RGB, Rec.2020, ACES, ProPhoto, DCI-P3, etc.
27
    - Advanced: Jzazbz, Oklab, CAM16, IPT, OSA-UCS
28
    - Polar: LCHab, LCHuv, HSV, HSL, HCL
29
    - Video: YCbCr, YCoCg, ICtCp
30
    """
31

32
def describe_conversion_path(source: str, target: str) -> str:
33
    """
34
    Describe the automatic conversion path between two colour spaces.
35
    
36
    Parameters:
37
    - source: source colour space name
38
    - target: target colour space name
39
    
40
    Returns:
41
    Human-readable description of conversion steps
42
    """
43
```
44

45
### CIE Standard Colour Spaces
46

47
Core CIE colour space transformations forming the foundation for colour science computations.
48

49
```python { .api }
50
def XYZ_to_Lab(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
51
    """
52
    Convert CIE XYZ tristimulus values to CIE L*a*b* colour space.
53
    
54
    Parameters:
55
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
56
    - illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
57
    
58
    Returns:
59
    CIE L*a*b* colour space array, shape (..., 3)
60
    
61
    Notes:
62
    L* ranges [0, 100], a* and b* range approximately [-100, 100]
63
    """
64

65
def Lab_to_XYZ(Lab: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
66
    """
67
    Convert CIE L*a*b* colour space to CIE XYZ tristimulus values.
68
    
69
    Parameters:
70
    - Lab: CIE L*a*b* colour space array, shape (..., 3)
71
    - illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
72
    
73
    Returns:
74
    CIE XYZ tristimulus values, shape (..., 3)
75
    """
76

77
def XYZ_to_Luv(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
78
    """
79
    Convert CIE XYZ tristimulus values to CIE L*u*v* colour space.
80
    
81
    Parameters:
82
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
83
    - illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
84
    
85
    Returns:
86
    CIE L*u*v* colour space array, shape (..., 3)
87
    """
88

89
def Luv_to_XYZ(Luv: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
90
    """
91
    Convert CIE L*u*v* colour space to CIE XYZ tristimulus values.
92
    
93
    Parameters:
94
    - Luv: CIE L*u*v* colour space array, shape (..., 3)
95
    - illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
96
    
97
    Returns:
98
    CIE XYZ tristimulus values, shape (..., 3)
99
    """
100

101
def XYZ_to_xyY(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
102
    """
103
    Convert CIE XYZ tristimulus values to CIE xyY colour space.
104
    
105
    Parameters:
106
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
107
    - illuminant: reference illuminant for handling zero luminance cases
108
    
109
    Returns:
110
    CIE xyY colour space array, shape (..., 3)
111
    
112
    Notes:
113
    x, y are chromaticity coordinates [0, 1], Y is luminance [0, 1]
114
    """
115

116
def xyY_to_XYZ(xyY: ArrayLike) -> NDArray:
117
    """
118
    Convert CIE xyY colour space to CIE XYZ tristimulus values.
119
    
120
    Parameters:
121
    - xyY: CIE xyY colour space array, shape (..., 3)
122
    
123
    Returns:
124
    CIE XYZ tristimulus values, shape (..., 3)
125
    """
126

127
def XYZ_to_xy(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
128
    """
129
    Convert CIE XYZ tristimulus values to CIE xy chromaticity coordinates.
130
    
131
    Parameters:
132
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
133
    - illuminant: reference illuminant for handling zero luminance cases
134
    
135
    Returns:
136
    CIE xy chromaticity coordinates, shape (..., 2)
137
    """
138

139
def xy_to_XYZ(xy: ArrayLike) -> NDArray:
140
    """
141
    Convert CIE xy chromaticity coordinates to CIE XYZ tristimulus values.
142
    Assumes Y = 1 for the conversion.
143
    
144
    Parameters:
145
    - xy: CIE xy chromaticity coordinates, shape (..., 2)
146
    
147
    Returns:
148
    CIE XYZ tristimulus values with Y=1, shape (..., 3)
149
    """
150
```
151

152
### CIE Uniform Colour Spaces
153

154
Legacy CIE uniform colour space transformations.
155

156
```python { .api }
157
def XYZ_to_UVW(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
158
    """
159
    Convert CIE XYZ tristimulus values to CIE 1964 U*V*W* colour space.
160
    
161
    Parameters:
162
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
163
    - illuminant: reference illuminant CIE xy chromaticity coordinates
164
    
165
    Returns:
166
    CIE 1964 U*V*W* colour space array, shape (..., 3)
167
    """
168

169
def UVW_to_XYZ(UVW: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
170
    """
171
    Convert CIE 1964 U*V*W* colour space to CIE XYZ tristimulus values.
172
    
173
    Parameters:
174
    - UVW: CIE 1964 U*V*W* colour space array, shape (..., 3)
175
    - illuminant: reference illuminant CIE xy chromaticity coordinates
176
    
177
    Returns:
178
    CIE XYZ tristimulus values, shape (..., 3)
179
    """
180

181
def XYZ_to_CIE1960UCS(XYZ: ArrayLike) -> NDArray:
182
    """
183
    Convert CIE XYZ tristimulus values to CIE 1960 UCS colour space.
184
    
185
    Parameters:
186
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
187
    
188
    Returns:
189
    CIE 1960 UCS colour space array, shape (..., 3)
190
    """
191

192
def CIE1960UCS_to_XYZ(UCS: ArrayLike) -> NDArray:
193
    """
194
    Convert CIE 1960 UCS colour space to CIE XYZ tristimulus values.
195
    
196
    Parameters:
197
    - UCS: CIE 1960 UCS colour space array, shape (..., 3)
198
    
199
    Returns:
200
    CIE XYZ tristimulus values, shape (..., 3)
201
    """
202

203
def XYZ_to_CIE1976UCS(XYZ: ArrayLike) -> NDArray:
204
    """
205
    Convert CIE XYZ tristimulus values to CIE 1976 UCS colour space.
206
    
207
    Parameters:
208
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
209
    
210
    Returns:
211
    CIE 1976 UCS colour space array, shape (..., 3)
212
    """
213

214
def CIE1976UCS_to_XYZ(UCS: ArrayLike) -> NDArray:
215
    """
216
    Convert CIE 1976 UCS colour space to CIE XYZ tristimulus values.
217
    
218
    Parameters:
219
    - UCS: CIE 1976 UCS colour space array, shape (..., 3)
220
    
221
    Returns:
222
    CIE XYZ tristimulus values, shape (..., 3)
223
    """
224
```
225

226
### RGB Colour Spaces and Models
227

228
Comprehensive RGB colour space support with device-dependent transformations.
229

230
```python { .api }
231
class RGB_Colourspace:
232
    """
233
    RGB colour space definition with primaries, whitepoint, and transfer functions.
234
    
235
    Parameters:
236
    - name: colour space name
237
    - primaries: RGB primaries as CIE xy chromaticity coordinates, shape (3, 2)
238
    - whitepoint: whitepoint CIE xy chromaticity coordinates, shape (2,)
239
    - whitepoint_name: optional whitepoint name
240
    - matrix_RGB_to_XYZ: transformation matrix from RGB to XYZ, shape (3, 3)
241
    - matrix_XYZ_to_RGB: transformation matrix from XYZ to RGB, shape (3, 3)
242
    - cctf_encoding: colour component transfer function (gamma encoding)
243
    - cctf_decoding: inverse colour component transfer function (gamma decoding)
244
    """
245
    def __init__(self, name: str, primaries: ArrayLike, whitepoint: ArrayLike, whitepoint_name: str = None, 
246
                 matrix_RGB_to_XYZ: ArrayLike = None, matrix_XYZ_to_RGB: ArrayLike = None,
247
                 cctf_encoding: Callable = None, cctf_decoding: Callable = None): ...
248

249
def RGB_to_XYZ(RGB: ArrayLike, colourspace: Union[RGB_Colourspace, str] = RGB_COLOURSPACE_sRGB, 
250
               illuminant: ArrayLike = None, chromatic_adaptation_transform: str = "CAT02",
251
               apply_cctf_decoding: bool = False) -> NDArray:
252
    """
253
    Convert RGB values to CIE XYZ tristimulus values.
254
    
255
    Parameters:
256
    - RGB: RGB colour array, shape (..., 3)
257
    - colourspace: RGB colour space or name (e.g., 'sRGB', 'Adobe RGB (1998)', 'Rec. 2020')
258
    - illuminant: target illuminant for chromatic adaptation
259
    - chromatic_adaptation_transform: chromatic adaptation method ('CAT02', 'Bradford', etc.)
260
    - apply_cctf_decoding: whether to apply gamma decoding before conversion
261
    
262
    Returns:
263
    CIE XYZ tristimulus values, shape (..., 3)
264
    """
265

266
def XYZ_to_RGB(XYZ: ArrayLike, colourspace: Union[RGB_Colourspace, str] = RGB_COLOURSPACE_sRGB,
267
               illuminant: ArrayLike = None, chromatic_adaptation_transform: str = "CAT02",
268
               apply_cctf_encoding: bool = False) -> NDArray:
269
    """
270
    Convert CIE XYZ tristimulus values to RGB values.
271
    
272
    Parameters:
273
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
274
    - colourspace: RGB colour space or name (e.g., 'sRGB', 'Adobe RGB (1998)', 'Rec. 2020')
275
    - illuminant: source illuminant for chromatic adaptation
276
    - chromatic_adaptation_transform: chromatic adaptation method ('CAT02', 'Bradford', etc.)
277
    - apply_cctf_encoding: whether to apply gamma encoding after conversion
278
    
279
    Returns:
280
    RGB colour array, shape (..., 3)
281
    """
282

283
def RGB_to_RGB(RGB: ArrayLike, input_colourspace: Union[RGB_Colourspace, str],
284
               output_colourspace: Union[RGB_Colourspace, str],
285
               chromatic_adaptation_transform: str = "CAT02") -> NDArray:
286
    """
287
    Convert RGB values between different RGB colour spaces.
288
    
289
    Parameters:
290
    - RGB: RGB colour array in input colourspace, shape (..., 3)
291
    - input_colourspace: source RGB colour space
292
    - output_colourspace: target RGB colour space
293
    - chromatic_adaptation_transform: chromatic adaptation method
294
    
295
    Returns:
296
    RGB colour array in output colourspace, shape (..., 3)
297
    """
298

299
# Common RGB colour space constants
300
RGB_COLOURSPACE_sRGB: RGB_Colourspace
301
RGB_COLOURSPACE_ADOBE_RGB1998: RGB_Colourspace  
302
RGB_COLOURSPACE_REC_2020: RGB_Colourspace
303
RGB_COLOURSPACE_DCI_P3: RGB_Colourspace
304
RGB_COLOURSPACE_DISPLAY_P3: RGB_Colourspace
305
RGB_COLOURSPACE_PROPHOTO_RGB: RGB_Colourspace
306
RGB_COLOURSPACE_ACES2065_1: RGB_Colourspace
307
RGB_COLOURSPACE_ACESCG: RGB_Colourspace
308
RGB_COLOURSPACE_BT709: RGB_Colourspace
309
RGB_COLOURSPACE_BT2020: RGB_Colourspace
310
```
311

312
### RGB Cylindrical Representations
313

314
Convert between RGB and cylindrical colour representations.
315

316
```python { .api }
317
def RGB_to_HSV(RGB: ArrayLike) -> NDArray:
318
    """
319
    Convert RGB values to HSV (Hue, Saturation, Value) colour space.
320
    
321
    Parameters:
322
    - RGB: RGB colour array, shape (..., 3), values in [0, 1]
323
    
324
    Returns:
325
    HSV colour array, shape (..., 3)
326
    H in [0, 360], S in [0, 1], V in [0, 1]
327
    """
328

329
def HSV_to_RGB(HSV: ArrayLike) -> NDArray:
330
    """
331
    Convert HSV (Hue, Saturation, Value) values to RGB colour space.
332
    
333
    Parameters:
334
    - HSV: HSV colour array, shape (..., 3)
335
      H in [0, 360], S in [0, 1], V in [0, 1]
336
    
337
    Returns:
338
    RGB colour array, shape (..., 3), values in [0, 1]
339
    """
340

341
def RGB_to_HSL(RGB: ArrayLike) -> NDArray:
342
    """
343
    Convert RGB values to HSL (Hue, Saturation, Lightness) colour space.
344
    
345
    Parameters:
346
    - RGB: RGB colour array, shape (..., 3), values in [0, 1]
347
    
348
    Returns:
349
    HSL colour array, shape (..., 3)
350
    H in [0, 360], S in [0, 1], L in [0, 1]
351
    """
352

353
def HSL_to_RGB(HSL: ArrayLike) -> NDArray:
354
    """
355
    Convert HSL (Hue, Saturation, Lightness) values to RGB colour space.
356
    
357
    Parameters:
358
    - HSL: HSL colour array, shape (..., 3)
359
      H in [0, 360], S in [0, 1], L in [0, 1]
360
    
361
    Returns:
362
    RGB colour array, shape (..., 3), values in [0, 1]
363
    """
364

365
def RGB_to_HCL(RGB: ArrayLike) -> NDArray:
366
    """
367
    Convert RGB values to HCL (Hue, Chroma, Luma) colour space.
368
    
369
    Parameters:
370
    - RGB: RGB colour array, shape (..., 3), values in [0, 1]
371
    
372
    Returns:
373
    HCL colour array, shape (..., 3)
374
    """
375

376
def HCL_to_RGB(HCL: ArrayLike) -> NDArray:
377
    """
378
    Convert HCL (Hue, Chroma, Luma) values to RGB colour space.
379
    
380
    Parameters:
381
    - HCL: HCL colour array, shape (..., 3)
382
    
383
    Returns:
384
    RGB colour array, shape (..., 3), values in [0, 1]
385
    """
386
```
387

388
### Advanced Perceptual Colour Models
389

390
Modern colour models designed for perceptual uniformity and wide gamut applications.
391

392
```python { .api }
393
def XYZ_to_Oklab(XYZ: ArrayLike) -> NDArray:
394
    """
395
    Convert CIE XYZ tristimulus values to Oklab colour space.
396
    
397
    Oklab is a perceptually uniform colour space designed for image processing
398
    with better performance than CIE Lab for wide gamut and HDR applications.
399
    
400
    Parameters:
401
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
402
    
403
    Returns:
404
    Oklab colour space array, shape (..., 3)
405
    L in [0, 1], a and b approximately [-0.5, 0.5]
406
    """
407

408
def Oklab_to_XYZ(Oklab: ArrayLike) -> NDArray:
409
    """
410
    Convert Oklab colour space to CIE XYZ tristimulus values.
411
    
412
    Parameters:
413
    - Oklab: Oklab colour space array, shape (..., 3)
414
    
415
    Returns:
416
    CIE XYZ tristimulus values, shape (..., 3)
417
    """
418

419
def XYZ_to_Jzazbz(XYZ: ArrayLike, method: str = "Safdar 2017") -> NDArray:
420
    """
421
    Convert CIE XYZ tristimulus values to Jzazbz colour space.
422
    
423
    Jzazbz is designed for high dynamic range (HDR) and wide colour gamut applications,
424
    providing better perceptual uniformity than CIE Lab in these contexts.
425
    
426
    Parameters:
427
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
428
    - method: computational method ('Safdar 2017')
429
    
430
    Returns:
431
    Jzazbz colour space array, shape (..., 3)
432
    """
433

434
def Jzazbz_to_XYZ(Jzazbz: ArrayLike, method: str = "Safdar 2017") -> NDArray:
435
    """
436
    Convert Jzazbz colour space to CIE XYZ tristimulus values.
437
    
438
    Parameters:
439
    - Jzazbz: Jzazbz colour space array, shape (..., 3)
440
    - method: computational method ('Safdar 2017')
441
    
442
    Returns:
443
    CIE XYZ tristimulus values, shape (..., 3)
444
    """
445

446
def XYZ_to_IPT(XYZ: ArrayLike) -> NDArray:
447
    """
448
    Convert CIE XYZ tristimulus values to IPT colour space.
449
    
450
    IPT colour space designed for better hue constancy and perceptual uniformity.
451
    
452
    Parameters:
453
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
454
    
455
    Returns:
456
    IPT colour space array, shape (..., 3)
457
    """
458

459
def IPT_to_XYZ(IPT: ArrayLike) -> NDArray:
460
    """
461
    Convert IPT colour space to CIE XYZ tristimulus values.
462
    
463
    Parameters:
464
    - IPT: IPT colour space array, shape (..., 3)
465
    
466
    Returns:
467
    CIE XYZ tristimulus values, shape (..., 3)
468
    """
469

470
def XYZ_to_OSA_UCS(XYZ: ArrayLike) -> NDArray:
471
    """
472
    Convert CIE XYZ tristimulus values to OSA-UCS colour space.
473
    
474
    Parameters:
475
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
476
    
477
    Returns:
478
    OSA-UCS colour space array (L, j, g), shape (..., 3)
479
    """
480

481
def OSA_UCS_to_XYZ(OSA_UCS: ArrayLike) -> NDArray:
482
    """
483
    Convert OSA-UCS colour space to CIE XYZ tristimulus values.
484
    
485
    Parameters:
486
    - OSA_UCS: OSA-UCS colour space array (L, j, g), shape (..., 3)
487
    
488
    Returns:
489
    CIE XYZ tristimulus values, shape (..., 3)
490
    """
491
```
492

493
### CAM16 Colour Appearance Model
494

495
Convert between XYZ and CAM16 uniform colour spaces designed for colour appearance applications.
496

497
```python { .api }
498
def XYZ_to_CAM16UCS(XYZ: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
499
    """
500
    Convert CIE XYZ tristimulus values to CAM16-UCS colour space.
501
    
502
    Parameters:
503
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
504
    - coefficients: CAM16 viewing conditions coefficients
505
    
506
    Returns:
507
    CAM16-UCS colour space array, shape (..., 3)
508
    """
509

510
def CAM16UCS_to_XYZ(UCS: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
511
    """
512
    Convert CAM16-UCS colour space to CIE XYZ tristimulus values.
513
    
514
    Parameters:
515
    - UCS: CAM16-UCS colour space array, shape (..., 3)
516
    - coefficients: CAM16 viewing conditions coefficients
517
    
518
    Returns:
519
    CIE XYZ tristimulus values, shape (..., 3)
520
    """
521

522
def XYZ_to_CAM16LCD(XYZ: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
523
    """
524
    Convert CIE XYZ tristimulus values to CAM16-LCD colour space.
525
    
526
    Parameters:
527
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
528
    - coefficients: CAM16 viewing conditions coefficients
529
    
530
    Returns:
531
    CAM16-LCD colour space array, shape (..., 3)
532
    """
533

534
def CAM16LCD_to_XYZ(LCD: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
535
    """
536
    Convert CAM16-LCD colour space to CIE XYZ tristimulus values.
537
    
538
    Parameters:
539
    - LCD: CAM16-LCD colour space array, shape (..., 3)
540
    - coefficients: CAM16 viewing conditions coefficients
541
    
542
    Returns:
543
    CIE XYZ tristimulus values, shape (..., 3)
544
    """
545

546
def XYZ_to_CAM16SCD(XYZ: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
547
    """
548
    Convert CIE XYZ tristimulus values to CAM16-SCD colour space.
549
    
550
    Parameters:
551
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
552
    - coefficients: CAM16 viewing conditions coefficients
553
    
554
    Returns:
555
    CAM16-SCD colour space array, shape (..., 3)
556
    """
557

558
def CAM16SCD_to_XYZ(SCD: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
559
    """
560
    Convert CAM16-SCD colour space to CIE XYZ tristimulus values.
561
    
562
    Parameters:
563
    - SCD: CAM16-SCD colour space array, shape (..., 3)
564
    - coefficients: CAM16 viewing conditions coefficients
565
    
566
    Returns:
567
    CIE XYZ tristimulus values, shape (..., 3)
568
    """
569
```
570

571
### Polar Coordinate Conversions
572

573
Convert between Cartesian and polar representations of various colour spaces.
574

575
```python { .api }
576
def Lab_to_LCHab(Lab: ArrayLike) -> NDArray:
577
    """
578
    Convert CIE L*a*b* to CIE L*C*H*ab polar representation.
579
    
580
    Parameters:
581
    - Lab: CIE L*a*b* colour space array, shape (..., 3)
582
    
583
    Returns:
584
    CIE L*C*H*ab polar coordinates, shape (..., 3)
585
    L* [0, 100], C*ab [0, 100+], H*ab [0, 360]
586
    """
587

588
def LCHab_to_Lab(LCHab: ArrayLike) -> NDArray:
589
    """
590
    Convert CIE L*C*H*ab polar coordinates to CIE L*a*b*.
591
    
592
    Parameters:
593
    - LCHab: CIE L*C*H*ab polar coordinates, shape (..., 3)
594
    
595
    Returns:
596
    CIE L*a*b* colour space array, shape (..., 3)
597
    """
598

599
def Luv_to_LCHuv(Luv: ArrayLike) -> NDArray:
600
    """
601
    Convert CIE L*u*v* to CIE L*C*H*uv polar representation.
602
    
603
    Parameters:
604
    - Luv: CIE L*u*v* colour space array, shape (..., 3)
605
    
606
    Returns:
607
    CIE L*C*H*uv polar coordinates, shape (..., 3)
608
    """
609

610
def LCHuv_to_Luv(LCHuv: ArrayLike) -> NDArray:
611
    """
612
    Convert CIE L*C*H*uv polar coordinates to CIE L*u*v*.
613
    
614
    Parameters:
615
    - LCHuv: CIE L*C*H*uv polar coordinates, shape (..., 3)
616
    
617
    Returns:
618
    CIE L*u*v* colour space array, shape (..., 3)
619
    """
620

621
def Oklab_to_Oklch(Oklab: ArrayLike) -> NDArray:
622
    """
623
    Convert Oklab to Oklch polar representation.
624
    
625
    Parameters:
626
    - Oklab: Oklab colour space array, shape (..., 3)
627
    
628
    Returns:
629
    Oklch polar coordinates, shape (..., 3)
630
    L [0, 1], C [0, 0.5+], h [0, 360]
631
    """
632

633
def Oklch_to_Oklab(Oklch: ArrayLike) -> NDArray:
634
    """
635
    Convert Oklch polar coordinates to Oklab.
636
    
637
    Parameters:
638
    - Oklch: Oklch polar coordinates, shape (..., 3)
639
    
640
    Returns:
641
    Oklab colour space array, shape (..., 3)
642
    """
643

644
def Jzazbz_to_JzCHab(Jzazbz: ArrayLike) -> NDArray:
645
    """
646
    Convert Jzazbz to JzCHab polar representation.
647
    
648
    Parameters:
649
    - Jzazbz: Jzazbz colour space array, shape (..., 3)
650
    
651
    Returns:
652
    JzCHab polar coordinates, shape (..., 3)
653
    """
654

655
def JzCHab_to_Jzazbz(JzCHab: ArrayLike) -> NDArray:
656
    """
657
    Convert JzCHab polar coordinates to Jzazbz.
658
    
659
    Parameters:
660
    - JzCHab: JzCHab polar coordinates, shape (..., 3)
661
    
662
    Returns:
663
    Jzazbz colour space array, shape (..., 3)
664
    """
665

666
def IPT_to_ICH(IPT: ArrayLike) -> NDArray:
667
    """
668
    Convert IPT to ICH polar representation.
669
    
670
    Parameters:
671
    - IPT: IPT colour space array, shape (..., 3)
672
    
673
    Returns:
674
    ICH polar coordinates, shape (..., 3)
675
    """
676

677
def ICH_to_IPT(ICH: ArrayLike) -> NDArray:
678
    """
679
    Convert ICH polar coordinates to IPT.
680
    
681
    Parameters:
682
    - ICH: ICH polar coordinates, shape (..., 3)
683
    
684
    Returns:
685
    IPT colour space array, shape (..., 3)
686
    """
687
```
688

689
### Video and Digital Imaging Colour Spaces
690

691
Colour spaces commonly used in video production and digital imaging.
692

693
```python { .api }
694
def RGB_to_YCbCr(RGB: ArrayLike, K: ArrayLike = WEIGHTS_YCBCR["ITU-R BT.709"], 
695
                 in_bits: int = 10, in_legal: bool = False, in_int: bool = False,
696
                 out_bits: int = 10, out_legal: bool = False, out_int: bool = False) -> NDArray:
697
    """
698
    Convert RGB values to YCbCr colour space.
699
    
700
    Parameters:
701
    - RGB: RGB colour array, shape (..., 3)
702
    - K: luma coefficients (ITU-R BT.601, BT.709, BT.2020, etc.)
703
    - in_bits: input bit depth
704
    - in_legal: whether input uses legal range
705
    - in_int: whether input is integer
706
    - out_bits: output bit depth  
707
    - out_legal: whether output uses legal range
708
    - out_int: whether output is integer
709
    
710
    Returns:
711
    YCbCr colour array, shape (..., 3)
712
    """
713

714
def YCbCr_to_RGB(YCbCr: ArrayLike, K: ArrayLike = WEIGHTS_YCBCR["ITU-R BT.709"],
715
                 in_bits: int = 10, in_legal: bool = False, in_int: bool = False,
716
                 out_bits: int = 10, out_legal: bool = False, out_int: bool = False) -> NDArray:
717
    """
718
    Convert YCbCr colour space to RGB values.
719
    
720
    Parameters:
721
    - YCbCr: YCbCr colour array, shape (..., 3)
722
    - K: luma coefficients
723
    - in_bits: input bit depth
724
    - in_legal: whether input uses legal range
725
    - in_int: whether input is integer
726
    - out_bits: output bit depth
727
    - out_legal: whether output uses legal range  
728
    - out_int: whether output is integer
729
    
730
    Returns:
731
    RGB colour array, shape (..., 3)
732
    """
733

734
def RGB_to_YCoCg(RGB: ArrayLike) -> NDArray:
735
    """
736
    Convert RGB values to YCoCg colour space.
737
    
738
    Parameters:
739
    - RGB: RGB colour array, shape (..., 3)
740
    
741
    Returns:
742
    YCoCg colour array, shape (..., 3)
743
    """
744

745
def YCoCg_to_RGB(YCoCg: ArrayLike) -> NDArray:
746
    """
747
    Convert YCoCg colour space to RGB values.
748
    
749
    Parameters:
750
    - YCoCg: YCoCg colour array, shape (..., 3)
751
    
752
    Returns:
753
    RGB colour array, shape (..., 3)
754
    """
755

756
def XYZ_to_ICtCp(XYZ: ArrayLike) -> NDArray:
757
    """
758
    Convert CIE XYZ tristimulus values to ICtCp colour space.
759
    
760
    ICtCp is designed for HDR and wide colour gamut content.
761
    
762
    Parameters:
763
    - XYZ: CIE XYZ tristimulus values, shape (..., 3)
764
    
765
    Returns:
766
    ICtCp colour space array, shape (..., 3)
767
    """
768

769
def ICtCp_to_XYZ(ICtCp: ArrayLike) -> NDArray:
770
    """
771
    Convert ICtCp colour space to CIE XYZ tristimulus values.
772
    
773
    Parameters:
774
    - ICtCp: ICtCp colour space array, shape (..., 3)
775
    
776
    Returns:
777
    CIE XYZ tristimulus values, shape (..., 3)
778
    """
779
```
780

781
### Transfer Functions
782

783
Gamma correction and other transfer functions for colour encoding/decoding.
784

785
```python { .api }
786
def eotf_sRGB(V: ArrayLike) -> NDArray:
787
    """
788
    Apply sRGB electro-optical transfer function (gamma decoding).
789
    
790
    Parameters:
791
    - V: electrical signal values, shape (...,)
792
    
793
    Returns:
794
    Optical signal values (linear light), shape (...,)
795
    """
796

797
def eotf_inverse_sRGB(L: ArrayLike) -> NDArray:
798
    """
799
    Apply inverse sRGB electro-optical transfer function (gamma encoding).
800
    
801
    Parameters:
802
    - L: optical signal values (linear light), shape (...,)
803
    
804
    Returns:
805
    Electrical signal values, shape (...,)
806
    """
807

808
def oetf_BT709(L: ArrayLike) -> NDArray:
809
    """
810
    Apply ITU-R BT.709 opto-electronic transfer function.
811
    
812
    Parameters:
813
    - L: optical signal values, shape (...,)
814
    
815
    Returns:
816
    Electrical signal values, shape (...,)
817
    """
818

819
def oetf_inverse_BT709(V: ArrayLike) -> NDArray:
820
    """
821
    Apply inverse ITU-R BT.709 opto-electronic transfer function.
822
    
823
    Parameters:
824
    - V: electrical signal values, shape (...,)
825
    
826
    Returns:
827
    Optical signal values, shape (...,)
828
    """
829

830
def oetf_BT2020(L: ArrayLike) -> NDArray:
831
    """
832
    Apply ITU-R BT.2020 opto-electronic transfer function.
833
    
834
    Parameters:
835
    - L: optical signal values, shape (...,)
836
    
837
    Returns:
838
    Electrical signal values, shape (...,)
839
    """
840

841
def oetf_inverse_BT2020(V: ArrayLike) -> NDArray:
842
    """
843
    Apply inverse ITU-R BT.2020 opto-electronic transfer function.
844
    
845
    Parameters:
846
    - V: electrical signal values, shape (...,)
847
    
848
    Returns:
849
    Optical signal values, shape (...,)
850
    """
851

852
def eotf_ST2084(N: ArrayLike) -> NDArray:
853
    """
854
    Apply SMPTE ST 2084 electro-optical transfer function (Perceptual Quantizer).
855
    
856
    Parameters:
857
    - N: non-linear signal values, shape (...,)
858
    
859
    Returns:
860
    Optical signal values (cd/m²), shape (...,)
861
    """
862

863
def eotf_inverse_ST2084(L: ArrayLike) -> NDArray:
864
    """
865
    Apply inverse SMPTE ST 2084 electro-optical transfer function.
866
    
867
    Parameters:
868
    - L: optical signal values (cd/m²), shape (...,)
869
    
870
    Returns:
871
    Non-linear signal values, shape (...,)
872
    """
873
```
874

875
## Usage Examples
876

877
### Basic Colour Space Conversions
878

879
```python
880
import numpy as np
881
import colour
882

883
# Convert sRGB to CIE Lab via automatic conversion
884
rgb = np.array([0.5, 0.3, 0.8])
885
lab = colour.convert(rgb, 'sRGB', 'Lab')
886
print(f"sRGB {rgb} -> Lab {lab}")
887

888
# Convert using specific functions  
889
xyz = colour.sRGB_to_XYZ(rgb)
890
lab_direct = colour.XYZ_to_Lab(xyz)
891
print(f"Direct: Lab {lab_direct}")
892

893
# Convert to modern perceptual spaces
894
oklab = colour.convert(rgb, 'sRGB', 'Oklab')
895
jzazbz = colour.convert(rgb, 'sRGB', 'Jzazbz')
896
print(f"Oklab: {oklab}")
897
print(f"Jzazbz: {jzazbz}")
898
```
899

900
### RGB Colour Space Transformations
901

902
```python
903
# Convert between different RGB colour spaces
904
srgb = np.array([0.5, 0.3, 0.8])
905

906
# Convert sRGB to Adobe RGB (1998)
907
adobe_rgb = colour.RGB_to_RGB(
908
    srgb, 
909
    colour.RGB_COLOURSPACE_sRGB,
910
    colour.RGB_COLOURSPACE_ADOBE_RGB1998
911
)
912

913
# Convert sRGB to Rec. 2020 for HDR content
914
rec2020 = colour.RGB_to_RGB(
915
    srgb,
916
    colour.RGB_COLOURSPACE_sRGB, 
917
    colour.RGB_COLOURSPACE_BT2020
918
)
919

920
print(f"sRGB: {srgb}")
921
print(f"Adobe RGB: {adobe_rgb}")
922
print(f"Rec. 2020: {rec2020}")
923
```
924

925
### Cylindrical Colour Representations
926

927
```python
928
# Convert RGB to HSV for colour manipulation
929
rgb = np.array([0.8, 0.2, 0.4])
930
hsv = colour.RGB_to_HSV(rgb)
931
print(f"RGB {rgb} -> HSV {hsv}")
932

933
# Modify hue and convert back
934
hsv_modified = hsv.copy()
935
hsv_modified[0] = (hsv_modified[0] + 60) % 360  # Shift hue by 60 degrees
936
rgb_modified = colour.HSV_to_RGB(hsv_modified)
937
print(f"Modified RGB: {rgb_modified}")
938

939
# Polar coordinate representations for perceptual uniformity
940
lab = colour.convert(rgb, 'sRGB', 'Lab')
941
lchab = colour.Lab_to_LCHab(lab)
942
print(f"Lab {lab} -> LCHab {lchab}")
943

944
oklab = colour.convert(rgb, 'sRGB', 'Oklab') 
945
oklch = colour.Oklab_to_Oklch(oklab)
946
print(f"Oklab {oklab} -> Oklch {oklch}")
947
```
948

949
### Advanced Colour Space Applications
950

951
```python
952
# HDR-capable colour space conversions
953
hdr_rgb = np.array([2.0, 1.5, 0.8])  # HDR values > 1.0
954

955
# Use Jzazbz for HDR content
956
jzazbz = colour.convert(hdr_rgb, 'BT2020', 'Jzazbz')
957
print(f"HDR RGB -> Jzazbz: {jzazbz}")
958

959
# Convert to ICtCp for video processing
960
ictcp = colour.convert(hdr_rgb, 'BT2020', 'ICtCp')  
961
print(f"HDR RGB -> ICtCp: {ictcp}")
962

963
# Wide gamut colour space handling
964
wide_gamut_rgb = np.array([0.9, -0.1, 0.7])  # Out-of-sRGB-gamut colour
965
p3_rgb = colour.convert(wide_gamut_rgb, 'BT2020', 'Display P3')
966
print(f"BT2020 -> Display P3: {p3_rgb}")
967
```
968

969
### Automatic Conversion Path Analysis
970

971
```python
972
# Understand conversion paths
973
path = colour.describe_conversion_path('sRGB', 'Oklab')
974
print("sRGB to Oklab conversion path:")
975
print(path)
976

977
# Multiple conversion paths available
978
path_cam16 = colour.describe_conversion_path('Lab', 'CAM16UCS')
979
print("\nLab to CAM16UCS conversion path:")
980
print(path_cam16)
981
```