tessl/pypi-colour-science

Comprehensive Python library providing algorithms and datasets for colour science computations, including chromatic adaptation, colour appearance models, colorimetry, and spectral analysis.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Plotting and Visualization

Name: tessl/pypi-colour-science
Author: tessl

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

Capabilities

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

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

Core Classes

ColourSwatch

Data structure for representing colour patches with optional naming.

@dataclass
class ColourSwatch:
    """
    Colour swatch representation for plotting.
    
    Parameters:
    - RGB: RGB colour values (ArrayLike)
    - name: Optional colour name for labeling (str | None)
    
    Examples:
    >>> swatch = ColourSwatch((0.45, 0.31, 0.04), name="Custom Orange")
    >>> plot_single_colour_swatch(swatch)
    """
    RGB: ArrayLike
    name: str | None = None

Common Plotting Functions

Basic Colour Visualization

Core functions for plotting colour swatches and basic visualizations.

def plot_single_colour_swatch(
    colour_swatch: ArrayLike | ColourSwatch, 
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot a single colour swatch.
    
    Parameters:
    - colour_swatch: Colour data as ArrayLike or ColourSwatch instance
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Examples:
    >>> RGB = ColourSwatch((0.456, 0.031, 0.041))
    >>> plot_single_colour_swatch(RGB)
    """

def plot_multi_colour_swatches(
    colour_swatches: Sequence[ArrayLike | ColourSwatch],
    width: float = 1,
    height: float = 1,
    spacing: float = 0,
    columns: int | None = None,
    direction: Literal["+y", "-y"] | str = "+y",
    text_kwargs: dict | None = None,
    background_colour: ArrayLike = (1.0, 1.0, 1.0),
    compare_swatches: Literal["Diagonal", "Stacked"] | str | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot multiple colour swatches in a grid layout.
    
    Parameters:
    - colour_swatches: Sequence of colour data or ColourSwatch instances
    - width: Individual swatch width (default: 1)
    - height: Individual swatch height (default: 1)
    - spacing: Spacing between swatches (default: 0)
    - columns: Number of columns, auto-calculated if None
    - direction: Row stacking direction ("+y" or "-y")
    - text_kwargs: Text styling parameters
    - background_colour: Background colour for the plot
    - compare_swatches: Comparison mode ("Diagonal" or "Stacked")
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

def plot_image(
    image: ArrayLike,
    text_kwargs: dict | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot given image with optional text overlay.
    
    Parameters:
    - image: Image array to display
    - text_kwargs: Text overlay styling parameters
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

Function and Data Plotting

def plot_single_function(
    function: Callable,
    samples: ArrayLike | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot a single mathematical function.
    
    Parameters:
    - function: Callable function to plot
    - samples: Sample points for function evaluation
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

def plot_multi_functions(
    functions: Sequence[Callable],
    samples: ArrayLike | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot multiple mathematical functions on the same axes.
    
    Parameters:
    - functions: Sequence of callable functions
    - samples: Sample points for function evaluation  
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

Chromaticity Diagrams

CIE Standard Diagrams

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

def plot_chromaticity_diagram_CIE1931(
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    show_diagram_colours: bool = True,
    show_spectral_locus: bool = True,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot the CIE 1931 Chromaticity Diagram.
    
    Parameters:
    - cmfs: Colour matching functions for spectral locus computation
    - show_diagram_colours: Display background chromaticity colours
    - show_spectral_locus: Display the spectral locus boundary
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Accurate spectral locus from 380-780nm
    - Colour-filled background showing all visible colours
    - Wavelength labels along spectral locus
    - Standard illuminants and colour spaces can be overlaid
    """

def plot_chromaticity_diagram_CIE1960UCS(
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    show_diagram_colours: bool = True,
    show_spectral_locus: bool = True,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot the CIE 1960 UCS Chromaticity Diagram.
    
    Parameters:
    - cmfs: Colour matching functions for spectral locus computation
    - show_diagram_colours: Display background chromaticity colours
    - show_spectral_locus: Display the spectral locus boundary
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - More perceptually uniform than CIE 1931
    - Used for correlated colour temperature calculations
    - Better spacing for colour difference evaluations
    """

def plot_chromaticity_diagram_CIE1976UCS(
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer", 
    show_diagram_colours: bool = True,
    show_spectral_locus: bool = True,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot the CIE 1976 UCS (u', v') Chromaticity Diagram.
    
    Parameters:
    - cmfs: Colour matching functions for spectral locus computation
    - show_diagram_colours: Display background chromaticity colours
    - show_spectral_locus: Display the spectral locus boundary
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Most perceptually uniform CIE chromaticity diagram
    - Foundation for CIELUV colour space
    - Preferred for modern colour difference calculations
    """

Spectral Distribution Overlays

def plot_sds_in_chromaticity_diagram_CIE1931(
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    annotate_kwargs: dict | None = None,
    chromaticity_diagram_callable: Callable = plot_chromaticity_diagram_CIE1931,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot spectral distributions in CIE 1931 chromaticity diagram.
    
    Parameters:
    - sds: Spectral distributions to plot as points
    - cmfs: Colour matching functions for chromaticity calculation
    - annotate_kwargs: Annotation styling parameters
    - chromaticity_diagram_callable: Base diagram plotting function
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Use Cases:
    - Visualizing illuminant chromaticity coordinates
    - Comparing LED or other light source colours
    - Quality control of lighting products
    """

def plot_sds_in_chromaticity_diagram_CIE1960UCS(
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    annotate_kwargs: dict | None = None,
    chromaticity_diagram_callable: Callable = plot_chromaticity_diagram_CIE1960UCS,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot spectral distributions in CIE 1960 UCS chromaticity diagram.
    
    Parameters:
    - sds: Spectral distributions to plot as points
    - cmfs: Colour matching functions for chromaticity calculation  
    - annotate_kwargs: Annotation styling parameters
    - chromaticity_diagram_callable: Base diagram plotting function
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

def plot_sds_in_chromaticity_diagram_CIE1976UCS(
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    annotate_kwargs: dict | None = None, 
    chromaticity_diagram_callable: Callable = plot_chromaticity_diagram_CIE1976UCS,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot spectral distributions in CIE 1976 UCS chromaticity diagram.
    
    Parameters:
    - sds: Spectral distributions to plot as points
    - cmfs: Colour matching functions for chromaticity calculation
    - annotate_kwargs: Annotation styling parameters
    - chromaticity_diagram_callable: Base diagram plotting function
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

Spectral Distribution Plotting

Single and Multi-Spectral Plots

def plot_single_sd(
    sd: SpectralDistribution,
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    out_of_gamut_clipping: bool = True,
    modulate_colours_with_sd_amplitude: bool = False,
    equalize_sd_amplitude: bool = False,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot a single spectral distribution with colour representation.
    
    Parameters:
    - sd: Spectral distribution to plot
    - cmfs: Colour matching functions for colour computation
    - out_of_gamut_clipping: Clip out-of-gamut colours vs. gray background
    - modulate_colours_with_sd_amplitude: Modulate colours by amplitude
    - equalize_sd_amplitude: Normalize amplitude for uniform colour display
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Spectrum coloured by wavelength-dependent hues
    - Amplitude modulation options for realistic appearance
    - Out-of-gamut handling for accurate colour rendering
    - Supports reflectance, transmittance, and emission spectra
    """

def plot_multi_sds(
    sds: Sequence[SpectralDistribution | MultiSpectralDistributions | str],
    plot_kwargs: Sequence[dict] | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot multiple spectral distributions on the same axes.
    
    Parameters:
    - sds: Sequence of spectral distributions to plot
    - plot_kwargs: Individual styling parameters for each spectrum
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Use Cases:
    - Comparing multiple illuminants or LEDs
    - Visualizing before/after spectral corrections
    - Material characterization studies
    """

def plot_visible_spectrum(
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    out_of_gamut_clipping: bool = True,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot the visible spectrum as a continuous colour bar.
    
    Parameters:
    - cmfs: Colour matching functions defining visible range
    - out_of_gamut_clipping: Clip out-of-gamut colours vs. desaturate
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Pure spectral colours from ~380-780nm
    - Accurate representation of human colour vision
    - Educational tool for wavelength-colour relationships
    """

Colour Matching Functions

def plot_single_cmfs(
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str],
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot colour matching functions (CMFs) showing tristimulus responses.
    
    Parameters:
    - cmfs: Colour matching functions to plot
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - X, Y, Z tristimulus curves
    - Standard observer data (2°, 10°)
    - Fundamental response functions
    """

def plot_multi_cmfs(
    cmfs: Sequence[MultiSpectralDistributions | str],
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot multiple colour matching functions for comparison.
    
    Parameters:
    - cmfs: Sequence of colour matching functions
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Use Cases:
    - Comparing 2° vs 10° standard observers
    - Visualizing individual differences in colour vision
    - Research into alternative colour matching functions
    """

Illuminant Plotting

def plot_single_illuminant_sd(
    illuminant: SpectralDistribution | str,
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot a single illuminant spectral distribution.
    
    Parameters:
    - illuminant: Illuminant spectral distribution or name
    - cmfs: Colour matching functions for colour computation
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Supported Illuminants:
    - Standard illuminants (A, D50, D65, E)
    - Fluorescent series (F1-F12) 
    - LED and specialty sources
    """

def plot_multi_illuminant_sds(
    illuminants: Sequence[SpectralDistribution | str],
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot multiple illuminant spectral distributions.
    
    Parameters:
    - illuminants: Sequence of illuminant distributions or names
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

Blackbody and Planckian Radiation

def plot_blackbody_spectral_radiance(
    temperature: ArrayLike,
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    blackbody: SpectralDistribution | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot blackbody spectral radiance for given temperature(s).
    
    Parameters:
    - temperature: Blackbody temperature(s) in Kelvin
    - cmfs: Colour matching functions for visible range
    - blackbody: Optional pre-computed blackbody distribution
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Applications:
    - Thermal radiation visualization
    - Colour temperature understanding
    - Planck's law demonstration
    """

def plot_blackbody_colours(
    shape: SpectralShape,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot blackbody colours across temperature range.
    
    Parameters:
    - shape: Spectral shape defining temperature range and resolution
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Continuous colour progression with temperature
    - Visualization of correlated colour temperature
    - Educational tool for thermal radiation colour
    """

Quality Assessment Plotting

Colour Rendering Index (CRI)

def plot_single_sd_colour_rendering_index_bars(
    sd: SpectralDistribution | str,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot colour rendering index (CRI) bars for a single illuminant.
    
    Parameters:
    - sd: Spectral distribution or illuminant name
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - CRI for 14 test colour samples (TCS01-TCS14)
    - Overall Ra value prominently displayed
    - Individual sample colour fidelity scores
    - Standard CRI calculation methodology
    """

def plot_multi_sds_colour_rendering_indexes_bars(
    sds: Sequence[SpectralDistribution | str],
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot CRI comparison bars for multiple illuminants.
    
    Parameters:
    - sds: Sequence of spectral distributions or illuminant names
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Use Cases:
    - LED product comparisons
    - Illuminant quality assessment
    - Lighting design validation
    """

Colour Quality Scale (CQS)

def plot_single_sd_colour_quality_scale_bars(
    sd: SpectralDistribution | str,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot colour quality scale (CQS) bars for a single illuminant.
    
    Parameters:
    - sd: Spectral distribution or illuminant name
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Modern alternative to CRI with better LED performance
    - Improved colour samples and calculation methods
    - Enhanced correlation with visual assessments
    """

def plot_multi_sds_colour_quality_scales_bars(
    sds: Sequence[SpectralDistribution | str],
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot CQS comparison bars for multiple illuminants.
    
    Parameters:
    - sds: Sequence of spectral distributions or illuminant names  
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

TM-30 Colour Rendition Reports

def plot_single_sd_colour_rendition_report(
    sd: SpectralDistribution | str,
    report_type: Literal["Full", "Intermediate", "Simple"] | str = "Full",
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Generate comprehensive TM-30 colour rendition report.
    
    Parameters:
    - sd: Spectral distribution or illuminant name
    - report_type: Detail level ("Full", "Intermediate", "Simple")
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Report Components:
    - Colour fidelity index (Rf) and colour gamut index (Rg)
    - 16-bin colour fidelity and gamut area charts  
    - Local chroma and hue shift visualizations
    - Spectral power distribution with colour rendition
    - Vector graphics showing colour accuracy
    
    Standards Compliance:
    - ANSI/IES TM-30-18 methodology
    - Professional lighting industry standard
    - Comprehensive illuminant characterization
    """

RGB Colourspace Visualization

Gamut Plotting

def plot_RGB_colourspaces_gamuts(
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
    segments: int = 8,
    show_grid: bool = True,
    grid_segments: int = 10,
    show_spectral_locus: bool = False,
    spectral_locus_colour: ArrayLike | None = None,
    points: ArrayLike | None = None,
    points_colours: ArrayLike | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes3D]:
    """
    Plot 3D gamut volumes for RGB colourspaces.
    
    Parameters:
    - colourspaces: RGB colourspaces to visualize
    - segments: Gamut surface tessellation detail
    - show_grid: Display coordinate grid
    - grid_segments: Grid line density
    - show_spectral_locus: Include spectral locus boundary
    - spectral_locus_colour: Spectral locus line colour
    - points: Additional points to plot
    - points_colours: Point colours
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and 3D Axes objects
    
    Colourspace Support:
    - sRGB, Adobe RGB, ProPhoto RGB
    - Rec.2020, DCI-P3, ACES
    - Custom colourspaces via RGB_Colourspace
    
    Features:
    - Interactive 3D navigation
    - Transparent gamut surfaces
    - Comparative volume analysis
    - Spectral locus reference
    """

def plot_RGB_scatter(
    RGB: ArrayLike,
    colourspace: RGB_Colourspace | LiteralRGBColourspace | str = "sRGB",
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str] | None = None,
    segments: int = 8,
    show_grid: bool = True,
    grid_segments: int = 10,
    **kwargs: Any
) -> Tuple[Figure, Axes3D]:
    """
    Plot RGB colour data as 3D scatter points within gamut boundaries.
    
    Parameters:
    - RGB: RGB colour data array
    - colourspace: Primary colourspace for the data
    - colourspaces: Additional colourspace gamuts to show
    - segments: Gamut surface tessellation detail
    - show_grid: Display coordinate grid
    - grid_segments: Grid line density  
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and 3D Axes objects
    
    Applications:
    - Colour distribution analysis
    - Gamut utilization studies  
    - Out-of-gamut detection
    - Colour grading visualization
    """

Chromaticity Gamut Plots

def plot_RGB_colourspaces_in_chromaticity_diagram_CIE1931(
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    show_whitepoints: bool = True,
    show_pointer_gamut: bool = False,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot RGB colourspace gamuts in CIE 1931 chromaticity diagram.
    
    Parameters:
    - colourspaces: RGB colourspaces to plot
    - cmfs: Colour matching functions
    - show_whitepoints: Display whitepoint markers
    - show_pointer_gamut: Include Pointer's gamut reference
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Triangular gamut boundaries
    - Primary and secondary colour vertices
    - Whitepoint locations
    - Relative gamut size comparison
    """

def plot_RGB_colourspaces_in_chromaticity_diagram_CIE1960UCS(
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer",
    show_whitepoints: bool = True,
    show_pointer_gamut: bool = False,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot RGB colourspace gamuts in CIE 1960 UCS chromaticity diagram.
    
    Parameters:
    - colourspaces: RGB colourspaces to plot
    - cmfs: Colour matching functions
    - show_whitepoints: Display whitepoint markers
    - show_pointer_gamut: Include Pointer's gamut reference
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

def plot_RGB_colourspaces_in_chromaticity_diagram_CIE1976UCS(
    colourspaces: Sequence[RGB_Colourspace | LiteralRGBColourspace | str],
    cmfs: MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] = "CIE 1931 2 Degree Standard Observer", 
    show_whitepoints: bool = True,
    show_pointer_gamut: bool = False,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot RGB colourspace gamuts in CIE 1976 UCS chromaticity diagram.
    
    Parameters:
    - colourspaces: RGB colourspaces to plot
    - cmfs: Colour matching functions
    - show_whitepoints: Display whitepoint markers  
    - show_pointer_gamut: Include Pointer's gamut reference
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

Pointer's Gamut

def plot_pointer_gamut(
    method: Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"] | str = "CIE 1931",
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot Pointer's gamut representing real surface colours.
    
    Parameters:
    - method: Chromaticity diagram type
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Background:
    - Represents colours of real surface materials
    - Benchmark for display and printer gamuts
    - Based on Munsell colour measurements
    - Standard reference in colour science
    """

Temperature and Daylight

Planckian Locus

def plot_planckian_locus_in_chromaticity_diagram_CIE1931(
    illuminants: Sequence[str] | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot Planckian locus in CIE 1931 chromaticity diagram.
    
    Parameters:
    - illuminants: Specific illuminants to highlight
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Blackbody radiation locus from 1000K to 100000K
    - Temperature tick marks at standard intervals
    - Isothermal lines for correlated colour temperature
    - Standard illuminant positions
    """

def plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
    illuminants: Sequence[str] | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot Planckian locus in CIE 1960 UCS chromaticity diagram.
    
    Parameters:
    - illuminants: Specific illuminants to highlight
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Applications:
    - Correlated colour temperature calculations
    - Daylight and artificial light analysis
    - White balance evaluation
    """

def plot_planckian_locus_in_chromaticity_diagram_CIE1976UCS(
    illuminants: Sequence[str] | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot Planckian locus in CIE 1976 UCS chromaticity diagram.
    
    Parameters:
    - illuminants: Specific illuminants to highlight
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

Advanced Visualizations

MacAdam Ellipses

def plot_ellipses_MacAdam1942_in_chromaticity_diagram_CIE1931(
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot MacAdam 1942 discrimination ellipses in CIE 1931 diagram.
    
    Parameters:
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Features:
    - Just-noticeable-difference boundaries
    - Visual discrimination thresholds
    - Foundation for uniform colour spaces
    - Historic colour science reference
    """

def plot_ellipses_MacAdam1942_in_chromaticity_diagram_CIE1960UCS(
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot MacAdam 1942 discrimination ellipses in CIE 1960 UCS diagram.
    
    Parameters:
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

def plot_ellipses_MacAdam1942_in_chromaticity_diagram_CIE1976UCS(
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot MacAdam 1942 discrimination ellipses in CIE 1976 UCS diagram.
    
    Parameters:
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    """

Constant Hue Loci

def plot_constant_hue_loci(
    data: ArrayLike | None = None,
    model: LiteralColourspaceModel | str = "CIE Lab",
    scatter_kwargs: dict | None = None,
    convert_kwargs: dict | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot constant hue loci in given colour space.
    
    Parameters:
    - data: Colour data for hue line computation
    - model: Colour space model for the visualization
    - scatter_kwargs: Scatter plot styling parameters  
    - convert_kwargs: Colour space conversion parameters
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Applications:
    - Colour space evaluation
    - Hue constancy studies
    - Colour appearance research
    - Display calibration assessment
    """

Transfer Function Visualization

def plot_single_cctf(
    cctf: str | Callable,
    cctf_decoding: Callable | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot colour component transfer function (CCTF).
    
    Parameters:
    - cctf: CCTF name or function for encoding
    - cctf_decoding: Optional decoding function
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Supported CCTFs:
    - sRGB transfer function
    - Rec.709, Rec.2020 
    - PQ (SMPTE ST 2084)
    - HLG (Hybrid Log-Gamma)
    - Gamma functions
    """

def plot_multi_cctfs(
    cctfs: Sequence[str | Callable],
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot multiple colour component transfer functions.
    
    Parameters:
    - cctfs: Sequence of CCTF names or functions
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Use Cases:
    - Transfer function comparison
    - HDR vs SDR analysis
    - Gamma curve evaluation
    """

Specialized Applications

Colour Vision Deficiency

def plot_cvd_simulation_Machado2009(
    RGB: ArrayLike,
    deficiency: Literal["Protanomaly", "Deuteranomaly", "Tritanomaly"] | str = "Protanomaly",
    severity: float = 1,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Simulate colour vision deficiency using Machado 2009 method.
    
    Parameters:
    - RGB: Original RGB colour data
    - deficiency: Type of colour vision deficiency
    - severity: Severity from 0 (normal) to 1 (complete deficiency)
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Deficiency Types:
    - Protanomaly: Reduced red sensitivity
    - Deuteranomaly: Reduced green sensitivity  
    - Tritanomaly: Reduced blue sensitivity
    
    Applications:
    - Accessibility testing
    - User interface design
    - Educational demonstrations
    """

Phenomena Visualization

def plot_single_sd_rayleigh_scattering(
    sd: SpectralDistribution | None = None,
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Plot Rayleigh scattering coefficient for atmospheric phenomena.
    
    Parameters:
    - sd: Optional spectral distribution for scattering computation
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Applications:
    - Atmospheric optics modeling
    - Sky colour prediction
    - Environmental light transport
    """

def plot_the_blue_sky(
    **kwargs: Any
) -> Tuple[Figure, Axes]:
    """
    Demonstrate why the sky appears blue through Rayleigh scattering.
    
    Parameters:
    - **kwargs: Additional plotting parameters
    
    Returns:
    Tuple of matplotlib Figure and Axes objects
    
    Educational Features:
    - Wavelength-dependent scattering visualization
    - Solar spectrum modification by atmosphere
    - Physical basis for sky colour
    """

Automatic Conversion Graph

def plot_automatic_colour_conversion_graph(
    filename: str | None = None,
    **kwargs: Any
) -> None:
    """
    Plot the automatic colour conversion graph showing all supported pathways.
    
    Parameters:
    - filename: Optional output filename for saving
    - **kwargs: Additional plotting parameters
    
    Features:
    - Complete conversion pathway visualization
    - Node and edge analysis
    - Shortest path identification
    - Debugging tool for conversion issues
    """

Style and Utilities

Plot Styling

def colour_style(**kwargs: Any) -> dict:
    """
    Return the current colour plotting style.
    
    Parameters:
    - **kwargs: Style modification parameters
    
    Returns:
    Dictionary of matplotlib style parameters
    
    Style Elements:
    - Colour palette and cycling
    - Font families and sizes
    - Grid and axis styling
    - Figure dimensions
    """

def override_style(**kwargs: Any) -> Callable:
    """
    Decorator to override plotting style for specific functions.
    
    Parameters:
    - **kwargs: Style override parameters
    
    Returns:
    Decorator function for style modification
    
    Usage:
    >>> @override_style(axes.grid=True)
    >>> def custom_plot(): ...
    """

def font_scaling(scaling_factor: LiteralFontScaling | str) -> dict:
    """
    Generate font scaling parameters for plot readability.
    
    Parameters:
    - scaling_factor: Scaling preset ("xx-small" to "xx-large")
    
    Returns:
    Dictionary of font size parameters
    """

Colour Space Conversion for Plotting

def XYZ_to_plotting_colourspace(
    XYZ: ArrayLike,
    illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"],
    chromatic_adaptation_transform: LiteralChromaticAdaptationTransform | str = "CAT02",
    apply_cctf_encoding: bool = True,
) -> NDArrayFloat:
    """
    Convert XYZ tristimulus values to RGB for plotting display.
    
    Parameters:
    - XYZ: XYZ tristimulus values to convert
    - illuminant: Reference white point for adaptation
    - chromatic_adaptation_transform: Adaptation method  
    - apply_cctf_encoding: Apply gamma encoding for display
    
    Returns:
    RGB values suitable for matplotlib display
    
    Features:
    - Automatic gamut mapping
    - Display-referred encoding
    - Standard sRGB output colourspace
    """

Filter Functions

def filter_passthrough(
    mapping: Mapping,
    filterers: str | Sequence[str],
    anchors: bool = True,
    allow_non_siblings: bool = True,
    flags: int = 0,
) -> CanonicalMapping:
    """
    Filter mapping with passthrough for unmatched items.
    
    Parameters:
    - mapping: Input mapping to filter
    - filterers: Filter patterns or keywords
    - anchors: Use regex anchors for exact matching
    - allow_non_siblings: Allow non-sibling key matching
    - flags: Regular expression flags
    
    Returns:
    Filtered canonical mapping
    """

def filter_RGB_colourspaces(
    filterers: str | RGB_Colourspace | Sequence[str | RGB_Colourspace]
) -> CanonicalMapping:
    """
    Filter available RGB colourspaces by name or instance.
    
    Parameters:
    - filterers: Colourspace names, instances, or patterns
    
    Returns:
    Filtered mapping of RGB colourspaces
    """

def filter_cmfs(
    filterers: str | MultiSpectralDistributions | Sequence[str | MultiSpectralDistributions]
) -> CanonicalMapping:
    """
    Filter available colour matching functions.
    
    Parameters:
    - filterers: CMF names, instances, or patterns
    
    Returns:
    Filtered mapping of colour matching functions
    """

def filter_illuminants(
    filterers: str | SpectralDistribution | Sequence[str | SpectralDistribution]
) -> CanonicalMapping:
    """
    Filter available illuminants by name or instance.
    
    Parameters:
    - filterers: Illuminant names, instances, or patterns
    
    Returns:
    Filtered mapping of illuminants
    """

def filter_colour_checkers(
    filterers: str | ColourChecker | Sequence[str | ColourChecker]
) -> CanonicalMapping:
    """
    Filter available colour checkers by name or instance.
    
    Parameters:
    - filterers: Colour checker names, instances, or patterns
    
    Returns:
    Filtered mapping of colour checkers
    """

Method Collections and Constants

Available Methods

# Chromaticity diagram methods
METHODS_CHROMATICITY_DIAGRAM: CanonicalMapping = {
    "CIE 1931": {...},      # xy chromaticity coordinates  
    "CIE 1960 UCS": {...},  # uv chromaticity coordinates
    "CIE 1976 UCS": {...}   # u'v' chromaticity coordinates
}

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

# Planckian locus labels  
LABELS_PLANCKIAN_LOCUS_DEFAULT: tuple = (
    1667, 2000, 2500, 3000, 4000, 5000, 6500, 10000
)

Style Constants

# Core colour style definitions
CONSTANTS_COLOUR_STYLE: Structure = {
    "colour": {
        "darkest": "#111111",
        "darker": "#222222", 
        "dark": "#333333",
        "bright": "#EEEEEE",
        "cycle": ("#F44336", "#9C27B0", "#3F51B5", "#03A9F4", "#009688", ...)
    },
    "geometry": {...},
    "opacity": {...}
}

# Arrow style constants for annotations
CONSTANTS_ARROW_STYLE: Structure = {
    "colour": (0.0, 0.0, 0.0),
    "arrowstyle": "->",
    "connectionstyle": "arc3,rad=0.2"
}

Usage Examples

Basic Plotting Workflow

import colour
from colour.plotting import *

# Plot colour swatches
swatches = [
    ColourSwatch((0.9, 0.1, 0.1), "Red"),
    ColourSwatch((0.1, 0.9, 0.1), "Green"), 
    ColourSwatch((0.1, 0.1, 0.9), "Blue")
]
plot_multi_colour_swatches(swatches)

# Chromaticity diagram with colourspace gamuts
plot_RGB_colourspaces_in_chromaticity_diagram_CIE1931(
    ["sRGB", "Adobe RGB", "Rec.2020"]
)

# Spectral distribution analysis
illuminant = colour.SDS_ILLUMINANTS["D65"]
plot_single_sd(illuminant, modulate_colours_with_sd_amplitude=True)

Quality Assessment Workflow

# CRI analysis for LED
led_spectrum = colour.SpectralDistribution({
    380: 0.01, 420: 0.05, 450: 0.15, 480: 0.25,
    520: 0.35, 560: 0.95, 600: 0.85, 650: 0.75, 700: 0.05
})
plot_single_sd_colour_rendering_index_bars(led_spectrum)

# TM-30 comprehensive report
plot_single_sd_colour_rendition_report(led_spectrum, report_type="Full")

Gamut Analysis Workflow

# 3D gamut comparison
plot_RGB_colourspaces_gamuts(
    ["sRGB", "Adobe RGB", "ProPhoto RGB", "Rec.2020"],
    show_spectral_locus=True
)

# RGB colour distribution analysis
import numpy as np
rgb_data = np.random.random((1000, 3))  # Random RGB colours
plot_RGB_scatter(rgb_data, colourspace="sRGB", 
                colourspaces=["Adobe RGB", "Rec.2020"])

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

Install with Tessl CLI