4333918782

Build Type

push

github-actions

Committed by Thomas Mansencal

Commit Message

Add "planckian_locus_iso_temperature_lines_D_uv" kwargs to "colour.plotting.temperature.plot_planckian_locus" definition.

Run Details

1 of 1 new or added line in 1 file covered. (100.0%)

29863 of 38610 relevant lines covered (77.35%)

0.77 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

76.36

/colour/plotting/temperature.py

"""
Colour Temperature & Correlated Colour Temperature Plotting
===========================================================

Defines the colour temperature and correlated colour temperature plotting
objects:

-   :func:`colour.plotting.\
plot_planckian_locus_in_chromaticity_diagram_CIE1931`
-   :func:`colour.plotting.\
plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS`
"""

from __future__ import annotations

import matplotlib.pyplot as plt
import numpy as np
from matplotlib.collections import LineCollection

from colour.algebra import normalise_maximum
from colour.colorimetry import MSDS_CMFS, CCS_ILLUMINANTS
from colour.hints import (
    Any,
    ArrayLike,
    Callable,
    Dict,
    List,
    Literal,
    NDArrayFloat,
    Sequence,
    Tuple,
    cast,
)
from colour.models import (
    UCS_to_uv,
    UCS_uv_to_xy,
    XYZ_to_UCS,
    xy_to_Luv_uv,
    xy_to_XYZ,
)
from colour.temperature import mired_to_CCT, CCT_to_uv
from colour.plotting import (
    CONSTANTS_COLOUR_STYLE,
    CONSTANTS_ARROW_STYLE,
    XYZ_to_plotting_colourspace,
    artist,
    plot_chromaticity_diagram_CIE1931,
    plot_chromaticity_diagram_CIE1960UCS,
    filter_passthrough,
    override_style,
    render,
    update_settings_collection,
)
from colour.plotting.diagrams import plot_chromaticity_diagram
from colour.utilities import (
    as_int_scalar,
    as_float_scalar,
    full,
    optional,
    tstack,
    validate_method,
    zeros,
)

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

__all__ = [
    "plot_planckian_locus",
    "plot_planckian_locus_in_chromaticity_diagram",
    "plot_planckian_locus_in_chromaticity_diagram_CIE1931",
    "plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS",
]


