# art3d.py, original mplot3d version by John Porter

# Parts rewritten by Reinier Heeres <[email protected]>

# Minor additions by Ben Axelrod <[email protected]>

"""

Module containing 3D artist code and functions to convert 2D

artists into 3D versions which can be added to an Axes3D.

"""

import math

import numpy as np

from contextlib import contextmanager

from matplotlib import (

_api, artist, cbook, colors as mcolors, lines, text as mtext,

path as mpath, rcParams)

from matplotlib.collections import (

Collection, LineCollection, PolyCollection, PatchCollection, PathCollection)

from matplotlib.patches import Patch

from . import proj3d

def _norm_angle(a):

"""Return the given angle normalized to -180 < *a* <= 180 degrees."""

a = (a + 360) % 360

if a > 180:

a = a - 360

return a

def _norm_text_angle(a):

"""Return the given angle normalized to -90 < *a* <= 90 degrees."""

a = (a + 180) % 180

if a > 90:

a = a - 180

return a

def get_dir_vector(zdir):

"""

Return a direction vector.

Parameters

----------

zdir : {'x', 'y', 'z', None, 3-tuple}

The direction. Possible values are:

- 'x': equivalent to (1, 0, 0)

- 'y': equivalent to (0, 1, 0)

- 'z': equivalent to (0, 0, 1)

- *None*: equivalent to (0, 0, 0)

- an iterable (x, y, z) is converted to an array

Returns

-------

x, y, z : array

The direction vector.

"""

if cbook._str_equal(zdir, 'x'):

return np.array((1, 0, 0))

elif cbook._str_equal(zdir, 'y'):

return np.array((0, 1, 0))

elif cbook._str_equal(zdir, 'z'):

return np.array((0, 0, 1))

elif zdir is None:

return np.array((0, 0, 0))

elif np.iterable(zdir) and len(zdir) == 3:

return np.array(zdir)

else:

raise ValueError("'x', 'y', 'z', None or vector of length 3 expected")

def _viewlim_mask(xs, ys, zs, axes):

"""

Return the mask of the points outside the axes view limits.

Parameters

----------

xs, ys, zs : array-like

The points to mask. These should be in data coordinates.

axes : Axes3D

The axes to use for the view limits.

Returns

-------

mask : np.array

The mask of the points as a bool array.

"""

mask = np.logical_or.reduce((xs < axes.xy_viewLim.xmin,

xs > axes.xy_viewLim.xmax,

ys < axes.xy_viewLim.ymin,

ys > axes.xy_viewLim.ymax,

zs < axes.zz_viewLim.xmin,

zs > axes.zz_viewLim.xmax))

return mask

class Text3D(mtext.Text):

"""

Text object with 3D position and direction.

Parameters

----------

x, y, z : float

The position of the text.

text : str

The text string to display.

zdir : {'x', 'y', 'z', None, 3-tuple}

The direction of the text. See `.get_dir_vector` for a description of

the values.

axlim_clip : bool, default: False

Whether to hide text outside the axes view limits.

.. versionadded:: 3.10

Other Parameters

----------------

**kwargs

All other parameters are passed on to `~matplotlib.text.Text`.

"""

def __init__(self, x=0, y=0, z=0, text='', zdir='z', axlim_clip=False,

**kwargs):

if 'rotation' in kwargs:

_api.warn_external(

"The `rotation` parameter has not yet been implemented "

"and is currently ignored."

)

if 'rotation_mode' in kwargs:

_api.warn_external(

"The `rotation_mode` parameter has not yet been implemented "

"and is currently ignored."

)

mtext.Text.__init__(self, x, y, text, **kwargs)

self.set_3d_properties(z, zdir, axlim_clip)

def get_position_3d(self):

"""Return the (x, y, z) position of the text."""

return self._x, self._y, self._z

def set_position_3d(self, xyz, zdir=None):

"""

Set the (*x*, *y*, *z*) position of the text.

Parameters

----------

xyz : (float, float, float)

The position in 3D space.

zdir : {'x', 'y', 'z', None, 3-tuple}

The direction of the text. If unspecified, the *zdir* will not be

changed. See `.get_dir_vector` for a description of the values.

"""

super().set_position(xyz[:2])

self.set_z(xyz[2])

