0
# Plotting and Visualization
1

2
Comprehensive plotting and visualization functions for creating scientific colour plots, chromaticity diagrams, spectral distributions, quality assessments, and colour space visualizations.
3

4
## Capabilities
5

6
The plotting module provides over 150 specialized plotting functions organized into distinct categories:
7

8
- **Common plotting utilities** - Basic colour swatches, functions, and image rendering
9
- **Chromaticity diagrams** - CIE 1931, 1960 UCS, and 1976 UCS diagrams with spectral locus
10
- **Spectral distribution plots** - Single/multi-spectral data visualization
11
- **Colour matching functions** - CMF and illuminant plotting
12
- **Quality assessment plots** - CRI, CQS, and TM-30 visualizations  
13
- **RGB colourspace gamuts** - 3D gamut volumes and scatter plots
14
- **Colour appearance plots** - CAM16, CIECAM02 appearance model visualizations
15
- **Temperature and daylight locus** - Planckian locus and daylight plots
16
- **Advanced visualizations** - Section plots, constant hue loci, MacAdam ellipses
17

18
## Core Classes
19

20
### ColourSwatch
21

22
Data structure for representing colour patches with optional naming.
23

24
```python { .api }
25
@dataclass
26
class ColourSwatch:
27
    """
28
    Colour swatch representation for plotting.
29
    
30
    Parameters:
31
    - RGB: RGB colour values (ArrayLike)
32
    - name: Optional colour name for labeling (str | None)
33
    
34
    Examples:
35
    >>> swatch = ColourSwatch((0.45, 0.31, 0.04), name="Custom Orange")
36
    >>> plot_single_colour_swatch(swatch)
37
    """
38
    RGB: ArrayLike
39
    name: str | None = None
40
```
41

42
## Common Plotting Functions
43

44
### Basic Colour Visualization
45

46
Core functions for plotting colour swatches and basic visualizations.
47

48
```python { .api }
49
def plot_single_colour_swatch(
50
    colour_swatch: ArrayLike | ColourSwatch, 
51
    **kwargs: Any
52
) -> Tuple[Figure, Axes]:
53
    """
54
    Plot a single colour swatch.
55
    
56
    Parameters:
57
    - colour_swatch: Colour data as ArrayLike or ColourSwatch instance
58
    - **kwargs: Additional plotting parameters
59
    
60
    Returns:
61
    Tuple of matplotlib Figure and Axes objects
62
    
63
    Examples:
64
    >>> RGB = ColourSwatch((0.456, 0.031, 0.041))
65
    >>> plot_single_colour_swatch(RGB)
66
    """
67

68
def plot_multi_colour_swatches(
69
    colour_swatches: Sequence[ArrayLike | ColourSwatch],
70
    width: float = 1,
71
    height: float = 1,
72
    spacing: float = 0,
73
    columns: int | None = None,
74
    direction: Literal["+y", "-y"] | str = "+y",
75
    text_kwargs: dict | None = None,
76
    background_colour: ArrayLike = (1.0, 1.0, 1.0),
77
    compare_swatches: Literal["Diagonal", "Stacked"] | str | None = None,
78
    **kwargs: Any
79
) -> Tuple[Figure, Axes]:
80
    """
81
    Plot multiple colour swatches in a grid layout.
82
    
83
    Parameters:
84
    - colour_swatches: Sequence of colour data or ColourSwatch instances
85
    - width: Individual swatch width (default: 1)
86
    - height: Individual swatch height (default: 1)
87
    - spacing: Spacing between swatches (default: 0)
88
    - columns: Number of columns, auto-calculated if None
89
    - direction: Row stacking direction ("+y" or "-y")
90
    - text_kwargs: Text styling parameters
91
    - background_colour: Background colour for the plot
92
    - compare_swatches: Comparison mode ("Diagonal" or "Stacked")
93
    - **kwargs: Additional plotting parameters
94
    
95
    Returns:
96
    Tuple of matplotlib Figure and Axes objects
97
    """
98

99
def plot_image(
100
    image: ArrayLike,
101
    text_kwargs: dict | None = None,
102
    **kwargs: Any
103
) -> Tuple[Figure, Axes]:
104
    """
105
    Plot given image with optional text overlay.
106
    
107
    Parameters:
108
    - image: Image array to display
109
    - text_kwargs: Text overlay styling parameters
110
    - **kwargs: Additional plotting parameters
111
    
112
    Returns:
113
    Tuple of matplotlib Figure and Axes objects
114
    """
115
```
116

117
### Function and Data Plotting
118

119
```python { .api }
120
def plot_single_function(
121
    function: Callable,
122
    samples: ArrayLike | None = None,
123
    **kwargs: Any
124
) -> Tuple[Figure, Axes]:
125
    """
126
    Plot a single mathematical function.
127
    
128
    Parameters:
129
    - function: Callable function to plot
130
    - samples: Sample points for function evaluation
131
    - **kwargs: Additional plotting parameters
132
    
133
    Returns:
134
    Tuple of matplotlib Figure and Axes objects
135
    """
136

137
def plot_multi_functions(
138
    functions: Sequence[Callable],
139
    samples: ArrayLike | None = None,
140
    **kwargs: Any
141
) -> Tuple[Figure, Axes]:
142
    """
143
    Plot multiple mathematical functions on the same axes.
144
    
145
    Parameters:
146
    - functions: Sequence of callable functions
147
    - samples: Sample points for function evaluation  
148
    - **kwargs: Additional plotting parameters
149
    
150
    Returns:
151
    Tuple of matplotlib Figure and Axes objects
152
    """
153
```
154

155
## Chromaticity Diagrams
156

157
### CIE Standard Diagrams
158

159
Core CIE chromaticity diagrams with spectral locus and colour gamut visualization.
160

