Version 3.1.2
mpl_toolkits.mplot3d.axes3d.Axes3D(fig, rect=None, *args, azim=-60, elev=30, zscale=None, sharez=None, proj_type='persp', **kwargs)[source]¶Bases: matplotlib.axes._axes.Axes
3D axes object.
| Parameters: |
|
|---|
Notes
New in version 1.2.1: The sharez parameter.
add_collection3d(self, 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.
autoscale(self, 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.
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
autoscale_view(self, 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.
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)[source]¶Add 2D bar(s).
| Parameters: |
|
|---|---|
| Returns: |
|
bar3d(self, x, y, z, dx, dy, dz, color=None, zsort='average', shade=True, *args, **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: |
|
|---|---|
| Returns: |
|
can_pan(self)[source]¶Return True if this axes supports the pan/zoom button functionality.
3D axes objects do not use the pan/zoom button.
can_zoom(self)[source]¶Return True if this axes supports the zoom box button functionality.
3D axes objects do not use the zoom box button.
clabel(self, *args, **kwargs)[source]¶This function is currently not implemented for 3D axes. Returns None.
contour(self, X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, **kwargs)[source]¶Create a 3D contour plot.
| Parameters: |
|
|---|---|
| Returns: |
|
contour3D(self, X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, **kwargs)¶Create a 3D contour plot.
| Parameters: |
|
|---|---|
| Returns: |
|
contourf(self, X, Y, Z, *args, zdir='z', offset=None, **kwargs)[source]¶Create a 3D filled contour plot.
| Parameters: |
|
|---|---|
| Returns: |
|
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: |
|
|---|---|
| Returns: |
|
Notes
New in version 1.1.0: The zdir and offset parameters.
convert_zunits(self, z)[source]¶For artists in an axes, if the zaxis has units support, convert z using zaxis unit type
New in version 1.2.1.
format_coord(self, 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(self, 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(self)[source]¶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)[source]¶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_proj(self)[source]¶Create the projection matrix from the current viewing position.
elev stores the elevation angle in the z plane azim stores the azimuth angle in the x,y plane
dist is the distance of the eye viewing point from the object point.
get_xlim(self)¶Return the x-axis view limits.
| Returns: |
|
|---|
See also
set_xlimset_xbound, get_xboundinvert_xaxis, xaxis_invertedNotes
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_xlim3d(self)[source]¶Return the x-axis view limits.
| Returns: |
|
|---|
See also
set_xlimset_xbound, get_xboundinvert_xaxis, xaxis_invertedNotes
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)¶Return the y-axis view limits.
| Returns: |
|
|---|
See also
set_ylimset_ybound, get_yboundinvert_yaxis, yaxis_invertedNotes
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_ylim3d(self)[source]¶Return the y-axis view limits.
| Returns: |
|
|---|
See also
set_ylimset_ybound, get_yboundinvert_yaxis, yaxis_invertedNotes
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_zbound(self)[source]¶Returns the z-axis numerical bounds where:
lowerBound < upperBound
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
get_zlabel(self)[source]¶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)¶Get 3D z limits.
get_zmajorticklabels(self)[source]¶Get the ztick labels as a list of Text instances
New in version 1.1.0.
get_zminorticklabels(self)[source]¶Get the ztick labels as a list of Text instances
Note
Minor ticks are not supported. This function was added only for completeness.
New in version 1.1.0.
get_zticklabels(self, minor=False)[source]¶Get ztick labels as a list of Text instances.
See matplotlib.axes.Axes.get_yticklabels() for more details.
Note
Minor ticks are not supported.
New in version 1.1.0.
get_zticklines(self)[source]¶Get ztick lines as a list of Line2D instances. Note that this function is provided merely for completeness. These lines are re-calculated as the display changes.
New in version 1.1.0.
get_zticks(self, minor=False)[source]¶Return the z ticks as a list of locations
See matplotlib.axes.Axes.get_yticks() for more details.
Note
Minor ticks are not supported.
New in version 1.1.0.
grid(self, b=True, **kwargs)[source]¶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.
Changed in version 1.1.0: This function was changed, but not tested. Please report any bugs.
invert_zaxis(self)[source]¶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)[source]¶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)[source]¶Convenience method to set or retrieve autoscaling 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: This function was added, but not tested. Please report any bugs.
mouse_init(self, rotate_btn=1, zoom_btn=3)[source]¶Initializes mouse button callbacks to enable 3D rotation of the axes. Also optionally sets the mouse buttons for 3D rotation and zooming.
| Parameters: |
|
|---|
name = '3d'¶plot(self, xs, ys, *args, zdir='z', **kwargs)[source]¶Plot 2D or 3D data.
| Parameters: |
|
|---|
plot3D(self, xs, ys, *args, zdir='z', **kwargs)¶Plot 2D or 3D data.
| Parameters: |
|
|---|
plot_surface(self, X, Y, Z, *args, norm=None, vmin=None, vmax=None, lightsource=None, **kwargs)[source]¶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.
| Parameters: |
|
|---|
plot_trisurf(self, *args, color=None, norm=None, vmin=None, vmax=None, lightsource=None, **kwargs)[source]¶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: |
|
|---|
Examples
(Source code, png, pdf)
(Source code, png, pdf)
New in version 1.2.0: This plotting function was added for the v1.2.0 release.
plot_wireframe(self, X, Y, Z, *args, **kwargs)[source]¶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: |
|
|---|
quiver(X, Y, Z, U, V, W, /, length=1, arrow_length_ratio=.3, pivot='tail', normalize=False, **kwargs)[source]¶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: |
|
|---|
quiver3D(X, Y, Z, U, V, W, /, length=1, arrow_length_ratio=.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: |
|
|---|
scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, **kwargs)[source]¶Create a scatter plot.
| Parameters: |
|
|---|---|
| Returns: |
|
scatter3D(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, **kwargs)¶Create a scatter plot.
| Parameters: |
|
|---|---|
| Returns: |
|
set_autoscale_on(self, b)[source]¶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: |
|
|---|
set_autoscalez_on(self, b)[source]¶Set 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.
| Parameters: |
|
|---|
set_axis_off(self)[source]¶Turn the x- and y-axis off.
This affects the axis lines, ticks, ticklabels, grid and axis labels.
set_axis_on(self)[source]¶Turn the x- and y-axis on.
This affects the axis lines, ticks, ticklabels, grid and axis labels.
set_frame_on(self, b)[source]¶Set whether the 3D axes panels are drawn.
New in version 1.1.0.
| Parameters: |
|
|---|
set_proj_type(self, proj_type)[source]¶Set the projection type.
| Parameters: |
|
|---|
set_title(self, 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: |
|
|---|---|
| Returns: |
|
| Other Parameters: |
set_xlim(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_xlim3d(self, 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_xscale(self, value, **kwargs)[source]¶Set the x-axis scale.
| Parameters: |
|
|---|
Notes
By default, Matplotlib supports the above mentioned scales.
Additionally, custom scales may be registered using
matplotlib.scale.register_scale. These scales can then also
be used here.
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
set_ylim(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_ylim3d(self, 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_yscale(self, value, **kwargs)[source]¶Set the y-axis scale.
| Parameters: |
|
|---|
Notes
By default, Matplotlib supports the above mentioned scales.
Additionally, custom scales may be registered using
matplotlib.scale.register_scale. These scales can then also
be used here.
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
set_zbound(self, 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 _autoscaleZon attribute.
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
set_zlabel(self, zlabel, fontdict=None, labelpad=None, **kwargs)[source]¶Set zlabel. See doc for set_ylabel() for description.
set_zlim(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_zlim3d(self, 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(self, 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
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
set_zscale(self, value, **kwargs)[source]¶Set the z-axis scale.
| Parameters: |
|
|---|
Notes
Currently, Axes3D objects only supports linear scales. Other scales may or may not work, and support for these is improving with each release.
By default, Matplotlib supports the above mentioned scales.
Additionally, custom scales may be registered using
matplotlib.scale.register_scale. These scales may then also
be used here as support is added.
set_zticklabels(self, *args, **kwargs)[source]¶Set z-axis tick labels.
See matplotlib.axes.Axes.set_yticklabels() for more details.
Note
Minor ticks are not supported by Axes3D objects.
New in version 1.1.0.
set_zticks(self, *args, **kwargs)[source]¶Set z-axis tick locations.
See matplotlib.axes.Axes.set_yticks() for more details.
Note
Minor ticks are not supported.
New in version 1.1.0.
text(self, 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(self, x, y, s, fontdict=None, withdash=<deprecated parameter>, **kwargs)¶Add text to the axes.
Add the text s to the axes at location x, y in data coordinates.
| Parameters: |
|
|---|---|
| Returns: | |
| Other Parameters: |
|
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)[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
While this function is currently implemented, the core part of the Axes3D object may ignore some of these settings. Future releases will fix this. Priority will be given to those who file bugs.
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
ticklabel_format(self, *, style='', scilimits=None, useOffset=None, axis='both')[source]¶Convenience method for manipulating the ScalarFormatter used by default for linear axes in Axed3D objects.
See matplotlib.axes.Axes.ticklabel_format() for full
documentation. Note that this version applies to all three
axes of the Axes3D object. Therefore, the axis argument
will also accept a value of 'z' and the value of 'both' will
apply to all three axes.
New in version 1.1.0: This function was added, but not tested. Please report any bugs.
tricontour(self, *args, extend3d=False, stride=5, zdir='z', offset=None, **kwargs)[source]¶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: |
|
|---|---|
| Returns: |
|
tricontourf(self, *args, zdir='z', offset=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: |
|
|---|---|
| Returns: |
|
Notes
New in version 1.1.0: The zdir and offset parameters.
Changed in version 1.3.0: Added support for custom triangulations
update_datalim(self, 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: |
|
|---|
view_init(self, elev=None, azim=None)[source]¶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)[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.
New in version 2.1.
| Parameters: |
|
|---|---|
| Returns: |
|
Examples
(Source code, png, pdf)
(Source code, png, pdf)
(Source code, png, pdf)
(Source code, png, pdf)
zaxis_date(self, tz=None)[source]¶Sets up z-axis ticks and labels that treat the z data as dates.
tz is a timezone string or tzinfo instance.
Defaults to rc value.
Note
This function is merely provided for completeness. Axes3D objects do not officially support dates for ticks, and so this may or may not work as expected.
New in version 1.1.0: This function was added, but not tested. Please report any bugs.