if zdir is not None:

self._dir_vec = get_dir_vector(zdir)

def set_z(self, z):

"""

Set the *z* position of the text.

Parameters

----------

z : float

"""

self._z = z

self.stale = True

def set_3d_properties(self, z=0, zdir='z', axlim_clip=False):

"""

Set the *z* position and direction of the text.

Parameters

----------

z : float

The z-position in 3D space.

zdir : {'x', 'y', 'z', 3-tuple}

The direction of the text. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide text outside the axes view limits.

.. versionadded:: 3.10

"""

self._z = z

self._dir_vec = get_dir_vector(zdir)

self._axlim_clip = axlim_clip

self.stale = True

@artist.allow_rasterization

def draw(self, renderer):

if self._axlim_clip:

mask = _viewlim_mask(self._x, self._y, self._z, self.axes)

pos3d = np.ma.array([self._x, self._y, self._z],

mask=mask, dtype=float).filled(np.nan)

else:

pos3d = np.array([self._x, self._y, self._z], dtype=float)

dir_end = pos3d + self._dir_vec

points = np.asarray([pos3d, dir_end])

proj = proj3d._scale_proj_transform(

points[:, 0], points[:, 1], points[:, 2], self.axes)

dx = proj[0][1] - proj[0][0]

dy = proj[1][1] - proj[1][0]

angle = math.degrees(math.atan2(dy, dx))

with cbook._setattr_cm(self, _x=proj[0][0], _y=proj[1][0],

_rotation=_norm_text_angle(angle)):

mtext.Text.draw(self, renderer)

self.stale = False

def get_tightbbox(self, renderer=None):

# Overwriting the 2d Text behavior which is not valid for 3d.

# For now, just return None to exclude from layout calculation.

return None

def text_2d_to_3d(obj, z=0, zdir='z', axlim_clip=False):

"""

Convert a `.Text` to a `.Text3D` object.

Parameters

----------

z : float

The z-position in 3D space.

zdir : {'x', 'y', 'z', 3-tuple}

The direction of the text. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide text outside the axes view limits.

.. versionadded:: 3.10

"""

obj.__class__ = Text3D

obj.set_3d_properties(z, zdir, axlim_clip)

class Line3D(lines.Line2D):

"""

3D line object.

.. note:: Use `get_data_3d` to obtain the data associated with the line.

`~.Line2D.get_data`, `~.Line2D.get_xdata`, and `~.Line2D.get_ydata` return

the x- and y-coordinates of the projected 2D-line, not the x- and y-data of

the 3D-line. Similarly, use `set_data_3d` to set the data, not

`~.Line2D.set_data`, `~.Line2D.set_xdata`, and `~.Line2D.set_ydata`.

"""

def __init__(self, xs, ys, zs, *args, axlim_clip=False, **kwargs):

"""

Parameters

----------

xs : array-like

The x-data to be plotted.

ys : array-like

The y-data to be plotted.

zs : array-like

The z-data to be plotted.

*args, **kwargs

Additional arguments are passed to `~matplotlib.lines.Line2D`.

"""

super().__init__([], [], *args, **kwargs)

self.set_data_3d(xs, ys, zs)

self._axlim_clip = axlim_clip

def set_3d_properties(self, zs=0, zdir='z', axlim_clip=False):

"""

Set the *z* position and direction of the line.

Parameters

----------

zs : float or array of floats

The location along the *zdir* axis in 3D space to position the

line.

zdir : {'x', 'y', 'z'}

Plane to plot line orthogonal to. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide lines with an endpoint outside the axes view limits.

.. versionadded:: 3.10

"""

xs = self.get_xdata()

ys = self.get_ydata()

zs = cbook._to_unmasked_float_array(zs).ravel()

zs = np.broadcast_to(zs, len(xs))

self._verts3d = juggle_axes(xs, ys, zs, zdir)

self._axlim_clip = axlim_clip

self.stale = True

def set_data_3d(self, *args):

"""

Set the x, y and z data

Parameters

----------

x : array-like

The x-data to be plotted.

y : array-like

The y-data to be plotted.

z : array-like

The z-data to be plotted.

Notes

-----

Accepts x, y, z arguments or a single array-like (x, y, z)

"""

