9579473519

Committed 19 Jun 2024 09:20AM UTC coverage: 2.36% (-97.6%) from 99.978%

Build # 9579473519

Build Type

push

github

Committed by

KelSolaar

Commit Message

Test only `colour/volume/tests`.

Run Details

952 of 40339 relevant lines covered (2.36%)

0.02 hits per line

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

0.0

/colour/plotting/section.py

"""
Gamut Section Plotting
======================

Define the gamut section plotting objects:

-   :func:`colour.plotting.section.plot_hull_section_colours`
-   :func:`colour.plotting.section.plot_hull_section_contour`
-   :func:`colour.plotting.plot_visible_spectrum_section`
-   :func:`colour.plotting.plot_RGB_colourspace_section`
"""

from __future__ import annotations

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.colorimetry import (
    MultiSpectralDistributions,
    SpectralDistribution,
    SpectralShape,
    reshape_msds,
)
from colour.geometry import hull_section, primitive_cube
from colour.graph import convert
from colour.hints import (
    Any,
    ArrayLike,
    Dict,
    Literal,
    LiteralColourspaceModel,
    LiteralRGBColourspace,
    Real,
    Sequence,
    Tuple,
    cast,
)
from colour.models import (
    COLOURSPACE_MODELS_AXIS_LABELS,
    COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE,
    RGB_Colourspace,
    RGB_to_XYZ,
)
from colour.notation import HEX_to_RGB
from colour.plotting import (
    CONSTANTS_COLOUR_STYLE,
    XYZ_to_plotting_colourspace,
    artist,
    colourspace_model_axis_reorder,
    filter_cmfs,
    filter_illuminants,
    filter_RGB_colourspaces,
    override_style,
    render,
)
from colour.utilities import (
    CanonicalMapping,
    as_int_array,
    first_item,
    full,
    optional,
    required,
    suppress_warnings,
    tstack,
    validate_method,
)
from colour.volume import solid_RoschMacAdam

__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__ = [
    "MAPPING_AXIS_TO_PLANE",
    "plot_hull_section_colours",
    "plot_hull_section_contour",
    "plot_visible_spectrum_section",
    "plot_RGB_colourspace_section",
]

MAPPING_AXIS_TO_PLANE: CanonicalMapping = CanonicalMapping(
    {"+x": (1, 2), "+y": (0, 2), "+z": (0, 1)}
)
MAPPING_AXIS_TO_PLANE.__doc__ = """Axis to plane mapping."""


@required("trimesh")
@override_style()
def plot_hull_section_colours(
    hull: trimesh.Trimesh,  # pyright: ignore  # noqa: F821
    model: LiteralColourspaceModel | str = "CIE xyY",
    axis: Literal["+z", "+x", "+y"] | str = "+z",
    origin: float = 0.5,
    normalise: bool = True,
    section_colours: ArrayLike | str | None = None,
    section_opacity: float = 1,
    convert_kwargs: dict | None = None,
    samples: int = 256,
    **kwargs: Any,
) -> Tuple[Figure, Axes]:
    """
    Plot the section colours of given *trimesh* hull along given axis and
    origin.

    Parameters
    ----------
    hull
        *Trimesh* hull.
    model
        Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
        the list of supported colourspace models.
    axis
        Axis the hull section will be normal to.
    origin
        Coordinate along ``axis`` at which to plot the hull section.
    normalise
        Whether to normalise ``axis`` to the extent of the hull along it.
    section_colours
        Colours of the hull section, if ``section_colours`` is set to *RGB*,
        the colours will be computed according to the corresponding
        coordinates.
    section_opacity
        Opacity of the hull section colours.
    convert_kwargs
        Keyword arguments for the :func:`colour.convert` definition.
    samples
        Sample count on one axis when computing the hull section colours.

    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
    --------
    >>> from colour.models import RGB_COLOURSPACE_sRGB
    >>> from colour.utilities import is_trimesh_installed
    >>> vertices, faces, _outline = primitive_cube(1, 1, 1, 64, 64, 64)
    >>> XYZ_vertices = RGB_to_XYZ(vertices["position"] + 0.5, RGB_COLOURSPACE_sRGB)
    >>> if is_trimesh_installed:
    ...     from trimesh import Trimesh
    ...
    ...     hull = Trimesh(XYZ_vertices, faces, process=False)
    ...     plot_hull_section_colours(hull, section_colours="RGB")
    ...     # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_Plot_Hull_Section_Colours.png
        :align: center
        :alt: plot_hull_section_colours
    """

    axis = validate_method(
        axis,
        ("+z", "+x", "+y"),
        '"{0}" axis is invalid, it must be one of {1}!',
    )

    hull = hull.copy()

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

    _figure, axes = artist(**settings)

    section_colours = optional(
        section_colours, HEX_to_RGB(CONSTANTS_COLOUR_STYLE.colour.average)
    )

    convert_kwargs = optional(convert_kwargs, {})

    # Luminance / Lightness reordered along "z" axis.
    with suppress_warnings(python_warnings=True):
        ijk_vertices = colourspace_model_axis_reorder(
            convert(hull.vertices, "CIE XYZ", model, **convert_kwargs), model
        )
        ijk_vertices = np.nan_to_num(ijk_vertices)
        ijk_vertices *= COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model]

    hull.vertices = ijk_vertices

    if axis == "+x":
        index_origin = 0
    elif axis == "+y":
        index_origin = 1
    elif axis == "+z":
        index_origin = 2
    plane = MAPPING_AXIS_TO_PLANE[axis]

    section = hull_section(hull, axis, origin, normalise)

    padding = 0.1 * np.mean(COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model])
    min_x = np.min(ijk_vertices[..., plane[0]]) - padding
    max_x = np.max(ijk_vertices[..., plane[0]]) + padding
    min_y = np.min(ijk_vertices[..., plane[1]]) - padding
    max_y = np.max(ijk_vertices[..., plane[1]]) + padding
    extent = (min_x, max_x, min_y, max_y)

    use_RGB_section_colours = str(section_colours).upper() == "RGB"
    if use_RGB_section_colours:
        ii, jj = np.meshgrid(
            np.linspace(min_x, max_x, samples),
            np.linspace(max_y, min_y, samples),
        )
        ij = tstack([ii, jj])
        ijk_section = full(
            (samples, samples, 3),
            cast(Real, np.median(section[..., index_origin])),
        )
        ijk_section[..., plane] = ij
        ijk_section /= COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model]
        XYZ_section = convert(
            colourspace_model_axis_reorder(ijk_section, model, "Inverse"),
            model,
            "CIE XYZ",
            **convert_kwargs,
        )
        RGB_section = XYZ_to_plotting_colourspace(XYZ_section)
    else:
        section_colours = np.hstack([section_colours, section_opacity])

    facecolor = "none" if use_RGB_section_colours else section_colours
    polygon = Polygon(
        section[..., plane],
        facecolor=facecolor,
        edgecolor="none",
        zorder=CONSTANTS_COLOUR_STYLE.zorder.background_polygon,
    )
    axes.add_patch(polygon)

    if use_RGB_section_colours:
        image = axes.imshow(
            np.clip(RGB_section, 0, 1),
            interpolation="bilinear",
            extent=extent,
            clip_path=None,
            alpha=section_opacity,
            zorder=CONSTANTS_COLOUR_STYLE.zorder.background_polygon,
        )
        image.set_clip_path(polygon)

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

    return render(**settings)


