mplot3d API

Contents

• mplot3d API
  • axes3d
  • axis3d
  • art3d
  • proj3d

axes3d

Note

Significant effort went into bringing axes3d to feature-parity with regular axes objects for version 1.1.0. However, more work remains. Please report any functions that do not behave as expected as a bug. In addition, help and patches would be greatly appreciated!

Module containing Axes3D, an object which can plot 3D objects on a 2D matplotlib figure.

class mpl_toolkits.mplot3d.axes3d.Axes3D(fig, rect=None, *args, **kwargs)

Bases: matplotlib.axes._axes.Axes

3D axes object.

add_collection3d(col, zs=0, zdir=u'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
• LineColleciton
• PatchCollection

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

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

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

autoscale(enable=True, axis=u'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. Therfore, ‘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(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(left, height, zs=0, zdir=u'z', *args, **kwargs)

Add 2D bar(s).

Argument	Description
left	The x coordinates of the left sides of the bars.
height	The height of the bars.
zs	Z coordinate of bars, if one value is specified they will all be placed at the same z.
zdir	Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.

Keyword arguments are passed onto bar().

Returns a Patch3DCollection

bar3d(x, y, z, dx, dy, dz, color=u'b', zsort=u'average', *args, **kwargs)

Generate a 3D bar, or multiple bars.

When generating multiple bars, x, y, z have to be arrays. dx, dy, dz can be arrays or scalars.

color can be:

• A single color value, 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

Keyword arguments are passed onto Poly3DCollection()

can_pan()

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

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

can_zoom()

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

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

cla()

Clear axes

clabel(*args, **kwargs)

This function is currently not implemented for 3D axes. Returns None.

contour(X, Y, Z, *args, **kwargs)

Create a 3D contour plot.

Argument	Description
X, Y,	Data values as numpy.arrays
Z
extend3d	Whether to extend contour in 3D (default: False)
stride	Stride (step size) for extending contour
zdir	The direction to use: x, y or z (default)
offset	If specified plot a projection of the contour lines on this position in plane normal to zdir

The positional and other keyword arguments are passed on to contour()

Returns a contour

contour3D(X, Y, Z, *args, **kwargs)

Create a 3D contour plot.

Argument	Description
X, Y,	Data values as numpy.arrays
Z
extend3d	Whether to extend contour in 3D (default: False)
stride	Stride (step size) for extending contour
zdir	The direction to use: x, y or z (default)
offset	If specified plot a projection of the contour lines on this position in plane normal to zdir

The positional and other keyword arguments are passed on to contour()

Returns a contour

contourf(X, Y, Z, *args, **kwargs)

Create a 3D contourf plot.

Argument	Description
X, Y,	Data values as numpy.arrays
Z
zdir	The direction to use: x, y or z (default)
offset	If specified plot a projection of the filled contour on this position in plane normal to zdir

The positional and keyword arguments are passed on to contourf()

Returns a contourf

Changed in version 1.1.0: The zdir and offset kwargs were added.

contourf3D(X, Y, Z, *args, **kwargs)

Create a 3D contourf plot.

Argument	Description
X, Y,	Data values as numpy.arrays
Z
zdir	The direction to use: x, y or z (default)
offset	If specified plot a projection of the filled contour on this position in plane normal to zdir

The positional and keyword arguments are passed on to contourf()

Returns a contourf

Changed in version 1.1.0: The zdir and offset kwargs were added.

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

Disable mouse button callbacks.

draw(renderer)

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

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

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

get_axisbelow()

Get whether axis below is true or not.

For axes3d objects, this will always be True

New in version 1.1.0: This function was added for completeness.

get_children()

get_frame_on()

Get whether the 3D axes panels are drawn

New in version 1.1.0.

get_proj()

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

Get 3D world limits.

get_xlim()

Get the x-axis range [left, right]

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

get_xlim3d()

Get the x-axis range [left, right]

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

get_ylim()

Get the y-axis range [bottom, top]

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

get_ylim3d()

Get the y-axis range [bottom, top]

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

get_zbound()

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

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

Get 3D z limits.

get_zlim3d()

Get 3D z limits.

get_zmajorticklabels()

Get the ztick labels as a list of Text instances

New in version 1.1.0.

get_zminorticklabels()

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

get_zticklabels(minor=False)

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

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(minor=False)

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

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

have_units()

Return True if units are set on the x, y, or z axes

invert_zaxis()

Invert the z-axis.

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

locator_params(axis=u'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(*args, **kw)

Convenience method to set or retrieve autoscaling margins.

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 argument specifies xmargin, ymargin and zmargin. 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(rotate_btn=1, zoom_btn=3)

Initializes mouse button callbacks to enable 3D rotation of the axes. Also optionally sets the mouse buttons for 3D rotation and zooming.

Argument	Description
rotate_btn	The integer or list of integers specifying which mouse button or buttons to use for 3D rotation of the axes. Default = 1.
zoom_btn	The integer or list of integers specifying which mouse button or buttons to use to zoom the 3D axes. Default = 3.

name = u'3d'

plot(xs, ys, *args, **kwargs)

Plot 2D or 3D data.

Argument	Description
xs, ys	X, y coordinates of vertices
zs	z value(s), either one for all points or one for each point.
zdir	Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.

Other arguments are passed on to plot()

plot3D(xs, ys, *args, **kwargs)

Plot 2D or 3D data.

Argument	Description
xs, ys	X, y coordinates of vertices
zs	z value(s), either one for all points or one for each point.
zdir	Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.

Other arguments are passed on to plot()

plot_surface(X, Y, Z, *args, **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.

The rstride and cstride kwargs set the stride used to sample the input data to generate the graph. If 1k by 1k arrays are passed in the default values for the strides will result in a 100x100 grid being plotted.

Argument	Description
X, Y, Z	Data values as 2D arrays
rstride	Array row stride (step size), defaults to 10
cstride	Array column stride (step size), defaults to 10
color	Color of the surface patches
cmap	A colormap for the surface patches.
facecolors	Face colors for the individual patches
norm	An instance of Normalize to map values to colors
vmin	Minimum value to map
vmax	Maximum value to map
shade	Whether to shade the facecolors

Other arguments are passed on to Poly3DCollection

plot_trisurf(*args, **kwargs)

Argument	Description
X, Y, Z	Data values as 1D arrays
color	Color of the surface patches
cmap	A colormap for the surface patches.
norm	An instance of Normalize to map values to colors
vmin	Minimum value to map
vmax	Maximum value to map
shade	Whether to shade the facecolors

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.

Other arguments are passed on to Poly3DCollection

Examples:

(Source code, png)

(Source code)

(png)

(png)

New in version 1.2.0: This plotting function was added for the v1.2.0 release.

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

Plot a 3D wireframe.

The rstride and cstride kwargs set the stride used to sample the input data to generate the graph.

Argument	Description
X, Y,	Data values as 2D arrays
Z
rstride	Array row stride (step size), defaults to 1
cstride	Array column stride (step size), defaults to 1

Keyword arguments are passed on to LineCollection.

Returns a Line3DCollection

quiver(*args, **kwargs)

Plot a 3D field of arrows.

call signatures:

quiver(X, Y, Z, U, V, W, **kwargs)

Arguments:

X, Y, Z:

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

U, V, W:

The x, y and z components of the arrow vectors

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.

Keyword arguments:

length: [1.0 | float]

The length of each quiver, default to 1.0, the unit is the same with the axes

arrow_length_ratio: [0.3 | float]

The ratio of the arrow head with respect to the quiver, default to 0.3

pivot: [ ‘tail’ | ‘middle’ | ‘tip’ ]

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

Any additional keyword arguments are delegated to LineCollection

quiver3D(*args, **kwargs)

Plot a 3D field of arrows.

call signatures:

quiver(X, Y, Z, U, V, W, **kwargs)

Arguments:

X, Y, Z:

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

U, V, W:

The x, y and z components of the arrow vectors

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.

Keyword arguments:

length: [1.0 | float]

The length of each quiver, default to 1.0, the unit is the same with the axes

arrow_length_ratio: [0.3 | float]

The ratio of the arrow head with respect to the quiver, default to 0.3

pivot: [ ‘tail’ | ‘middle’ | ‘tip’ ]

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

Any additional keyword arguments are delegated to LineCollection

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

Create a scatter plot.

Argument	Description
xs, ys	Positions of data points.
zs	Either an array of the same length as xs and ys or a single value to place all points in the same plane. Default is 0.
zdir	Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.
s	size in points^2. It is a scalar or an array of the same length as x and y.
c	a color. c can be a single color format string, or a sequence of color specifications of length N, or a sequence of N numbers to be mapped to colors using the cmap and norm specified via kwargs (see below). Note that c should not be a single numeric RGB or RGBA sequence because that is indistinguishable from an array of values to be colormapped. c can be a 2-D array in which the rows are RGB or RGBA, however.
depthshade	Whether or not to shade the scatter markers to give the appearance of depth. Default is True.

Keyword arguments are passed on to scatter().

Returns a Patch3DCollection

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

Create a scatter plot.

Argument	Description
xs, ys	Positions of data points.
zs	Either an array of the same length as xs and ys or a single value to place all points in the same plane. Default is 0.
zdir	Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.
s	size in points^2. It is a scalar or an array of the same length as x and y.
c	a color. c can be a single color format string, or a sequence of color specifications of length N, or a sequence of N numbers to be mapped to colors using the cmap and norm specified via kwargs (see below). Note that c should not be a single numeric RGB or RGBA sequence because that is indistinguishable from an array of values to be colormapped. c can be a 2-D array in which the rows are RGB or RGBA, however.
depthshade	Whether or not to shade the scatter markers to give the appearance of depth. Default is True.

Keyword arguments are passed on to scatter().

Returns a Patch3DCollection

set_autoscale_on(b)

Set whether autoscaling is applied on plot commands

accepts: [ True | False ]

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

set_autoscalez_on(b)

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

accepts: [ True | False ]

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

set_axis_off()

set_axis_on()

set_axisbelow(b)

Set whether the axis ticks and gridlines are above or below most artists

For axes3d objects, this will ignore any settings and just use True

ACCEPTS: [ True | False ]

New in version 1.1.0: This function was added for completeness.

set_frame_on(b)

Set whether the 3D axes panels are drawn

ACCEPTS: [ True | False ]

New in version 1.1.0.

set_title(label, fontdict=None, loc=u'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:

label : str

Text to use for the title

fontdict : dict

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

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

loc : {‘center’, ‘left’, ‘right’}, str, optional

Which title to set, defaults to ‘center’

Returns:

text : Text

The matplotlib text instance representing the title

Other Parameters:  

kwargs : text properties

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

set_top_view()

set_xlim(left=None, right=None, emit=True, auto=False, **kw)

Set 3D x limits.

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

set_xlim3d(left=None, right=None, emit=True, auto=False, **kw)

Set 3D x limits.

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

set_xscale(value, **kwargs)

Call signature:

set_xscale(value)

Set the scaling of the x-axis: u’linear’ | u’log’ | u’symlog’

ACCEPTS: [u’linear’ | u’log’ | u’symlog’]

Different kwargs are accepted, depending on the scale:

‘linear’

‘log’

basex/basey:

The base of the logarithm

nonposx/nonposy: [‘mask’ | ‘clip’ ]

non-positive values in x or y can be masked as invalid, or clipped to a very small positive number

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

‘symlog’

basex/basey:

The base of the logarithm

linthreshx/linthreshy:

The range (-x, x) within which the plot is linear (to avoid having the plot go to infinity around zero).

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

linscalex/linscaley:

This allows the linear range (-linthresh to linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range.

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

set_ylim(bottom=None, top=None, emit=True, auto=False, **kw)

Set 3D y limits.

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

set_ylim3d(bottom=None, top=None, emit=True, auto=False, **kw)

Set 3D y limits.

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

set_yscale(value, **kwargs)

Call signature:

set_yscale(value)

Set the scaling of the y-axis: u’linear’ | u’log’ | u’symlog’

ACCEPTS: [u’linear’ | u’log’ | u’symlog’]

Different kwargs are accepted, depending on the scale:

‘linear’

‘log’

basex/basey:

The base of the logarithm

nonposx/nonposy: [‘mask’ | ‘clip’ ]

non-positive values in x or y can be masked as invalid, or clipped to a very small positive number

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

‘symlog’

basex/basey:

The base of the logarithm

linthreshx/linthreshy:

The range (-x, x) within which the plot is linear (to avoid having the plot go to infinity around zero).

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

linscalex/linscaley:

This allows the linear range (-linthresh to linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range.

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

set_zbound(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 _autoscaleZon attribute.

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

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

Set zlabel. See doc for set_ylabel() for description.

Note

Currently, labelpad does not have an effect on the labels.

set_zlim(bottom=None, top=None, emit=True, auto=False, **kw)

Set 3D z limits.

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

set_zlim3d(bottom=None, top=None, emit=True, auto=False, **kw)

Set 3D z limits.

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

set_zmargin(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: This function was added, but not tested. Please report any bugs.

set_zscale(value, **kwargs)

call signature:

set_zscale(value)

Set the scaling of the z-axis: u’linear’ | u’log’ | u’symlog’

ACCEPTS: [u’linear’ | u’log’ | u’symlog’]

Different kwargs are accepted, depending on the scale:

‘linear’

‘log’

basex/basey:

The base of the logarithm

nonposx/nonposy: [‘mask’ | ‘clip’ ]

non-positive values in x or y can be masked as invalid, or clipped to a very small positive number

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

‘symlog’

basex/basey:

The base of the logarithm

linthreshx/linthreshy:

The range (-x, x) within which the plot is linear (to avoid having the plot go to infinity around zero).

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

linscalex/linscaley:

This allows the linear range (-linthresh to linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range.

Note

Currently, Axes3D objects only supports linear scales. Other scales may or may not work, and support for these is improving with each release.

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

set_zticklabels(*args, **kwargs)

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(*args, **kwargs)

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(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(x, y, s, fontdict=None, withdash=False, **kwargs)

Add text to the axes.

Add text in string s to axis at location x, y, data coordinates.

Parameters:

x, y : scalars

data coordinates

s : string

text

fontdict : dictionary, optional, default: None

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

withdash : boolean, optional, default: False

Creates a TextWithDash instance instead of a Text instance.

Other Parameters:  

kwargs : Text properties.

Other miscellaneous text 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(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(axis=u'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

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(**kwargs)

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(*args, **kwargs)

Create a 3D contour plot.

Argument	Description
X, Y,	Data values as numpy.arrays
Z
extend3d	Whether to extend contour in 3D (default: False)
stride	Stride (step size) for extending contour
zdir	The direction to use: x, y or z (default)
offset	If specified plot a projection of the contour lines on this position in plane normal to zdir

Other keyword arguments are passed on to tricontour()

Returns a contour

Changed in version 1.3.0: Added support for custom triangulations

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

tricontourf(*args, **kwargs)

Create a 3D contourf plot.

Argument	Description
X, Y,	Data values as numpy.arrays
Z
zdir	The direction to use: x, y or z (default)
offset	If specified plot a projection of the contour lines on this position in plane normal to zdir

Other keyword arguments are passed on to tricontour()

Returns a contour

Changed in version 1.3.0: Added support for custom triangulations

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

tunit_cube(vals=None, M=None)

tunit_edges(vals=None, M=None)

unit_cube(vals=None)

update_datalim(xys, **kwargs)

view_init(elev=None, azim=None)

Set the elevation and azimuth of the axes.

This can be used to rotate the axes programatically.

‘elev’ stores the elevation angle in the z plane. ‘azim’ stores the azimuth angle in the x,y plane.

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

zaxis_date(tz=None)

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.

zaxis_inverted()

Returns True if the z-axis is inverted.

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

mpl_toolkits.mplot3d.axes3d.get_test_data(delta=0.05)

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

mpl_toolkits.mplot3d.axes3d.unit_bbox()

axis3d

Note

Historically, axis3d has suffered from having hard-coded constants controlling the look and feel of the 3D plot. This precluded user level adjustments such as label spacing, font colors and panel colors. For version 1.1.0, these constants have been consolidated into a single private member dictionary, self._axinfo, for the axis object. This is intended only as a stop-gap measure to allow user-level customization, but it is not intended to be permanent.

class mpl_toolkits.mplot3d.axis3d.Axis(adir, v_intervalx, d_intervalx, axes, *args, **kwargs)

Bases: matplotlib.axis.XAxis

draw(renderer)

draw_pane(renderer)

get_major_ticks(numticks=None)

get_rotate_label(text)

get_tick_positions()

get_tightbbox(renderer)

get_view_interval()

return the Interval instance for this 3d axis view limits

init3d()

set_pane_color(color)

Set pane color to a RGBA tuple

set_pane_pos(xys)

set_rotate_label(val)

Whether to rotate the axis label: True, False or None. If set to None the label will be rotated if longer than 4 chars.

set_view_interval(vmin, vmax, ignore=False)

class mpl_toolkits.mplot3d.axis3d.XAxis(adir, v_intervalx, d_intervalx, axes, *args, **kwargs)

Bases: mpl_toolkits.mplot3d.axis3d.Axis

get_data_interval()

return the Interval instance for this axis data limits

class mpl_toolkits.mplot3d.axis3d.YAxis(adir, v_intervalx, d_intervalx, axes, *args, **kwargs)

Bases: mpl_toolkits.mplot3d.axis3d.Axis

get_data_interval()

return the Interval instance for this axis data limits

class mpl_toolkits.mplot3d.axis3d.ZAxis(adir, v_intervalx, d_intervalx, axes, *args, **kwargs)

Bases: mpl_toolkits.mplot3d.axis3d.Axis

get_data_interval()

return the Interval instance for this axis data limits

mpl_toolkits.mplot3d.axis3d.get_flip_min_max(coord, index, mins, maxs)

mpl_toolkits.mplot3d.axis3d.move_from_center(coord, centers, deltas, axmask=(True, True, True))

Return a coordinate that is moved by “deltas” away from the center.

mpl_toolkits.mplot3d.axis3d.tick_update_position(tick, tickxs, tickys, labelpos)

Update tick line and label position and style.

art3d

Module containing 3D artist code and functions to convert 2D artists into 3D versions which can be added to an Axes3D.

class mpl_toolkits.mplot3d.art3d.Line3D(xs, ys, zs, *args, **kwargs)

Bases: matplotlib.lines.Line2D

3D line object.

Keyword arguments are passed onto Line2D().

draw(renderer)

set_3d_properties(zs=0, zdir=u'z')

class mpl_toolkits.mplot3d.art3d.Line3DCollection(segments, *args, **kwargs)

Bases: matplotlib.collections.LineCollection

A collection of 3D lines.

Keyword arguments are passed onto LineCollection().

do_3d_projection(renderer)

Project the points according to renderer matrix.

draw(renderer, project=False)

set_segments(segments)

Set 3D segments

set_sort_zpos(val)

Set the position to use for z-sorting.

class mpl_toolkits.mplot3d.art3d.Patch3D(*args, **kwargs)

Bases: matplotlib.patches.Patch

3D patch object.

do_3d_projection(renderer)

draw(renderer)

get_facecolor()

get_path()

set_3d_properties(verts, zs=0, zdir=u'z')

class mpl_toolkits.mplot3d.art3d.Patch3DCollection(*args, **kwargs)

Bases: matplotlib.collections.PatchCollection

A collection of 3D patches.

Create a collection of flat 3D patches with its normal vector pointed in zdir direction, and located at zs on the zdir axis. ‘zs’ can be a scalar or an array-like of the same length as the number of patches in the collection.

Constructor arguments are the same as for PatchCollection. In addition, keywords zs=0 and zdir=’z’ are available.

Also, the keyword argument “depthshade” is available to indicate whether or not to shade the patches in order to give the appearance of depth (default is True). This is typically desired in scatter plots.

do_3d_projection(renderer)

set_3d_properties(zs, zdir)

set_sort_zpos(val)

Set the position to use for z-sorting.

class mpl_toolkits.mplot3d.art3d.Path3DCollection(*args, **kwargs)

Bases: matplotlib.collections.PathCollection

A collection of 3D paths.

Create a collection of flat 3D paths with its normal vector pointed in zdir direction, and located at zs on the zdir axis. ‘zs’ can be a scalar or an array-like of the same length as the number of paths in the collection.

Constructor arguments are the same as for PathCollection. In addition, keywords zs=0 and zdir=’z’ are available.

Also, the keyword argument “depthshade” is available to indicate whether or not to shade the patches in order to give the appearance of depth (default is True). This is typically desired in scatter plots.

do_3d_projection(renderer)

set_3d_properties(zs, zdir)

set_sort_zpos(val)

Set the position to use for z-sorting.

class mpl_toolkits.mplot3d.art3d.PathPatch3D(path, **kwargs)

Bases: mpl_toolkits.mplot3d.art3d.Patch3D

3D PathPatch object.

do_3d_projection(renderer)

set_3d_properties(path, zs=0, zdir=u'z')

class mpl_toolkits.mplot3d.art3d.Poly3DCollection(verts, *args, **kwargs)

Bases: matplotlib.collections.PolyCollection

A collection of 3D polygons.

Create a Poly3DCollection.

verts should contain 3D coordinates.

Keyword arguments: zsort, see set_zsort for options.

Note that this class does a bit of magic with the _facecolors and _edgecolors properties.

do_3d_projection(renderer)

Perform the 3D projection for this object.

draw(renderer)

get_edgecolor()

get_edgecolors()

get_facecolor()

get_facecolors()

get_vector(segments3d)

Optimize points for projection

set_3d_properties()

set_alpha(alpha)

Set the alpha tranparencies of the collection. alpha must be a float or None.

ACCEPTS: float or None

set_edgecolor(colors)

set_edgecolors(colors)

set_facecolor(colors)

set_facecolors(colors)

set_sort_zpos(val)

Set the position to use for z-sorting.

set_verts(verts, closed=True)

Set 3D vertices.

set_zsort(zsort)

Set z-sorting behaviour:

boolean: if True use default ‘average’ string: ‘average’, ‘min’ or ‘max’

class mpl_toolkits.mplot3d.art3d.Text3D(x=0, y=0, z=0, text=u'', zdir=u'z', **kwargs)

Bases: matplotlib.text.Text

Text object with 3D position and (in the future) direction.

x, y, z Position of text text Text string to display zdir Direction of text

Keyword arguments are passed onto Text().

draw(renderer)

set_3d_properties(z=0, zdir=u'z')

mpl_toolkits.mplot3d.art3d.get_colors(c, num)

Stretch the color argument to provide the required number num

mpl_toolkits.mplot3d.art3d.get_dir_vector(zdir)

mpl_toolkits.mplot3d.art3d.get_patch_verts(patch)

Return a list of vertices for the path of a patch.

mpl_toolkits.mplot3d.art3d.iscolor(c)

mpl_toolkits.mplot3d.art3d.juggle_axes(xs, ys, zs, zdir)

Reorder coordinates so that 2D xs, ys can be plotted in the plane orthogonal to zdir. zdir is normally x, y or z. However, if zdir starts with a ‘-‘ it is interpreted as a compensation for rotate_axes.

mpl_toolkits.mplot3d.art3d.line_2d_to_3d(line, zs=0, zdir=u'z')

Convert a 2D line to 3D.

mpl_toolkits.mplot3d.art3d.line_collection_2d_to_3d(col, zs=0, zdir=u'z')

Convert a LineCollection to a Line3DCollection object.

mpl_toolkits.mplot3d.art3d.norm_angle(a)

Return angle between -180 and +180

mpl_toolkits.mplot3d.art3d.norm_text_angle(a)

Return angle between -90 and +90

mpl_toolkits.mplot3d.art3d.patch_2d_to_3d(patch, z=0, zdir=u'z')

Convert a Patch to a Patch3D object.

mpl_toolkits.mplot3d.art3d.patch_collection_2d_to_3d(col, zs=0, zdir=u'z', depthshade=True)

Convert a PatchCollection into a Patch3DCollection object (or a PathCollection into a Path3DCollection object).

Keywords:

za The location or locations to place the patches in the

collection along the zdir axis. Defaults to 0.

zdir The axis in which to place the patches. Default is “z”.

depthshade Whether to shade the patches to give a sense of depth.

Defaults to True.

mpl_toolkits.mplot3d.art3d.path_to_3d_segment(path, zs=0, zdir=u'z')

Convert a path to a 3D segment.

mpl_toolkits.mplot3d.art3d.pathpatch_2d_to_3d(pathpatch, z=0, zdir=u'z')

Convert a PathPatch to a PathPatch3D object.

mpl_toolkits.mplot3d.art3d.paths_to_3d_segments(paths, zs=0, zdir=u'z')

Convert paths from a collection object to 3D segments.

mpl_toolkits.mplot3d.art3d.poly_collection_2d_to_3d(col, zs=0, zdir=u'z')

Convert a PolyCollection to a Poly3DCollection object.

mpl_toolkits.mplot3d.art3d.rotate_axes(xs, ys, zs, zdir)

Reorder coordinates so that the axes are rotated with zdir along the original z axis. Prepending the axis with a ‘-‘ does the inverse transform, so zdir can be x, -x, y, -y, z or -z

mpl_toolkits.mplot3d.art3d.text_2d_to_3d(obj, z=0, zdir=u'z')

Convert a Text to a Text3D object.

mpl_toolkits.mplot3d.art3d.zalpha(colors, zs)

Modify the alphas of the color list according to depth

proj3d

Various transforms used for by the 3D code

mpl_toolkits.mplot3d.proj3d.inv_transform(xs, ys, zs, M)

mpl_toolkits.mplot3d.proj3d.line2d(p0, p1)

Return 2D equation of line in the form ax+by+c = 0

mpl_toolkits.mplot3d.proj3d.line2d_dist(l, p)

Distance from line to point line is a tuple of coefficients a,b,c

mpl_toolkits.mplot3d.proj3d.line2d_seg_dist(p1, p2, p0)

distance(s) from line defined by p1 - p2 to point(s) p0

p0[0] = x(s) p0[1] = y(s)

intersection point p = p1 + u*(p2-p1) and intersection point lies within segment if u is between 0 and 1

mpl_toolkits.mplot3d.proj3d.mod(v)

3d vector length

mpl_toolkits.mplot3d.proj3d.persp_transformation(zfront, zback)

mpl_toolkits.mplot3d.proj3d.proj_points(points, M)

mpl_toolkits.mplot3d.proj3d.proj_trans_clip_points(points, M)

mpl_toolkits.mplot3d.proj3d.proj_trans_points(points, M)

mpl_toolkits.mplot3d.proj3d.proj_transform(xs, ys, zs, M)

Transform the points by the projection matrix

mpl_toolkits.mplot3d.proj3d.proj_transform_clip(xs, ys, zs, M)

Transform the points by the projection matrix and return the clipping result returns txs,tys,tzs,tis

mpl_toolkits.mplot3d.proj3d.proj_transform_vec(vec, M)

mpl_toolkits.mplot3d.proj3d.proj_transform_vec_clip(vec, M)

mpl_toolkits.mplot3d.proj3d.rot_x(V, alpha)

mpl_toolkits.mplot3d.proj3d.test_lines_dists()

mpl_toolkits.mplot3d.proj3d.test_proj()

mpl_toolkits.mplot3d.proj3d.test_proj_draw_axes(M, s=1)

mpl_toolkits.mplot3d.proj3d.test_proj_make_M(E=None)

mpl_toolkits.mplot3d.proj3d.test_rot()

mpl_toolkits.mplot3d.proj3d.test_world()

mpl_toolkits.mplot3d.proj3d.transform(xs, ys, zs, M)

Transform the points by the projection matrix

mpl_toolkits.mplot3d.proj3d.vec_pad_ones(xs, ys, zs)

mpl_toolkits.mplot3d.proj3d.view_transformation(E, R, V)

mpl_toolkits.mplot3d.proj3d.world_transformation(xmin, xmax, ymin, ymax, zmin, zmax)