if len(args) == 1:

args = args[0]

for name, xyz in zip('xyz', args):

if not np.iterable(xyz):

raise RuntimeError(f'{name} must be a sequence')

self._verts3d = args

self.stale = True

def get_data_3d(self):

"""

Get the current data

Returns

-------

verts3d : length-3 tuple or array-like

The current data as a tuple or array-like.

"""

return self._verts3d

@artist.allow_rasterization

def draw(self, renderer):

if self._axlim_clip:

mask = np.broadcast_to(

_viewlim_mask(*self._verts3d, self.axes),

(len(self._verts3d), *self._verts3d[0].shape)

)

xs3d, ys3d, zs3d = np.ma.array(self._verts3d,

dtype=float, mask=mask).filled(np.nan)

else:

xs3d, ys3d, zs3d = self._verts3d

xs, ys, zs, tis = proj3d._scale_proj_transform_clip(xs3d, ys3d, zs3d, self.axes)

self.set_data(xs, ys)

super().draw(renderer)

self.stale = False

def line_2d_to_3d(line, zs=0, zdir='z', axlim_clip=False):

"""

Convert a `.Line2D` to a `.Line3D` object.

Parameters

----------

zs : float

The location along the *zdir* axis in 3D space to position the line.

zdir : {'x', 'y', 'z'}

Plane to plot line orthogonal to. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide lines with an endpoint outside the axes view limits.

.. versionadded:: 3.10

"""

line.__class__ = Line3D

line.set_3d_properties(zs, zdir, axlim_clip)

def _path_to_3d_segment(path, zs=0, zdir='z'):

"""Convert a path to a 3D segment."""

zs = np.broadcast_to(zs, len(path))

pathsegs = path.iter_segments(simplify=False, curves=False)

seg = [(x, y, z) for (((x, y), code), z) in zip(pathsegs, zs)]

seg3d = [juggle_axes(x, y, z, zdir) for (x, y, z) in seg]

return seg3d

def _paths_to_3d_segments(paths, zs=0, zdir='z'):

"""Convert paths from a collection object to 3D segments."""

if not np.iterable(zs):

zs = np.broadcast_to(zs, len(paths))

else:

if len(zs) != len(paths):

raise ValueError('Number of z-coordinates does not match paths.')

segs = [_path_to_3d_segment(path, pathz, zdir)

for path, pathz in zip(paths, zs)]

return segs

def _path_to_3d_segment_with_codes(path, zs=0, zdir='z'):

"""Convert a path to a 3D segment with path codes."""

zs = np.broadcast_to(zs, len(path))

pathsegs = path.iter_segments(simplify=False, curves=False)

seg_codes = [((x, y, z), code) for ((x, y), code), z in zip(pathsegs, zs)]

if seg_codes:

seg, codes = zip(*seg_codes)

seg3d = [juggle_axes(x, y, z, zdir) for (x, y, z) in seg]

else:

seg3d = []

codes = []

return seg3d, list(codes)

def _paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):

"""

Convert paths from a collection object to 3D segments with path codes.

"""

zs = np.broadcast_to(zs, len(paths))

segments_codes = [_path_to_3d_segment_with_codes(path, pathz, zdir)

for path, pathz in zip(paths, zs)]

if segments_codes:

segments, codes = zip(*segments_codes)

else:

segments, codes = [], []

return list(segments), list(codes)

class Collection3D(Collection):

"""A collection of 3D paths."""

def do_3d_projection(self):

"""Project the points according to renderer matrix."""

vs_list = [vs for vs, _ in self._3dverts_codes]

if self._axlim_clip:

vs_list = [np.ma.array(vs, mask=np.broadcast_to(

_viewlim_mask(*vs.T, self.axes), vs.shape))

for vs in vs_list]

xyzs_list = [proj3d._scale_proj_transform(

vs[:, 0], vs[:, 1], vs[:, 2], self.axes) for vs in vs_list]

self._paths = [mpath.Path(np.ma.column_stack([xs, ys]), cs)

for (xs, ys, _), (_, cs) in zip(xyzs_list, self._3dverts_codes)]

zs = np.concatenate([zs for _, _, zs in xyzs_list])

return zs.min() if len(zs) else 1e9

