Source code for colour.plotting.diagrams

"""
CIE Chromaticity Diagrams Plotting
==================================

Define the *CIE* chromaticity diagrams plotting objects:

-   :func:`colour.plotting.lines_spectral_locus`
-   :func:`colour.plotting.plot_chromaticity_diagram_CIE1931`
-   :func:`colour.plotting.plot_chromaticity_diagram_CIE1960UCS`
-   :func:`colour.plotting.plot_chromaticity_diagram_CIE1976UCS`
-   :func:`colour.plotting.plot_sds_in_chromaticity_diagram_CIE1931`
-   :func:`colour.plotting.plot_sds_in_chromaticity_diagram_CIE1960UCS`
-   :func:`colour.plotting.plot_sds_in_chromaticity_diagram_CIE1976UCS`
"""

from __future__ import annotations

import bisect

import numpy as np
from matplotlib.axes import Axes
from matplotlib.collections import LineCollection
from matplotlib.figure import Figure
from matplotlib.patches import Polygon

from colour.algebra import normalise_maximum, normalise_vector
from colour.colorimetry import (
    SDS_ILLUMINANTS,
    MultiSpectralDistributions,
    SpectralDistribution,
    sd_to_XYZ,
    sds_and_msds_to_sds,
)
from colour.constants import DTYPE_FLOAT_DEFAULT
from colour.hints import (
    Any,
    ArrayLike,
    Callable,
    Dict,
    List,
    Literal,
    NDArray,
    Sequence,
    Tuple,
    cast,
)
from colour.models import (
    Luv_to_uv,
    Luv_uv_to_xy,
    UCS_to_uv,
    UCS_uv_to_xy,
    XYZ_to_Luv,
    XYZ_to_UCS,
    XYZ_to_xy,
    xy_to_Luv_uv,
    xy_to_UCS_uv,
    xy_to_XYZ,
)
from colour.notation import HEX_to_RGB
from colour.plotting import (
    CONSTANTS_ARROW_STYLE,
    CONSTANTS_COLOUR_STYLE,
    XYZ_to_plotting_colourspace,
    artist,
    filter_cmfs,
    filter_illuminants,
    override_style,
    render,
    update_settings_collection,
)
from colour.utilities import (
    CanonicalMapping,
    as_float_array,
    domain_range_scale,
    first_item,
    optional,
    tsplit,
    tstack,
    validate_method,
    zeros,
)

__author__ = "Colour Developers"
__copyright__ = "Copyright 2013 Colour Developers"
__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
__maintainer__ = "Colour Developers"
__email__ = "colour-developers@colour-science.org"
__status__ = "Production"

__all__ = [
    "METHODS_CHROMATICITY_DIAGRAM",
    "LABELS_CHROMATICITY_DIAGRAM_DEFAULT",
    "lines_spectral_locus",
    "plot_spectral_locus",
    "plot_chromaticity_diagram_colours",
    "plot_chromaticity_diagram",
    "plot_chromaticity_diagram_CIE1931",
    "plot_chromaticity_diagram_CIE1960UCS",
    "plot_chromaticity_diagram_CIE1976UCS",
    "plot_sds_in_chromaticity_diagram",
    "plot_sds_in_chromaticity_diagram_CIE1931",
    "plot_sds_in_chromaticity_diagram_CIE1960UCS",
    "plot_sds_in_chromaticity_diagram_CIE1976UCS",
]

METHODS_CHROMATICITY_DIAGRAM: CanonicalMapping = CanonicalMapping(
    {
        "CIE 1931": {
            "XYZ_to_ij": lambda a, *args: XYZ_to_xy(a),  # noqa: ARG005
            "ij_to_XYZ": lambda a, *args: xy_to_XYZ(a),  # noqa: ARG005
            "xy_to_ij": lambda a, *args: a,  # noqa: ARG005
            "uv_to_ij": lambda a, *args: UCS_uv_to_xy(a),  # noqa: ARG005
        },
        "CIE 1960 UCS": {
            "XYZ_to_ij": lambda a, *args: UCS_to_uv(  # noqa: ARG005
                XYZ_to_UCS(a)
            ),
            "ij_to_XYZ": lambda a, *args: xy_to_XYZ(  # noqa: ARG005
                UCS_uv_to_xy(a)
            ),
            "xy_to_ij": lambda a, *args: xy_to_UCS_uv(a),  # noqa: ARG005
            "uv_to_ij": lambda a, *args: a,  # noqa: ARG005
        },
        "CIE 1976 UCS": {
            "XYZ_to_ij": lambda a, *args: Luv_to_uv(XYZ_to_Luv(a, *args), *args),
            "ij_to_XYZ": lambda a, *args: xy_to_XYZ(  # noqa: ARG005
                Luv_uv_to_xy(a)
            ),
            "xy_to_ij": lambda a, *args: xy_to_Luv_uv(a),  # noqa: ARG005
            "uv_to_ij": lambda a, *args: xy_to_Luv_uv(  # noqa: ARG005
                UCS_uv_to_xy(a)
            ),
        },
    }
)
"""Chromaticity diagram conversion methods."""