@required("trimesh")
@override_style()
def plot_hull_section_contour(
    hull: trimesh.Trimesh,  # pyright: ignore  # noqa: F821
    model: LiteralColourspaceModel | str = "CIE xyY",
    axis: Literal["+z", "+x", "+y"] | str = "+z",
    origin: float = 0.5,
    normalise: bool = True,
    contour_colours: ArrayLike | str | None = None,
    contour_opacity: float = 1,
    convert_kwargs: dict | None = None,
    **kwargs: Any,
) -> Tuple[Figure, Axes]:
    """
    Plot the section contour of given *trimesh* hull along given axis and
    origin.

    Parameters
    ----------
    hull
        *Trimesh* hull.
    model
        Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
        the list of supported colourspace models.
    axis
        Axis the hull section will be normal to.
    origin
        Coordinate along ``axis`` at which to plot the hull section.
    normalise
        Whether to normalise ``axis`` to the extent of the hull along it.
    contour_colours
        Colours of the hull section contour, if ``contour_colours`` is set to
        *RGB*, the colours will be computed according to the corresponding
        coordinates.
    contour_opacity
        Opacity of the hull section contour.
    convert_kwargs
        Keyword arguments for the :func:`colour.convert` definition.

    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
    --------
    >>> from colour.models import RGB_COLOURSPACE_sRGB
    >>> from colour.utilities import is_trimesh_installed
    >>> vertices, faces, _outline = primitive_cube(1, 1, 1, 64, 64, 64)
    >>> XYZ_vertices = RGB_to_XYZ(vertices["position"] + 0.5, RGB_COLOURSPACE_sRGB)
    >>> if is_trimesh_installed:
    ...     from trimesh import Trimesh
    ...
    ...     hull = Trimesh(XYZ_vertices, faces, process=False)
    ...     plot_hull_section_contour(hull, contour_colours="RGB")
    ...     # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_Plot_Hull_Section_Contour.png
        :align: center
        :alt: plot_hull_section_contour
    """

    hull = hull.copy()

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

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

    _figure, axes = artist(**settings)

    convert_kwargs = optional(convert_kwargs, {})

    # Luminance / Lightness is re-ordered along "z-up" axis.
    with suppress_warnings(python_warnings=True):
        ijk_vertices = colourspace_model_axis_reorder(
            convert(hull.vertices, "CIE XYZ", model, **convert_kwargs), model
        )
        ijk_vertices = np.nan_to_num(ijk_vertices)
        ijk_vertices *= COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model]

    hull.vertices = ijk_vertices

    plane = MAPPING_AXIS_TO_PLANE[axis]

    padding = 0.1 * np.mean(COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model])
    min_x = np.min(ijk_vertices[..., plane[0]]) - padding
    max_x = np.max(ijk_vertices[..., plane[0]]) + padding
    min_y = np.min(ijk_vertices[..., plane[1]]) - padding
    max_y = np.max(ijk_vertices[..., plane[1]]) + padding
    extent = (min_x, max_x, min_y, max_y)

    use_RGB_contour_colours = str(contour_colours).upper() == "RGB"
    section = hull_section(hull, axis, origin, normalise)
    if use_RGB_contour_colours:
        ijk_section = (
            section / (COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model])
        )
        XYZ_section = convert(
            colourspace_model_axis_reorder(ijk_section, model, "Inverse"),
            model,
            "CIE XYZ",
            **convert_kwargs,
        )
        contour_colours = np.clip(XYZ_to_plotting_colourspace(XYZ_section), 0, 1)

    section = np.reshape(section[..., plane], (-1, 1, 2))
    line_collection = LineCollection(
        np.concatenate([section[:-1], section[1:]], axis=1),  # pyright: ignore
        colors=contour_colours,
        alpha=contour_opacity,
        zorder=CONSTANTS_COLOUR_STYLE.zorder.background_line,
    )
    axes.add_collection(line_collection)

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

    return render(**settings)