def collection_2d_to_3d(col, zs=0, zdir='z', axlim_clip=False):

"""Convert a `.Collection` to a `.Collection3D` object."""

zs = np.broadcast_to(zs, len(col.get_paths()))

col._3dverts_codes = [

(np.column_stack(juggle_axes(

*np.column_stack([p.vertices, np.broadcast_to(z, len(p.vertices))]).T,

zdir)),

p.codes)

for p, z in zip(col.get_paths(), zs)]

col.__class__ = cbook._make_class_factory(Collection3D, "{}3D")(type(col))

col._axlim_clip = axlim_clip

class Line3DCollection(LineCollection):

"""

A collection of 3D lines.

"""

def __init__(self, lines, axlim_clip=False, **kwargs):

super().__init__(lines, **kwargs)

self._axlim_clip = axlim_clip

"""

Parameters

----------

lines : list of (N, 3) array-like

A sequence ``[line0, line1, ...]`` where each line is a (N, 3)-shape

array-like containing points:: line0 = [(x0, y0, z0), (x1, y1, z1), ...]

Each line can contain a different number of points.

linewidths : float or list of float, default: :rc:`lines.linewidth`

The width of each line in points.

colors : :mpltype:`color` or list of color, default: :rc:`lines.color`

A sequence of RGBA tuples (e.g., arbitrary color strings, etc, not

allowed).

antialiaseds : bool or list of bool, default: :rc:`lines.antialiased`

Whether to use antialiasing for each line.

facecolors : :mpltype:`color` or list of :mpltype:`color`, default: 'none'

When setting *facecolors*, each line is interpreted as a boundary

for an area, implicitly closing the path from the last point to the

first point. The enclosed area is filled with *facecolor*.

In order to manually specify what should count as the "interior" of

each line, please use `.PathCollection` instead, where the

"interior" can be specified by appropriate usage of

`~.path.Path.CLOSEPOLY`.

**kwargs : Forwarded to `.Collection`.

"""

def set_sort_zpos(self, val):

"""Set the position to use for z-sorting."""

self._sort_zpos = val

self.stale = True

def set_segments(self, segments):

"""

Set 3D segments.

"""

self._segments3d = segments

super().set_segments([])

def do_3d_projection(self):

"""

Project the points according to renderer matrix.

"""

segments = np.asanyarray(self._segments3d)

# Handle empty segments

if segments.size == 0:

LineCollection.set_segments(self, [])

return np.nan

mask = False

if np.ma.isMA(segments):

mask = segments.mask

if self._axlim_clip:

viewlim_mask = _viewlim_mask(segments[..., 0],

segments[..., 1],

segments[..., 2],

self.axes)

if np.any(viewlim_mask):

# broadcast mask to 3D

viewlim_mask = np.broadcast_to(viewlim_mask[..., np.newaxis],

(*viewlim_mask.shape, 3))

mask = mask | viewlim_mask

xyzs = np.ma.array(

proj3d._scale_proj_transform_vectors(segments, self.axes), mask=mask)

segments_2d = xyzs[..., 0:2]

LineCollection.set_segments(self, segments_2d)

# FIXME

if len(xyzs) > 0:

minz = min(xyzs[..., 2].min(), 1e9)

else:

minz = np.nan

return minz

def line_collection_2d_to_3d(col, zs=0, zdir='z', axlim_clip=False):

"""Convert a `.LineCollection` to a `.Line3DCollection` object."""

segments3d = _paths_to_3d_segments(col.get_paths(), zs, zdir)

col.__class__ = Line3DCollection

col.set_segments(segments3d)

col._axlim_clip = axlim_clip

class Patch3D(Patch):

"""

3D patch object.

"""

def __init__(self, *args, zs=(), zdir='z', axlim_clip=False, **kwargs):

"""

Parameters

----------

verts :

zs : float

The location along the *zdir* axis in 3D space to position the

patch.

zdir : {'x', 'y', 'z'}

Plane to plot patch orthogonal to. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide patches with a vertex outside the axes view limits.

.. versionadded:: 3.10

"""

super().__init__(*args, **kwargs)

self.set_3d_properties(zs, zdir, axlim_clip)

def set_3d_properties(self, verts, zs=0, zdir='z', axlim_clip=False):