161
```python { .api }
162
def plot_chromaticity_diagram_CIE1931(
163
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
164
    show_diagram_colours: bool = True,
165
    show_spectral_locus: bool = True,
166
    **kwargs: Any
167
) -> Tuple[Figure, Axes]:
168
    """
169
    Plot the CIE 1931 Chromaticity Diagram.
170
    
171
    Parameters:
172
    - cmfs: Colour matching functions for spectral locus computation
173
    - show_diagram_colours: Display background chromaticity colours
174
    - show_spectral_locus: Display the spectral locus boundary
175
    - **kwargs: Additional plotting parameters
176
    
177
    Returns:
178
    Tuple of matplotlib Figure and Axes objects
179
    
180
    Features:
181
    - Accurate spectral locus from 380-780nm
182
    - Colour-filled background showing all visible colours
183
    - Wavelength labels along spectral locus
184
    - Standard illuminants and colour spaces can be overlaid
185
    """
186

187
def plot_chromaticity_diagram_CIE1960UCS(
188
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
189
    show_diagram_colours: bool = True,
190
    show_spectral_locus: bool = True,
191
    **kwargs: Any
192
) -> Tuple[Figure, Axes]:
193
    """
194
    Plot the CIE 1960 UCS Chromaticity Diagram.
195
    
196
    Parameters:
197
    - cmfs: Colour matching functions for spectral locus computation
198
    - show_diagram_colours: Display background chromaticity colours
199
    - show_spectral_locus: Display the spectral locus boundary
200
    - **kwargs: Additional plotting parameters
201
    
202
    Returns:
203
    Tuple of matplotlib Figure and Axes objects
204
    
205
    Features:
206
    - More perceptually uniform than CIE 1931
207
    - Used for correlated colour temperature calculations
208
    - Better spacing for colour difference evaluations
209
    """
210

211
def plot_chromaticity_diagram_CIE1976UCS(
212
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer", 
213
    show_diagram_colours: bool = True,
214
    show_spectral_locus: bool = True,
215
    **kwargs: Any
216
) -> Tuple[Figure, Axes]:
217
    """
218
    Plot the CIE 1976 UCS (u', v') Chromaticity Diagram.
219
    
220
    Parameters:
221
    - cmfs: Colour matching functions for spectral locus computation
222
    - show_diagram_colours: Display background chromaticity colours
223
    - show_spectral_locus: Display the spectral locus boundary
224
    - **kwargs: Additional plotting parameters
225
    
226
    Returns:
227
    Tuple of matplotlib Figure and Axes objects
228
    
229
    Features:
230
    - Most perceptually uniform CIE chromaticity diagram
231
    - Foundation for CIELUV colour space
232
    - Preferred for modern colour difference calculations
233
    """
234
```
235

236
### Spectral Distribution Overlays
237

238
```python { .api }
239
def plot_sds_in_chromaticity_diagram_CIE1931(
240
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
241
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
242
    annotate_kwargs: dict | None = None,
243
    chromaticity_diagram_callable: Callable = plot_chromaticity_diagram_CIE1931,
244
    **kwargs: Any
245
) -> Tuple[Figure, Axes]:
246
    """
247
    Plot spectral distributions in CIE 1931 chromaticity diagram.
248
    
249
    Parameters:
250
    - sds: Spectral distributions to plot as points
251
    - cmfs: Colour matching functions for chromaticity calculation
252
    - annotate_kwargs: Annotation styling parameters
253
    - chromaticity_diagram_callable: Base diagram plotting function
254
    - **kwargs: Additional plotting parameters
255
    
256
    Returns:
257
    Tuple of matplotlib Figure and Axes objects
258
    
259
    Use Cases:
260
    - Visualizing illuminant chromaticity coordinates
261
    - Comparing LED or other light source colours
262
    - Quality control of lighting products
263
    """
264

265
def plot_sds_in_chromaticity_diagram_CIE1960UCS(
266
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
267
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
268
    annotate_kwargs: dict | None = None,
269
    chromaticity_diagram_callable: Callable = plot_chromaticity_diagram_CIE1960UCS,
270
    **kwargs: Any
271
) -> Tuple[Figure, Axes]:
272
    """
273
    Plot spectral distributions in CIE 1960 UCS chromaticity diagram.
274
    
275
    Parameters:
276
    - sds: Spectral distributions to plot as points
277
    - cmfs: Colour matching functions for chromaticity calculation  
278
    - annotate_kwargs: Annotation styling parameters
279
    - chromaticity_diagram_callable: Base diagram plotting function
280
    - **kwargs: Additional plotting parameters
281
    
282
    Returns:
283
    Tuple of matplotlib Figure and Axes objects
284
    """
285

286
def plot_sds_in_chromaticity_diagram_CIE1976UCS(
287
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
288
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
289
    annotate_kwargs: dict | None = None, 
290
    chromaticity_diagram_callable: Callable = plot_chromaticity_diagram_CIE1976UCS,
291
    **kwargs: Any
292
) -> Tuple[Figure, Axes]:
293
    """
294
    Plot spectral distributions in CIE 1976 UCS chromaticity diagram.
295
    
296
    Parameters:
297
    - sds: Spectral distributions to plot as points
298
    - cmfs: Colour matching functions for chromaticity calculation
299
    - annotate_kwargs: Annotation styling parameters
300
    - chromaticity_diagram_callable: Base diagram plotting function
301
    - **kwargs: Additional plotting parameters
302
    
303
    Returns:
304
    Tuple of matplotlib Figure and Axes objects
305
    """
306
```
307

308
## Spectral Distribution Plotting
309

310
### Single and Multi-Spectral Plots
311