@override_style()
def plot_planckian_locus(
    planckian_locus_colours: ArrayLike | str | None = None,
    planckian_locus_opacity: float = 1,
    planckian_locus_labels: Sequence | None = None,
    planckian_locus_use_mireds: bool = False,
    planckian_locus_iso_temperature_lines_D_uv: float = 0.05,
    method: Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"]
    | str = "CIE 1931",
    **kwargs: Any,
) -> Tuple[plt.Figure, plt.Axes]:
    """
    Plot the *Planckian Locus* according to given method.

    Parameters
    ----------
    planckian_locus_colours
        Colours of the *Planckian Locus*, if ``planckian_locus_colours`` is set
        to *RGB*, the colours will be computed according to the corresponding
        chromaticity coordinates.
    planckian_locus_opacity
       Opacity of the *Planckian Locus*.
    planckian_locus_labels
        Array of labels used to customise which iso-temperature lines will be
        drawn along the *Planckian Locus*. Passing an empty array will result
        in no iso-temperature lines being drawn.
    planckian_locus_use_mireds
        Whether to use micro reciprocal degrees for the iso-temperature lines.
    planckian_locus_iso_temperature_lines_D_uv
        Iso-temperature lines :math:`\\Delta_{uv}` length on each side of the
        *Planckian Locus*.

    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_planckian_locus(
    ...     planckian_locus_colours="RGB",
    ...     method="CIE 1960 UCS",
    ...     use_mireds=True,
    ... )
    ... # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_Plot_Planckian_Locus.png
        :align: center
        :alt: plot_planckian_locus
    """

    method = validate_method(
        method, ["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"]
    )

    planckian_locus_colours = optional(
        planckian_locus_colours, CONSTANTS_COLOUR_STYLE.colour.dark
    )

    labels = cast(
        tuple,
        optional(
            planckian_locus_labels,
            (0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000)
            if planckian_locus_use_mireds
            else (1e6 / 600, 2000, 2500, 3000, 4000, 6000, 1e6 / 100),
        ),
    )
    D_uv = planckian_locus_iso_temperature_lines_D_uv

    settings: Dict[str, Any] = {"uniform": True}
    settings.update(kwargs)

    _figure, axes = artist(**settings)

    if method == "cie 1931":

        def uv_to_ij(uv: NDArrayFloat) -> NDArrayFloat:
            """
            Convert given *uv* chromaticity coordinates to *ij* chromaticity
            coordinates.
            """

            return UCS_uv_to_xy(uv)

    elif method == "cie 1960 ucs":

        def uv_to_ij(uv: NDArrayFloat) -> NDArrayFloat:
            """
            Convert given *uv* chromaticity coordinates to *ij* chromaticity
            coordinates.
            """

            return uv

    elif method == "cie 1976 ucs":

        def uv_to_ij(uv: NDArrayFloat) -> NDArrayFloat:
            """
            Convert given *uv* chromaticity coordinates to *ij* chromaticity
            coordinates.
            """

            return xy_to_Luv_uv(UCS_uv_to_xy(uv))

    def CCT_D_uv_to_plotting_colourspace(CCT_D_uv):
        """
        Convert given *uv* chromaticity coordinates to the default plotting
        colourspace.
        """

        return normalise_maximum(
            XYZ_to_plotting_colourspace(
                xy_to_XYZ(UCS_uv_to_xy(CCT_to_uv(CCT_D_uv, "Robertson 1968")))
            ),
            axis=-1,
        )

    start, end = (
        (0, 1000) if planckian_locus_use_mireds else (1e6 / 600, 1e6 / 10)
    )

    CCT = np.arange(start, end + 100, 10)
    CCT = mired_to_CCT(CCT) if planckian_locus_use_mireds else CCT
    CCT_D_uv = np.reshape(tstack([CCT, zeros(CCT.shape)]), (-1, 1, 2))
    ij = uv_to_ij(CCT_to_uv(CCT_D_uv, "Robertson 1968"))

    use_RGB_planckian_locus_colours = (
        str(planckian_locus_colours).upper() == "RGB"
    )
    if use_RGB_planckian_locus_colours:
        pl_colours = CCT_D_uv_to_plotting_colourspace(CCT_D_uv)
    else:
        pl_colours = planckian_locus_colours

    line_collection = LineCollection(
        np.concatenate([ij[:-1], ij[1:]], axis=1),
        colors=pl_colours,
        alpha=planckian_locus_opacity,
        zorder=CONSTANTS_COLOUR_STYLE.zorder.foreground_line,
    )
    axes.add_collection(line_collection)

    for label in labels:
        CCT_D_uv = np.reshape(
            tstack(
                [
                    full(
                        10,
                        as_float_scalar(mired_to_CCT(label))
                        if planckian_locus_use_mireds
                        else label,
                    ),
                    np.linspace(-D_uv, D_uv, 10),
                ]
            ),
            (-1, 1, 2),
        )

        if use_RGB_planckian_locus_colours:
            itl_colours = CCT_D_uv_to_plotting_colourspace(CCT_D_uv)
        else:
            itl_colours = planckian_locus_colours

        ij = uv_to_ij(CCT_to_uv(CCT_D_uv, "Robertson 1968"))

        line_collection = LineCollection(
            np.concatenate([ij[:-1], ij[1:]], axis=1),
            colors=itl_colours,
            alpha=planckian_locus_opacity,
            zorder=CONSTANTS_COLOUR_STYLE.zorder.foreground_line,
        )
        axes.add_collection(line_collection)
        axes.annotate(
            f'{as_int_scalar(label)}{"M" if planckian_locus_use_mireds else "K"}',
            xy=(ij[-1, :, 0], ij[-1, :, 1]),
            xytext=(0, CONSTANTS_COLOUR_STYLE.geometry.long / 2),
            textcoords="offset points",
            size="x-small",
            zorder=CONSTANTS_COLOUR_STYLE.zorder.foreground_label,
        )

    settings = {"axes": axes}
    settings.update(kwargs)

    return render(**settings)