"""

Set the *z* position and direction of the patch.

Parameters

----------

verts :

zs : float

The location along the *zdir* axis in 3D space to position the

patch.

zdir : {'x', 'y', 'z'}

Plane to plot patch orthogonal to. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide patches with a vertex outside the axes view limits.

.. versionadded:: 3.10

"""

zs = np.broadcast_to(zs, len(verts))

self._segment3d = [juggle_axes(x, y, z, zdir)

for ((x, y), z) in zip(verts, zs)]

self._axlim_clip = axlim_clip

def get_path(self):

# docstring inherited

# self._path2d is not initialized until do_3d_projection

if not hasattr(self, '_path2d'):

self.axes.M = self.axes.get_proj()

self.do_3d_projection()

return self._path2d

def do_3d_projection(self):

s = self._segment3d

if self._axlim_clip:

mask = _viewlim_mask(*zip(*s), self.axes)

xs, ys, zs = np.ma.array(zip(*s),

dtype=float, mask=mask).filled(np.nan)

else:

xs, ys, zs = zip(*s)

vxs, vys, vzs, vis = proj3d._scale_proj_transform_clip(xs, ys, zs, self.axes)

self._path2d = mpath.Path(np.ma.column_stack([vxs, vys]))

return min(vzs)

class PathPatch3D(Patch3D):

"""

3D PathPatch object.

"""

def __init__(self, path, *, zs=(), zdir='z', axlim_clip=False, **kwargs):

"""

Parameters

----------

path :

zs : float

The location along the *zdir* axis in 3D space to position the

path patch.

zdir : {'x', 'y', 'z', 3-tuple}

Plane to plot path patch orthogonal to. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide path patches with a point outside the axes view limits.

.. versionadded:: 3.10

"""

# Not super().__init__!

Patch.__init__(self, **kwargs)

self.set_3d_properties(path, zs, zdir, axlim_clip)

def set_3d_properties(self, path, zs=0, zdir='z', axlim_clip=False):

"""

Set the *z* position and direction of the path patch.

Parameters

----------

path :

zs : float

The location along the *zdir* axis in 3D space to position the

path patch.

zdir : {'x', 'y', 'z', 3-tuple}

Plane to plot path patch orthogonal to. Default: 'z'.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide path patches with a point outside the axes view limits.

.. versionadded:: 3.10

"""

Patch3D.set_3d_properties(self, path.vertices, zs=zs, zdir=zdir,

axlim_clip=axlim_clip)

self._code3d = path.codes

def do_3d_projection(self):

s = self._segment3d

if self._axlim_clip:

mask = _viewlim_mask(*zip(*s), self.axes)

xs, ys, zs = np.ma.array(zip(*s),

dtype=float, mask=mask).filled(np.nan)

else:

xs, ys, zs = zip(*s)

vxs, vys, vzs, vis = proj3d._scale_proj_transform_clip(xs, ys, zs, self.axes)

self._path2d = mpath.Path(np.ma.column_stack([vxs, vys]), self._code3d)

return min(vzs)

def _get_patch_verts(patch):

"""Return a list of vertices for the path of a patch."""

trans = patch.get_patch_transform()

path = patch.get_path()

polygons = path.to_polygons(trans)

return polygons[0] if len(polygons) else np.array([])

def patch_2d_to_3d(patch, z=0, zdir='z', axlim_clip=False):

"""Convert a `.Patch` to a `.Patch3D` object."""

verts = _get_patch_verts(patch)

patch.__class__ = Patch3D

patch.set_3d_properties(verts, z, zdir, axlim_clip)

def pathpatch_2d_to_3d(pathpatch, z=0, zdir='z'):

"""Convert a `.PathPatch` to a `.PathPatch3D` object."""

path = pathpatch.get_path()

trans = pathpatch.get_patch_transform()

mpath = trans.transform_path(path)

pathpatch.__class__ = PathPatch3D

pathpatch.set_3d_properties(mpath, z, zdir)

class Patch3DCollection(PatchCollection):

"""

A collection of 3D patches.

"""

def __init__(

self,

*args,

zs=0,

zdir="z",

depthshade=None,

depthshade_minalpha=None,

axlim_clip=False,

**kwargs

):