@required("trimesh")
@override_style()
def plot_visible_spectrum_section(
    cmfs: (
        MultiSpectralDistributions | str | Sequence[MultiSpectralDistributions | str]
    ) = "CIE 1931 2 Degree Standard Observer",
    illuminant: SpectralDistribution | str = "D65",
    model: LiteralColourspaceModel | str = "CIE xyY",
    axis: Literal["+z", "+x", "+y"] | str = "+z",
    origin: float = 0.5,
    normalise: bool = True,
    show_section_colours: bool = True,
    show_section_contour: bool = True,
    **kwargs: Any,
) -> Tuple[Figure, Axes]:
    """
    Plot the visible spectrum volume, i.e. *Rösch-MacAdam* colour solid,
    section colours along given axis and origin.

    Parameters
    ----------
    cmfs
        Standard observer colour matching functions, default to the
        *CIE 1931 2 Degree Standard Observer*.  ``cmfs`` can be of any type or
        form supported by the :func:`colour.plotting.common.filter_cmfs`
        definition.
    illuminant
        Illuminant spectral distribution, default to *CIE Illuminant D65*.
        ``illuminant`` can be of any type or form supported by the
        :func:`colour.plotting.common.filter_illuminants` definition.
    model
        Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
        the list of supported colourspace models.
    axis
        Axis the hull section will be normal to.
    origin
        Coordinate along ``axis`` at which to plot the hull section.
    normalise
        Whether to normalise ``axis`` to the extent of the hull along it.
    show_section_colours
        Whether to show the hull section colours.
    show_section_contour
        Whether to show the hull section contour.

    Other Parameters
    ----------------
    kwargs
        {:func:`colour.plotting.artist`,
        :func:`colour.plotting.render`,
        :func:`colour.plotting.section.plot_hull_section_colours`
        :func:`colour.plotting.section.plot_hull_section_contour`},
        See the documentation of the previously listed definitions.

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

    Examples
    --------
    >>> from colour.utilities import is_trimesh_installed
    >>> if is_trimesh_installed:
    ...     plot_visible_spectrum_section(section_colours="RGB", section_opacity=0.15)
    ...     # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_Plot_Visible_Spectrum_Section.png
        :align: center
        :alt: plot_visible_spectrum_section
    """

    import trimesh.convex
    from trimesh import Trimesh

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

    _figure, axes = artist(**settings)

    cmfs = cast(
        MultiSpectralDistributions,
        reshape_msds(
            first_item(filter_cmfs(cmfs).values()),
            SpectralShape(360, 780, 1),
            copy=False,
        ),
    )
    illuminant = cast(
        SpectralDistribution,
        first_item(filter_illuminants(illuminant).values()),
    )

    vertices = solid_RoschMacAdam(
        cmfs,
        illuminant,
        point_order="Pulse Wave Width",
        filter_jagged_points=True,
    )
    mesh = Trimesh(vertices)
    hull = trimesh.convex.convex_hull(mesh)

    if show_section_colours:
        settings = {"axes": axes}
        settings.update(kwargs)
        settings["show"] = False

        plot_hull_section_colours(hull, model, axis, origin, normalise, **settings)

    if show_section_contour:
        settings = {"axes": axes}
        settings.update(kwargs)
        settings["show"] = False

        plot_hull_section_contour(hull, model, axis, origin, normalise, **settings)

    title = (
        f"Visible Spectrum Section - "
        f"{f'{origin * 100}%' if normalise else origin} - "
        f"{model} - "
        f"{cmfs.display_name}"
    )

    plane = MAPPING_AXIS_TO_PLANE[axis]

    labels = np.array(COLOURSPACE_MODELS_AXIS_LABELS[model])[
        as_int_array(colourspace_model_axis_reorder([0, 1, 2], model))
    ]
    x_label, y_label = labels[plane[0]], labels[plane[1]]

    settings.update(
        {
            "axes": axes,
            "show": True,
            "title": title,
            "x_label": x_label,
            "y_label": y_label,
        }
    )
    settings.update(kwargs)

    return render(**settings)


