mpl_toolkits.mplot3d.art3d.Poly3DCollection

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

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.

Added in version 3.7.

lightsourceLightSource, optional

The lightsource to use when shade is True.

Added in version 3.7.

axlim_clipbool, default: False

Whether to hide polygons with a vertex outside the view limits.

*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()

Perform the 3D projection for this object.

get_edgecolor()

get_facecolor()

get_vector(segments3d)

[Deprecated]

Notes

Deprecated since version 3.10:

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>, hatch_linewidth=<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>)

Set multiple properties at once.

Supported properties are

Property	Description
3d_properties	unknown
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 or SubFigure
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	unknown
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(axlim_clip=False)

set_alpha(alpha)

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

Parameters:

alphaarray-like or float or None

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

set_edgecolor(colors)

Set the edgecolor(s) of the collection.

Parameters:

ccolor or list of color or 'face'

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

set_facecolor(colors)

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 color

set_sort_zpos(val)

Set the position to use for z-sorting.

set_verts(verts, closed=True)

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)

Set 3D vertices with path codes.

set_zsort(zsort)

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 3D polygons

Generate 3D polygons

3D plots as subplots

3D plots as subplots

3D surface (colormap)

3D surface (colormap)

3D surface (checkerboard)

3D surface (checkerboard)