"""

Create a collection of flat 3D patches with its normal vector

pointed in *zdir* direction, and located at *zs* on the *zdir*

axis. 'zs' can be a scalar or an array-like of the same length as

the number of patches in the collection.

Constructor arguments are the same as for

:class:`~matplotlib.collections.PatchCollection`. In addition,

keywords *zs=0* and *zdir='z'* are available.

The keyword argument *depthshade* is available to

indicate whether or not to shade the patches in order to

give the appearance of depth (default is *True*).

This is typically desired in scatter plots.

*depthshade_minalpha* sets the minimum alpha value applied by

depth-shading.

"""

if depthshade is None:

depthshade = rcParams['axes3d.depthshade']

if depthshade_minalpha is None:

depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']

self._depthshade = depthshade

self._depthshade_minalpha = depthshade_minalpha

super().__init__(*args, **kwargs)

self.set_3d_properties(zs, zdir, axlim_clip)

def get_depthshade(self):

return self._depthshade

def set_depthshade(

self,

depthshade,

depthshade_minalpha=None,

):

"""

Set whether depth shading is performed on collection members.

Parameters

----------

depthshade : bool

Whether to shade the patches in order to give the appearance of

depth.

depthshade_minalpha : float, default: :rc:`axes3d.depthshade_minalpha`

Sets the minimum alpha value used by depth-shading.

.. versionadded:: 3.11

"""

if depthshade_minalpha is None:

depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']

self._depthshade = depthshade

self._depthshade_minalpha = depthshade_minalpha

self.stale = True

def set_sort_zpos(self, val):

"""Set the position to use for z-sorting."""

self._sort_zpos = val

self.stale = True

def set_3d_properties(self, zs, zdir, axlim_clip=False):

"""

Set the *z* positions and direction of the patches.

Parameters

----------

zs : float or array of floats

The location or locations to place the patches in the collection

along the *zdir* axis.

zdir : {'x', 'y', 'z'}

Plane to plot patches orthogonal to.

All patches must have the same direction.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide patches with a vertex outside the axes view limits.

.. versionadded:: 3.10

"""

# Force the collection to initialize the face and edgecolors

# just in case it is a scalarmappable with a colormap.

self.update_scalarmappable()

offsets = self.get_offsets()

if len(offsets) > 0:

xs, ys = offsets.T

else:

xs = []

ys = []

self._offsets3d = juggle_axes(xs, ys, np.atleast_1d(zs), zdir)

self._z_markers_idx = slice(-1)

self._vzs = None

self._axlim_clip = axlim_clip

self.stale = True

def do_3d_projection(self):

if self._axlim_clip:

mask = _viewlim_mask(*self._offsets3d, self.axes)

xs, ys, zs = np.ma.array(self._offsets3d, mask=mask)

else:

xs, ys, zs = self._offsets3d

vxs, vys, vzs, vis = proj3d._scale_proj_transform_clip(xs, ys, zs, self.axes)

self._vzs = vzs

if np.ma.isMA(vxs):

super().set_offsets(np.ma.column_stack([vxs, vys]))

else:

super().set_offsets(np.column_stack([vxs, vys]))

if vzs.size > 0:

return min(vzs)

else:

return np.nan

def _maybe_depth_shade_and_sort_colors(self, color_array):

color_array = (

_zalpha(

color_array,

self._vzs,

min_alpha=self._depthshade_minalpha,

)

if self._vzs is not None and self._depthshade

else color_array

)

if len(color_array) > 1:

color_array = color_array[self._z_markers_idx]

return mcolors.to_rgba_array(color_array, self._alpha)

def get_facecolor(self):

return self._maybe_depth_shade_and_sort_colors(super().get_facecolor())

def get_edgecolor(self):

# We need this check here to make sure we do not double-apply the depth

# based alpha shading when the edge color is "face" which means the

# edge colour should be identical to the face colour.

if cbook._str_equal(self._edgecolors, 'face'):

return self.get_facecolor()

return self._maybe_depth_shade_and_sort_colors(super().get_edgecolor())

def _get_data_scale(X, Y, Z):

"""

Estimate the scale of the 3D data for use in depth shading

Parameters

----------

X, Y, Z : masked arrays

The data to estimate the scale of.

"""