@override_style()
def plot_planckian_locus_in_chromaticity_diagram(
    illuminants: str | Sequence[str],
    chromaticity_diagram_callable: Callable = plot_chromaticity_diagram,
    method: Literal["CIE 1931", "CIE 1960 UCS"] | str = "CIE 1931",
    annotate_kwargs: dict | List[dict] | None = None,
    plot_kwargs: dict | List[dict] | None = None,
    **kwargs: Any,
) -> Tuple[plt.Figure, plt.Axes]:
    """
    Plot the *Planckian Locus* and given illuminants in the
    *Chromaticity Diagram* according to given method.

    Parameters
    ----------
    illuminants
        Illuminants to plot. ``illuminants`` elements can be of any
        type or form supported by the
        :func:`colour.plotting.common.filter_passthrough` 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 illuminants. ``plot_kwargs``
        can be either a single dictionary applied to all the plotted
        illuminants with the same settings or a sequence of dictionaries with
        different settings for eachplotted illuminant.

    Other Parameters
    ----------------
    kwargs
        {:func:`colour.plotting.artist`,
        :func:`colour.plotting.diagrams.plot_chromaticity_diagram`,
        :func:`colour.plotting.temperature.plot_planckian_locus`,
        :func:`colour.plotting.render`},
        See the documentation of the previously listed definitions.

    Returns
    -------
    :class:`tuple`
        Current figure and axes.

    Examples
    --------
    >>> annotate_kwargs = [
    ...     {"xytext": (-25, 15), "arrowprops": {"arrowstyle": "-"}},
    ...     {"arrowprops": {"arrowstyle": "-["}},
    ...     {},
    ... ]
    >>> plot_kwargs = [
    ...     {
    ...         "markersize": 15,
    ...     },
    ...     {"color": "r"},
    ...     {},
    ... ]
    >>> plot_planckian_locus_in_chromaticity_diagram(
    ...     ["A", "B", "C"],
    ...     annotate_kwargs=annotate_kwargs,
    ...     plot_kwargs=plot_kwargs,
    ... )  # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_\
Plot_Planckian_Locus_In_Chromaticity_Diagram.png
        :align: center
        :alt: plot_planckian_locus_in_chromaticity_diagram
    """

    method = validate_method(method, ["CIE 1931", "CIE 1960 UCS"])

    cmfs = MSDS_CMFS["CIE 1931 2 Degree Standard Observer"]

    illuminants_filtered = filter_passthrough(
        CCS_ILLUMINANTS[cmfs.name], illuminants
    )

    settings: Dict[str, Any] = {"uniform": True}
    settings.update(kwargs)

    _figure, axes = artist(**settings)

    method = method.upper()

    settings = {"axes": axes, "method": method}
    settings.update(kwargs)
    settings["standalone"] = False

    chromaticity_diagram_callable(**settings)

    plot_planckian_locus(**settings)

    if method == "CIE 1931":

        def xy_to_ij(xy: NDArrayFloat) -> NDArrayFloat:
            """
            Convert given *CIE xy* chromaticity coordinates to *ij*
            chromaticity coordinates.
            """

            return xy

        bounding_box = (-0.1, 0.9, -0.1, 0.9)
    elif method == "CIE 1960 UCS":

        def xy_to_ij(xy: NDArrayFloat) -> NDArrayFloat:
            """
            Convert given *CIE xy* chromaticity coordinates to *ij*
            chromaticity coordinates.
            """

            return UCS_to_uv(XYZ_to_UCS(xy_to_XYZ(xy)))

        bounding_box = (-0.1, 0.7, -0.2, 0.6)

    annotate_settings_collection = [
        {
            "annotate": True,
            "xytext": (-50, 30),
            "textcoords": "offset points",
            "arrowprops": CONSTANTS_ARROW_STYLE,
            "zorder": CONSTANTS_COLOUR_STYLE.zorder.foreground_annotation,
        }
        for _ in range(len(illuminants_filtered))
    ]

    if annotate_kwargs is not None:
        update_settings_collection(
            annotate_settings_collection,
            annotate_kwargs,
            len(illuminants_filtered),
        )

    plot_settings_collection = [
        {
            "color": CONSTANTS_COLOUR_STYLE.colour.brightest,
            "label": f"{illuminant}",
            "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.foreground_line,
        }
        for illuminant in illuminants_filtered
    ]

    if plot_kwargs is not None:
        update_settings_collection(
            plot_settings_collection, plot_kwargs, len(illuminants_filtered)
        )

    for i, (illuminant, xy) in enumerate(illuminants_filtered.items()):
        plot_settings = plot_settings_collection[i]

        ij = xy_to_ij(xy)

        axes.plot(ij[0], ij[1], **plot_settings)

        if annotate_settings_collection[i]["annotate"]:
            annotate_settings = annotate_settings_collection[i]
            annotate_settings.pop("annotate")

            axes.annotate(illuminant, xy=ij, **annotate_settings)

    title = (
        (
            f"{', '.join(illuminants_filtered)} Illuminants - Planckian Locus\n"
            f"{method.upper()} Chromaticity Diagram - "
            "CIE 1931 2 Degree Standard Observer"
        )
        if illuminants_filtered
        else (
            f"Planckian Locus\n{method.upper()} Chromaticity Diagram - "
            f"CIE 1931 2 Degree Standard Observer"
        )
    )

    settings.update(
        {
            "axes": axes,
            "standalone": True,
            "bounding_box": bounding_box,
            "title": title,
        }
    )
    settings.update(kwargs)

    return render(**settings)