312
```python { .api }
313
def plot_single_sd(
314
    sd: SpectralDistribution,
315
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
316
    out_of_gamut_clipping: bool = True,
317
    modulate_colours_with_sd_amplitude: bool = False,
318
    equalize_sd_amplitude: bool = False,
319
    **kwargs: Any
320
) -> Tuple[Figure, Axes]:
321
    """
322
    Plot a single spectral distribution with colour representation.
323
    
324
    Parameters:
325
    - sd: Spectral distribution to plot
326
    - cmfs: Colour matching functions for colour computation
327
    - out_of_gamut_clipping: Clip out-of-gamut colours vs. gray background
328
    - modulate_colours_with_sd_amplitude: Modulate colours by amplitude
329
    - equalize_sd_amplitude: Normalize amplitude for uniform colour display
330
    - **kwargs: Additional plotting parameters
331
    
332
    Returns:
333
    Tuple of matplotlib Figure and Axes objects
334
    
335
    Features:
336
    - Spectrum coloured by wavelength-dependent hues
337
    - Amplitude modulation options for realistic appearance
338
    - Out-of-gamut handling for accurate colour rendering
339
    - Supports reflectance, transmittance, and emission spectra
340
    """
341

342
def plot_multi_sds(
343
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
344
    plot_kwargs: Sequence[dict] | None = None,
345
    **kwargs: Any
346
) -> Tuple[Figure, Axes]:
347
    """
348
    Plot multiple spectral distributions on the same axes.
349
    
350
    Parameters:
351
    - sds: Sequence of spectral distributions to plot
352
    - plot_kwargs: Individual styling parameters for each spectrum
353
    - **kwargs: Additional plotting parameters
354
    
355
    Returns:
356
    Tuple of matplotlib Figure and Axes objects
357
    
358
    Use Cases:
359
    - Comparing multiple illuminants or LEDs
360
    - Visualizing before/after spectral corrections
361
    - Material characterization studies
362
    """
363

364
def plot_visible_spectrum(
365
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
366
    out_of_gamut_clipping: bool = True,
367
    **kwargs: Any
368
) -> Tuple[Figure, Axes]:
369
    """
370
    Plot the visible spectrum as a continuous colour bar.
371
    
372
    Parameters:
373
    - cmfs: Colour matching functions defining visible range
374
    - out_of_gamut_clipping: Clip out-of-gamut colours vs. desaturate
375
    - **kwargs: Additional plotting parameters
376
    
377
    Returns:
378
    Tuple of matplotlib Figure and Axes objects
379
    
380
    Features:
381
    - Pure spectral colours from ~380-780nm
382
    - Accurate representation of human colour vision
383
    - Educational tool for wavelength-colour relationships
384
    """
385
```
386

387
### Colour Matching Functions
388

389
```python { .api }
390
def plot_single_cmfs(
391
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str],
392
    **kwargs: Any
393
) -> Tuple[Figure, Axes]:
394
    """
395
    Plot colour matching functions (CMFs) showing tristimulus responses.
396
    
397
    Parameters:
398
    - cmfs: Colour matching functions to plot
399
    - **kwargs: Additional plotting parameters
400
    
401
    Returns:
402
    Tuple of matplotlib Figure and Axes objects
403
    
404
    Features:
405
    - X, Y, Z tristimulus curves
406
    - Standard observer data (2°, 10°)
407
    - Fundamental response functions
408
    """
409

410
def plot_multi_cmfs(
411
    cmfs: Sequence[MultiSpectralDistributions | str],
412
    **kwargs: Any
413
) -> Tuple[Figure, Axes]:
414
    """
415
    Plot multiple colour matching functions for comparison.
416
    
417
    Parameters:
418
    - cmfs: Sequence of colour matching functions
419
    - **kwargs: Additional plotting parameters
420
    
421
    Returns:
422
    Tuple of matplotlib Figure and Axes objects
423
    
424
    Use Cases:
425
    - Comparing 2° vs 10° standard observers
426
    - Visualizing individual differences in colour vision
427
    - Research into alternative colour matching functions
428
    """
429
```
430

431
### Illuminant Plotting
432

433
```python { .api }
434
def plot_single_illuminant_sd(
435
    illuminant: SpectralDistribution | str,
436
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
437
    **kwargs: Any
438
) -> Tuple[Figure, Axes]:
439
    """
440
    Plot a single illuminant spectral distribution.
441
    
442
    Parameters:
443
    - illuminant: Illuminant spectral distribution or name
444
    - cmfs: Colour matching functions for colour computation
445
    - **kwargs: Additional plotting parameters
446
    
447
    Returns:
448
    Tuple of matplotlib Figure and Axes objects
449
    
450
    Supported Illuminants:
451
    - Standard illuminants (A, D50, D65, E)
452
    - Fluorescent series (F1-F12) 
453
    - LED and specialty sources
454
    """
455

456
def plot_multi_illuminant_sds(
457
    illuminants: Sequence[SpectralDistribution | str],
458
    **kwargs: Any
459
) -> Tuple[Figure, Axes]:
460
    """
461
    Plot multiple illuminant spectral distributions.
462
    
463
    Parameters:
464
    - illuminants: Sequence of illuminant distributions or names
465
    - **kwargs: Additional plotting parameters
466
    
467
    Returns:
468
    Tuple of matplotlib Figure and Axes objects
469
    """
470
```
471

472
### Blackbody and Planckian Radiation
473

474
```python { .api }
475
def plot_blackbody_spectral_radiance(
476
    temperature: ArrayLike,
477
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
478
    blackbody: SpectralDistribution | None = None,
479
    **kwargs: Any
480
) -> Tuple[Figure, Axes]:
481
    """
482
    Plot blackbody spectral radiance for given temperature(s).
483
    
484
    Parameters:
485
    - temperature: Blackbody temperature(s) in Kelvin
486
    - cmfs: Colour matching functions for visible range
487
    - blackbody: Optional pre-computed blackbody distribution
488
    - **kwargs: Additional plotting parameters
489
    
490
    Returns:
491
    Tuple of matplotlib Figure and Axes objects
492
    
493
    Applications:
494
    - Thermal radiation visualization
495
    - Colour temperature understanding
496
    - Planck's law demonstration
497
    """
498

499
def plot_blackbody_colours(
500
    shape: SpectralShape,
501
    **kwargs: Any
502
) -> Tuple[Figure, Axes]:
503
    """
504
    Plot blackbody colours across temperature range.
505
    
506
    Parameters:
507
    - shape: Spectral shape defining temperature range and resolution
508
    - **kwargs: Additional plotting parameters
509
    
510
    Returns:
511
    Tuple of matplotlib Figure and Axes objects
512
    
513
    Features:
514
    - Continuous colour progression with temperature
515
    - Visualization of correlated colour temperature
516
    - Educational tool for thermal radiation colour
517
    """
518
```
519