@required("trimesh")
@override_style()
def plot_RGB_colourspace_section(
    colourspace: (
        RGB_Colourspace
        | LiteralRGBColourspace
        | str
        | Sequence[RGB_Colourspace | LiteralRGBColourspace | str]
    ),
    model: LiteralColourspaceModel | str = "CIE xyY",
    axis: Literal["+z", "+x", "+y"] | str = "+z",
    origin: float = 0.5,
    normalise: bool = True,
    size: float = 1.0,
    show_section_colours: bool = True,
    show_section_contour: bool = True,
    segments: int = 64,
    **kwargs: Any,
) -> Tuple[Figure, Axes]:
    """
    Plot given *RGB* colourspace section colours along given axis and origin.

    Parameters
    ----------
    colourspace
        *RGB* colourspace of the *RGB* array. ``colourspace`` can be of any
        type or form supported by the
        :func:`colour.plotting.common.filter_RGB_colourspaces` definition.
    model
        Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
        the list of supported colourspace models.
    axis
        Axis the hull section will be normal to.
    origin
        Coordinate along ``axis`` at which to plot the hull section.
    normalise
        Whether to normalise ``axis`` to the extent of the hull along it.
    size:
        Size of the underlying *RGB* colourspace cube; used for plotting HDR
        related sections.
    show_section_colours
        Whether to show the hull section colours.
    show_section_contour
        Whether to show the hull section contour.
    segments
        Edge segments count for the *RGB* colourspace cube.

    Other Parameters
    ----------------
    kwargs
        {:func:`colour.plotting.artist`,
        :func:`colour.plotting.render`,
        :func:`colour.plotting.section.plot_hull_section_colours`
        :func:`colour.plotting.section.plot_hull_section_contour`},
        See the documentation of the previously listed definitions.

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

    Examples
    --------
    >>> from colour.utilities import is_trimesh_installed
    >>> if is_trimesh_installed:
    ...     plot_RGB_colourspace_section(
    ...         "sRGB", section_colours="RGB", section_opacity=0.15
    ...     )
    ...     # doctest: +ELLIPSIS
    (<Figure size ... with 1 Axes>, <...Axes...>)

    .. image:: ../_static/Plotting_Plot_RGB_Colourspace_Section.png
        :align: center
        :alt: plot_RGB_colourspace_section
    """

    from trimesh import Trimesh

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

    _figure, axes = artist(**settings)

    colourspace = cast(
        RGB_Colourspace,
        first_item(filter_RGB_colourspaces(colourspace).values()),
    )

    vertices, faces, _outline = primitive_cube(1, 1, 1, segments, segments, segments)
    XYZ_vertices = RGB_to_XYZ((vertices["position"] + 0.5) * size, colourspace)
    hull = Trimesh(XYZ_vertices, faces, process=False)

    if show_section_colours:
        settings = {"axes": axes}
        settings.update(kwargs)
        settings["show"] = False

        plot_hull_section_colours(hull, model, axis, origin, normalise, **settings)

    if show_section_contour:
        settings = {"axes": axes}
        settings.update(kwargs)
        settings["show"] = False

        plot_hull_section_contour(hull, model, axis, origin, normalise, **settings)

    title = (
        f"{colourspace.name} Section - "
        f"{f'{origin * 100}%' if normalise else origin} - "
        f"{model}"
    )

    plane = MAPPING_AXIS_TO_PLANE[axis]

    labels = np.array(COLOURSPACE_MODELS_AXIS_LABELS[model])[
        as_int_array(colourspace_model_axis_reorder([0, 1, 2], model))
    ]
    x_label, y_label = labels[plane[0]], labels[plane[1]]

    settings.update(
        {
            "axes": axes,
            "show": True,
            "title": title,
            "x_label": x_label,
            "y_label": y_label,
        }
    )
    settings.update(kwargs)

    return render(**settings)

