mpl_toolkits.mplot3d.axes3d.Axes3D#

class mpl_toolkits.mplot3d.axes3d.Axes3D(fig, rect=None, *args, elev=30, azim=-60, roll=0, sharez=None, proj_type='persp', box_aspect=None, computed_zorder=True, focal_length=None, **kwargs)[source]#

Bases: Axes

3D Axes object.

Note

As a user, you do not instantiate Axes directly, but use Axes creation methods instead; e.g. from pyplot or Figure: subplots, subplot_mosaic or Figure.add_axes.

Parameters:

figFigure

The parent figure.

recttuple (left, bottom, width, height), default: None.

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

elevfloat, default: 30

The elevation angle in degrees rotates the camera above and below the x-y plane, with a positive angle corresponding to a location above the plane.

azimfloat, default: -60

The azimuthal angle in degrees rotates the camera about the z axis, with a positive angle corresponding to a right-handed rotation. In other words, a positive azimuth rotates the camera about the origin from its location along the +x axis towards the +y axis.

rollfloat, default: 0

The roll angle in degrees rotates the camera about the viewing axis. A positive angle spins the camera clockwise, causing the scene to rotate counter-clockwise.

sharezAxes3D, optional

Other Axes to share z-limits with.

proj_type{'persp', 'ortho'}

The projection type, default 'persp'.

box_aspect3-tuple of floats, default: 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

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.

focal_lengthfloat, default: None

For a projection type of 'persp', the focal length of the virtual camera. Must be > 0. If None, defaults to 1. For a projection type of 'ortho', must be set to either None or infinity (numpy.inf). If None, defaults to infinity. The focal length can be computed from a desired Field Of View via the equation: focal_length = 1/tan(FOV/2)

**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 and two offsets from the bottom left corner of the image
`alpha`	scalar or None
`anchor`	(float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}
`animated`	bool
`aspect`	{'auto', 'equal', 'equalxy', 'equalxz', 'equalyz'}
`autoscale_on`	bool
`autoscalex_on`	unknown
`autoscaley_on`	unknown
`autoscalez_on`	unknown
`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
`mouseover`	bool
`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
`subplotspec`	unknown
`title`	unknown
`transform`	`Transform`
`url`	str
`visible`	bool
`xbound`	unknown
`xlabel`	str
`xlim` or xlim3d	(bottom: float, top: float)
`xlim3d`	(bottom: float, top: float)
`xmargin`	float greater than -0.5
`xscale`	unknown
`xticklabels`	unknown
`xticks`	unknown
`ybound`	unknown
`ylabel`	str
`ylim` or ylim3d	(bottom: float, top: float)
`ylim3d`	(bottom: float, top: float)
`ymargin`	float greater than -0.5
`yscale`	unknown
`yticklabels`	unknown
`yticks`	unknown
`zbound`	unknown
`zlabel`	unknown
`zlim` or zlim3d	unknown
`zmargin`	float greater than -0.5
`zorder`	float
`zscale`	unknown
`zticklabels`	unknown
`zticks`	unknown

Plotting#

`plot`	Plot 2D or 3D data.
`scatter`	Create a scatter plot.
`bar`	Add 2D bar(s).
`bar3d`	Generate a 3D barplot.
`plot_surface`	Create a surface plot.
`plot_wireframe`	Plot a 3D wireframe.
`plot_trisurf`	Plot a triangulated surface.
`clabel`	Currently not implemented for 3D axes, and returns None.
`contour`	Create a 3D contour plot.
`tricontour`	Create a 3D contour plot.
`contourf`	Create a 3D filled contour plot.
`tricontourf`	Create a 3D filled contour plot.
`quiver`	Plot a 3D field of arrows.
`voxels`	Plot a set of filled voxels
`errorbar`	Plot lines and/or markers with errorbars around them.
`stem`	Create a 3D stem plot.

Text and annotations#

`text`	Add text to the plot.
`text2D`	Add text to the Axes.

Clearing#

clear

Clear the Axes.

Appearance#

`set_axis_off`	Turn the x- and y-axis off.
`set_axis_on`	Turn the x- and y-axis on.
`grid`	Set / unset 3D grid.
`get_frame_on`	Get whether the 3D axes panels are drawn.
`set_frame_on`	Set whether the 3D axes panels are drawn.

Axis#

Axis limits and direction#

`get_zaxis`	Return the `ZAxis` (`Axis`) instance.
`get_xlim`	Return the x-axis view limits.
`get_ylim`	Return the y-axis view limits.
`get_zlim`	Get 3D z limits.
`set_zlim`	Set 3D z limits.
`get_w_lims`	Get 3D world limits.
`invert_zaxis`	Invert the z-axis.
`zaxis_inverted`	Return whether the zaxis is oriented in the "inverse" direction.
`get_zbound`	Return the lower and upper z-axis bounds, in increasing order.
`set_zbound`	Set the lower and upper numerical bounds of the z-axis.

Axis labels and title#

`set_zlabel`	Set zlabel.
`get_zlabel`	Get the z-label text string.
`set_title`	Set a title for the Axes.

Axis scales#

`set_xscale`	Set the x-axis scale.
`set_yscale`	Set the y-axis scale.
`set_zscale`	Set the z-axis scale.
`get_zscale`	Return the zaxis' scale (as a str).

Autoscaling and margins#

`set_zmargin`	Set padding of Z data limits prior to autoscaling.
`margins`	Set or retrieve autoscaling margins.
`autoscale`	Convenience method for simple axis view autoscaling.
`autoscale_view`	Autoscale the view limits using the data limits.
`set_autoscalez_on`	Set whether the zaxis is autoscaled when drawing or by `Axes.autoscale_view`.
`get_autoscalez_on`	Return whether the zaxis is autoscaled.
`auto_scale_xyz`

Aspect ratio#

`set_aspect`	Set the aspect ratios.
`set_box_aspect`	Set the Axes box aspect.
`apply_aspect`	Adjust the Axes for a specified data aspect ratio.

Ticks#

`tick_params`	Convenience method for changing the appearance of ticks and tick labels.
`set_zticks`	Set the zaxis' tick locations and optionally labels.
`get_zticks`	Return the zaxis' tick locations in data coordinates.
`set_zticklabels`	[Discouraged] Set the zaxis' tick labels with list of string labels.
`get_zticklines`	Return the zaxis' tick lines as a list of `Line2D`s.
`get_zgridlines`	Return the zaxis' grid lines as a list of `Line2D`s.
`get_zminorticklabels`	Return the zaxis' minor tick labels, as a list of `Text`.
`get_zmajorticklabels`	Return the zaxis' major tick labels, as a list of `Text`.
`zaxis_date`	Set up axis ticks and labels to treat data along the zaxis as dates.

Units#

convert_zunits

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

Adding artists#

add_collection3d

Add a 3D collection object to the plot.

Interactive#

`can_zoom`	Return whether this Axes supports the zoom box button functionality.
`can_pan`	Return whether this Axes supports the pan button functionality.
`disable_mouse_rotation`	Disable mouse buttons for 3D rotation, panning, and zooming.
`mouse_init`	Set the mouse buttons for 3D rotation and zooming.
`drag_pan`	Called when the mouse moves during a pan operation.
`format_zdata`	Return z string formatted.
`format_coord`	Given the 2D view coordinates attempt to guess a 3D coordinate.

Projection and perspective#

`view_init`	Set the elevation and azimuth of the axes in degrees (not radians).
`set_proj_type`	Set the projection type.
`get_proj`	Create the projection matrix from the current viewing position.
`set_top_view`

Drawing#

`draw`	Draw the Artist (and its children) using the given renderer.
`get_tightbbox`	Return the tight bounding box of the Axes, including axis and their decorators (xlabel, title, etc).

Aliases and deprecated methods#

`set_zlim3d`	Alias for `set_zlim`.
`stem3D`	Create a 3D stem plot.
`text3D`	Add text to the plot.
`tunit_cube`	[Deprecated]
`tunit_edges`	[Deprecated]
`unit_cube`	[Deprecated]
`w_xaxis`
`w_yaxis`
`w_zaxis`

Other#

`get_axis_position`
`add_contour_set`
`add_contourf_set`
`update_datalim`	Not implemented in `Axes3D`.

Sample 3D data#

axes3d.get_test_data

Return a tuple X, Y, Z with a test data set.