LABELS_CHROMATICITY_DIAGRAM_DEFAULT: CanonicalMapping = CanonicalMapping(
    {
        "CIE 1931": (
            390,
            460,
            470,
            480,
            490,
            500,
            510,
            520,
            540,
            560,
            580,
            600,
            620,
            700,
        ),
        "CIE 1960 UCS": (
            420,
            440,
            450,
            460,
            470,
            480,
            490,
            500,
            510,
            520,
            530,
            540,
            550,
            560,
            570,
            580,
            590,
            600,
            610,
            620,
            630,
            645,
            680,
        ),
        "CIE 1976 UCS": (
            420,
            440,
            450,
            460,
            470,
            480,
            490,
            500,
            510,
            520,
            530,
            540,
            550,
            560,
            570,
            580,
            590,
            600,
            610,
            620,
            630,
            645,
            680,
        ),
    }
)
"""*Chromaticity Diagram* default labels."""


[docs] def lines_spectral_locus( cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", labels: Sequence | None = None, method: (Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"] | str) = "CIE 1931", ) -> Tuple[NDArray, NDArray]: """ Return the *Spectral Locus* line vertices, i.e. positions, normals and colours, according to given method. Parameters ---------- cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. labels Array of wavelength labels used to customise which labels will be drawn around the spectral locus. Passing an empty array will result in no wavelength labels being drawn. method *Chromaticity Diagram* method. Returns ------- :class:`tuple` Tuple of *Spectral Locus* vertices and wavelength labels vertices. Examples -------- >>> lines = lines_spectral_locus() >>> len(lines) 2 >>> lines[0].dtype dtype([('position', '<f8', (2,)), ('normal', '<f8', (2,)), \ ('colour', '<f8', (3,))]) >>> lines[1].dtype dtype([('position', '<f8', (2,)), ('normal', '<f8', (2,)), \ ('colour', '<f8', (3,))]) """ cmfs = cast(MultiSpectralDistributions, first_item(filter_cmfs(cmfs).values())) labels = optional(labels, LABELS_CHROMATICITY_DIAGRAM_DEFAULT[method]) method = validate_method(method, tuple(METHODS_CHROMATICITY_DIAGRAM)) illuminant = CONSTANTS_COLOUR_STYLE.colour.colourspace.whitepoint wavelengths = list(cmfs.wavelengths) equal_energy = np.array([1 / 3] * 2) XYZ_to_ij = METHODS_CHROMATICITY_DIAGRAM[method]["XYZ_to_ij"] ij_to_XYZ = METHODS_CHROMATICITY_DIAGRAM[method]["ij_to_XYZ"] # CMFS ij_cmfs = XYZ_to_ij(cmfs.values, illuminant) # Line of Purples ij_pl = tstack( [ np.linspace(ij_cmfs[-1][0], ij_cmfs[0][0], 20), np.linspace(ij_cmfs[-1][1], ij_cmfs[0][1], 20), ] ) ij_sl = np.vstack([ij_cmfs, ij_pl]) colour_sl = normalise_maximum( XYZ_to_plotting_colourspace(np.reshape(ij_to_XYZ(ij_sl, illuminant), (-1, 3))), axis=-1, ) lines_sl = zeros( ij_sl.shape[0], [ ("position", DTYPE_FLOAT_DEFAULT, 2), ("normal", DTYPE_FLOAT_DEFAULT, 2), ("colour", DTYPE_FLOAT_DEFAULT, 3), ], # pyright: ignore ) lines_sl["position"] = ij_sl lines_sl["colour"] = colour_sl # Labels Normals ij_n, colour_l, normal_l = [], [], [] wl_ij_cmfs = dict(zip(wavelengths, ij_cmfs)) for label in cast(Tuple, labels): ij_l = wl_ij_cmfs.get(label) if ij_l is None: continue i, j = tsplit(ij_l) index = bisect.bisect(wavelengths, label) left = wavelengths[index - 1] if index >= 0 else wavelengths[index] right = wavelengths[index] if index < len(wavelengths) else wavelengths[-1] dx = wl_ij_cmfs[right][0] - wl_ij_cmfs[left][0] dy = wl_ij_cmfs[right][1] - wl_ij_cmfs[left][1] direction = np.array([-dy, dx]) normal = ( np.array([-dy, dx]) if np.dot( normalise_vector(ij_l - equal_energy), normalise_vector(direction), ) > 0 else np.array([dy, -dx]) ) normal = normalise_vector(normal) ij_n.append([[i, j], [i + normal[0] / 50, j + normal[1] / 50]]) normal_l.append([normal, normal]) colour_l.append([ij_l, ij_l]) ij_w = np.reshape(as_float_array(ij_n), (-1, 2)) normal_w = np.reshape(as_float_array(normal_l), (-1, 2)) colours_w = np.reshape(as_float_array(colour_l), (-1, 2)) colour_w = normalise_maximum( XYZ_to_plotting_colourspace( np.reshape(ij_to_XYZ(colours_w, illuminant), (-1, 3)) ), axis=-1, ) lines_w = zeros( ij_w.shape[0], [ ("position", DTYPE_FLOAT_DEFAULT, 2), ("normal", DTYPE_FLOAT_DEFAULT, 2), ("colour", DTYPE_FLOAT_DEFAULT, 3), ], # pyright: ignore ) lines_w["position"] = ij_w lines_w["normal"] = normal_w lines_w["colour"] = colour_w return lines_sl, lines_w
[docs] @override_style() def plot_spectral_locus( cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", spectral_locus_colours: ArrayLike | str | None = None, spectral_locus_opacity: float = 1, spectral_locus_labels: Sequence | None = None, method: (Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"] | str) = "CIE 1931", **kwargs: Any, ) -> Tuple[Figure, Axes]: """ Plot the *Spectral Locus* according to given method. Parameters ---------- cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. spectral_locus_colours Colours of the *Spectral Locus*, if ``spectral_locus_colours`` is set to *RGB*, the colours will be computed according to the corresponding chromaticity coordinates. spectral_locus_opacity Opacity of the *Spectral Locus*. spectral_locus_labels Array of wavelength labels used to customise which labels will be drawn around the spectral locus. Passing an empty array will result in no wavelength labels being drawn. method *Chromaticity Diagram* method. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> plot_spectral_locus(spectral_locus_colours="RGB") # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_Plot_Spectral_Locus.png :align: center :alt: plot_spectral_locus """ method = validate_method(method, tuple(METHODS_CHROMATICITY_DIAGRAM)) spectral_locus_colours = optional( spectral_locus_colours, CONSTANTS_COLOUR_STYLE.colour.dark ) labels = optional( spectral_locus_labels, LABELS_CHROMATICITY_DIAGRAM_DEFAULT[method] ) use_RGB_colours = str(spectral_locus_colours).upper() == "RGB" settings: Dict[str, Any] = {"uniform": True} settings.update(kwargs) _figure, axes = artist(**settings) cmfs = cast(MultiSpectralDistributions, first_item(filter_cmfs(cmfs).values())) lines_sl, lines_w = lines_spectral_locus(cmfs, spectral_locus_labels, method) axes.add_collection( LineCollection( np.reshape( np.concatenate( [lines_sl["position"][:-1], lines_sl["position"][1:]], axis=1, # pyright: ignore ), (-1, 2, 2), ), colors=(lines_sl["colour"] if use_RGB_colours else spectral_locus_colours), alpha=spectral_locus_opacity, zorder=CONSTANTS_COLOUR_STYLE.zorder.background_line, ) ) axes.add_collection( LineCollection( np.reshape(lines_w["position"], (-1, 2, 2)), # pyright: ignore colors=( lines_w["colour"][::2] if use_RGB_colours else spectral_locus_colours ), alpha=spectral_locus_opacity, zorder=CONSTANTS_COLOUR_STYLE.zorder.background_line, ) ) for i, label in enumerate([label for label in labels if label in cmfs.wavelengths]): positions = lines_w["position"][::2] normals = lines_w["normal"][::2] colours = lines_w["colour"][::2] axes.plot( positions[i, 0], positions[i, 1], "o", color=colours[i] if use_RGB_colours else spectral_locus_colours, alpha=spectral_locus_opacity, zorder=CONSTANTS_COLOUR_STYLE.zorder.background_line, ) axes.text( positions[i, 0] + normals[i, 0] / 50 * 1.25, positions[i, 1] + normals[i, 1] / 50 * 1.25, label, clip_on=True, ha="left" if lines_w["normal"][::2][i, 0] >= 0 else "right", va="center", fontsize="x-small-colour-science", zorder=CONSTANTS_COLOUR_STYLE.zorder.background_label, ) settings = {"axes": axes} settings.update(kwargs) return render(**kwargs)
[docs] @override_style() def plot_chromaticity_diagram_colours( samples: int = 256, diagram_colours: ArrayLike | str | None = None, diagram_opacity: float = 1, diagram_clipping_path: ArrayLike | None = None, cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", method: (Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"] | str) = "CIE 1931", **kwargs: Any, ) -> Tuple[Figure, Axes]: """ Plot the *Chromaticity Diagram* colours according to given method. Parameters ---------- samples Sample count on one axis when computing the *Chromaticity Diagram* colours. diagram_colours Colours of the *Chromaticity Diagram*, if ``diagram_colours`` is set to *RGB*, the colours will be computed according to the corresponding coordinates. diagram_opacity Opacity of the *Chromaticity Diagram*. diagram_clipping_path Path of points used to clip the *Chromaticity Diagram* colours. cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. method *Chromaticity Diagram* method. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> plot_chromaticity_diagram_colours(diagram_colours="RGB") ... # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_Plot_Chromaticity_Diagram_Colours.png :align: center :alt: plot_chromaticity_diagram_colours """ method = validate_method(method, ("CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS")) settings: Dict[str, Any] = {"uniform": True} settings.update(kwargs) _figure, axes = artist(**settings) diagram_colours = optional( diagram_colours, HEX_to_RGB(CONSTANTS_COLOUR_STYLE.colour.average) ) cmfs = cast(MultiSpectralDistributions, first_item(filter_cmfs(cmfs).values())) illuminant = CONSTANTS_COLOUR_STYLE.colour.colourspace.whitepoint XYZ_to_ij = METHODS_CHROMATICITY_DIAGRAM[method]["XYZ_to_ij"] spectral_locus = XYZ_to_ij(cmfs.values, illuminant) use_RGB_diagram_colours = str(diagram_colours).upper() == "RGB" if use_RGB_diagram_colours: ii, jj = np.meshgrid(np.linspace(0, 1, samples), np.linspace(1, 0, samples)) ij = tstack([ii, jj]) ij_to_XYZ = METHODS_CHROMATICITY_DIAGRAM[method]["ij_to_XYZ"] diagram_colours = normalise_maximum( XYZ_to_plotting_colourspace(ij_to_XYZ(ij), illuminant), axis=-1 ) polygon = Polygon( (spectral_locus if diagram_clipping_path is None else diagram_clipping_path), facecolor=( "none" if use_RGB_diagram_colours else np.hstack([diagram_colours, diagram_opacity]) ), edgecolor=( "none" if use_RGB_diagram_colours else np.hstack([diagram_colours, diagram_opacity]) ), zorder=CONSTANTS_COLOUR_STYLE.zorder.background_polygon, ) axes.add_patch(polygon) if use_RGB_diagram_colours: # Preventing bounding box related issues as per # https://github.com/matplotlib/matplotlib/issues/10529 image = axes.imshow( diagram_colours, interpolation="bilinear", extent=(0, 1, 0, 1), clip_path=None, alpha=diagram_opacity, zorder=CONSTANTS_COLOUR_STYLE.zorder.background_polygon, ) image.set_clip_path(polygon) settings = {"axes": axes} settings.update(kwargs) return render(**kwargs)
[docs] @override_style() def plot_chromaticity_diagram( cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", show_diagram_colours: bool = True, show_spectral_locus: bool = True, method: (Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"] | str) = "CIE 1931", **kwargs: Any, ) -> Tuple[Figure, Axes]: """ Plot the *Chromaticity Diagram* according to given method. Parameters ---------- cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. show_diagram_colours Whether to display the *Chromaticity Diagram* background colours. show_spectral_locus Whether to display the *Spectral Locus*. method *Chromaticity Diagram* method. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_spectral_locus`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram_colours`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> plot_chromaticity_diagram() # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_Plot_Chromaticity_Diagram.png :align: center :alt: plot_chromaticity_diagram """ method = validate_method(method, ("CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS")) settings: Dict[str, Any] = {"uniform": True} settings.update(kwargs) _figure, axes = artist(**settings) cmfs = cast(MultiSpectralDistributions, first_item(filter_cmfs(cmfs).values())) if show_diagram_colours: settings = {"axes": axes, "method": method, "diagram_colours": "RGB"} settings.update(kwargs) settings["show"] = False settings["cmfs"] = cmfs plot_chromaticity_diagram_colours(**settings) if show_spectral_locus: settings = {"axes": axes, "method": method} settings.update(kwargs) settings["show"] = False settings["cmfs"] = cmfs plot_spectral_locus(**settings) if method == "cie 1931": x_label, y_label = "CIE x", "CIE y" elif method == "cie 1960 ucs": x_label, y_label = "CIE u", "CIE v" elif method == "cie 1976 ucs": x_label, y_label = ( "CIE u'", "CIE v'", ) title = f"{method.upper()} Chromaticity Diagram - {cmfs.display_name}" settings.update( { "axes": axes, "show": True, "bounding_box": (0, 1, 0, 1), "title": title, "x_label": x_label, "y_label": y_label, } ) settings.update(kwargs) return render(**settings)
[docs] @override_style() 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 Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. show_diagram_colours Whether to display the *Chromaticity Diagram* background colours. show_spectral_locus Whether to display the *Spectral Locus*. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> plot_chromaticity_diagram_CIE1931() # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_Plot_Chromaticity_Diagram_CIE1931.png :align: center :alt: plot_chromaticity_diagram_CIE1931 """ settings = dict(kwargs) settings.update({"method": "CIE 1931"}) return plot_chromaticity_diagram( cmfs, show_diagram_colours, show_spectral_locus, **settings )
[docs] @override_style() 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 Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. show_diagram_colours Whether to display the *Chromaticity Diagram* background colours. show_spectral_locus Whether to display the *Spectral Locus*. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> plot_chromaticity_diagram_CIE1960UCS() # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_Plot_Chromaticity_Diagram_CIE1960UCS.png :align: center :alt: plot_chromaticity_diagram_CIE1960UCS """ settings = dict(kwargs) settings.update({"method": "CIE 1960 UCS"}) return plot_chromaticity_diagram( cmfs, show_diagram_colours, show_spectral_locus, **settings )
[docs] @override_style() 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 Chromaticity Diagram*. Parameters ---------- cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. show_diagram_colours Whether to display the *Chromaticity Diagram* background colours. show_spectral_locus Whether to display the *Spectral Locus*. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> plot_chromaticity_diagram_CIE1976UCS() # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_Plot_Chromaticity_Diagram_CIE1976UCS.png :align: center :alt: plot_chromaticity_diagram_CIE1976UCS """ settings = dict(kwargs) settings.update({"method": "CIE 1976 UCS"}) return plot_chromaticity_diagram( cmfs, show_diagram_colours, show_spectral_locus, **settings )
[docs] @override_style() def plot_sds_in_chromaticity_diagram( sds: ( Sequence[SpectralDistribution | MultiSpectralDistributions] | SpectralDistribution | MultiSpectralDistributions ), cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", chromaticity_diagram_callable: Callable = plot_chromaticity_diagram, method: (Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"] | str) = "CIE 1931", annotate_kwargs: dict | List[dict] | None = None, plot_kwargs: dict | List[dict] | None = None, **kwargs: Any, ) -> Tuple[Figure, Axes]: """ Plot given spectral distribution chromaticity coordinates into the *Chromaticity Diagram* using given method. Parameters ---------- sds Spectral distributions or multi-spectral distributions to plot. `sds` can be a single :class:`colour.MultiSpectralDistributions` class instance, a list of :class:`colour.MultiSpectralDistributions` class instances or a List of :class:`colour.SpectralDistribution` class instances. cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. chromaticity_diagram_callable Callable responsible for drawing the *Chromaticity Diagram*. method *Chromaticity Diagram* method. annotate_kwargs Keyword arguments for the :func:`matplotlib.pyplot.annotate` definition, used to annotate the resulting chromaticity coordinates with their respective spectral distribution names. ``annotate_kwargs`` can be either a single dictionary applied to all the arrows with same settings or a sequence of dictionaries with different settings for each spectral distribution. The following special keyword arguments can also be used: - ``annotate`` : Whether to annotate the spectral distributions. plot_kwargs Keyword arguments for the :func:`matplotlib.pyplot.plot` definition, used to control the style of the plotted spectral distributions. `plot_kwargs`` can be either a single dictionary applied to all the plotted spectral distributions with the same settings or a sequence of dictionaries with different settings for each plotted spectral distributions. The following special keyword arguments can also be used: - ``illuminant`` : The illuminant used to compute the spectral distributions colours. The default is the illuminant associated with the whitepoint of the default plotting colourspace. ``illuminant`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``cmfs`` : The standard observer colour matching functions used for computing the spectral distributions colours. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``normalise_sd_colours`` : Whether to normalise the computed spectral distributions colours. The default is *True*. - ``use_sd_colours`` : Whether to use the computed spectral distributions colours under the plotting colourspace illuminant. Alternatively, it is possible to use the :func:`matplotlib.pyplot.plot` definition ``color`` argument with pre-computed values. The default is *True*. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> A = SDS_ILLUMINANTS["A"] >>> D65 = SDS_ILLUMINANTS["D65"] >>> annotate_kwargs = [ ... {"xytext": (-25, 15), "arrowprops": {"arrowstyle": "-"}}, ... {}, ... ] >>> plot_kwargs = [ ... { ... "illuminant": SDS_ILLUMINANTS["E"], ... "markersize": 15, ... "normalise_sd_colours": True, ... "use_sd_colours": True, ... }, ... {"illuminant": SDS_ILLUMINANTS["E"]}, ... ] >>> plot_sds_in_chromaticity_diagram( ... [A, D65], annotate_kwargs=annotate_kwargs, plot_kwargs=plot_kwargs ... ) ... # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_Plot_SDS_In_Chromaticity_Diagram.png :align: center :alt: plot_sds_in_chromaticity_diagram """ method = validate_method(method, ("CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS")) sds_converted = sds_and_msds_to_sds(sds) settings: Dict[str, Any] = {"uniform": True} settings.update(kwargs) _figure, axes = artist(**settings) settings.update( { "axes": axes, "show": False, "method": method, "cmfs": cmfs, } ) chromaticity_diagram_callable(**settings) XYZ_to_ij = METHODS_CHROMATICITY_DIAGRAM[method]["XYZ_to_ij"] if method == "cie 1931": bounding_box = (-0.1, 0.9, -0.1, 0.9) elif method == "cie 1960 ucs": bounding_box = (-0.1, 0.7, -0.2, 0.6) elif method == "cie 1976 ucs": bounding_box = (-0.1, 0.7, -0.1, 0.7) annotate_settings_collection = [ { "annotate": True, "xytext": (-50, 30), "textcoords": "offset points", "arrowprops": CONSTANTS_ARROW_STYLE, "zorder": CONSTANTS_COLOUR_STYLE.zorder.midground_annotation, } for _ in range(len(sds_converted)) ] if annotate_kwargs is not None: update_settings_collection( annotate_settings_collection, annotate_kwargs, len(sds_converted) ) plot_settings_collection = [ { "color": CONSTANTS_COLOUR_STYLE.colour.brightest, "label": f"{sd.display_name}", "marker": "o", "markeredgecolor": CONSTANTS_COLOUR_STYLE.colour.dark, "markeredgewidth": CONSTANTS_COLOUR_STYLE.geometry.short * 0.75, "markersize": ( CONSTANTS_COLOUR_STYLE.geometry.short * 6 + CONSTANTS_COLOUR_STYLE.geometry.short * 0.75 ), "zorder": CONSTANTS_COLOUR_STYLE.zorder.midground_line, "cmfs": cmfs, "illuminant": SDS_ILLUMINANTS["E"], "use_sd_colours": False, "normalise_sd_colours": False, } for sd in sds_converted ] if plot_kwargs is not None: update_settings_collection( plot_settings_collection, plot_kwargs, len(sds_converted) ) for i, sd in enumerate(sds_converted): plot_settings = plot_settings_collection[i] cmfs = cast( MultiSpectralDistributions, first_item(filter_cmfs(plot_settings.pop("cmfs")).values()), ) illuminant = cast( SpectralDistribution, first_item(filter_illuminants(plot_settings.pop("illuminant")).values()), ) normalise_sd_colours = plot_settings.pop("normalise_sd_colours") use_sd_colours = plot_settings.pop("use_sd_colours") with domain_range_scale("1"): XYZ = sd_to_XYZ(sd, cmfs, illuminant) if use_sd_colours: if normalise_sd_colours: XYZ /= XYZ[..., 1] plot_settings["color"] = np.clip(XYZ_to_plotting_colourspace(XYZ), 0, 1) ij = cast(tuple[float, float], XYZ_to_ij(XYZ)) axes.plot(ij[0], ij[1], **plot_settings) if sd.name is not None and annotate_settings_collection[i]["annotate"]: annotate_settings = annotate_settings_collection[i] annotate_settings.pop("annotate") axes.annotate(sd.name, xy=ij, **annotate_settings) settings.update({"show": True, "bounding_box": bounding_box}) settings.update(kwargs) return render(**settings)
[docs] @override_style() def plot_sds_in_chromaticity_diagram_CIE1931( sds: ( Sequence[SpectralDistribution | MultiSpectralDistributions] | MultiSpectralDistributions ), cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", chromaticity_diagram_callable_CIE1931: Callable = ( plot_chromaticity_diagram_CIE1931 ), annotate_kwargs: dict | List[dict] | None = None, plot_kwargs: dict | List[dict] | None = None, **kwargs: Any, ) -> Tuple[Figure, Axes]: """ Plot given spectral distribution chromaticity coordinates into the *CIE 1931 Chromaticity Diagram*. Parameters ---------- sds Spectral distributions or multi-spectral distributions to plot. `sds` can be a single :class:`colour.MultiSpectralDistributions` class instance, a list of :class:`colour.MultiSpectralDistributions` class instances or a list of :class:`colour.SpectralDistribution` class instances. cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. chromaticity_diagram_callable_CIE1931 Callable responsible for drawing the *CIE 1931 Chromaticity Diagram*. annotate_kwargs Keyword arguments for the :func:`matplotlib.pyplot.annotate` definition, used to annotate the resulting chromaticity coordinates with their respective spectral distribution names. ``annotate_kwargs`` can be either a single dictionary applied to all the arrows with same settings or a sequence of dictionaries with different settings for each spectral distribution. The following special keyword arguments can also be used: - ``annotate`` : Whether to annotate the spectral distributions. plot_kwargs Keyword arguments for the :func:`matplotlib.pyplot.plot` definition, used to control the style of the plotted spectral distributions. `plot_kwargs`` can be either a single dictionary applied to all the plotted spectral distributions with the same settings or a sequence of dictionaries with different settings for each plotted spectral distributions. The following special keyword arguments can also be used: - ``illuminant`` : The illuminant used to compute the spectral distributions colours. The default is the illuminant associated with the whitepoint of the default plotting colourspace. ``illuminant`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``cmfs`` : The standard observer colour matching functions used for computing the spectral distributions colours. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``normalise_sd_colours`` : Whether to normalise the computed spectral distributions colours. The default is *True*. - ``use_sd_colours`` : Whether to use the computed spectral distributions colours under the plotting colourspace illuminant. Alternatively, it is possible to use the :func:`matplotlib.pyplot.plot` definition ``color`` argument with pre-computed values. The default is *True*. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> A = SDS_ILLUMINANTS["A"] >>> D65 = SDS_ILLUMINANTS["D65"] >>> plot_sds_in_chromaticity_diagram_CIE1931([A, D65]) ... # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_\ Plot_SDS_In_Chromaticity_Diagram_CIE1931.png :align: center :alt: plot_sds_in_chromaticity_diagram_CIE1931 """ settings = dict(kwargs) settings.update({"method": "CIE 1931"}) return plot_sds_in_chromaticity_diagram( sds, cmfs, chromaticity_diagram_callable_CIE1931, annotate_kwargs=annotate_kwargs, plot_kwargs=plot_kwargs, **settings, )
[docs] @override_style() def plot_sds_in_chromaticity_diagram_CIE1960UCS( sds: ( Sequence[SpectralDistribution | MultiSpectralDistributions] | MultiSpectralDistributions ), cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", chromaticity_diagram_callable_CIE1960UCS: Callable = ( plot_chromaticity_diagram_CIE1960UCS ), annotate_kwargs: dict | List[dict] | None = None, plot_kwargs: dict | List[dict] | None = None, **kwargs: Any, ) -> Tuple[Figure, Axes]: """ Plot given spectral distribution chromaticity coordinates into the *CIE 1960 UCS Chromaticity Diagram*. Parameters ---------- sds Spectral distributions or multi-spectral distributions to plot. `sds` can be a single :class:`colour.MultiSpectralDistributions` class instance, a list of :class:`colour.MultiSpectralDistributions` class instances or a list of :class:`colour.SpectralDistribution` class instances. cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. chromaticity_diagram_callable_CIE1960UCS Callable responsible for drawing the *CIE 1960 UCS Chromaticity Diagram*. annotate_kwargs Keyword arguments for the :func:`matplotlib.pyplot.annotate` definition, used to annotate the resulting chromaticity coordinates with their respective spectral distribution names. ``annotate_kwargs`` can be either a single dictionary applied to all the arrows with same settings or a sequence of dictionaries with different settings for each spectral distribution. The following special keyword arguments can also be used: - ``annotate`` : Whether to annotate the spectral distributions. plot_kwargs Keyword arguments for the :func:`matplotlib.pyplot.plot` definition, used to control the style of the plotted spectral distributions. `plot_kwargs`` can be either a single dictionary applied to all the plotted spectral distributions with the same settings or a sequence of dictionaries with different settings for each plotted spectral distributions. The following special keyword arguments can also be used: - ``illuminant`` : The illuminant used to compute the spectral distributions colours. The default is the illuminant associated with the whitepoint of the default plotting colourspace. ``illuminant`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``cmfs`` : The standard observer colour matching functions used for computing the spectral distributions colours. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``normalise_sd_colours`` : Whether to normalise the computed spectral distributions colours. The default is *True*. - ``use_sd_colours`` : Whether to use the computed spectral distributions colours under the plotting colourspace illuminant. Alternatively, it is possible to use the :func:`matplotlib.pyplot.plot` definition ``color`` argument with pre-computed values. The default is *True*. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> A = SDS_ILLUMINANTS["A"] >>> D65 = SDS_ILLUMINANTS["D65"] >>> plot_sds_in_chromaticity_diagram_CIE1960UCS([A, D65]) ... # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_\ Plot_SDS_In_Chromaticity_Diagram_CIE1960UCS.png :align: center :alt: plot_sds_in_chromaticity_diagram_CIE1960UCS """ settings = dict(kwargs) settings.update({"method": "CIE 1960 UCS"}) return plot_sds_in_chromaticity_diagram( sds, cmfs, chromaticity_diagram_callable_CIE1960UCS, annotate_kwargs=annotate_kwargs, plot_kwargs=plot_kwargs, **settings, )
[docs] @override_style() def plot_sds_in_chromaticity_diagram_CIE1976UCS( sds: ( Sequence[SpectralDistribution | MultiSpectralDistributions] | MultiSpectralDistributions ), cmfs: ( MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str] ) = "CIE 1931 2 Degree Standard Observer", chromaticity_diagram_callable_CIE1976UCS: Callable = ( plot_chromaticity_diagram_CIE1976UCS ), annotate_kwargs: dict | List[dict] | None = None, plot_kwargs: dict | List[dict] | None = None, **kwargs: Any, ) -> Tuple[Figure, Axes]: """ Plot given spectral distribution chromaticity coordinates into the *CIE 1976 UCS Chromaticity Diagram*. Parameters ---------- sds Spectral distributions or multi-spectral distributions to plot. `sds` can be a single :class:`colour.MultiSpectralDistributions` class instance, a list of :class:`colour.MultiSpectralDistributions` class instances or a list of :class:`colour.SpectralDistribution` class instances. cmfs Standard observer colour matching functions used for computing the spectral locus boundaries. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. chromaticity_diagram_callable_CIE1976UCS Callable responsible for drawing the *CIE 1976 UCS Chromaticity Diagram*. annotate_kwargs Keyword arguments for the :func:`matplotlib.pyplot.annotate` definition, used to annotate the resulting chromaticity coordinates with their respective spectral distribution names. ``annotate_kwargs`` can be either a single dictionary applied to all the arrows with same settings or a sequence of dictionaries with different settings for each spectral distribution. The following special keyword arguments can also be used: - ``annotate`` : Whether to annotate the spectral distributions. plot_kwargs Keyword arguments for the :func:`matplotlib.pyplot.plot` definition, used to control the style of the plotted spectral distributions. `plot_kwargs`` can be either a single dictionary applied to all the plotted spectral distributions with the same settings or a sequence of dictionaries with different settings for each plotted spectral distributions. The following special keyword arguments can also be used: - ``illuminant`` : The illuminant used to compute the spectral distributions colours. The default is the illuminant associated with the whitepoint of the default plotting colourspace. ``illuminant`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``cmfs`` : The standard observer colour matching functions used for computing the spectral distributions colours. ``cmfs`` can be of any type or form supported by the :func:`colour.plotting.common.filter_cmfs` definition. - ``normalise_sd_colours`` : Whether to normalise the computed spectral distributions colours. The default is *True*. - ``use_sd_colours`` : Whether to use the computed spectral distributions colours under the plotting colourspace illuminant. Alternatively, it is possible to use the :func:`matplotlib.pyplot.plot` definition ``color`` argument with pre-computed values. The default is *True*. Other Parameters ---------------- kwargs {:func:`colour.plotting.artist`, :func:`colour.plotting.diagrams.plot_chromaticity_diagram`, :func:`colour.plotting.render`}, See the documentation of the previously listed definitions. Returns ------- :class:`tuple` Current figure and axes. Examples -------- >>> A = SDS_ILLUMINANTS["A"] >>> D65 = SDS_ILLUMINANTS["D65"] >>> plot_sds_in_chromaticity_diagram_CIE1976UCS([A, D65]) ... # doctest: +ELLIPSIS (<Figure size ... with 1 Axes>, <...Axes...>) .. image:: ../_static/Plotting_\ Plot_SDS_In_Chromaticity_Diagram_CIE1976UCS.png :align: center :alt: plot_sds_in_chromaticity_diagram_CIE1976UCS """ settings = dict(kwargs) settings.update({"method": "CIE 1976 UCS"}) return plot_sds_in_chromaticity_diagram( sds, cmfs, chromaticity_diagram_callable_CIE1976UCS, annotate_kwargs=annotate_kwargs, plot_kwargs=plot_kwargs, **settings, )