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, computed_zorder=True, **kwargs)[source]#

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'.

computed_zorderbool, default: True

If True, the draw order is computed based on the average position of the Artists along the view direction. Set to False if you want to manually control the order in which Artists are drawn on top of each other using their zorder attribute. This can be used for fine-tuning if the automatic order does not produce the desired result. Note however, that a manual zorder will only be correct for a limited view angle. If the figure is rotated by the user, it will look wrong from certain angles.

auto_add_to_figurebool, default: True

Prior to Matplotlib 3.4 Axes3D would add themselves to their host Figure on init. Other Axes class do not do this.

This behavior is deprecated in 3.4, the default will change to False in 3.5. The keyword will be undocumented and a non-False value will be an error in 3.6.

**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`	scalar or None
`anchor`	(float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}
`animated`	bool
`aspect`	{'auto'}
`autoscale_on`	unknown
`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
`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 float or callable
`position`	[left, bottom, width, height] or `Bbox`
`proj_type`	{'persp', 'ortho'}
`prop_cycle`	unknown
`rasterization_zorder`	float or None
`rasterized`	bool
`sketch_params`	(scale: float, length: float, randomness: float)
`snap`	bool or None
`title`	unknown
`transform`	`Transform`
`url`	str
`visible`	bool
`xbound`	unknown
`xlabel`	str
`xlim3d` or xlim	unknown
`xmargin`	unknown
`xscale`	{"linear"}
`xticklabels`	unknown
`xticks`	unknown
`ybound`	unknown
`ylabel`	str
`ylim3d` or ylim	unknown
`ymargin`	unknown
`yscale`	{"linear"}
`yticklabels`	unknown
`yticks`	unknown
`zbound`	unknown
`zlabel`	unknown
`zlim3d` or zlim	unknown
`zmargin`	unknown
`zorder`	float
`zscale`	{"linear"}
`zticklabels`	unknown
`zticks`	unknown

add_collection3d(col, zs=0, zdir='z')[source]#

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(cset, extend3d=False, stride=5, zdir='z', offset=None)[source]#

add_contourf_set(cset, zdir='z', offset=None)[source]#

apply_aspect(position=None)[source]#

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(X, Y, Z=None, had_data=None)[source]#

autoscale(enable=True, axis='both', tight=None)[source]#: 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.

autoscale_view(tight=None, scalex=True, scaley=True, scalez=True)[source]#: 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.

bar(left, height, zs=0, zdir='z', *args, data=None, **kwargs)[source]#

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').
dataindexable object, optional: If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).
**kwargs: Other arguments are forwarded to matplotlib.axes.Axes.bar.

Returns

mpl_toolkits.mplot3d.art3d.Patch3DCollection

bar3d(x, y, z, dx, dy, dz, color=None, zsort='average', shade=True, lightsource=None, *args, data=None, **kwargs)[source]#

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:

-Z (bottom of box)
+Z (top of box)
-Y
+Y
-X
+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.

dataindexable object, optional

If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).

**kwargs

Any additional keyword arguments are passed onto Poly3DCollection.

Returns

collectionPoly3DCollection: A collection of three dimensional polygons representing the bars.

can_pan()[source]#

Return whether this axes supports the pan/zoom button functionality.

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

can_zoom()[source]#

Return whether this axes supports the zoom box button functionality.

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

cla()[source]#: Clear the Axes.

clabel(*args, **kwargs)[source]#: Currently not implemented for 3D axes, and returns None.

contour(X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, data=None, **kwargs)[source]#

Create a 3D contour plot.

Parameters

X, Y, Zarray-like,: Input data. See contour for acceptable data shapes.
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.
dataindexable object, optional: If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).
*args, **kwargs: Other arguments are forwarded to matplotlib.axes.Axes.contour.

Returns

matplotlib.contour.QuadContourSet

contour3D(X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, data=None, **kwargs)[source]#

Create a 3D contour plot.

Parameters

X, Y, Zarray-like,: Input data. See contour for acceptable data shapes.
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.
dataindexable object, optional: If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).
*args, **kwargs: Other arguments are forwarded to matplotlib.axes.Axes.contour.

Returns

matplotlib.contour.QuadContourSet

contourf(X, Y, Z, *args, zdir='z', offset=None, data=None, **kwargs)[source]#

Create a 3D filled contour plot.

Parameters

X, Y, Zarray-like: Input data. See contourf for acceptable data shapes.
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.
dataindexable object, optional: If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).
*args, **kwargs: Other arguments are forwarded to matplotlib.axes.Axes.contourf.

Returns

matplotlib.contour.QuadContourSet

contourf3D(X, Y, Z, *args, zdir='z', offset=None, data=None, **kwargs)[source]#

Create a 3D filled contour plot.

Parameters

X, Y, Zarray-like: Input data. See contourf for acceptable data shapes.
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.
dataindexable object, optional: If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).
*args, **kwargs: Other arguments are forwarded to matplotlib.axes.Axes.contourf.

Returns

matplotlib.contour.QuadContourSet

convert_zunits(z)[source]#: For artists in an axes, if the zaxis has units support, convert z using zaxis unit type

disable_mouse_rotation()[source]#: Disable mouse buttons for 3D rotation and zooming.

draw(renderer)[source]#

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.

errorbar(x, y, z, zerr=None, yerr=None, xerr=None, fmt='', barsabove=False, errorevery=1, ecolor=None, elinewidth=None, capsize=None, capthick=None, xlolims=False, xuplims=False, ylolims=False, yuplims=False, zlolims=False, zuplims=False, *, data=None, **kwargs)[source]#

Plot lines and/or markers with errorbars around them.

x/y/z define the data locations, and xerr/yerr/zerr define the errorbar sizes. By default, this draws the data markers/lines as well the errorbars. Use fmt='none' to draw errorbars only.

Parameters

x, y, zfloat or array-like

The data positions.

xerr, yerr, zerrfloat or array-like, shape (N,) or (2, N), optional

The errorbar sizes:

scalar: Symmetric +/- values for all data points.
shape(N,): Symmetric +/-values for each data point.
shape(2, N): Separate - and + values for each bar. First row contains the lower errors, the second row contains the upper errors.
None: No errorbar.

Note that all error arrays should have positive values.

fmtstr, default: ''

The format for the data points / data lines. See plot for details.

Use 'none' (case insensitive) to plot errorbars without any data markers.

ecolorcolor, default: None

The color of the errorbar lines. If None, use the color of the line connecting the markers.

elinewidthfloat, default: None

The linewidth of the errorbar lines. If None, the linewidth of the current style is used.

capsizefloat, default: rcParams["errorbar.capsize"] (default: 0.0)

The length of the error bar caps in points.

capthickfloat, default: None

An alias to the keyword argument markeredgewidth (a.k.a. mew). This setting is a more sensible name for the property that controls the thickness of the error bar cap in points. For backwards compatibility, if mew or markeredgewidth are given, then they will over-ride capthick. This may change in future releases.

barsabovebool, default: False

If True, will plot the errorbars above the plot symbols. Default is below.

xlolims, ylolims, zlolimsbool, default: False

These arguments can be used to indicate that a value gives only lower limits. In that case a caret symbol is used to indicate this. lims-arguments may be scalars, or array-likes of the same length as the errors. To use limits with inverted axes, set_xlim or set_ylim must be called before errorbar(). Note the tricky parameter names: setting e.g. ylolims to True means that the y-value is a lower limit of the True value, so, only an upward-pointing arrow will be drawn!

xuplims, yuplims, zuplimsbool, default: False

Same as above, but for controlling the upper limits.

erroreveryint or (int, int), default: 1

draws error bars on a subset of the data. errorevery =N draws error bars on the points (x[::N], y[::N], z[::N]). errorevery =(start, N) draws error bars on the points (x[start::N], y[start::N], z[start::N]). e.g. errorevery=(6, 3) adds error bars to the data at (x[6], x[9], x[12], x[15], ...). Used to avoid overlapping error bars when two series share x-axis values.

Returns

errlineslist: List of Line3DCollection instances each containing an errorbar line.
caplineslist: List of Line3D instances each containing a capline object.
limmarkslist: List of Line3D instances each containing a marker with an upper or lower limit.

Other Parameters

dataindexable object, optional

If given, the following parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception):

x, y, z, xerr, yerr, zerr

**kwargs

All other keyword arguments for styling errorbar lines are passed Line3DCollection.

Examples

(Source code, png, pdf)

format_coord(xd, yd)[source]#: 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(z)[source]#: 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()[source]#: Return True if each axis is autoscaled, False otherwise.

get_autoscalez_on()[source]#: Return whether the z-axis is autoscaled.

get_axis_position()[source]#

get_frame_on()[source]#: Get whether the 3D axes panels are drawn.

get_proj()[source]#: Create the projection matrix from the current viewing position.

get_tightbbox(renderer, call_axes_locator=True, bbox_extra_artists=None, *, for_layout_only=False)[source]#

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()[source]#: Get 3D world limits.

get_xlim()[source]#: Alias for get_xlim3d.

get_xlim3d()[source]#

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.

get_ylim()[source]#: Alias for get_ylim3d.

get_ylim3d()[source]#

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.

get_zaxis()[source]#: Return the ZAxis (Axis) instance.

get_zbound()[source]#: Return the lower and upper z-axis bounds, in increasing order.

get_zgridlines()[source]#: Return the zaxis' grid lines as a list of Line2Ds.

get_zlabel()[source]#: Get the z-label text string.

get_zlim()[source]#: Alias for get_zlim3d.

get_zlim3d()[source]#: Get 3D z limits.

get_zmajorticklabels()[source]#: Return the zaxis' major tick labels, as a list of Text.

get_zminorticklabels()[source]#: Return the zaxis' minor tick labels, as a list of Text.

get_zscale()[source]#

get_zticklabels(minor=False, which=None)[source]#

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.

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

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

See also

mpl_toolkits.mplot3d.axes3d.Axes3D.set_box_aspect

set_autoscale_on(b)[source]#

Set whether autoscaling is applied to each axis on the next draw or call to Axes.autoscale_view.

Parameters

bbool

set_autoscalez_on(b)[source]#

Set whether the z-axis is autoscaled on the next draw or call to Axes.autoscale_view.

Parameters

bbool

set_axis_off()[source]#

Turn the x- and y-axis off.

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

set_axis_on()[source]#

Turn the x- and y-axis on.

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

set_box_aspect(aspect, *, zoom=1)[source]#

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(b)[source]#

Set whether the 3D axes panels are drawn.

Parameters

bbool

set_proj_type(proj_type)[source]#

Set the projection type.

Parameters

proj_type{'persp', 'ortho'}

set_title(label, fontdict=None, loc='center', **kwargs)[source]#

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 location for the title (1.0 is the top). If None (the default) and rcParams["axes.titley"] (default: None) is also None, 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()[source]#

set_xlim(left=None, right=None, emit=True, auto=False, *, xmin=None, xmax=None)[source]#: Alias for set_xlim3d.

set_xlim3d(left=None, right=None, emit=True, auto=False, *, xmin=None, xmax=None)[source]#

Set 3D x limits.

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

set_xmargin(m)[source]#

Set padding of X 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. For example, if your data is in the range [0, 2], a factor of m = 0.1 will result in a range [-0.2, 2.2].

Negative values -0.5 < m < 0 will result in clipping of the data range. I.e. for a data range [0, 2], a factor of m = -0.1 will result in a range [0.2, 1.8].

Parameters

mfloat greater than -0.5

set_xscale(value, **kwargs)[source]#

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(bottom=None, top=None, emit=True, auto=False, *, ymin=None, ymax=None)[source]#: Alias for set_ylim3d.

set_ylim3d(bottom=None, top=None, emit=True, auto=False, *, ymin=None, ymax=None)[source]#

Set 3D y limits.

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

set_ymargin(m)[source]#

Set padding of Y data limits prior to autoscaling.

Negative values -0.5 < m < 0 will result in clipping of the data range. I.e. for a data range [0, 2], a factor of m = -0.1 will result in a range [0.2, 1.8].

Parameters

mfloat greater than -0.5

set_yscale(value, **kwargs)[source]#

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(lower=None, upper=None)[source]#

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

set_zlabel(zlabel, fontdict=None, labelpad=None, **kwargs)[source]#: Set zlabel. See doc for set_ylabel for description.

set_zlim(bottom=None, top=None, emit=True, auto=False, *, zmin=None, zmax=None)[source]#: Alias for set_zlim3d.

set_zlim3d(bottom=None, top=None, emit=True, auto=False, *, zmin=None, zmax=None)[source]#

Set 3D z limits.

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

set_zmargin(m)[source]#

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

set_zscale(value, **kwargs)[source]#

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(labels, *, fontdict=None, minor=False, **kwargs)[source]#

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(ticks, labels=None, *, minor=False, **kwargs)[source]#

Set the zaxis' tick locations and optionally labels.

If necessary, the view limits of the Axis are expanded so that all given ticks are visible.

Parameters

tickslist of floats: List of tick locations.
labelslist of str, optional: List of tick labels. If not set, the labels show the data value.
minorbool, default: False: If False, set the major ticks; if True, the minor ticks.
**kwargs: Text properties for the labels. These take effect only if you pass labels. In other cases, please use tick_params.

Notes

The mandatory expansion of the view limits is an intentional design choice to prevent the surprise of a non-visible tick. If you need other limits, you should set the limits explicitly after setting the ticks.

stem(x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-', bottom=0, label=None, orientation='z', data=None)[source]#

Create a 3D stem plot.

A stem plot draws lines perpendicular to a baseline, and places markers at the heads. By default, the baseline is defined by x and y, and stems are drawn vertically from bottom to z.

Parameters

x, y, zarray-like

The positions of the heads of the stems. The stems are drawn along the orientation-direction from the baseline at bottom (in the orientation-coordinate) to the heads. By default, the x and y positions are used for the baseline and z for the head position, but this can be changed by orientation.

linefmtstr, default: 'C0-'

A string defining the properties of the vertical lines. Usually, this will be a color or a color and a linestyle:

Character	Line Style
`'-'`	solid line
`'--'`	dashed line
`'-.'`	dash-dot line
`':'`	dotted line

Note: While it is technically possible to specify valid formats other than color or color and linestyle (e.g. 'rx' or '-.'), this is beyond the intention of the method and will most likely not result in a reasonable plot.

markerfmtstr, default: 'C0o'

A string defining the properties of the markers at the stem heads.

basefmtstr, default: 'C3-'

A format string defining the properties of the baseline.

bottomfloat, default: 0

The position of the baseline, in orientation-coordinates.

labelstr, default: None

The label to use for the stems in legends.

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

The direction along which stems are drawn.

dataindexable object, optional

If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).

Returns

StemContainer: The container may be treated like a tuple (markerline, stemlines, baseline)

Examples

(Source code, png, pdf)

(png, pdf)

(png, pdf)

stem3D(x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-', bottom=0, label=None, orientation='z', data=None)[source]#

Create a 3D stem plot.

A stem plot draws lines perpendicular to a baseline, and places markers at the heads. By default, the baseline is defined by x and y, and stems are drawn vertically from bottom to z.

Parameters

x, y, zarray-like

linefmtstr, default: 'C0-'

A string defining the properties of the vertical lines. Usually, this will be a color or a color and a linestyle:

Character	Line Style
`'-'`	solid line
`'--'`	dashed line
`'-.'`	dash-dot line
`':'`	dotted line

markerfmtstr, default: 'C0o'

A string defining the properties of the markers at the stem heads.

basefmtstr, default: 'C3-'

A format string defining the properties of the baseline.

bottomfloat, default: 0

The position of the baseline, in orientation-coordinates.

labelstr, default: None

The label to use for the stems in legends.

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

The direction along which stems are drawn.

dataindexable object, optional

If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).

Returns

StemContainer: The container may be treated like a tuple (markerline, stemlines, baseline)

Examples

(Source code, png, pdf)

(png, pdf)

text(x, y, z, s, zdir=None, **kwargs)[source]#: 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(x, y, s, fontdict=None, **kwargs)[source]#

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`	scalar or None
`animated`	bool
`backgroundcolor`	color
`bbox`	dict with properties for `patches.FancyBboxPatch`
`clip_box`	unknown
`clip_on`	unknown
`clip_path`	unknown
`color` or c	color
`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)
`math_fontfamily`	str
`multialignment` or ma	{'left', 'right', 'center'}
`parse_math`	bool
`path_effects`	`AbstractPathEffect`
`picker`	None or bool or float or callable
`position`	(float, float)
`rasterized`	bool
`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`
`transform_rotates_text`	bool
`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(x, y, z, s, zdir=None, **kwargs)[source]#: 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(axis='both', **kwargs)[source]#

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.

tricontour(*args, extend3d=False, stride=5, zdir='z', offset=None, data=None, **kwargs)[source]#

Create a 3D 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. See tricontour for acceptable data shapes.
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.
dataindexable object, optional: If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).
*args, **kwargs: Other arguments are forwarded to matplotlib.axes.Axes.tricontour.

Returns

matplotlib.tri.tricontour.TriContourSet

tricontourf(*args, zdir='z', offset=None, data=None, **kwargs)[source]#

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. See tricontourf for acceptable data shapes.
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.
dataindexable object, optional: If given, all parameters also accept a string s, which is interpreted as data[s] (unless this raises an exception).
*args, **kwargs: Other arguments are forwarded to matplotlib.axes.Axes.tricontourf.

Returns

matplotlib.tri.tricontour.TriContourSet

tunit_cube(vals=None, M=None)[source]#

tunit_edges(vals=None, M=None)[source]#

unit_cube(vals=None)[source]#

update_datalim(xys, **kwargs)[source]#

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(elev=None, azim=None, vertical_axis='z')[source]#

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

This can be used to rotate the axes programmatically.

Parameters

elevfloat, default: None: The elevation angle in the vertical plane in degrees. If None then the initial value as specified in the Axes3D constructor is used.
azimfloat, default: None: The azimuth angle in the horizontal plane in degrees. If None then the initial value as specified in the Axes3D constructor is used.
vertical_axis{"z", "x", "y"}, default: "z": The axis to align vertically. azim rotates about this axis.

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

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.

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. These parameters 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.

lightsourceLightSource

The lightsource to use when shade is True.

**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[source]#

property w_yaxis[source]#

property w_zaxis[source]#

zaxis_date(tz=None)[source]#

Set 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.

Notes

This function is merely provided for completeness, but 3D axes do not support dates for ticks, and so this may not work as expected.

zaxis_inverted()[source]#: Returns True if the z-axis is inverted.