mpl_toolkits.mplot3d.axes3d.Axes3D

class mpl_toolkits.mplot3d.axes3d.Axes3D(fig, rect=None, *args, azim=- 60, elev=30, sharez=None, proj_type='persp', box_aspect=None, **kwargs)

Bases: matplotlib.axes._axes.Axes

3D axes object.

Parameters:

figFigure

The parent figure.

rect(float, float, float, float)

The (left, bottom, width, height) axes position.

azimfloat, default: -60

Azimuthal viewing angle.

elevfloat, default: 30

Elevation viewing angle.

sharezAxes3D, optional

Other axes to share z-limits with.

proj_type{'persp', 'ortho'}

The projection type, default 'persp'.

**kwargs

Other optional keyword arguments:

Property	Description
adjustable	{'box', 'datalim'}
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha	float or None
anchor	2-tuple of floats or {'C', 'SW', 'S', 'SE', ...}
animated	bool
aspect	{'auto'}
autoscale_on	bool
autoscalex_on	bool
autoscaley_on	bool
autoscalez_on	bool
axes_locator	Callable[[Axes, Renderer], Bbox]
axisbelow	bool or 'line'
box_aspect	3-tuple of floats or None
clip_box	Bbox
clip_on	bool
clip_path	Patch or (Path, Transform) or None
contains	unknown
facecolor or fc	color
figure	Figure
frame_on	bool
gid	str
in_layout	bool
label	object
navigate	bool
navigate_mode	unknown
path_effects	AbstractPathEffect
picker	None or bool or callable
position	[left, bottom, width, height] or Bbox
proj_type	{'persp', 'ortho'}
prop_cycle	unknown
rasterization_zorder	float or None
rasterized	bool or None
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
title	str
transform	Transform
url	str
visible	bool
xbound	unknown
xlabel	str
xlim3d or xlim	unknown
xmargin	float greater than -0.5
xscale	{"linear"}
xticklabels	unknown
xticks	unknown
ybound	unknown
ylabel	str
ylim3d or ylim	unknown
ymargin	float greater than -0.5
yscale	{"linear"}
yticklabels	unknown
yticks	unknown
zbound	unknown
zlabel	unknown
zlim3d or zlim	unknown
zmargin	unknown
zorder	float
zscale	{"linear"}
zticklabels	unknown
zticks	unknown

Notes

New in version 1.2.1: The sharez parameter.

__init__(self, fig, rect=None, *args, azim=- 60, elev=30, sharez=None, proj_type='persp', box_aspect=None, **kwargs)

Parameters:

figFigure

The parent figure.

rect(float, float, float, float)

The (left, bottom, width, height) axes position.

azimfloat, default: -60

Azimuthal viewing angle.

elevfloat, default: 30

Elevation viewing angle.

sharezAxes3D, optional

Other axes to share z-limits with.

proj_type{'persp', 'ortho'}

The projection type, default 'persp'.

**kwargs

Other optional keyword arguments:

Property	Description
adjustable	{'box', 'datalim'}
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha	float or None
anchor	2-tuple of floats or {'C', 'SW', 'S', 'SE', ...}
animated	bool
aspect	{'auto'}
autoscale_on	bool
autoscalex_on	bool
autoscaley_on	bool
autoscalez_on	bool
axes_locator	Callable[[Axes, Renderer], Bbox]
axisbelow	bool or 'line'
box_aspect	3-tuple of floats or None
clip_box	Bbox
clip_on	bool
clip_path	Patch or (Path, Transform) or None
contains	unknown
facecolor or fc	color
figure	Figure
frame_on	bool
gid	str
in_layout	bool
label	object
navigate	bool
navigate_mode	unknown
path_effects	AbstractPathEffect
picker	None or bool or callable
position	[left, bottom, width, height] or Bbox
proj_type	{'persp', 'ortho'}
prop_cycle	unknown
rasterization_zorder	float or None
rasterized	bool or None
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
title	str
transform	Transform
url	str
visible	bool
xbound	unknown
xlabel	str
xlim3d or xlim	unknown
xmargin	float greater than -0.5
xscale	{"linear"}
xticklabels	unknown
xticks	unknown
ybound	unknown
ylabel	str
ylim3d or ylim	unknown
ymargin	float greater than -0.5
yscale	{"linear"}
yticklabels	unknown
yticks	unknown
zbound	unknown
zlabel	unknown
zlim3d or zlim	unknown
zmargin	unknown
zorder	float
zscale	{"linear"}
zticklabels	unknown
zticks	unknown

Notes

New in version 1.2.1: The sharez parameter.

__module__ = 'mpl_toolkits.mplot3d.axes3d'

add_collection3d(self, col, zs=0, zdir='z')

Add a 3D collection object to the plot.

2D collection types are converted to a 3D version by modifying the object and adding z coordinate information.

Supported are:

• PolyCollection
• LineCollection
• PatchCollection

add_contour_set(self, cset, extend3d=False, stride=5, zdir='z', offset=None)

add_contourf_set(self, cset, zdir='z', offset=None)

apply_aspect(self, position=None)

Adjust the Axes for a specified data aspect ratio.

Depending on get_adjustable this will modify either the Axes box (position) or the view limits. In the former case, get_anchor will affect the position.

See also

matplotlib.axes.Axes.set_aspect

For a description of aspect ratio handling.