520
## Quality Assessment Plotting
521

522
### Colour Rendering Index (CRI)
523

524
```python { .api }
525
def plot_single_sd_colour_rendering_index_bars(
526
    sd: SpectralDistribution | str,
527
    **kwargs: Any
528
) -> Tuple[Figure, Axes]:
529
    """
530
    Plot colour rendering index (CRI) bars for a single illuminant.
531
    
532
    Parameters:
533
    - sd: Spectral distribution or illuminant name
534
    - **kwargs: Additional plotting parameters
535
    
536
    Returns:
537
    Tuple of matplotlib Figure and Axes objects
538
    
539
    Features:
540
    - CRI for 14 test colour samples (TCS01-TCS14)
541
    - Overall Ra value prominently displayed
542
    - Individual sample colour fidelity scores
543
    - Standard CRI calculation methodology
544
    """
545

546
def plot_multi_sds_colour_rendering_indexes_bars(
547
    sds: Sequence[SpectralDistribution | str],
548
    **kwargs: Any
549
) -> Tuple[Figure, Axes]:
550
    """
551
    Plot CRI comparison bars for multiple illuminants.
552
    
553
    Parameters:
554
    - sds: Sequence of spectral distributions or illuminant names
555
    - **kwargs: Additional plotting parameters
556
    
557
    Returns:
558
    Tuple of matplotlib Figure and Axes objects
559
    
560
    Use Cases:
561
    - LED product comparisons
562
    - Illuminant quality assessment
563
    - Lighting design validation
564
    """
565
```
566

567
### Colour Quality Scale (CQS)
568

569
```python { .api }
570
def plot_single_sd_colour_quality_scale_bars(
571
    sd: SpectralDistribution | str,
572
    **kwargs: Any
573
) -> Tuple[Figure, Axes]:
574
    """
575
    Plot colour quality scale (CQS) bars for a single illuminant.
576
    
577
    Parameters:
578
    - sd: Spectral distribution or illuminant name
579
    - **kwargs: Additional plotting parameters
580
    
581
    Returns:
582
    Tuple of matplotlib Figure and Axes objects
583
    
584
    Features:
585
    - Modern alternative to CRI with better LED performance
586
    - Improved colour samples and calculation methods
587
    - Enhanced correlation with visual assessments
588
    """
589

590
def plot_multi_sds_colour_quality_scales_bars(
591
    sds: Sequence[SpectralDistribution | str],
592
    **kwargs: Any
593
) -> Tuple[Figure, Axes]:
594
    """
595
    Plot CQS comparison bars for multiple illuminants.
596
    
597
    Parameters:
598
    - sds: Sequence of spectral distributions or illuminant names  
599
    - **kwargs: Additional plotting parameters
600
    
601
    Returns:
602
    Tuple of matplotlib Figure and Axes objects
603
    """
604
```
605

606
### TM-30 Colour Rendition Reports
607

608
```python { .api }
609
def plot_single_sd_colour_rendition_report(
610
    sd: SpectralDistribution | str,
611
    report_type: Literal["Full", "Intermediate", "Simple"] | str = "Full",
612
    **kwargs: Any
613
) -> Tuple[Figure, Axes]:
614
    """
615
    Generate comprehensive TM-30 colour rendition report.
616
    
617
    Parameters:
618
    - sd: Spectral distribution or illuminant name
619
    - report_type: Detail level ("Full", "Intermediate", "Simple")
620
    - **kwargs: Additional plotting parameters
621
    
622
    Returns:
623
    Tuple of matplotlib Figure and Axes objects
624
    
625
    Report Components:
626
    - Colour fidelity index (Rf) and colour gamut index (Rg)
627
    - 16-bin colour fidelity and gamut area charts  
628
    - Local chroma and hue shift visualizations
629
    - Spectral power distribution with colour rendition
630
    - Vector graphics showing colour accuracy
631
    
632
    Standards Compliance:
633
    - ANSI/IES TM-30-18 methodology
634
    - Professional lighting industry standard
635
    - Comprehensive illuminant characterization
636
    """
637
```
638

639
## RGB Colourspace Visualization
640

641
### Gamut Plotting
642

643
```python { .api }
644
def plot_RGB_colourspaces_gamuts(
645
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
646
    segments: int = 8,
647
    show_grid: bool = True,
648
    grid_segments: int = 10,
649
    show_spectral_locus: bool = False,
650
    spectral_locus_colour: ArrayLike | None = None,
651
    points: ArrayLike | None = None,
652
    points_colours: ArrayLike | None = None,
653
    **kwargs: Any
654
) -> Tuple[Figure, Axes3D]:
655
    """
656
    Plot 3D gamut volumes for RGB colourspaces.
657
    
658
    Parameters:
659
    - colourspaces: RGB colourspaces to visualize
660
    - segments: Gamut surface tessellation detail
661
    - show_grid: Display coordinate grid
662
    - grid_segments: Grid line density
663
    - show_spectral_locus: Include spectral locus boundary
664
    - spectral_locus_colour: Spectral locus line colour
665
    - points: Additional points to plot
666
    - points_colours: Point colours
667
    - **kwargs: Additional plotting parameters
668
    
669
    Returns:
670
    Tuple of matplotlib Figure and 3D Axes objects
671
    
672
    Colourspace Support:
673
    - sRGB, Adobe RGB, ProPhoto RGB
674
    - Rec.2020, DCI-P3, ACES
675
    - Custom colourspaces via RGB_Colourspace
676
    
677
    Features:
678
    - Interactive 3D navigation
679
    - Transparent gamut surfaces
680
    - Comparative volume analysis
681
    - Spectral locus reference
682
    """
683

684
def plot_RGB_scatter(
685
    RGB: ArrayLike,
686
    colourspace: RGB_Colourspace | LiteralRGBColourspace | str = "sRGB",
687
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str] | None = None,
688
    segments: int = 8,
689
    show_grid: bool = True,
690
    grid_segments: int = 10,
691
    **kwargs: Any
692
) -> Tuple[Figure, Axes3D]:
693
    """
694
    Plot RGB colour data as 3D scatter points within gamut boundaries.
695
    
696
    Parameters:
697
    - RGB: RGB colour data array
698
    - colourspace: Primary colourspace for the data
699
    - colourspaces: Additional colourspace gamuts to show
700
    - segments: Gamut surface tessellation detail
701
    - show_grid: Display coordinate grid
702
    - grid_segments: Grid line density  
703
    - **kwargs: Additional plotting parameters
704
    
705
    Returns:
706
    Tuple of matplotlib Figure and 3D Axes objects
707
    
708
    Applications:
709
    - Colour distribution analysis
710
    - Gamut utilization studies  
711
    - Out-of-gamut detection
712
    - Colour grading visualization
713
    """
714
```
715

716
### Chromaticity Gamut Plots
717

718
```python { .api }
719
def plot_RGB_colourspaces_in_chromaticity_diagram_CIE1931(
720
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
721
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
722
    show_whitepoints: bool = True,
723
    show_pointer_gamut: bool = False,
724
    **kwargs: Any
725
) -> Tuple[Figure, Axes]:
726
    """
727
    Plot RGB colourspace gamuts in CIE 1931 chromaticity diagram.
728
    
729
    Parameters:
730
    - colourspaces: RGB colourspaces to plot
731
    - cmfs: Colour matching functions
732
    - show_whitepoints: Display whitepoint markers
733
    - show_pointer_gamut: Include Pointer's gamut reference
734
    - **kwargs: Additional plotting parameters
735
    
736
    Returns:
737
    Tuple of matplotlib Figure and Axes objects
738
    
739
    Features:
740
    - Triangular gamut boundaries
741
    - Primary and secondary colour vertices
742
    - Whitepoint locations
743
    - Relative gamut size comparison
744
    """
745

746
def plot_RGB_colourspaces_in_chromaticity_diagram_CIE1960UCS(
747
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
748
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
749
    show_whitepoints: bool = True,
750
    show_pointer_gamut: bool = False,
751
    **kwargs: Any
752
) -> Tuple[Figure, Axes]:
753
    """
754
    Plot RGB colourspace gamuts in CIE 1960 UCS chromaticity diagram.
755
    
756
    Parameters:
757
    - colourspaces: RGB colourspaces to plot
758
    - cmfs: Colour matching functions
759
    - show_whitepoints: Display whitepoint markers
760
    - show_pointer_gamut: Include Pointer's gamut reference
761
    - **kwargs: Additional plotting parameters
762
    
763
    Returns:
764
    Tuple of matplotlib Figure and Axes objects
765
    """
766

767
def plot_RGB_colourspaces_in_chromaticity_diagram_CIE1976UCS(
768
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
769
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer", 
770
    show_whitepoints: bool = True,
771
    show_pointer_gamut: bool = False,
772
    **kwargs: Any
773
) -> Tuple[Figure, Axes]:
774
    """
775
    Plot RGB colourspace gamuts in CIE 1976 UCS chromaticity diagram.
776
    
777
    Parameters:
778
    - colourspaces: RGB colourspaces to plot
779
    - cmfs: Colour matching functions
780
    - show_whitepoints: Display whitepoint markers  
781
    - show_pointer_gamut: Include Pointer's gamut reference
782
    - **kwargs: Additional plotting parameters
783
    
784
    Returns:
785
    Tuple of matplotlib Figure and Axes objects
786
    """
787
```
788

789
### Pointer's Gamut
790

791
```python { .api }
792
def plot_pointer_gamut(
793
    method: Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"] | str = "CIE 1931",
794
    **kwargs: Any
795
) -> Tuple[Figure, Axes]:
796
    """
797
    Plot Pointer's gamut representing real surface colours.
798
    
799
    Parameters:
800
    - method: Chromaticity diagram type
801
    - **kwargs: Additional plotting parameters
802
    
803
    Returns:
804
    Tuple of matplotlib Figure and Axes objects
805
    
806
    Background:
807
    - Represents colours of real surface materials
808
    - Benchmark for display and printer gamuts
809
    - Based on Munsell colour measurements
810
    - Standard reference in colour science
811
    """
812
```
813

814
## Temperature and Daylight
815

816
### Planckian Locus
817

818
```python { .api }
819
def plot_planckian_locus_in_chromaticity_diagram_CIE1931(
820
    illuminants: Sequence[str] | None = None,
821
    **kwargs: Any
822
) -> Tuple[Figure, Axes]:
823
    """
824
    Plot Planckian locus in CIE 1931 chromaticity diagram.
825
    
826
    Parameters:
827
    - illuminants: Specific illuminants to highlight
828
    - **kwargs: Additional plotting parameters
829
    
830
    Returns:
831
    Tuple of matplotlib Figure and Axes objects
832
    
833
    Features:
834
    - Blackbody radiation locus from 1000K to 100000K
835
    - Temperature tick marks at standard intervals
836
    - Isothermal lines for correlated colour temperature
837
    - Standard illuminant positions
838
    """
839

840
def plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
841
    illuminants: Sequence[str] | None = None,
842
    **kwargs: Any
843
) -> Tuple[Figure, Axes]:
844
    """
845
    Plot Planckian locus in CIE 1960 UCS chromaticity diagram.
846
    
847
    Parameters:
848
    - illuminants: Specific illuminants to highlight
849
    - **kwargs: Additional plotting parameters
850
    
851
    Returns:
852
    Tuple of matplotlib Figure and Axes objects
853
    
854
    Applications:
855
    - Correlated colour temperature calculations
856
    - Daylight and artificial light analysis
857
    - White balance evaluation
858
    """
859

860
def plot_planckian_locus_in_chromaticity_diagram_CIE1976UCS(
861
    illuminants: Sequence[str] | None = None,
862
    **kwargs: Any
863
) -> Tuple[Figure, Axes]:
864
    """
865
    Plot Planckian locus in CIE 1976 UCS chromaticity diagram.
866
    
867
    Parameters:
868
    - illuminants: Specific illuminants to highlight
869
    - **kwargs: Additional plotting parameters
870
    
871
    Returns:
872
    Tuple of matplotlib Figure and Axes objects
873
    """
874
```
875

876
## Advanced Visualizations
877

878
### MacAdam Ellipses
879

880
```python { .api }
881
def plot_ellipses_MacAdam1942_in_chromaticity_diagram_CIE1931(
882
    **kwargs: Any
883
) -> Tuple[Figure, Axes]:
884
    """
885
    Plot MacAdam 1942 discrimination ellipses in CIE 1931 diagram.
886
    
887
    Parameters:
888
    - **kwargs: Additional plotting parameters
889
    
890
    Returns:
891
    Tuple of matplotlib Figure and Axes objects
892
    
893
    Features:
894
    - Just-noticeable-difference boundaries
895
    - Visual discrimination thresholds
896
    - Foundation for uniform colour spaces
897
    - Historic colour science reference
898
    """
899

900
def plot_ellipses_MacAdam1942_in_chromaticity_diagram_CIE1960UCS(
901
    **kwargs: Any
902
) -> Tuple[Figure, Axes]:
903
    """
904
    Plot MacAdam 1942 discrimination ellipses in CIE 1960 UCS diagram.
905
    
906
    Parameters:
907
    - **kwargs: Additional plotting parameters
908
    
909
    Returns:
910
    Tuple of matplotlib Figure and Axes objects
911
    """
912

913
def plot_ellipses_MacAdam1942_in_chromaticity_diagram_CIE1976UCS(
914
    **kwargs: Any
915
) -> Tuple[Figure, Axes]:
916
    """
917
    Plot MacAdam 1942 discrimination ellipses in CIE 1976 UCS diagram.
918
    
919
    Parameters:
920
    - **kwargs: Additional plotting parameters
921
    
922
    Returns:
923
    Tuple of matplotlib Figure and Axes objects
924
    """
925
```
926

927
### Constant Hue Loci
928

929
```python { .api }
930
def plot_constant_hue_loci(
931
    data: ArrayLike | None = None,
932
    model: LiteralColourspaceModel | str = "CIE Lab",
933
    scatter_kwargs: dict | None = None,
934
    convert_kwargs: dict | None = None,
935
    **kwargs: Any
936
) -> Tuple[Figure, Axes]:
937
    """
938
    Plot constant hue loci in given colour space.
939
    
940
    Parameters:
941
    - data: Colour data for hue line computation
942
    - model: Colour space model for the visualization
943
    - scatter_kwargs: Scatter plot styling parameters  
944
    - convert_kwargs: Colour space conversion parameters
945
    - **kwargs: Additional plotting parameters
946
    
947
    Returns:
948
    Tuple of matplotlib Figure and Axes objects
949
    
950
    Applications:
951
    - Colour space evaluation
952
    - Hue constancy studies
953
    - Colour appearance research
954
    - Display calibration assessment
955
    """
956
```
957

958
### Transfer Function Visualization
959

960
```python { .api }
961
def plot_single_cctf(
962
    cctf: str | Callable,
963
    cctf_decoding: Callable | None = None,
964
    **kwargs: Any
965
) -> Tuple[Figure, Axes]:
966
    """
967
    Plot colour component transfer function (CCTF).
968
    
969
    Parameters:
970
    - cctf: CCTF name or function for encoding
971
    - cctf_decoding: Optional decoding function
972
    - **kwargs: Additional plotting parameters
973
    
974
    Returns:
975
    Tuple of matplotlib Figure and Axes objects
976
    
977
    Supported CCTFs:
978
    - sRGB transfer function
979
    - Rec.709, Rec.2020 
980
    - PQ (SMPTE ST 2084)
981
    - HLG (Hybrid Log-Gamma)
982
    - Gamma functions
983
    """
984

985
def plot_multi_cctfs(
986
    cctfs: Sequence[str | Callable],
987
    **kwargs: Any
988
) -> Tuple[Figure, Axes]:
989
    """
990
    Plot multiple colour component transfer functions.
991
    
992
    Parameters:
993
    - cctfs: Sequence of CCTF names or functions
994
    - **kwargs: Additional plotting parameters
995
    
996
    Returns:
997
    Tuple of matplotlib Figure and Axes objects
998
    
999
    Use Cases:
1000
    - Transfer function comparison
1001
    - HDR vs SDR analysis
1002
    - Gamma curve evaluation
1003
    """
1004
```
1005

1006
## Specialized Applications
1007

1008
### Colour Vision Deficiency
1009

1010
```python { .api }
1011
def plot_cvd_simulation_Machado2009(
1012
    RGB: ArrayLike,
1013
    deficiency: Literal["Protanomaly", "Deuteranomaly", "Tritanomaly"] | str = "Protanomaly",
1014
    severity: float = 1,
1015
    **kwargs: Any
1016
) -> Tuple[Figure, Axes]:
1017
    """
1018
    Simulate colour vision deficiency using Machado 2009 method.
1019
    
1020
    Parameters:
1021
    - RGB: Original RGB colour data
1022
    - deficiency: Type of colour vision deficiency
1023
    - severity: Severity from 0 (normal) to 1 (complete deficiency)
1024
    - **kwargs: Additional plotting parameters
1025
    
1026
    Returns:
1027
    Tuple of matplotlib Figure and Axes objects
1028
    
1029
    Deficiency Types:
1030
    - Protanomaly: Reduced red sensitivity
1031
    - Deuteranomaly: Reduced green sensitivity  
1032
    - Tritanomaly: Reduced blue sensitivity
1033
    
1034
    Applications:
1035
    - Accessibility testing
1036
    - User interface design
1037
    - Educational demonstrations
1038
    """
1039
```
1040

1041
### Phenomena Visualization
1042

1043
```python { .api }
1044
def plot_single_sd_rayleigh_scattering(
1045
    sd: SpectralDistribution | None = None,
1046
    **kwargs: Any
1047
) -> Tuple[Figure, Axes]:
1048
    """
1049
    Plot Rayleigh scattering coefficient for atmospheric phenomena.
1050
    
1051
    Parameters:
1052
    - sd: Optional spectral distribution for scattering computation
1053
    - **kwargs: Additional plotting parameters
1054
    
1055
    Returns:
1056
    Tuple of matplotlib Figure and Axes objects
1057
    
1058
    Applications:
1059
    - Atmospheric optics modeling
1060
    - Sky colour prediction
1061
    - Environmental light transport
1062
    """
1063

1064
def plot_the_blue_sky(
1065
    **kwargs: Any
1066
) -> Tuple[Figure, Axes]:
1067
    """
1068
    Demonstrate why the sky appears blue through Rayleigh scattering.
1069
    
1070
    Parameters:
1071
    - **kwargs: Additional plotting parameters
1072
    
1073
    Returns:
1074
    Tuple of matplotlib Figure and Axes objects
1075
    
1076
    Educational Features:
1077
    - Wavelength-dependent scattering visualization
1078
    - Solar spectrum modification by atmosphere
1079
    - Physical basis for sky colour
1080
    """
1081
```
1082

1083
### Automatic Conversion Graph
1084

1085
```python { .api }
1086
def plot_automatic_colour_conversion_graph(
1087
    filename: str | None = None,
1088
    **kwargs: Any
1089
) -> None:
1090
    """
1091
    Plot the automatic colour conversion graph showing all supported pathways.
1092
    
1093
    Parameters:
1094
    - filename: Optional output filename for saving
1095
    - **kwargs: Additional plotting parameters
1096
    
1097
    Features:
1098
    - Complete conversion pathway visualization
1099
    - Node and edge analysis
1100
    - Shortest path identification
1101
    - Debugging tool for conversion issues
1102
    """
1103
```
1104

1105
## Style and Utilities
1106

1107
### Plot Styling
1108

1109
```python { .api }
1110
def colour_style(**kwargs: Any) -> dict:
1111
    """
1112
    Return the current colour plotting style.
1113
    
1114
    Parameters:
1115
    - **kwargs: Style modification parameters
1116
    
1117
    Returns:
1118
    Dictionary of matplotlib style parameters
1119
    
1120
    Style Elements:
1121
    - Colour palette and cycling
1122
    - Font families and sizes
1123
    - Grid and axis styling
1124
    - Figure dimensions
1125
    """
1126

1127
def override_style(**kwargs: Any) -> Callable:
1128
    """
1129
    Decorator to override plotting style for specific functions.
1130
    
1131
    Parameters:
1132
    - **kwargs: Style override parameters
1133
    
1134
    Returns:
1135
    Decorator function for style modification
1136
    
1137
    Usage:
1138
    >>> @override_style(axes.grid=True)
1139
    >>> def custom_plot(): ...
1140
    """
1141

1142
def font_scaling(scaling_factor: LiteralFontScaling | str) -> dict:
1143
    """
1144
    Generate font scaling parameters for plot readability.
1145
    
1146
    Parameters:
1147
    - scaling_factor: Scaling preset ("xx-small" to "xx-large")
1148
    
1149
    Returns:
1150
    Dictionary of font size parameters
1151
    """
1152
```
1153

1154
### Colour Space Conversion for Plotting
1155

1156
```python { .api }
1157
def XYZ_to_plotting_colourspace(
1158
    XYZ: ArrayLike,
1159
    illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"],
1160
    chromatic_adaptation_transform: LiteralChromaticAdaptationTransform | str = "CAT02",
1161
    apply_cctf_encoding: bool = True,
1162
) -> NDArrayFloat:
1163
    """
1164
    Convert XYZ tristimulus values to RGB for plotting display.
1165
    
1166
    Parameters:
1167
    - XYZ: XYZ tristimulus values to convert
1168
    - illuminant: Reference white point for adaptation
1169
    - chromatic_adaptation_transform: Adaptation method  
1170
    - apply_cctf_encoding: Apply gamma encoding for display
1171
    
1172
    Returns:
1173
    RGB values suitable for matplotlib display
1174
    
1175
    Features:
1176
    - Automatic gamut mapping
1177
    - Display-referred encoding
1178
    - Standard sRGB output colourspace
1179
    """
1180
```
1181

1182
### Filter Functions
1183

