mpl_toolkits.mplot3d.art3d.Poly3DCollection#

class mpl_toolkits.mplot3d.art3d.Poly3DCollection(verts, *args, zsort='average', shade=False, lightsource=None, **kwargs)[source]#

Bases: PolyCollection

A collection of 3D polygons.

Note

Filling of 3D polygons

There is no simple definition of the enclosed surface of a 3D polygon unless the polygon is planar.

In practice, Matplotlib fills the 2D projection of the polygon. This gives a correct filling appearance only for planar polygons. For all other polygons, you'll find orientations in which the edges of the polygon intersect in the projection. This will lead to an incorrect visualization of the 3D area.

If you need filled areas, it is recommended to create them via plot_trisurf, which creates a triangulation and thus generates consistent surfaces.

Parameters:
vertslist of (N, 3) array-like

The sequence of polygons [verts0, verts1, ...] where each element verts_i defines the vertices of polygon i as a 2D array-like of shape (N, 3).

zsort{'average', 'min', 'max'}, default: 'average'

The calculation method for the z-order. See set_zsort for details.

shadebool, default: False

Whether to shade facecolors and edgecolors. When activating shade, facecolors and/or edgecolors must be provided.

New in version 3.7.

lightsourceLightSource, optional

The lightsource to use when shade is True.

New in version 3.7.

*args, **kwargs

All other parameters are forwarded to PolyCollection.

Notes

Note that this class does a bit of magic with the _facecolors and _edgecolors properties.

do_3d_projection()[source]#

Perform the 3D projection for this object.

get_edgecolor()[source]#
get_facecolor()[source]#
get_vector(segments3d)[source]#

Optimize points for projection.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, array=<UNSET>, capstyle=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, gid=<UNSET>, hatch=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, offset_transform=<UNSET>, offsets=<UNSET>, path_effects=<UNSET>, paths=<UNSET>, picker=<UNSET>, pickradius=<UNSET>, rasterized=<UNSET>, sizes=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, sort_zpos=<UNSET>, transform=<UNSET>, url=<UNSET>, urls=<UNSET>, verts=<UNSET>, verts_and_codes=<UNSET>, visible=<UNSET>, zorder=<UNSET>, zsort=<UNSET>)[source]#

Set multiple properties at once.

Supported properties are

Property

Description

agg_filter

a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image

alpha

unknown

animated

bool

antialiased or aa or antialiaseds

bool or list of bools

array

array-like or None

capstyle

CapStyle or {'butt', 'projecting', 'round'}

clim

(vmin: float, vmax: float)

clip_box

BboxBase or None

clip_on

bool

clip_path

Patch or (Path, Transform) or None

cmap

Colormap or str or None

color

color or list of RGBA tuples

edgecolor or ec or edgecolors

unknown

facecolor or facecolors or fc

unknown

figure

Figure

gid

str

hatch

{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}

in_layout

bool

joinstyle

JoinStyle or {'miter', 'round', 'bevel'}

label

object

linestyle or dashes or linestyles or ls

str or tuple or list thereof

linewidth or linewidths or lw

float or list of floats

mouseover

bool

norm

Normalize or str or None

offset_transform or transOffset

Transform

offsets

(N, 2) or (2,) array-like

path_effects

list of AbstractPathEffect

paths

list of array-like

picker

None or bool or float or callable

pickradius

float

rasterized

bool

sizes

numpy.ndarray or None

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

sort_zpos

unknown

transform

Transform

url

str

urls

list of str or None

verts

list of (N, 3) array-like

verts_and_codes

unknown

visible

bool

zorder

float

zsort

{'average', 'min', 'max'}

set_3d_properties()[source]#
set_alpha(alpha)[source]#

Set the alpha value used for blending - not supported on all backends.

Parameters:
alphaarray-like or scalar or None

All values must be within the 0-1 range, inclusive. Masked values and nans are not supported.

set_edgecolor(colors)[source]#

Set the edgecolor(s) of the collection.

Parameters:
ccolor or list of colors or 'face'

The collection edgecolor(s). If a sequence, the patches cycle through it. If 'face', match the facecolor.

set_facecolor(colors)[source]#

Set the facecolor(s) of the collection. c can be a color (all patches have same color), or a sequence of colors; if it is a sequence the patches will cycle through the sequence.

If c is 'none', the patch will not be filled.

Parameters:
ccolor or list of colors
set_sort_zpos(val)[source]#

Set the position to use for z-sorting.

set_verts(verts, closed=True)[source]#

Set 3D vertices.

Parameters:
vertslist of (N, 3) array-like

The sequence of polygons [verts0, verts1, ...] where each element verts_i defines the vertices of polygon i as a 2D array-like of shape (N, 3).

closedbool, default: True

Whether the polygon should be closed by adding a CLOSEPOLY connection at the end.

set_verts_and_codes(verts, codes)[source]#

Set 3D vertices with path codes.

set_zsort(zsort)[source]#

Set the calculation method for the z-order.

Parameters:
zsort{'average', 'min', 'max'}

The function applied on the z-coordinates of the vertices in the viewer's coordinate system, to determine the z-order.

Examples using mpl_toolkits.mplot3d.art3d.Poly3DCollection#

Custom hillshading in a 3D surface plot

Custom hillshading in a 3D surface plot

2D and 3D axes in same figure

2D and 3D axes in same figure

Generate polygons to fill under 3D line graph

Generate polygons to fill under 3D line graph

3D plots as subplots

3D plots as subplots

3D surface (colormap)

3D surface (colormap)

3D surface (checkerboard)

3D surface (checkerboard)