matplotlib.axes.Axes.set_adjustable

Set how the Axes adjusts to achieve the required aspect ratio.

matplotlib.axes.Axes.set_anchor

Set the position in case of extra space.

Notes

This is called automatically when each Axes is drawn. You may need to call it yourself if you need to update the Axes position and/or view limits before the Figure is drawn.

auto_scale_xyz(self, X, Y, Z=None, had_data=None)

autoscale(self, enable=True, axis='both', tight=None)

Convenience method for simple axis view autoscaling. See matplotlib.axes.Axes.autoscale() for full explanation. Note that this function behaves the same, but for all three axes. Therefore, 'z' can be passed for axis, and 'both' applies to all three axes.

New in version 1.1.0.

autoscale_view(self, tight=None, scalex=True, scaley=True, scalez=True)

Autoscale the view limits using the data limits. See matplotlib.axes.Axes.autoscale_view() for documentation. Note that this function applies to the 3D axes, and as such adds the scalez to the function arguments.

Changed in version 1.1.0: Function signature was changed to better match the 2D version. tight is now explicitly a kwarg and placed first.

Changed in version 1.2.1: This is now fully functional.

bar(self, left, height, zs=0, zdir='z', *args, **kwargs)

Add 2D bar(s).

Parameters:

left1D array-like

The x coordinates of the left sides of the bars.

height1D array-like

The height of the bars.

zsfloat or 1D array-like

Z coordinate of bars; if a single value is specified, it will be used for all bars.

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

When plotting 2D data, the direction to use as z ('x', 'y' or 'z').

**kwargs

Other arguments are forwarded to matplotlib.axes.Axes.bar.

Returns:

mpl_toolkits.mplot3d.art3d.Patch3DCollection

bar3d(self, x, y, z, dx, dy, dz, color=None, zsort='average', shade=True, lightsource=None, *args, **kwargs)

Generate a 3D barplot.

This method creates three dimensional barplot where the width, depth, height, and color of the bars can all be uniquely set.

Parameters:

x, y, zarray-like

The coordinates of the anchor point of the bars.

dx, dy, dzfloat or array-like

The width, depth, and height of the bars, respectively.

colorsequence of colors, optional

The color of the bars can be specified globally or individually. This parameter can be:

• A single color, to color all bars the same color.
• An array of colors of length N bars, to color each bar independently.
• An array of colors of length 6, to color the faces of the bars similarly.
• An array of colors of length 6 * N bars, to color each face independently.

When coloring the faces of the boxes specifically, this is the order of the coloring:

1. -Z (bottom of box)
2. +Z (top of box)
3. -Y
4. +Y
5. -X
6. +X

zsortstr, optional

The z-axis sorting scheme passed onto Poly3DCollection

shadebool, default: True

When true, this shades the dark sides of the bars (relative to the plot's source of light).

lightsourceLightSource

The lightsource to use when shade is True.

**kwargs

Any additional keyword arguments are passed onto Poly3DCollection.

Returns:

collectionPoly3DCollection

A collection of three dimensional polygons representing the bars.

can_pan(self)

Return True if this axes supports the pan/zoom button functionality.

3D axes objects do not use the pan/zoom button.

can_zoom(self)

Return True if this axes supports the zoom box button functionality.

3D axes objects do not use the zoom box button.

cla(self)

Clear the current axes.

clabel(self, *args, **kwargs)

Currently not implemented for 3D axes, and returns None.

contour(self, X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, **kwargs)

Create a 3D contour plot.

Parameters:

X, Y, Zarray-like

Input data.

extend3dbool, default: False

Whether to extend contour in 3D.

strideint

Step size for extending contour.

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

The direction to use.

offsetfloat, optional

If specified, plot a projection of the contour lines at this position in a plane normal to zdir.

*args, **kwargs

Other arguments are forwarded to matplotlib.axes.Axes.contour.

Returns:

matplotlib.contour.QuadContourSet

contour3D(self, X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, **kwargs)

Create a 3D contour plot.

Parameters:

X, Y, Zarray-like

Input data.

extend3dbool, default: False

Whether to extend contour in 3D.

strideint

Step size for extending contour.

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

The direction to use.

offsetfloat, optional

If specified, plot a projection of the contour lines at this position in a plane normal to zdir.

*args, **kwargs

Other arguments are forwarded to matplotlib.axes.Axes.contour.

Returns:

matplotlib.contour.QuadContourSet

contourf(self, X, Y, Z, *args, zdir='z', offset=None, **kwargs)

Create a 3D filled contour plot.

Parameters:

X, Y, Zarray-like

Input data.

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

The direction to use.

offsetfloat, optional

If specified, plot a projection of the contour lines at this position in a plane normal to zdir.

*args, **kwargs

Other arguments are forwarded to matplotlib.axes.Axes.contourf.

Returns:

matplotlib.contour.QuadContourSet

Notes

New in version 1.1.0: The zdir and offset parameters.

contourf3D(self, X, Y, Z, *args, zdir='z', offset=None, **kwargs)

Create a 3D filled contour plot.

Parameters:

X, Y, Zarray-like

Input data.

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

The direction to use.

offsetfloat, optional

If specified, plot a projection of the contour lines at this position in a plane normal to zdir.

*args, **kwargs

Other arguments are forwarded to matplotlib.axes.Axes.contourf.

Returns:

matplotlib.contour.QuadContourSet

Notes

New in version 1.1.0: The zdir and offset parameters.

convert_zunits(self, z)

For artists in an axes, if the zaxis has units support, convert z using zaxis unit type

New in version 1.2.1.

disable_mouse_rotation(self)

Disable mouse buttons for 3D rotation and zooming.

draw(self, renderer)

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:

rendererRendererBase subclass.

Notes

This method is overridden in the Artist subclasses.

format_coord(self, xd, yd)

Given the 2D view coordinates attempt to guess a 3D coordinate. Looks for the nearest edge to the point and then assumes that the point is at the same z location as the nearest point on the edge.

format_zdata(self, z)

Return z string formatted. This function will use the fmt_zdata attribute if it is callable, else will fall back on the zaxis major formatter

get_autoscale_on(self)

Get whether autoscaling is applied for all axes on plot commands

New in version 1.1.0: This function was added, but not tested. Please report any bugs.

get_autoscalez_on(self)

Get whether autoscaling for the z-axis is applied on plot commands

New in version 1.1.0: This function was added, but not tested. Please report any bugs.

get_axis_position(self)

get_frame_on(self)

Get whether the 3D axes panels are drawn.

get_proj(self)

Create the projection matrix from the current viewing position.

get_tightbbox(self, renderer, call_axes_locator=True, bbox_extra_artists=None, *, for_layout_only=False)

Return the tight bounding box of the axes, including axis and their decorators (xlabel, title, etc).

Artists that have artist.set_in_layout(False) are not included in the bbox.

Parameters:

rendererRendererBase subclass

renderer that will be used to draw the figures (i.e. fig.canvas.get_renderer())

bbox_extra_artistslist of Artist or None

List of artists to include in the tight bounding box. If None (default), then all artist children of the axes are included in the tight bounding box.

call_axes_locatorbool, default: True

If call_axes_locator is False, it does not call the _axes_locator attribute, which is necessary to get the correct bounding box. call_axes_locator=False can be used if the caller is only interested in the relative size of the tightbbox compared to the axes bbox.

for_layout_onlydefault: False

The bounding box will not include the x-extent of the title and the xlabel, or the y-extent of the ylabel.

Returns:

BboxBase

Bounding box in figure pixel coordinates.

See also

matplotlib.axes.Axes.get_window_extent

matplotlib.axis.Axis.get_tightbbox

matplotlib.spines.Spine.get_window_extent

get_w_lims(self)

Get 3D world limits.

get_xlim(self)

Alias for get_xlim3d.

get_xlim3d(self)

Return the x-axis view limits.

Returns:

left, right(float, float)

The current x-axis limits in data coordinates.

See also

set_xlim

set_xbound, get_xbound

invert_xaxis, xaxis_inverted

Notes

The x-axis may be inverted, in which case the left value will be greater than the right value.

Changed in version 1.1.0: This function now correctly refers to the 3D x-limits

get_ylim(self)

Alias for get_ylim3d.

get_ylim3d(self)

Return the y-axis view limits.

Returns:

bottom, top(float, float)

The current y-axis limits in data coordinates.

See also

set_ylim

set_ybound, get_ybound

invert_yaxis, yaxis_inverted

Notes

The y-axis may be inverted, in which case the bottom value will be greater than the top value.

Changed in version 1.1.0: This function now correctly refers to the 3D y-limits.

get_zaxis(self)

Return the ZAxis (Axis) instance.

get_zbound(self)

Return the lower and upper z-axis bounds, in increasing order.

New in version 1.1.0.

get_zgridlines(self)

Return the zaxis' grid lines as a list of Line2Ds.

get_zlabel(self)

Get the z-label text string.

New in version 1.1.0: This function was added, but not tested. Please report any bugs.

get_zlim(self)

Alias for get_zlim3d.

get_zlim3d(self)

Get 3D z limits.

get_zmajorticklabels(self)

Return the zaxis' major tick labels, as a list of Text.

get_zminorticklabels(self)

Return the zaxis' minor tick labels, as a list of Text.

get_zscale(self)

get_zticklabels(self, minor=False, which=None)

Get the zaxis' tick labels.

Parameters:

minorbool

Whether to return the minor or the major ticklabels.

whichNone, ('minor', 'major', 'both')

Overrides minor.

Selects which ticklabels to return

Returns:

list of Text

Notes

The tick label strings are not populated until a draw method has been called.

See also: draw and draw.

get_zticklines(self, minor=False)

Return the zaxis' tick lines as a list of Line2Ds.

get_zticks(self, *, minor=False)

Return the zaxis' tick locations in data coordinates.

grid(self, b=True, **kwargs)

Set / unset 3D grid.

Note

Currently, this function does not behave the same as matplotlib.axes.Axes.grid(), but it is intended to eventually support that behavior.

New in version 1.1.0.

invert_zaxis(self)

Invert the z-axis.

New in version 1.1.0: This function was added, but not tested. Please report any bugs.

locator_params(self, axis='both', tight=None, **kwargs)

Convenience method for controlling tick locators.

See matplotlib.axes.Axes.locator_params() for full documentation. Note that this is for Axes3D objects, therefore, setting axis to 'both' will result in the parameters being set for all three axes. Also, axis can also take a value of 'z' to apply parameters to the z axis.

New in version 1.1.0: This function was added, but not tested. Please report any bugs.

margins(self, *margins, x=None, y=None, z=None, tight=True)

Convenience method to set or retrieve autoscaling margins.

Call signatures:

margins()

returns xmargin, ymargin, zmargin

margins(margin)

margins(xmargin, ymargin, zmargin)

margins(x=xmargin, y=ymargin, z=zmargin)

margins(..., tight=False)

All forms above set the xmargin, ymargin and zmargin parameters. All keyword parameters are optional. A single positional argument specifies xmargin, ymargin and zmargin. Passing both positional and keyword arguments for xmargin, ymargin, and/or zmargin is invalid.

The tight parameter is passed to autoscale_view(), which is executed after a margin is changed; the default here is True, on the assumption that when margins are specified, no additional padding to match tick marks is usually desired. Setting tight to None will preserve the previous setting.

Specifying any margin changes only the autoscaling; for example, if xmargin is not None, then xmargin times the X data interval will be added to each end of that interval before it is used in autoscaling.

New in version 1.1.0.

mouse_init(self, rotate_btn=1, zoom_btn=3)

Set the mouse buttons for 3D rotation and zooming.

Parameters:

rotate_btnint or list of int, default: 1

The mouse button or buttons to use for 3D rotation of the axes.

zoom_btnint or list of int, default: 3

The mouse button or buttons to use to zoom the 3D axes.

name = '3d'

plot(self, xs, ys, *args, zdir='z', **kwargs)

Plot 2D or 3D data.

Parameters:

xs1D array-like

x coordinates of vertices.

ys1D array-like

y coordinates of vertices.

zsfloat or 1D array-like

z coordinates of vertices; either one for all points or one for each point.

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

When plotting 2D data, the direction to use as z ('x', 'y' or 'z').

**kwargs

Other arguments are forwarded to matplotlib.axes.Axes.plot.

plot3D(self, xs, ys, *args, zdir='z', **kwargs)

Plot 2D or 3D data.

Parameters:

xs1D array-like

x coordinates of vertices.

ys1D array-like

y coordinates of vertices.

zsfloat or 1D array-like

z coordinates of vertices; either one for all points or one for each point.

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

When plotting 2D data, the direction to use as z ('x', 'y' or 'z').

**kwargs

Other arguments are forwarded to matplotlib.axes.Axes.plot.

plot_surface(self, X, Y, Z, *args, norm=None, vmin=None, vmax=None, lightsource=None, **kwargs)

Create a surface plot.

By default it will be colored in shades of a solid color, but it also supports color mapping by supplying the cmap argument.

Note

The rcount and ccount kwargs, which both default to 50, determine the maximum number of samples used in each direction. If the input data is larger, it will be downsampled (by slicing) to these numbers of points.

Note

To maximize rendering speed consider setting rstride and cstride to divisors of the number of rows minus 1 and columns minus 1 respectively. For example, given 51 rows rstride can be any of the divisors of 50.

Similarly, a setting of rstride and cstride equal to 1 (or rcount and ccount equal the number of rows and columns) can use the optimized path.

Parameters:

X, Y, Z2d arrays

Data values.

rcount, ccountint

Maximum number of samples used in each direction. If the input data is larger, it will be downsampled (by slicing) to these numbers of points. Defaults to 50.

New in version 2.0.

rstride, cstrideint

Downsampling stride in each direction. These arguments are mutually exclusive with rcount and ccount. If only one of rstride or cstride is set, the other defaults to 10.

'classic' mode uses a default of rstride = cstride = 10 instead of the new default of rcount = ccount = 50.

colorcolor-like

Color of the surface patches.

cmapColormap

Colormap of the surface patches.

facecolorsarray-like of colors.

Colors of each individual patch.

normNormalize

Normalization for the colormap.

vmin, vmaxfloat

Bounds for the normalization.

shadebool, default: True

Whether to shade the facecolors. Shading is always disabled when cmap is specified.

lightsourceLightSource

The lightsource to use when shade is True.

**kwargs

Other arguments are forwarded to Poly3DCollection.

plot_trisurf(self, *args, color=None, norm=None, vmin=None, vmax=None, lightsource=None, **kwargs)

Plot a triangulated surface.

The (optional) triangulation can be specified in one of two ways; either:

plot_trisurf(triangulation, ...)

where triangulation is a Triangulation object, or:

plot_trisurf(X, Y, ...)
plot_trisurf(X, Y, triangles, ...)
plot_trisurf(X, Y, triangles=triangles, ...)

in which case a Triangulation object will be created. See Triangulation for a explanation of these possibilities.

The remaining arguments are:

plot_trisurf(..., Z)

where Z is the array of values to contour, one per point in the triangulation.

Parameters:

X, Y, Zarray-like

Data values as 1D arrays.

color

Color of the surface patches.

cmap

A colormap for the surface patches.

normNormalize

An instance of Normalize to map values to colors.

vmin, vmaxfloat, default: None

Minimum and maximum value to map.

shadebool, default: True

Whether to shade the facecolors. Shading is always disabled when cmap is specified.

lightsourceLightSource

The lightsource to use when shade is True.

**kwargs

All other arguments are passed on to Poly3DCollection

Examples

(Source code, png, pdf)

(Source code, png, pdf)

New in version 1.2.0.

plot_wireframe(self, X, Y, Z, *args, **kwargs)

Plot a 3D wireframe.

Note

The rcount and ccount kwargs, which both default to 50, determine the maximum number of samples used in each direction. If the input data is larger, it will be downsampled (by slicing) to these numbers of points.

Parameters:

X, Y, Z2d arrays

Data values.

rcount, ccountint

Maximum number of samples used in each direction. If the input data is larger, it will be downsampled (by slicing) to these numbers of points. Setting a count to zero causes the data to be not sampled in the corresponding direction, producing a 3D line plot rather than a wireframe plot. Defaults to 50.

New in version 2.0.

rstride, cstrideint

Downsampling stride in each direction. These arguments are mutually exclusive with rcount and ccount. If only one of rstride or cstride is set, the other defaults to 1. Setting a stride to zero causes the data to be not sampled in the corresponding direction, producing a 3D line plot rather than a wireframe plot.

'classic' mode uses a default of rstride = cstride = 1 instead of the new default of rcount = ccount = 50.

**kwargs

Other arguments are forwarded to Line3DCollection.

quiver(X, Y, Z, U, V, W, /, length=1, arrow_length_ratio=0.3, pivot='tail', normalize=False, **kwargs)

Plot a 3D field of arrows.

The arguments could be array-like or scalars, so long as they they can be broadcast together. The arguments can also be masked arrays. If an element in any of argument is masked, then that corresponding quiver element will not be plotted.

Parameters:

X, Y, Zarray-like

The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).

U, V, Warray-like

The x, y and z components of the arrow vectors.

lengthfloat, default: 1

The length of each quiver.

arrow_length_ratiofloat, default: 0.3

The ratio of the arrow head with respect to the quiver.

pivot{'tail', 'middle', 'tip'}, default: 'tail'

The part of the arrow that is at the grid point; the arrow rotates about this point, hence the name pivot.

normalizebool, default: False

Whether all arrows are normalized to have the same length, or keep the lengths defined by u, v, and w.

**kwargs

Any additional keyword arguments are delegated to LineCollection

quiver3D(X, Y, Z, U, V, W, /, length=1, arrow_length_ratio=0.3, pivot='tail', normalize=False, **kwargs)

Plot a 3D field of arrows.

The arguments could be array-like or scalars, so long as they they can be broadcast together. The arguments can also be masked arrays. If an element in any of argument is masked, then that corresponding quiver element will not be plotted.

Parameters:

X, Y, Zarray-like

The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).

U, V, Warray-like

The x, y and z components of the arrow vectors.

lengthfloat, default: 1

The length of each quiver.

arrow_length_ratiofloat, default: 0.3

The ratio of the arrow head with respect to the quiver.

pivot{'tail', 'middle', 'tip'}, default: 'tail'

The part of the arrow that is at the grid point; the arrow rotates about this point, hence the name pivot.

normalizebool, default: False

Whether all arrows are normalized to have the same length, or keep the lengths defined by u, v, and w.

**kwargs

Any additional keyword arguments are delegated to LineCollection

scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, **kwargs)

Create a scatter plot.

Parameters:

xs, ysarray-like

The data positions.

zsfloat or array-like, default: 0

The z-positions. Either an array of the same length as xs and ys or a single value to place all points in the same plane.

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

The axis direction for the zs. This is useful when plotting 2D data on a 3D Axes. The data must be passed as xs, ys. Setting zdir to 'y' then plots the data to the x-z-plane.

See also Plot 2D data on 3D plot.

sfloat or array-like, default: 20

The marker size in points**2. Either an array of the same length as xs and ys or a single value to make all markers the same size.

ccolor, sequence, or sequence of colors, optional

The marker color. Possible values:

• A single color format string.
• A sequence of colors of length n.
• A sequence of n numbers to be mapped to colors using cmap and norm.
• A 2-D array in which the rows are RGB or RGBA.

For more details see the c argument of scatter.

depthshadebool, default: True

Whether to shade the scatter markers to give the appearance of depth. Each call to scatter() will perform its depthshading independently.

**kwargs

All other arguments are passed on to scatter.

Returns:

pathsPathCollection

scatter3D(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, **kwargs)

Create a scatter plot.

Parameters:

xs, ysarray-like

The data positions.

zsfloat or array-like, default: 0

The z-positions. Either an array of the same length as xs and ys or a single value to place all points in the same plane.

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

The axis direction for the zs. This is useful when plotting 2D data on a 3D Axes. The data must be passed as xs, ys. Setting zdir to 'y' then plots the data to the x-z-plane.

See also Plot 2D data on 3D plot.

sfloat or array-like, default: 20

The marker size in points**2. Either an array of the same length as xs and ys or a single value to make all markers the same size.

ccolor, sequence, or sequence of colors, optional

The marker color. Possible values:

• A single color format string.
• A sequence of colors of length n.
• A sequence of n numbers to be mapped to colors using cmap and norm.
• A 2-D array in which the rows are RGB or RGBA.

For more details see the c argument of scatter.

depthshadebool, default: True

Whether to shade the scatter markers to give the appearance of depth. Each call to scatter() will perform its depthshading independently.

**kwargs

All other arguments are passed on to scatter.

Returns:

pathsPathCollection

set_anchor(self, anchor, share=False)

Define the anchor location.

The actual drawing area (active position) of the Axes may be smaller than the Bbox (original position) when a fixed aspect is required. The anchor defines where the drawing area will be located within the available space.

Parameters:

anchor2-tuple of floats or {'C', 'SW', 'S', 'SE', ...}

The anchor position may be either:

• a sequence (cx, cy). cx and cy may range from 0 to 1, where 0 is left or bottom and 1 is right or top.

• a string using cardinal directions as abbreviation:

  • 'C' for centered
  • 'S' (south) for bottom-center
  • 'SW' (south west) for bottom-left
  • etc.

  Here is an overview of the possible positions:

  'NW'	'N'	'NE'
  'W'	'C'	'E'
  'SW'	'S'	'SE'

sharebool, default: False

If True, apply the settings to all shared Axes.

See also

matplotlib.axes.Axes.set_aspect

for a description of aspect handling.

set_aspect(self, aspect, adjustable=None, anchor=None, share=False)

Set the aspect ratios.

Axes 3D does not current support any aspect but 'auto' which fills the axes with the data limits.

To simulate having equal aspect in data space, set the ratio of your data limits to match the value of get_box_aspect. To control box aspect ratios use set_box_aspect.

Parameters:

aspect{'auto'}

Possible values:

value	description
'auto'	automatic; fill the position rectangle with data.

adjustableNone

Currently ignored by Axes3D

If not None, this defines which parameter will be adjusted to meet the required aspect. See set_adjustable for further details.

anchorNone or str or 2-tuple of float, optional

If not None, this defines where the Axes will be drawn if there is extra space due to aspect constraints. The most common way to to specify the anchor are abbreviations of cardinal directions:

value	description
'C'	centered
'SW'	lower left corner
'S'	middle of bottom edge
'SE'	lower right corner
etc.

See set_anchor for further details.

sharebool, default: False

If True, apply the settings to all shared Axes.

See also

mpl_toolkits.mplot3d.axes3d.Axes3D.set_box_aspect

set_autoscale_on(self, b)

Set whether autoscaling is applied on plot commands

New in version 1.1.0: This function was added, but not tested. Please report any bugs.

Parameters:

bbool

set_autoscalez_on(self, b)

Set whether autoscaling for the z-axis is applied on plot commands

New in version 1.1.0.

Parameters:

bbool

set_axis_off(self)

Turn the x- and y-axis off.

This affects the axis lines, ticks, ticklabels, grid and axis labels.

set_axis_on(self)

Turn the x- and y-axis on.

This affects the axis lines, ticks, ticklabels, grid and axis labels.

set_box_aspect(self, aspect, *, zoom=1)

Set the axes box aspect.

The box aspect is the ratio of height to width in display units for each face of the box when viewed perpendicular to that face. This is not to be confused with the data aspect (which for Axes3D is always 'auto'). The default ratios are 4:4:3 (x:y:z).

To simulate having equal aspect in data space, set the box aspect to match your data range in each dimension.

zoom controls the overall size of the Axes3D in the figure.

Parameters:

aspect3-tuple of floats or None

Changes the physical dimensions of the Axes3D, such that the ratio of the axis lengths in display units is x:y:z.

If None, defaults to 4:4:3

zoomfloat

Control overall size of the Axes3D in the figure.

set_frame_on(self, b)

Set whether the 3D axes panels are drawn.

Parameters:

bbool

set_proj_type(self, proj_type)

Set the projection type.

Parameters:

proj_type{'persp', 'ortho'}

set_title(self, label, fontdict=None, loc='center', **kwargs)

Set a title for the axes.

Set one of the three available axes titles. The available titles are positioned above the axes in the center, flush with the left edge, and flush with the right edge.

Parameters:

labelstr

Text to use for the title

fontdictdict

A dictionary controlling the appearance of the title text, the default fontdict is:

{'fontsize': rcParams['axes.titlesize'],
 'fontweight': rcParams['axes.titleweight'],
 'color': rcParams['axes.titlecolor'],
 'verticalalignment': 'baseline',
 'horizontalalignment': loc}

loc{'center', 'left', 'right'}, default: rcParams["axes.titlelocation"] (default: 'center')

Which title to set.

yfloat, default: rcParams["axes.titley"] (default: None)

Vertical axes loation for the title (1.0 is the top). If None (the default), y is determined automatically to avoid decorators on the axes.

padfloat, default: rcParams["axes.titlepad"] (default: 6.0)

The offset of the title from the top of the axes, in points.

Returns:

Text

The matplotlib text instance representing the title

Other Parameters:

**kwargsText properties

Other keyword arguments are text properties, see Text for a list of valid text properties.

set_top_view(self)

set_xlim(self, left=None, right=None, emit=True, auto=False, *, xmin=None, xmax=None)

Alias for set_xlim3d.

set_xlim3d(self, left=None, right=None, emit=True, auto=False, *, xmin=None, xmax=None)

Set 3D x limits.

See matplotlib.axes.Axes.set_xlim() for full documentation.

set_xscale(self, value, **kwargs)

Set the x-axis scale.

Parameters:

value{"linear"}

The axis scale type to apply. 3D axes currently only support linear scales; other scales yield nonsensical results.

**kwargs

Keyword arguments are nominally forwarded to the scale class, but none of them is applicable for linear scales.

set_ylim(self, bottom=None, top=None, emit=True, auto=False, *, ymin=None, ymax=None)

Alias for set_ylim3d.

set_ylim3d(self, bottom=None, top=None, emit=True, auto=False, *, ymin=None, ymax=None)

Set 3D y limits.

See matplotlib.axes.Axes.set_ylim() for full documentation.

set_yscale(self, value, **kwargs)

Set the y-axis scale.

Parameters:

value{"linear"}

The axis scale type to apply. 3D axes currently only support linear scales; other scales yield nonsensical results.

**kwargs

Keyword arguments are nominally forwarded to the scale class, but none of them is applicable for linear scales.

set_zbound(self, lower=None, upper=None)

Set the lower and upper numerical bounds of the z-axis.

This method will honor axes inversion regardless of parameter order. It will not change the autoscaling setting (get_autoscalez_on()).

New in version 1.1.0.

set_zlabel(self, zlabel, fontdict=None, labelpad=None, **kwargs)

Set zlabel. See doc for set_ylabel for description.

set_zlim(self, bottom=None, top=None, emit=True, auto=False, *, zmin=None, zmax=None)

Alias for set_zlim3d.

set_zlim3d(self, bottom=None, top=None, emit=True, auto=False, *, zmin=None, zmax=None)

Set 3D z limits.

See matplotlib.axes.Axes.set_ylim() for full documentation

set_zmargin(self, m)

Set padding of Z data limits prior to autoscaling.

m times the data interval will be added to each end of that interval before it is used in autoscaling.

accepts: float in range 0 to 1

New in version 1.1.0.

set_zscale(self, value, **kwargs)

Set the z-axis scale.

Parameters:

value{"linear"}

The axis scale type to apply. 3D axes currently only support linear scales; other scales yield nonsensical results.

**kwargs

Keyword arguments are nominally forwarded to the scale class, but none of them is applicable for linear scales.

set_zticklabels(self, labels, *, fontdict=None, minor=False, **kwargs)

Set the zaxis' labels with list of string labels.

Warning

This method should only be used after fixing the tick positions using Axes3D.set_zticks. Otherwise, the labels may end up in unexpected positions.

Parameters:

labelslist of str

The label texts.

fontdictdict, optional

A dictionary controlling the appearance of the ticklabels. The default fontdict is:

{'fontsize': rcParams['axes.titlesize'],
 'fontweight': rcParams['axes.titleweight'],
 'verticalalignment': 'baseline',
 'horizontalalignment': loc}

minorbool, default: False

Whether to set the minor ticklabels rather than the major ones.

Returns:

list of Text

The labels.

Other Parameters:

**kwargsText properties.

set_zticks(self, ticks, *, minor=False)

Set the zaxis' tick locations.

Parameters:

tickslist of floats

List of tick locations.

minorbool, default: False

If False, set the major ticks; if True, the minor ticks.

text(self, x, y, z, s, zdir=None, **kwargs)

Add text to the plot. kwargs will be passed on to Axes.text, except for the zdir keyword, which sets the direction to be used as the z direction.

text2D(self, x, y, s, fontdict=None, **kwargs)

Add text to the axes.

Add the text s to the axes at location x, y in data coordinates.

Parameters:

x, yfloat

The position to place the text. By default, this is in data coordinates. The coordinate system can be changed using the transform parameter.

sstr

The text.

fontdictdict, default: None

A dictionary to override the default text properties. If fontdict is None, the defaults are determined by rcParams.

Returns:

Text

The created Text instance.

Other Parameters:

**kwargsText properties.

Other miscellaneous text parameters.

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
alpha	float or None
animated	bool
backgroundcolor	color
bbox	dict with properties for patches.FancyBboxPatch
clip_box	Bbox
clip_on	bool
clip_path	Patch or (Path, Transform) or None
color or c	color
contains	unknown
figure	Figure
fontfamily or family	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties or font or font_properties	font_manager.FontProperties or str or pathlib.Path
fontsize or size	float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch or stretch	{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle or style	{'normal', 'italic', 'oblique'}
fontvariant or variant	{'normal', 'small-caps'}
fontweight or weight	{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid	str
horizontalalignment or ha	{'center', 'right', 'left'}
in_layout	bool
label	object
linespacing	float (multiple of font size)
multialignment or ma	{'left', 'right', 'center'}
path_effects	AbstractPathEffect
picker	None or bool or callable
position	(float, float)
rasterized	bool or None
rotation	float or {'vertical', 'horizontal'}
rotation_mode	{None, 'default', 'anchor'}
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
text	object
transform	Transform
url	str
usetex	bool or None
verticalalignment or va	{'center', 'top', 'bottom', 'baseline', 'center_baseline'}
visible	bool
wrap	bool
x	float
y	float
zorder	float

Examples

Individual keyword arguments can be used to override any given parameter:

>>> text(x, y, s, fontsize=12)

The default transform specifies that text is in data coords, alternatively, you can specify text in axis coords ((0, 0) is lower-left and (1, 1) is upper-right). The example below places text in the center of the axes:

>>> text(0.5, 0.5, 'matplotlib', horizontalalignment='center',
...      verticalalignment='center', transform=ax.transAxes)

You can put a rectangular box around the text instance (e.g., to set a background color) by using the keyword bbox. bbox is a dictionary of Rectangle properties. For example:

>>> text(x, y, s, bbox=dict(facecolor='red', alpha=0.5))

text3D(self, x, y, z, s, zdir=None, **kwargs)

Add text to the plot. kwargs will be passed on to Axes.text, except for the zdir keyword, which sets the direction to be used as the z direction.

tick_params(self, axis='both', **kwargs)

Convenience method for changing the appearance of ticks and tick labels.

See matplotlib.axes.Axes.tick_params() for more complete documentation.

The only difference is that setting axis to 'both' will mean that the settings are applied to all three axes. Also, the axis parameter also accepts a value of 'z', which would mean to apply to only the z-axis.

Also, because of how Axes3D objects are drawn very differently from regular 2D axes, some of these settings may have ambiguous meaning. For simplicity, the 'z' axis will accept settings as if it was like the 'y' axis.

Note

Axes3D currently ignores some of these settings.

New in version 1.1.0.

tricontour(self, *args, extend3d=False, stride=5, zdir='z', offset=None, **kwargs)

Create a 3D contour plot.

Changed in version 1.3.0: Added support for custom triangulations

Note

This method currently produces incorrect output due to a longstanding bug in 3D PolyCollection rendering.

Parameters:

X, Y, Zarray-like

Input data.

extend3dbool, default: False

Whether to extend contour in 3D.

strideint

Step size for extending contour.

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

The direction to use.

offsetfloat, optional

If specified, plot a projection of the contour lines at this position in a plane normal to zdir.

*args, **kwargs

Other arguments are forwarded to matplotlib.axes.Axes.tricontour.

Returns:

matplotlib.tri.tricontour.TriContourSet

tricontourf(self, *args, zdir='z', offset=None, **kwargs)

Create a 3D filled contour plot.

Note

This method currently produces incorrect output due to a longstanding bug in 3D PolyCollection rendering.

Parameters:

X, Y, Zarray-like

Input data.

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

The direction to use.

offsetfloat, optional

If specified, plot a projection of the contour lines at this position in a plane normal to zdir.

*args, **kwargs

Other arguments are forwarded to matplotlib.axes.Axes.tricontourf.

Returns:

matplotlib.tri.tricontour.TriContourSet

Notes

New in version 1.1.0: The zdir and offset parameters.

Changed in version 1.3.0: Added support for custom triangulations

tunit_cube(self, vals=None, M=None)

tunit_edges(self, vals=None, M=None)

unit_cube(self, vals=None)

update_datalim(self, xys, **kwargs)

Extend the dataLim Bbox to include the given points.

If no data is set currently, the Bbox will ignore its limits and set the bound to be the bounds of the xydata (xys). Otherwise, it will compute the bounds of the union of its current data and the data in xys.

Parameters:

xys2D array-like

The points to include in the data limits Bbox. This can be either a list of (x, y) tuples or a Nx2 array.

updatex, updateybool, default: True

Whether to update the x/y limits.

view_init(self, elev=None, azim=None)

Set the elevation and azimuth of the axes in degrees (not radians).

This can be used to rotate the axes programmatically.

'elev' stores the elevation angle in the z plane (in degrees). 'azim' stores the azimuth angle in the (x, y) plane (in degrees).

if 'elev' or 'azim' are None (default), then the initial value is used which was specified in the Axes3D constructor.

voxels([x, y, z, ]/, filled, facecolors=None, edgecolors=None, **kwargs)

Plot a set of filled voxels

All voxels are plotted as 1x1x1 cubes on the axis, with filled[0, 0, 0] placed with its lower corner at the origin. Occluded faces are not plotted.

New in version 2.1.

Parameters:

filled3D np.array of bool

A 3d array of values, with truthy values indicating which voxels to fill

x, y, z3D np.array, optional

The coordinates of the corners of the voxels. This should broadcast to a shape one larger in every dimension than the shape of filled. These can be used to plot non-cubic voxels.

If not specified, defaults to increasing integers along each axis, like those returned by indices(). As indicated by the / in the function signature, these arguments can only be passed positionally.

facecolors, edgecolorsarray-like, optional

The color to draw the faces and edges of the voxels. Can only be passed as keyword arguments. This parameter can be:

• A single color value, to color all voxels the same color. This can be either a string, or a 1D rgb/rgba array
• None, the default, to use a single color for the faces, and the style default for the edges.
• A 3D ndarray of color names, with each item the color for the corresponding voxel. The size must match the voxels.
• A 4D ndarray of rgb/rgba data, with the components along the last axis.

shadebool, default: True

Whether to shade the facecolors. Shading is always disabled when cmap is specified.

New in version 3.1.

lightsourceLightSource

The lightsource to use when shade is True.

New in version 3.1.

**kwargs

Additional keyword arguments to pass onto Poly3DCollection.

Returns:

facesdict

A dictionary indexed by coordinate, where faces[i, j, k] is a Poly3DCollection of the faces drawn for the voxel filled[i, j, k]. If no faces were drawn for a given voxel, either because it was not asked to be drawn, or it is fully occluded, then (i, j, k) not in faces.

Examples

(Source code, png, pdf)

(Source code, png, pdf)

(Source code, png, pdf)

(Source code, png, pdf)

property w_xaxis

property w_yaxis

property w_zaxis

zaxis_date(self, tz=None)

Sets up axis ticks and labels to treat data along the zaxis as dates.

Parameters:

tzstr or datetime.tzinfo, default: rcParams["timezone"] (default: 'UTC')

The timezone used to create date labels.

zaxis_inverted(self)

Returns True if the z-axis is inverted.

New in version 1.1.0.

Examples using mpl_toolkits.mplot3d.axes3d.Axes3D