1184
```python { .api }
1185
def filter_passthrough(
1186
    mapping: Mapping,
1187
    filterers: str | Sequence[str],
1188
    anchors: bool = True,
1189
    allow_non_siblings: bool = True,
1190
    flags: int = 0,
1191
) -> CanonicalMapping:
1192
    """
1193
    Filter mapping with passthrough for unmatched items.
1194
    
1195
    Parameters:
1196
    - mapping: Input mapping to filter
1197
    - filterers: Filter patterns or keywords
1198
    - anchors: Use regex anchors for exact matching
1199
    - allow_non_siblings: Allow non-sibling key matching
1200
    - flags: Regular expression flags
1201
    
1202
    Returns:
1203
    Filtered canonical mapping
1204
    """
1205

1206
def filter_RGB_colourspaces(
1207
    filterers: str | RGB_Colourspace | Sequence[str | RGB_Colourspace]
1208
) -> CanonicalMapping:
1209
    """
1210
    Filter available RGB colourspaces by name or instance.
1211
    
1212
    Parameters:
1213
    - filterers: Colourspace names, instances, or patterns
1214
    
1215
    Returns:
1216
    Filtered mapping of RGB colourspaces
1217
    """
1218

1219
def filter_cmfs(
1220
    filterers: str | MultiSpectralDistributions | Sequence[str | MultiSpectralDistributions]
1221
) -> CanonicalMapping:
1222
    """
1223
    Filter available colour matching functions.
1224
    
1225
    Parameters:
1226
    - filterers: CMF names, instances, or patterns
1227
    
1228
    Returns:
1229
    Filtered mapping of colour matching functions
1230
    """
1231

1232
def filter_illuminants(
1233
    filterers: str | SpectralDistribution | Sequence[str | SpectralDistribution]
1234
) -> CanonicalMapping:
1235
    """
1236
    Filter available illuminants by name or instance.
1237
    
1238
    Parameters:
1239
    - filterers: Illuminant names, instances, or patterns
1240
    
1241
    Returns:
1242
    Filtered mapping of illuminants
1243
    """
1244

1245
def filter_colour_checkers(
1246
    filterers: str | ColourChecker | Sequence[str | ColourChecker]
1247
) -> CanonicalMapping:
1248
    """
1249
    Filter available colour checkers by name or instance.
1250
    
1251
    Parameters:
1252
    - filterers: Colour checker names, instances, or patterns
1253
    
1254
    Returns:
1255
    Filtered mapping of colour checkers
1256
    """
1257
```
1258

1259
## Method Collections and Constants
1260

1261
### Available Methods
1262

1263
```python { .api }
1264
# Chromaticity diagram methods
1265
METHODS_CHROMATICITY_DIAGRAM: CanonicalMapping = {
1266
    "CIE 1931": {...},      # xy chromaticity coordinates  
1267
    "CIE 1960 UCS": {...},  # uv chromaticity coordinates
1268
    "CIE 1976 UCS": {...}   # u'v' chromaticity coordinates
1269
}
1270

1271
# Default wavelength labels for spectral locus
1272
LABELS_CHROMATICITY_DIAGRAM_DEFAULT: CanonicalMapping = {
1273
    "CIE 1931": (390, 460, 470, 480, 490, 500, 510, 520, 540, 560, 580, 600, 620, 700),
1274
    "CIE 1960 UCS": (390, 460, 470, 480, 490, 500, 510, 520, 540, 560, 580, 600, 620, 700),
1275
    "CIE 1976 UCS": (390, 460, 470, 480, 490, 500, 510, 520, 540, 560, 580, 600, 620, 700)
1276
}
1277

1278
# Planckian locus labels  
1279
LABELS_PLANCKIAN_LOCUS_DEFAULT: tuple = (
1280
    1667, 2000, 2500, 3000, 4000, 5000, 6500, 10000
1281
)
1282
```
1283

1284
### Style Constants
1285

1286
```python { .api }
1287
# Core colour style definitions
1288
CONSTANTS_COLOUR_STYLE: Structure = {
1289
    "colour": {
1290
        "darkest": "#111111",
1291
        "darker": "#222222", 
1292
        "dark": "#333333",
1293
        "bright": "#EEEEEE",
1294
        "cycle": ("#F44336", "#9C27B0", "#3F51B5", "#03A9F4", "#009688", ...)
1295
    },
1296
    "geometry": {...},
1297
    "opacity": {...}
1298
}
1299

1300
# Arrow style constants for annotations
1301
CONSTANTS_ARROW_STYLE: Structure = {
1302
    "colour": (0.0, 0.0, 0.0),
1303
    "arrowstyle": "->",
1304
    "connectionstyle": "arc3,rad=0.2"
1305
}
1306
```
1307

1308
## Usage Examples
1309

1310
### Basic Plotting Workflow
1311

1312
```python
1313
import colour
1314
from colour.plotting import *
1315

1316
# Plot colour swatches
1317
swatches = [
1318
    ColourSwatch((0.9, 0.1, 0.1), "Red"),
1319
    ColourSwatch((0.1, 0.9, 0.1), "Green"), 
1320
    ColourSwatch((0.1, 0.1, 0.9), "Blue")
1321
]
1322
plot_multi_colour_swatches(swatches)
1323

1324
# Chromaticity diagram with colourspace gamuts
1325
plot_RGB_colourspaces_in_chromaticity_diagram_CIE1931(
1326
    ["sRGB", "Adobe RGB", "Rec.2020"]
1327
)
1328

1329
# Spectral distribution analysis
1330
illuminant = colour.SDS_ILLUMINANTS["D65"]
1331
plot_single_sd(illuminant, modulate_colours_with_sd_amplitude=True)
1332
```
1333

1334
### Quality Assessment Workflow  
1335

1336
```python
1337
# CRI analysis for LED
1338
led_spectrum = colour.SpectralDistribution({
1339
    380: 0.01, 420: 0.05, 450: 0.15, 480: 0.25,
1340
    520: 0.35, 560: 0.95, 600: 0.85, 650: 0.75, 700: 0.05
1341
})
1342
plot_single_sd_colour_rendering_index_bars(led_spectrum)
1343

1344
# TM-30 comprehensive report
1345
plot_single_sd_colour_rendition_report(led_spectrum, report_type="Full")
1346
```
1347

1348
### Gamut Analysis Workflow
1349

1350
```python
1351
# 3D gamut comparison
1352
plot_RGB_colourspaces_gamuts(
1353
    ["sRGB", "Adobe RGB", "ProPhoto RGB", "Rec.2020"],
1354
    show_spectral_locus=True
1355
)
1356

1357
# RGB colour distribution analysis
1358
import numpy as np
1359
rgb_data = np.random.random((1000, 3))  # Random RGB colours
1360
plot_RGB_scatter(rgb_data, colourspace="sRGB", 
1361
                colourspaces=["Adobe RGB", "Rec.2020"])
1362
```
1363

1364
This comprehensive plotting API provides everything needed for professional colour science visualization, from basic colour swatches to advanced quality assessments and 3D gamut analysis.