1	"""
2	Gamut Section Plotting
3	======================
4
5	Define the gamut section plotting objects:
6
7	- :func:`colour.plotting.section.plot_hull_section_colours`
8	- :func:`colour.plotting.section.plot_hull_section_contour`
9	- :func:`colour.plotting.plot_visible_spectrum_section`
10	- :func:`colour.plotting.plot_RGB_colourspace_section`
11	"""
12
13	from __future__ import annotations	×
14
15	import numpy as np	×
16	from matplotlib.axes import Axes	×
17	from matplotlib.collections import LineCollection	×
18	from matplotlib.figure import Figure	×
19	from matplotlib.patches import Polygon	×
20
21	from colour.colorimetry import (	×
22	MultiSpectralDistributions,
23	SpectralDistribution,
24	SpectralShape,
25	reshape_msds,
26	)
27	from colour.geometry import hull_section, primitive_cube	×
28	from colour.graph import convert	×
29	from colour.hints import (	×
30	Any,
31	ArrayLike,
32	Dict,
33	Literal,
34	LiteralColourspaceModel,
35	LiteralRGBColourspace,
36	Real,
37	Sequence,
38	Tuple,
39	cast,
40	)
41	from colour.models import (	×
42	COLOURSPACE_MODELS_AXIS_LABELS,
43	COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE,
44	RGB_Colourspace,
45	RGB_to_XYZ,
46	)
47	from colour.notation import HEX_to_RGB	×
48	from colour.plotting import (	×
49	CONSTANTS_COLOUR_STYLE,
50	XYZ_to_plotting_colourspace,
51	artist,
52	colourspace_model_axis_reorder,
53	filter_cmfs,
54	filter_illuminants,
55	filter_RGB_colourspaces,
56	override_style,
57	render,
58	)
59	from colour.utilities import (	×
60	CanonicalMapping,
61	as_int_array,
62	first_item,
63	full,
64	optional,
65	required,
66	suppress_warnings,
67	tstack,
68	validate_method,
69	)
70	from colour.volume import solid_RoschMacAdam	×
71
72	__author__ = "Colour Developers"	×
73	__copyright__ = "Copyright 2013 Colour Developers"	×
74	__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"	×
75	__maintainer__ = "Colour Developers"	×
76	__email__ = "colour-developers@colour-science.org"	×
77	__status__ = "Production"	×
78
79	__all__ = [	×
80	"MAPPING_AXIS_TO_PLANE",
81	"plot_hull_section_colours",
82	"plot_hull_section_contour",
83	"plot_visible_spectrum_section",
84	"plot_RGB_colourspace_section",
85	]
86
87	MAPPING_AXIS_TO_PLANE: CanonicalMapping = CanonicalMapping(	×
88	{"+x": (1, 2), "+y": (0, 2), "+z": (0, 1)}
89	)
90	MAPPING_AXIS_TO_PLANE.__doc__ = """Axis to plane mapping."""	×
91
92
93	@required("trimesh")	×
94	@override_style()	×
95	def plot_hull_section_colours(	×
96	hull: trimesh.Trimesh, # pyright: ignore # noqa: F821
97	model: LiteralColourspaceModel \| str = "CIE xyY",
98	axis: Literal["+z", "+x", "+y"] \| str = "+z",
99	origin: float = 0.5,
100	normalise: bool = True,
101	section_colours: ArrayLike \| str \| None = None,
102	section_opacity: float = 1,
103	convert_kwargs: dict \| None = None,
104	samples: int = 256,
105	**kwargs: Any,
106	) -> Tuple[Figure, Axes]:
107	"""
108	Plot the section colours of given trimesh hull along given axis and
109	origin.
110
111	Parameters
112	----------
113	hull
114	Trimesh hull.
115	model
116	Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
117	the list of supported colourspace models.
118	axis
119	Axis the hull section will be normal to.
120	origin
121	Coordinate along ``axis`` at which to plot the hull section.
122	normalise
123	Whether to normalise ``axis`` to the extent of the hull along it.
124	section_colours
125	Colours of the hull section, if ``section_colours`` is set to RGB,
126	the colours will be computed according to the corresponding
127	coordinates.
128	section_opacity
129	Opacity of the hull section colours.
130	convert_kwargs
131	Keyword arguments for the :func:`colour.convert` definition.
132	samples
133	Sample count on one axis when computing the hull section colours.
134
135	Other Parameters
136	----------------
137	kwargs
138	{:func:`colour.plotting.artist`,
139	:func:`colour.plotting.render`},
140	See the documentation of the previously listed definitions.
141
142	Returns
143	-------
144	:class:`tuple`
145	Current figure and axes.
146
147	Examples
148	--------
149	>>> from colour.models import RGB_COLOURSPACE_sRGB
150	>>> from colour.utilities import is_trimesh_installed
151	>>> vertices, faces, _outline = primitive_cube(1, 1, 1, 64, 64, 64)
152	>>> XYZ_vertices = RGB_to_XYZ(vertices["position"] + 0.5, RGB_COLOURSPACE_sRGB)
153	>>> if is_trimesh_installed:
154	... from trimesh import Trimesh
155	...
156	... hull = Trimesh(XYZ_vertices, faces, process=False)
157	... plot_hull_section_colours(hull, section_colours="RGB")
158	... # doctest: +ELLIPSIS
159	(<Figure size ... with 1 Axes>, <...Axes...>)
160
161	.. image:: ../_static/Plotting_Plot_Hull_Section_Colours.png
162	:align: center
163	:alt: plot_hull_section_colours
164	"""
165
166	axis = validate_method(	×
167	axis,
168	("+z", "+x", "+y"),
169	'"{0}" axis is invalid, it must be one of {1}!',
170	)
171
172	hull = hull.copy()	×
173
174	settings: Dict[str, Any] = {"uniform": True}	×
175	settings.update(kwargs)	×
176
177	_figure, axes = artist(**settings)	×
178
179	section_colours = optional(	×
180	section_colours, HEX_to_RGB(CONSTANTS_COLOUR_STYLE.colour.average)
181	)
182
183	convert_kwargs = optional(convert_kwargs, {})	×
184
185	# Luminance / Lightness reordered along "z" axis.
186	with suppress_warnings(python_warnings=True):	×
187	ijk_vertices = colourspace_model_axis_reorder(	×
188	convert(hull.vertices, "CIE XYZ", model, **convert_kwargs), model
189	)
190	ijk_vertices = np.nan_to_num(ijk_vertices)	×
191	ijk_vertices *= COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model]	×
192
193	hull.vertices = ijk_vertices	×
194
195	if axis == "+x":	×
196	index_origin = 0	×
197	elif axis == "+y":	×
198	index_origin = 1	×
199	elif axis == "+z":	×
200	index_origin = 2	×
201	plane = MAPPING_AXIS_TO_PLANE[axis]	×
202
203	section = hull_section(hull, axis, origin, normalise)	×
204
205	padding = 0.1 * np.mean(COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model])	×
206	min_x = np.min(ijk_vertices[..., plane[0]]) - padding	×
207	max_x = np.max(ijk_vertices[..., plane[0]]) + padding	×
208	min_y = np.min(ijk_vertices[..., plane[1]]) - padding	×
209	max_y = np.max(ijk_vertices[..., plane[1]]) + padding	×
210	extent = (min_x, max_x, min_y, max_y)	×
211
212	use_RGB_section_colours = str(section_colours).upper() == "RGB"	×
213	if use_RGB_section_colours:	×
214	ii, jj = np.meshgrid(	×
215	np.linspace(min_x, max_x, samples),
216	np.linspace(max_y, min_y, samples),
217	)
218	ij = tstack([ii, jj])	×
219	ijk_section = full(	×
220	(samples, samples, 3),
221	cast(Real, np.median(section[..., index_origin])),
222	)
223	ijk_section[..., plane] = ij	×
224	ijk_section /= COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model]	×
225	XYZ_section = convert(	×
226	colourspace_model_axis_reorder(ijk_section, model, "Inverse"),
227	model,
228	"CIE XYZ",
229	**convert_kwargs,
230	)
231	RGB_section = XYZ_to_plotting_colourspace(XYZ_section)	×
232	else:
233	section_colours = np.hstack([section_colours, section_opacity])	×
234
235	facecolor = "none" if use_RGB_section_colours else section_colours	×
236	polygon = Polygon(	×
237	section[..., plane],
238	facecolor=facecolor,
239	edgecolor="none",
240	zorder=CONSTANTS_COLOUR_STYLE.zorder.background_polygon,
241	)
242	axes.add_patch(polygon)	×
243
244	if use_RGB_section_colours:	×
245	image = axes.imshow(	×
246	np.clip(RGB_section, 0, 1),
247	interpolation="bilinear",
248	extent=extent,
249	clip_path=None,
250	alpha=section_opacity,
251	zorder=CONSTANTS_COLOUR_STYLE.zorder.background_polygon,
252	)
253	image.set_clip_path(polygon)	×
254
255	settings = {	×
256	"axes": axes,
257	"bounding_box": extent,
258	}
259	settings.update(kwargs)	×
260
261	return render(**settings)	×
262
263
264	@required("trimesh")	×
265	@override_style()	×
266	def plot_hull_section_contour(	×
267	hull: trimesh.Trimesh, # pyright: ignore # noqa: F821
268	model: LiteralColourspaceModel \| str = "CIE xyY",
269	axis: Literal["+z", "+x", "+y"] \| str = "+z",
270	origin: float = 0.5,
271	normalise: bool = True,
272	contour_colours: ArrayLike \| str \| None = None,
273	contour_opacity: float = 1,
274	convert_kwargs: dict \| None = None,
275	**kwargs: Any,
276	) -> Tuple[Figure, Axes]:
277	"""
278	Plot the section contour of given trimesh hull along given axis and
279	origin.
280
281	Parameters
282	----------
283	hull
284	Trimesh hull.
285	model
286	Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
287	the list of supported colourspace models.
288	axis
289	Axis the hull section will be normal to.
290	origin
291	Coordinate along ``axis`` at which to plot the hull section.
292	normalise
293	Whether to normalise ``axis`` to the extent of the hull along it.
294	contour_colours
295	Colours of the hull section contour, if ``contour_colours`` is set to
296	RGB, the colours will be computed according to the corresponding
297	coordinates.
298	contour_opacity
299	Opacity of the hull section contour.
300	convert_kwargs
301	Keyword arguments for the :func:`colour.convert` definition.
302
303	Other Parameters
304	----------------
305	kwargs
306	{:func:`colour.plotting.artist`,
307	:func:`colour.plotting.render`},
308	See the documentation of the previously listed definitions.
309
310	Returns
311	-------
312	:class:`tuple`
313	Current figure and axes.
314
315	Examples
316	--------
317	>>> from colour.models import RGB_COLOURSPACE_sRGB
318	>>> from colour.utilities import is_trimesh_installed
319	>>> vertices, faces, _outline = primitive_cube(1, 1, 1, 64, 64, 64)
320	>>> XYZ_vertices = RGB_to_XYZ(vertices["position"] + 0.5, RGB_COLOURSPACE_sRGB)
321	>>> if is_trimesh_installed:
322	... from trimesh import Trimesh
323	...
324	... hull = Trimesh(XYZ_vertices, faces, process=False)
325	... plot_hull_section_contour(hull, contour_colours="RGB")
326	... # doctest: +ELLIPSIS
327	(<Figure size ... with 1 Axes>, <...Axes...>)
328
329	.. image:: ../_static/Plotting_Plot_Hull_Section_Contour.png
330	:align: center
331	:alt: plot_hull_section_contour
332	"""
333
334	hull = hull.copy()	×
335
336	contour_colours = optional(contour_colours, CONSTANTS_COLOUR_STYLE.colour.dark)	×
337
338	settings: Dict[str, Any] = {"uniform": True}	×
339	settings.update(kwargs)	×
340
341	_figure, axes = artist(**settings)	×
342
343	convert_kwargs = optional(convert_kwargs, {})	×
344
345	# Luminance / Lightness is re-ordered along "z-up" axis.
346	with suppress_warnings(python_warnings=True):	×
347	ijk_vertices = colourspace_model_axis_reorder(	×
348	convert(hull.vertices, "CIE XYZ", model, **convert_kwargs), model
349	)
350	ijk_vertices = np.nan_to_num(ijk_vertices)	×
351	ijk_vertices *= COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model]	×
352
353	hull.vertices = ijk_vertices	×
354
355	plane = MAPPING_AXIS_TO_PLANE[axis]	×
356
357	padding = 0.1 * np.mean(COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model])	×
358	min_x = np.min(ijk_vertices[..., plane[0]]) - padding	×
359	max_x = np.max(ijk_vertices[..., plane[0]]) + padding	×
360	min_y = np.min(ijk_vertices[..., plane[1]]) - padding	×
361	max_y = np.max(ijk_vertices[..., plane[1]]) + padding	×
362	extent = (min_x, max_x, min_y, max_y)	×
363
364	use_RGB_contour_colours = str(contour_colours).upper() == "RGB"	×
365	section = hull_section(hull, axis, origin, normalise)	×
366	if use_RGB_contour_colours:	×
367	ijk_section = (	×
368	section / (COLOURSPACE_MODELS_DOMAIN_RANGE_SCALE_1_TO_REFERENCE[model])
369	)
370	XYZ_section = convert(	×
371	colourspace_model_axis_reorder(ijk_section, model, "Inverse"),
372	model,
373	"CIE XYZ",
374	**convert_kwargs,
375	)
376	contour_colours = np.clip(XYZ_to_plotting_colourspace(XYZ_section), 0, 1)	×
377
378	section = np.reshape(section[..., plane], (-1, 1, 2))	×
379	line_collection = LineCollection(	×
380	np.concatenate([section[:-1], section[1:]], axis=1), # pyright: ignore
381	colors=contour_colours,
382	alpha=contour_opacity,
383	zorder=CONSTANTS_COLOUR_STYLE.zorder.background_line,
384	)
385	axes.add_collection(line_collection)	×
386
387	settings = {	×
388	"axes": axes,
389	"bounding_box": extent,
390	}
391	settings.update(kwargs)	×
392
393	return render(**settings)	×
394
395
396	@required("trimesh")	×
397	@override_style()	×
398	def plot_visible_spectrum_section(	×
399	cmfs: (
400	MultiSpectralDistributions \| str \| Sequence[MultiSpectralDistributions \| str]
401	) = "CIE 1931 2 Degree Standard Observer",
402	illuminant: SpectralDistribution \| str = "D65",
403	model: LiteralColourspaceModel \| str = "CIE xyY",
404	axis: Literal["+z", "+x", "+y"] \| str = "+z",
405	origin: float = 0.5,
406	normalise: bool = True,
407	show_section_colours: bool = True,
408	show_section_contour: bool = True,
409	**kwargs: Any,
410	) -> Tuple[Figure, Axes]:
411	"""
412	Plot the visible spectrum volume, i.e. Rösch-MacAdam colour solid,
413	section colours along given axis and origin.
414
415	Parameters
416	----------
417	cmfs
418	Standard observer colour matching functions, default to the
419	CIE 1931 2 Degree Standard Observer. ``cmfs`` can be of any type or
420	form supported by the :func:`colour.plotting.common.filter_cmfs`
421	definition.
422	illuminant
423	Illuminant spectral distribution, default to CIE Illuminant D65.
424	``illuminant`` can be of any type or form supported by the
425	:func:`colour.plotting.common.filter_illuminants` definition.
426	model
427	Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
428	the list of supported colourspace models.
429	axis
430	Axis the hull section will be normal to.
431	origin
432	Coordinate along ``axis`` at which to plot the hull section.
433	normalise
434	Whether to normalise ``axis`` to the extent of the hull along it.
435	show_section_colours
436	Whether to show the hull section colours.
437	show_section_contour
438	Whether to show the hull section contour.
439
440	Other Parameters
441	----------------
442	kwargs
443	{:func:`colour.plotting.artist`,
444	:func:`colour.plotting.render`,
445	:func:`colour.plotting.section.plot_hull_section_colours`
446	:func:`colour.plotting.section.plot_hull_section_contour`},
447	See the documentation of the previously listed definitions.
448
449	Returns
450	-------
451	:class:`tuple`
452	Current figure and axes.
453
454	Examples
455	--------
456	>>> from colour.utilities import is_trimesh_installed
457	>>> if is_trimesh_installed:
458	... plot_visible_spectrum_section(section_colours="RGB", section_opacity=0.15)
459	... # doctest: +ELLIPSIS
460	(<Figure size ... with 1 Axes>, <...Axes...>)
461
462	.. image:: ../_static/Plotting_Plot_Visible_Spectrum_Section.png
463	:align: center
464	:alt: plot_visible_spectrum_section
465	"""
466
467	import trimesh.convex	×
468	from trimesh import Trimesh	×
469
470	settings: Dict[str, Any] = {"uniform": True}	×
471	settings.update(kwargs)	×
472
473	_figure, axes = artist(**settings)	×
474
475	cmfs = cast(	×
476	MultiSpectralDistributions,
477	reshape_msds(
478	first_item(filter_cmfs(cmfs).values()),
479	SpectralShape(360, 780, 1),
480	copy=False,
481	),
482	)
483	illuminant = cast(	×
484	SpectralDistribution,
485	first_item(filter_illuminants(illuminant).values()),
486	)
487
488	vertices = solid_RoschMacAdam(	×
489	cmfs,
490	illuminant,
491	point_order="Pulse Wave Width",
492	filter_jagged_points=True,
493	)
494	mesh = Trimesh(vertices)	×
495	hull = trimesh.convex.convex_hull(mesh)	×
496
497	if show_section_colours:	×
498	settings = {"axes": axes}	×
499	settings.update(kwargs)	×
500	settings["show"] = False	×
501
502	plot_hull_section_colours(hull, model, axis, origin, normalise, **settings)	×
503
504	if show_section_contour:	×
505	settings = {"axes": axes}	×
506	settings.update(kwargs)	×
507	settings["show"] = False	×
508
509	plot_hull_section_contour(hull, model, axis, origin, normalise, **settings)	×
510
511	title = (	×
512	f"Visible Spectrum Section - "
513	f"{f'{origin * 100}%' if normalise else origin} - "
514	f"{model} - "
515	f"{cmfs.display_name}"
516	)
517
518	plane = MAPPING_AXIS_TO_PLANE[axis]	×
519
520	labels = np.array(COLOURSPACE_MODELS_AXIS_LABELS[model])[	×
521	as_int_array(colourspace_model_axis_reorder([0, 1, 2], model))
522	]
523	x_label, y_label = labels[plane[0]], labels[plane[1]]	×
524
525	settings.update(	×
526	{
527	"axes": axes,
528	"show": True,
529	"title": title,
530	"x_label": x_label,
531	"y_label": y_label,
532	}
533	)
534	settings.update(kwargs)	×
535
536	return render(**settings)	×
537
538
539	@required("trimesh")	×
540	@override_style()	×
541	def plot_RGB_colourspace_section(	×
542	colourspace: (
543	RGB_Colourspace
544	\| LiteralRGBColourspace
545	\| str
546	\| Sequence[RGB_Colourspace \| LiteralRGBColourspace \| str]
547	),
548	model: LiteralColourspaceModel \| str = "CIE xyY",
549	axis: Literal["+z", "+x", "+y"] \| str = "+z",
550	origin: float = 0.5,
551	normalise: bool = True,
552	size: float = 1.0,
553	show_section_colours: bool = True,
554	show_section_contour: bool = True,
555	segments: int = 64,
556	**kwargs: Any,
557	) -> Tuple[Figure, Axes]:
558	"""
559	Plot given RGB colourspace section colours along given axis and origin.
560
561	Parameters
562	----------
563	colourspace
564	RGB colourspace of the RGB array. ``colourspace`` can be of any
565	type or form supported by the
566	:func:`colour.plotting.common.filter_RGB_colourspaces` definition.
567	model
568	Colourspace model, see :attr:`colour.COLOURSPACE_MODELS` attribute for
569	the list of supported colourspace models.
570	axis
571	Axis the hull section will be normal to.
572	origin
573	Coordinate along ``axis`` at which to plot the hull section.
574	normalise
575	Whether to normalise ``axis`` to the extent of the hull along it.
576	size:
577	Size of the underlying RGB colourspace cube; used for plotting HDR
578	related sections.
579	show_section_colours
580	Whether to show the hull section colours.
581	show_section_contour
582	Whether to show the hull section contour.
583	segments
584	Edge segments count for the RGB colourspace cube.
585
586	Other Parameters
587	----------------
588	kwargs
589	{:func:`colour.plotting.artist`,
590	:func:`colour.plotting.render`,
591	:func:`colour.plotting.section.plot_hull_section_colours`
592	:func:`colour.plotting.section.plot_hull_section_contour`},
593	See the documentation of the previously listed definitions.
594
595	Returns
596	-------
597	:class:`tuple`
598	Current figure and axes.
599
600	Examples
601	--------
602	>>> from colour.utilities import is_trimesh_installed
603	>>> if is_trimesh_installed:
604	... plot_RGB_colourspace_section(
605	... "sRGB", section_colours="RGB", section_opacity=0.15
606	... )
607	... # doctest: +ELLIPSIS
608	(<Figure size ... with 1 Axes>, <...Axes...>)
609
610	.. image:: ../_static/Plotting_Plot_RGB_Colourspace_Section.png
611	:align: center
612	:alt: plot_RGB_colourspace_section
613	"""
614
615	from trimesh import Trimesh	×
616
617	settings: Dict[str, Any] = {"uniform": True}	×
618	settings.update(kwargs)	×
619
620	_figure, axes = artist(**settings)	×
621
622	colourspace = cast(	×
623	RGB_Colourspace,
624	first_item(filter_RGB_colourspaces(colourspace).values()),
625	)
626
627	vertices, faces, _outline = primitive_cube(1, 1, 1, segments, segments, segments)	×
628	XYZ_vertices = RGB_to_XYZ((vertices["position"] + 0.5) * size, colourspace)	×
629	hull = Trimesh(XYZ_vertices, faces, process=False)	×
630
631	if show_section_colours:	×
632	settings = {"axes": axes}	×
633	settings.update(kwargs)	×
634	settings["show"] = False	×
635
636	plot_hull_section_colours(hull, model, axis, origin, normalise, **settings)	×
637
638	if show_section_contour:	×
639	settings = {"axes": axes}	×
640	settings.update(kwargs)	×
641	settings["show"] = False	×
642
643	plot_hull_section_contour(hull, model, axis, origin, normalise, **settings)	×
644
645	title = (	×
646	f"{colourspace.name} Section - "
647	f"{f'{origin * 100}%' if normalise else origin} - "
648	f"{model}"
649	)
650
651	plane = MAPPING_AXIS_TO_PLANE[axis]	×
652
653	labels = np.array(COLOURSPACE_MODELS_AXIS_LABELS[model])[	×
654	as_int_array(colourspace_model_axis_reorder([0, 1, 2], model))
655	]
656	x_label, y_label = labels[plane[0]], labels[plane[1]]	×
657
658	settings.update(	×
659	{
660	"axes": axes,
661	"show": True,
662	"title": title,
663	"x_label": x_label,
664	"y_label": y_label,
665	}
666	)
667	settings.update(kwargs)	×
668
669	return render(**settings)	×

colour-science / colour / 9579473519

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