# Account for empty datasets. Assume that X Y and Z have the same number

# of elements.

if not np.ma.count(X):

return 0

# Estimate the scale using the RSS of the ranges of the dimensions

# Note that we don't use np.ma.ptp() because we otherwise get a build

# warning about handing empty arrays.

ptp_x = X.max() - X.min()

ptp_y = Y.max() - Y.min()

ptp_z = Z.max() - Z.min()

return np.sqrt(ptp_x ** 2 + ptp_y ** 2 + ptp_z ** 2)

class Path3DCollection(PathCollection):

"""

A collection of 3D paths.

"""

def __init__(

self,

*args,

zs=0,

zdir="z",

depthshade=None,

depthshade_minalpha=None,

axlim_clip=False,

**kwargs

):

"""

Create a collection of flat 3D paths with its normal vector

pointed in *zdir* direction, and located at *zs* on the *zdir*

axis. 'zs' can be a scalar or an array-like of the same length as

the number of paths in the collection.

Constructor arguments are the same as for

:class:`~matplotlib.collections.PathCollection`. In addition,

keywords *zs=0* and *zdir='z'* are available.

Also, the keyword argument *depthshade* is available to

indicate whether or not to shade the patches in order to

give the appearance of depth (default is *True*).

This is typically desired in scatter plots.

*depthshade_minalpha* sets the minimum alpha value applied by

depth-shading.

"""

if depthshade is None:

depthshade = rcParams['axes3d.depthshade']

if depthshade_minalpha is None:

depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']

self._depthshade = depthshade

self._depthshade_minalpha = depthshade_minalpha

self._in_draw = False

super().__init__(*args, **kwargs)

self.set_3d_properties(zs, zdir, axlim_clip)

self._offset_zordered = None

def draw(self, renderer):

with self._use_zordered_offset():

with cbook._setattr_cm(self, _in_draw=True):

super().draw(renderer)

def set_sort_zpos(self, val):

"""Set the position to use for z-sorting."""

self._sort_zpos = val

self.stale = True

def set_3d_properties(self, zs, zdir, axlim_clip=False):

"""

Set the *z* positions and direction of the paths.

Parameters

----------

zs : float or array of floats

The location or locations to place the paths in the collection

along the *zdir* axis.

zdir : {'x', 'y', 'z'}

Plane to plot paths orthogonal to.

All paths must have the same direction.

See `.get_dir_vector` for a description of the values.

axlim_clip : bool, default: False

Whether to hide paths with a vertex outside the axes view limits.

.. versionadded:: 3.10

"""

# Force the collection to initialize the face and edgecolors

# just in case it is a scalarmappable with a colormap.

self.update_scalarmappable()

offsets = self.get_offsets()

if len(offsets) > 0:

xs, ys = offsets.T

else:

xs = []

ys = []

self._zdir = zdir

self._offsets3d = juggle_axes(xs, ys, np.atleast_1d(zs), zdir)

# In the base draw methods we access the attributes directly which

# means we cannot resolve the shuffling in the getter methods like

# we do for the edge and face colors.

#

# This means we need to carry around a cache of the unsorted sizes and

# widths (postfixed with 3d) and in `do_3d_projection` set the

# depth-sorted version of that data into the private state used by the

# base collection class in its draw method.

#

# Grab the current sizes and linewidths to preserve them.

self._sizes3d = self._sizes

self._linewidths3d = np.array(self._linewidths)

xs, ys, zs = self._offsets3d

# Sort the points based on z coordinates

# Performance optimization: Create a sorted index array and reorder

# points and point properties according to the index array

self._z_markers_idx = slice(-1)

self._vzs = None

self._axlim_clip = axlim_clip

self.stale = True

def set_sizes(self, sizes, dpi=72.0):

super().set_sizes(sizes, dpi)

if not self._in_draw:

self._sizes3d = sizes

def set_linewidth(self, lw):

super().set_linewidth(lw)

if not self._in_draw:

self._linewidths3d = np.array(self._linewidths)

def get_depthshade(self):

return self._depthshade

def set_depthshade(

self,

depthshade,

depthshade_minalpha=None,

):

"""

Set whether depth shading is performed on collection members.

Parameters

----------

depthshade : bool

Whether to shade the patches in order to give the appearance of