@override_style()
def plot_planckian_locus_in_chromaticity_diagram_CIE1931(
    illuminants: str | Sequence[str],
    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[plt.Figure, plt.Axes]:
    """
    Plot the *Planckian Locus* and given illuminants in
    *CIE 1931 Chromaticity Diagram*.

    Parameters
    ----------
    illuminants
        Illuminants to plot. ``illuminants`` elements can be of any
        type or form supported by the
        :func:`colour.plotting.common.filter_passthrough` 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 illuminants. ``plot_kwargs``
        can be either a single dictionary applied to all the plotted
        illuminants with the same settings or a sequence of dictionaries with
        different settings for eachplotted illuminant.

    Other Parameters
    ----------------
    kwargs
        {:func:`colour.plotting.artist`,
        :func:`colour.plotting.diagrams.plot_chromaticity_diagram`,
        :func:`colour.plotting.temperature.plot_planckian_locus`,
        :func:`colour.plotting.temperature.\
plot_planckian_locus_in_chromaticity_diagram`,
        :func:`colour.plotting.render`},
        See the documentation of the previously listed definitions.

    Returns
    -------
    :class:`tuple`
        Current figure and axes.

    Examples
    --------
    >>> plot_planckian_locus_in_chromaticity_diagram_CIE1931(["A", "B", "C"])
    ... # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_\
Plot_Planckian_Locus_In_Chromaticity_Diagram_CIE1931.png
        :align: center
        :alt: plot_planckian_locus_in_chromaticity_diagram_CIE1931
    """

    settings = dict(kwargs)
    settings.update({"method": "CIE 1931"})

    return plot_planckian_locus_in_chromaticity_diagram(
        illuminants,
        chromaticity_diagram_callable_CIE1931,
        annotate_kwargs=annotate_kwargs,
        plot_kwargs=plot_kwargs,
        **settings,
    )


@override_style()
def plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
    illuminants: str | Sequence[str],
    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[plt.Figure, plt.Axes]:
    """
    Plot the *Planckian Locus* and given illuminants in
    *CIE 1960 UCS Chromaticity Diagram*.

    Parameters
    ----------
    illuminants
        Illuminants to plot. ``illuminants`` elements can be of any
        type or form supported by the
        :func:`colour.plotting.common.filter_passthrough` 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 illuminants. ``plot_kwargs``
        can be either a single dictionary applied to all the plotted
        illuminants with the same settings or a sequence of dictionaries with
        different settings for eachplotted illuminant.

    Other Parameters
    ----------------
    kwargs
        {:func:`colour.plotting.artist`,
        :func:`colour.plotting.diagrams.plot_chromaticity_diagram`,
        :func:`colour.plotting.temperature.plot_planckian_locus`,
        :func:`colour.plotting.temperature.\
plot_planckian_locus_in_chromaticity_diagram`,
        :func:`colour.plotting.render`},
        See the documentation of the previously listed definitions.

    Returns
    -------
    :class:`tuple`
        Current figure and axes.

    Examples
    --------
    >>> plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
    ...     ["A", "C", "E"]
    ... )  # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_\
Plot_Planckian_Locus_In_Chromaticity_Diagram_CIE1960UCS.png
        :align: center
        :alt: plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS
    """

    settings = dict(kwargs)
    settings.update({"method": "CIE 1960 UCS"})

    return plot_planckian_locus_in_chromaticity_diagram(
        illuminants,
        chromaticity_diagram_callable_CIE1960UCS,
        annotate_kwargs=annotate_kwargs,
        plot_kwargs=plot_kwargs,
        **settings,
    )

1	"""
2	Colour Temperature & Correlated Colour Temperature Plotting
3	===========================================================
4
5	Defines the colour temperature and correlated colour temperature plotting
6	objects:
7
8	- :func:`colour.plotting.\
9	plot_planckian_locus_in_chromaticity_diagram_CIE1931`
10	- :func:`colour.plotting.\
11	plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS`
12	"""
13
14	from __future__ import annotations	×
15
16	import matplotlib.pyplot as plt	×
17	import numpy as np	×
18	from matplotlib.collections import LineCollection	×
19
20	from colour.algebra import normalise_maximum	×
21	from colour.colorimetry import MSDS_CMFS, CCS_ILLUMINANTS	×
22	from colour.hints import (	×
23	Any,
24	ArrayLike,
25	Callable,
26	Dict,
27	List,
28	Literal,
29	NDArrayFloat,
30	Sequence,
31	Tuple,
32	cast,
33	)
34	from colour.models import (	×
35	UCS_to_uv,
36	UCS_uv_to_xy,
37	XYZ_to_UCS,
38	xy_to_Luv_uv,
39	xy_to_XYZ,
40	)
41	from colour.temperature import mired_to_CCT, CCT_to_uv	×
42	from colour.plotting import (
43	CONSTANTS_COLOUR_STYLE,
44	CONSTANTS_ARROW_STYLE,
45	XYZ_to_plotting_colourspace,
46	artist,
47	plot_chromaticity_diagram_CIE1931,
48	plot_chromaticity_diagram_CIE1960UCS,
49	filter_passthrough,
50	override_style,
51	render,
52	update_settings_collection,
53	)
54	from colour.plotting.diagrams import plot_chromaticity_diagram	×
55	from colour.utilities import (	×
56	as_int_scalar,
57	as_float_scalar,
58	full,
59	optional,
60	tstack,
61	validate_method,
62	zeros,
63	)
64
65	__author__ = "Colour Developers"	×
66	__copyright__ = "Copyright 2013 Colour Developers"	×
67	__license__ = "New BSD License - https://opensource.org/licenses/BSD-3-Clause"	×
68	__maintainer__ = "Colour Developers"	×
69	__email__ = "colour-developers@colour-science.org"	×
70	__status__ = "Production"	×
71
72	__all__ = [	×
73	"plot_planckian_locus",
74	"plot_planckian_locus_in_chromaticity_diagram",
75	"plot_planckian_locus_in_chromaticity_diagram_CIE1931",
76	"plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS",
77	]
78
79
80	@override_style()	×
81	def plot_planckian_locus(	×
82	planckian_locus_colours: ArrayLike \| str \| None = None,
83	planckian_locus_opacity: float = 1,
84	planckian_locus_labels: Sequence \| None = None,
85	planckian_locus_use_mireds: bool = False,
86	planckian_locus_iso_temperature_lines_D_uv: float = 0.05,
87	method: Literal["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"]
88	\| str = "CIE 1931",
89	**kwargs: Any,
90	) -> Tuple[plt.Figure, plt.Axes]:
91	"""
92	Plot the Planckian Locus according to given method.
93
94	Parameters
95	----------
96	planckian_locus_colours
97	Colours of the Planckian Locus, if ``planckian_locus_colours`` is set
98	to RGB, the colours will be computed according to the corresponding
99	chromaticity coordinates.
100	planckian_locus_opacity
101	Opacity of the Planckian Locus.
102	planckian_locus_labels
103	Array of labels used to customise which iso-temperature lines will be
104	drawn along the Planckian Locus. Passing an empty array will result
105	in no iso-temperature lines being drawn.
106	planckian_locus_use_mireds
107	Whether to use micro reciprocal degrees for the iso-temperature lines.
108	planckian_locus_iso_temperature_lines_D_uv
109	Iso-temperature lines :math:`\\Delta_{uv}` length on each side of the
110	Planckian Locus.
111
112	method
113	Chromaticity Diagram method.
114
115	Other Parameters
116	----------------
117	kwargs
118	{:func:`colour.plotting.artist`, :func:`colour.plotting.render`},
119	See the documentation of the previously listed definitions.
120
121	Returns
122	-------
123	:class:`tuple`
124	Current figure and axes.
125
126	Examples
127	--------
128	>>> plot_planckian_locus(
129	... planckian_locus_colours="RGB",
130	... method="CIE 1960 UCS",
131	... use_mireds=True,
132	... )
133	... # doctest: +ELLIPSIS
134	(<Figure size ... with 1 Axes>, <...Axes...>)
135
136	.. image:: ../_static/Plotting_Plot_Planckian_Locus.png
137	:align: center
138	:alt: plot_planckian_locus
139	"""
140
141	method = validate_method(	1✔
142	method, ["CIE 1931", "CIE 1960 UCS", "CIE 1976 UCS"]
143	)
144
145	planckian_locus_colours = optional(	1✔
146	planckian_locus_colours, CONSTANTS_COLOUR_STYLE.colour.dark
147	)
148
149	labels = cast(	1✔
150	tuple,
151	optional(
152	planckian_locus_labels,
153	(0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000)
154	if planckian_locus_use_mireds
155	else (1e6 / 600, 2000, 2500, 3000, 4000, 6000, 1e6 / 100),
156	),
157	)
158	D_uv = planckian_locus_iso_temperature_lines_D_uv	1✔
159
160	settings: Dict[str, Any] = {"uniform": True}	1✔
161	settings.update(kwargs)	1✔
162
163	_figure, axes = artist(**settings)	1✔
164
165	if method == "cie 1931":	1✔
166
167	def uv_to_ij(uv: NDArrayFloat) -> NDArrayFloat:	1✔
168	"""
169	Convert given uv chromaticity coordinates to ij chromaticity
170	coordinates.
171	"""
172
173	return UCS_uv_to_xy(uv)	1✔
174
175	elif method == "cie 1960 ucs":	1✔
176
177	def uv_to_ij(uv: NDArrayFloat) -> NDArrayFloat:	1✔
178	"""
179	Convert given uv chromaticity coordinates to ij chromaticity
180	coordinates.
181	"""
182
183	return uv	1✔
184
185	elif method == "cie 1976 ucs":	1✔
186
187	def uv_to_ij(uv: NDArrayFloat) -> NDArrayFloat:	1✔
188	"""
189	Convert given uv chromaticity coordinates to ij chromaticity
190	coordinates.
191	"""
192
193	return xy_to_Luv_uv(UCS_uv_to_xy(uv))	1✔
194
195	def CCT_D_uv_to_plotting_colourspace(CCT_D_uv):	1✔
196	"""
197	Convert given uv chromaticity coordinates to the default plotting
198	colourspace.
199	"""
200
201	return normalise_maximum(	1✔
202	XYZ_to_plotting_colourspace(
203	xy_to_XYZ(UCS_uv_to_xy(CCT_to_uv(CCT_D_uv, "Robertson 1968")))
204	),
205	axis=-1,
206	)
207
208	start, end = (	1✔
209	(0, 1000) if planckian_locus_use_mireds else (1e6 / 600, 1e6 / 10)
210	)
211
212	CCT = np.arange(start, end + 100, 10)	1✔
213	CCT = mired_to_CCT(CCT) if planckian_locus_use_mireds else CCT	1✔
214	CCT_D_uv = np.reshape(tstack([CCT, zeros(CCT.shape)]), (-1, 1, 2))	1✔
215	ij = uv_to_ij(CCT_to_uv(CCT_D_uv, "Robertson 1968"))	1✔
216
217	use_RGB_planckian_locus_colours = (	1✔
218	str(planckian_locus_colours).upper() == "RGB"
219	)
220	if use_RGB_planckian_locus_colours:	1✔
221	pl_colours = CCT_D_uv_to_plotting_colourspace(CCT_D_uv)	1✔
222	else:
223	pl_colours = planckian_locus_colours	1✔
224
225	line_collection = LineCollection(	1✔
226	np.concatenate([ij[:-1], ij[1:]], axis=1),
227	colors=pl_colours,
228	alpha=planckian_locus_opacity,
229	zorder=CONSTANTS_COLOUR_STYLE.zorder.foreground_line,
230	)
231	axes.add_collection(line_collection)	1✔
232
233	for label in labels:	1✔
234	CCT_D_uv = np.reshape(	1✔
235	tstack(
236	[
237	full(
238	10,
239	as_float_scalar(mired_to_CCT(label))
240	if planckian_locus_use_mireds
241	else label,
242	),
243	np.linspace(-D_uv, D_uv, 10),
244	]
245	),
246	(-1, 1, 2),
247	)
248
249	if use_RGB_planckian_locus_colours:	1✔
250	itl_colours = CCT_D_uv_to_plotting_colourspace(CCT_D_uv)	1✔
251	else:
252	itl_colours = planckian_locus_colours	1✔
253
254	ij = uv_to_ij(CCT_to_uv(CCT_D_uv, "Robertson 1968"))	1✔
255
256	line_collection = LineCollection(	1✔
257	np.concatenate([ij[:-1], ij[1:]], axis=1),
258	colors=itl_colours,
259	alpha=planckian_locus_opacity,
260	zorder=CONSTANTS_COLOUR_STYLE.zorder.foreground_line,
261	)
262	axes.add_collection(line_collection)	1✔
263	axes.annotate(	1✔
264	f'{as_int_scalar(label)}{"M" if planckian_locus_use_mireds else "K"}',
265	xy=(ij[-1, :, 0], ij[-1, :, 1]),
266	xytext=(0, CONSTANTS_COLOUR_STYLE.geometry.long / 2),
267	textcoords="offset points",
268	size="x-small",
269	zorder=CONSTANTS_COLOUR_STYLE.zorder.foreground_label,
270	)
271
272	settings = {"axes": axes}	1✔
273	settings.update(kwargs)	1✔
274
275	return render(**settings)	1✔
276
277
278	@override_style()	×
279	def plot_planckian_locus_in_chromaticity_diagram(	×
280	illuminants: str \| Sequence[str],
281	chromaticity_diagram_callable: Callable = plot_chromaticity_diagram,
282	method: Literal["CIE 1931", "CIE 1960 UCS"] \| str = "CIE 1931",
283	annotate_kwargs: dict \| List[dict] \| None = None,
284	plot_kwargs: dict \| List[dict] \| None = None,
285	**kwargs: Any,
286	) -> Tuple[plt.Figure, plt.Axes]:
287	"""
288	Plot the Planckian Locus and given illuminants in the
289	Chromaticity Diagram according to given method.
290
291	Parameters
292	----------
293	illuminants
294	Illuminants to plot. ``illuminants`` elements can be of any
295	type or form supported by the
296	:func:`colour.plotting.common.filter_passthrough` definition.
297	chromaticity_diagram_callable
298	Callable responsible for drawing the Chromaticity Diagram.
299	method
300	Chromaticity Diagram method.
301	annotate_kwargs
302	Keyword arguments for the :func:`matplotlib.pyplot.annotate`
303	definition, used to annotate the resulting chromaticity coordinates
304	with their respective spectral distribution names. ``annotate_kwargs``
305	can be either a single dictionary applied to all the arrows with same
306	settings or a sequence of dictionaries with different settings for each
307	spectral distribution. The following special keyword arguments can also
308	be used:
309
310	- ``annotate`` : Whether to annotate the spectral distributions.
311	plot_kwargs
312	Keyword arguments for the :func:`matplotlib.pyplot.plot` definition,
313	used to control the style of the plotted illuminants. ``plot_kwargs``
314	can be either a single dictionary applied to all the plotted
315	illuminants with the same settings or a sequence of dictionaries with
316	different settings for eachplotted illuminant.
317
318	Other Parameters
319	----------------
320	kwargs
321	{:func:`colour.plotting.artist`,
322	:func:`colour.plotting.diagrams.plot_chromaticity_diagram`,
323	:func:`colour.plotting.temperature.plot_planckian_locus`,
324	:func:`colour.plotting.render`},
325	See the documentation of the previously listed definitions.
326
327	Returns
328	-------
329	:class:`tuple`
330	Current figure and axes.
331
332	Examples
333	--------
334	>>> annotate_kwargs = [
335	... {"xytext": (-25, 15), "arrowprops": {"arrowstyle": "-"}},
336	... {"arrowprops": {"arrowstyle": "-["}},
337	... {},
338	... ]
339	>>> plot_kwargs = [
340	... {
341	... "markersize": 15,
342	... },
343	... {"color": "r"},
344	... {},
345	... ]
346	>>> plot_planckian_locus_in_chromaticity_diagram(
347	... ["A", "B", "C"],
348	... annotate_kwargs=annotate_kwargs,
349	... plot_kwargs=plot_kwargs,
350	... ) # doctest: +ELLIPSIS
351	(<Figure size ... with 1 Axes>, <...Axes...>)
352
353	.. image:: ../_static/Plotting_\
354	Plot_Planckian_Locus_In_Chromaticity_Diagram.png
355	:align: center
356	:alt: plot_planckian_locus_in_chromaticity_diagram
357	"""
358
359	method = validate_method(method, ["CIE 1931", "CIE 1960 UCS"])	1✔
360
361	cmfs = MSDS_CMFS["CIE 1931 2 Degree Standard Observer"]	1✔
362
363	illuminants_filtered = filter_passthrough(
364	CCS_ILLUMINANTS[cmfs.name], illuminants
365	)
366
367	settings: Dict[str, Any] = {"uniform": True}	1✔
368	settings.update(kwargs)	1✔
369
370	_figure, axes = artist(**settings)	1✔
371
372	method = method.upper()	1✔
373
374	settings = {"axes": axes, "method": method}	1✔
375	settings.update(kwargs)	1✔
376	settings["standalone"] = False	1✔
377
378	chromaticity_diagram_callable(**settings)	1✔
379
380	plot_planckian_locus(**settings)	1✔
381
382	if method == "CIE 1931":	1✔
383
384	def xy_to_ij(xy: NDArrayFloat) -> NDArrayFloat:	1✔
385	"""
386	Convert given CIE xy chromaticity coordinates to ij
387	chromaticity coordinates.
388	"""
389
390	return xy	1✔
391
392	bounding_box = (-0.1, 0.9, -0.1, 0.9)	1✔
393	elif method == "CIE 1960 UCS":	1✔
394
395	def xy_to_ij(xy: NDArrayFloat) -> NDArrayFloat:	1✔
396	"""
397	Convert given CIE xy chromaticity coordinates to ij
398	chromaticity coordinates.
399	"""
400
401	return UCS_to_uv(XYZ_to_UCS(xy_to_XYZ(xy)))	1✔
402
403	bounding_box = (-0.1, 0.7, -0.2, 0.6)	1✔
404
405	annotate_settings_collection = [	1✔
406	{
407	"annotate": True,
408	"xytext": (-50, 30),
409	"textcoords": "offset points",
410	"arrowprops": CONSTANTS_ARROW_STYLE,
411	"zorder": CONSTANTS_COLOUR_STYLE.zorder.foreground_annotation,
412	}
413	for _ in range(len(illuminants_filtered))
414	]
415
416	if annotate_kwargs is not None:	1✔
417	update_settings_collection(	1✔
418	annotate_settings_collection,
419	annotate_kwargs,
420	len(illuminants_filtered),
421	)
422
423	plot_settings_collection = [	1✔
424	{
425	"color": CONSTANTS_COLOUR_STYLE.colour.brightest,
426	"label": f"{illuminant}",
427	"marker": "o",
428	"markeredgecolor": CONSTANTS_COLOUR_STYLE.colour.dark,
429	"markeredgewidth": CONSTANTS_COLOUR_STYLE.geometry.short * 0.75,
430	"markersize": (
431	CONSTANTS_COLOUR_STYLE.geometry.short * 6
432	+ CONSTANTS_COLOUR_STYLE.geometry.short * 0.75
433	),
434	"zorder": CONSTANTS_COLOUR_STYLE.zorder.foreground_line,
435	}
436	for illuminant in illuminants_filtered
437	]
438
439	if plot_kwargs is not None:	1✔
440	update_settings_collection(	1✔
441	plot_settings_collection, plot_kwargs, len(illuminants_filtered)
442	)
443
444	for i, (illuminant, xy) in enumerate(illuminants_filtered.items()):	1✔
445	plot_settings = plot_settings_collection[i]	1✔
446
447	ij = xy_to_ij(xy)	1✔
448
449	axes.plot(ij[0], ij[1], **plot_settings)	1✔
450
451	if annotate_settings_collection[i]["annotate"]:	1✔
452	annotate_settings = annotate_settings_collection[i]	1✔
453	annotate_settings.pop("annotate")	1✔
454
455	axes.annotate(illuminant, xy=ij, **annotate_settings)	1✔
456
457	title = (	1✔
458	(
459	f"{', '.join(illuminants_filtered)} Illuminants - Planckian Locus\n"
460	f"{method.upper()} Chromaticity Diagram - "
461	"CIE 1931 2 Degree Standard Observer"
462	)
463	if illuminants_filtered
464	else (
465	f"Planckian Locus\n{method.upper()} Chromaticity Diagram - "
466	f"CIE 1931 2 Degree Standard Observer"
467	)
468	)
469
470	settings.update(	1✔
471	{
472	"axes": axes,
473	"standalone": True,
474	"bounding_box": bounding_box,
475	"title": title,
476	}
477	)
478	settings.update(kwargs)	1✔
479
480	return render(**settings)	1✔
481
482
483	@override_style()	×
484	def plot_planckian_locus_in_chromaticity_diagram_CIE1931(	×
485	illuminants: str \| Sequence[str],
486	chromaticity_diagram_callable_CIE1931: Callable = (
487	plot_chromaticity_diagram_CIE1931
488	),
489	annotate_kwargs: dict \| List[dict] \| None = None,
490	plot_kwargs: dict \| List[dict] \| None = None,
491	**kwargs: Any,
492	) -> Tuple[plt.Figure, plt.Axes]:
493	"""
494	Plot the Planckian Locus and given illuminants in
495	CIE 1931 Chromaticity Diagram.
496
497	Parameters
498	----------
499	illuminants
500	Illuminants to plot. ``illuminants`` elements can be of any
501	type or form supported by the
502	:func:`colour.plotting.common.filter_passthrough` definition.
503	chromaticity_diagram_callable_CIE1931
504	Callable responsible for drawing the CIE 1931 Chromaticity Diagram.
505	annotate_kwargs
506	Keyword arguments for the :func:`matplotlib.pyplot.annotate`
507	definition, used to annotate the resulting chromaticity coordinates
508	with their respective spectral distribution names. ``annotate_kwargs``
509	can be either a single dictionary applied to all the arrows with same
510	settings or a sequence of dictionaries with different settings for each
511	spectral distribution. The following special keyword arguments can also
512	be used:
513
514	- ``annotate`` : Whether to annotate the spectral distributions.
515	plot_kwargs
516	Keyword arguments for the :func:`matplotlib.pyplot.plot` definition,
517	used to control the style of the plotted illuminants. ``plot_kwargs``
518	can be either a single dictionary applied to all the plotted
519	illuminants with the same settings or a sequence of dictionaries with
520	different settings for eachplotted illuminant.
521
522	Other Parameters
523	----------------
524	kwargs
525	{:func:`colour.plotting.artist`,
526	:func:`colour.plotting.diagrams.plot_chromaticity_diagram`,
527	:func:`colour.plotting.temperature.plot_planckian_locus`,
528	:func:`colour.plotting.temperature.\
529	plot_planckian_locus_in_chromaticity_diagram`,
530	:func:`colour.plotting.render`},
531	See the documentation of the previously listed definitions.
532
533	Returns
534	-------
535	:class:`tuple`
536	Current figure and axes.
537
538	Examples
539	--------
540	>>> plot_planckian_locus_in_chromaticity_diagram_CIE1931(["A", "B", "C"])
541	... # doctest: +ELLIPSIS
542	(<Figure size ... with 1 Axes>, <...Axes...>)
543
544	.. image:: ../_static/Plotting_\
545	Plot_Planckian_Locus_In_Chromaticity_Diagram_CIE1931.png
546	:align: center
547	:alt: plot_planckian_locus_in_chromaticity_diagram_CIE1931
548	"""
549
550	settings = dict(kwargs)	1✔
551	settings.update({"method": "CIE 1931"})	1✔
552
553	return plot_planckian_locus_in_chromaticity_diagram(	1✔
554	illuminants,
555	chromaticity_diagram_callable_CIE1931,
556	annotate_kwargs=annotate_kwargs,
557	plot_kwargs=plot_kwargs,
558	**settings,
559	)
560
561
562	@override_style()	×
563	def plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(	×
564	illuminants: str \| Sequence[str],
565	chromaticity_diagram_callable_CIE1960UCS: Callable = (
566	plot_chromaticity_diagram_CIE1960UCS
567	),
568	annotate_kwargs: dict \| List[dict] \| None = None,
569	plot_kwargs: dict \| List[dict] \| None = None,
570	**kwargs: Any,
571	) -> Tuple[plt.Figure, plt.Axes]:
572	"""
573	Plot the Planckian Locus and given illuminants in
574	CIE 1960 UCS Chromaticity Diagram.
575
576	Parameters
577	----------
578	illuminants
579	Illuminants to plot. ``illuminants`` elements can be of any
580	type or form supported by the
581	:func:`colour.plotting.common.filter_passthrough` definition.
582	chromaticity_diagram_callable_CIE1960UCS
583	Callable responsible for drawing the
584	CIE 1960 UCS Chromaticity Diagram.
585	annotate_kwargs
586	Keyword arguments for the :func:`matplotlib.pyplot.annotate`
587	definition, used to annotate the resulting chromaticity coordinates
588	with their respective spectral distribution names. ``annotate_kwargs``
589	can be either a single dictionary applied to all the arrows with same
590	settings or a sequence of dictionaries with different settings for each
591	spectral distribution. The following special keyword arguments can also
592	be used:
593
594	- ``annotate`` : Whether to annotate the spectral distributions.
595	plot_kwargs
596	Keyword arguments for the :func:`matplotlib.pyplot.plot` definition,
597	used to control the style of the plotted illuminants. ``plot_kwargs``
598	can be either a single dictionary applied to all the plotted
599	illuminants with the same settings or a sequence of dictionaries with
600	different settings for eachplotted illuminant.
601
602	Other Parameters
603	----------------
604	kwargs
605	{:func:`colour.plotting.artist`,
606	:func:`colour.plotting.diagrams.plot_chromaticity_diagram`,
607	:func:`colour.plotting.temperature.plot_planckian_locus`,
608	:func:`colour.plotting.temperature.\
609	plot_planckian_locus_in_chromaticity_diagram`,
610	:func:`colour.plotting.render`},
611	See the documentation of the previously listed definitions.
612
613	Returns
614	-------
615	:class:`tuple`
616	Current figure and axes.
617
618	Examples
619	--------
620	>>> plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
621	... ["A", "C", "E"]
622	... ) # doctest: +ELLIPSIS
623	(<Figure size ... with 1 Axes>, <...Axes...>)
624
625	.. image:: ../_static/Plotting_\
626	Plot_Planckian_Locus_In_Chromaticity_Diagram_CIE1960UCS.png
627	:align: center
628	:alt: plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS
629	"""
630
631	settings = dict(kwargs)	1✔
632	settings.update({"method": "CIE 1960 UCS"})	1✔
633
634	return plot_planckian_locus_in_chromaticity_diagram(	1✔
635	illuminants,
636	chromaticity_diagram_callable_CIE1960UCS,
637	annotate_kwargs=annotate_kwargs,
638	plot_kwargs=plot_kwargs,
639	**settings,
640	)

colour-science / colour / 4333918782

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous