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

shareviewAxes3D, optional

Other Axes to share view angles with.

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

BboxBase or None

clip_on

bool

clip_path

Patch or (Path, Transform) or None

facecolor or fc

color

figure

Figure

gid

str

in_layout

bool

label

object

mouseover

bool

navigate

bool

navigate_mode

unknown

path_effects

list of AbstractPathEffect

picker

None or bool or float or callable

position

[left, bottom, width, height] or Bbox

proj_type

{'persp', 'ortho'}

prop_cycle

Cycler

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

(lower: float, upper: float)

xlabel

str

xlim or xlim3d

(left: float, right: float)

xlim3d

(left: float, right: float)

xmargin

float greater than -0.5

xscale

unknown

xticklabels

unknown

xticks

unknown

ybound

(lower: float, upper: float)

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 the text s to the 3D Axes at location x, y, z in data coordinates.

text2D

Add text to the Axes.

Clearing#

clear

Clear the Axes.

Appearance#

set_axis_off

Hide all visual components of the x- and y-axis.

set_axis_on

Do not hide all visual components of the x- and y-axis.

grid

Set / unset 3D grid.

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

Return the 3D z-axis view 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 tick 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 Line2Ds.

get_zgridlines

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

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.

Sharing#

sharez

Share the z-axis with other.

shareview

Share the view angles with other.

Interactive#

can_zoom

Return whether this Axes supports the zoom box button functionality.

can_pan

Return whether this Axes supports any pan/zoom 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

Return a string giving the current view rotation angles, or the x, y, z coordinates of the point on the nearest axis pane underneath the mouse cursor, depending on the mouse button pressed.

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 the text s to the 3D Axes at location x, y, z in data coordinates.

tunit_cube

[Deprecated]

tunit_edges

[Deprecated]

unit_cube

[Deprecated]

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.