matplotlib

Table Of Contents

This Page

mplot3d API

mpl_toolkits.mplot3d.axes3d

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

3D axes object.

add_collection3d(col, zs=0, zdir='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
bar(left, height, zs=0, zdir='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='b')

Generate a 3D bar, or multiple bars.

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

contour(X, Y, Z, levels=10, **kwargs)

Create a 3D contour plot.

Argument Description
X, Y, Data values as numpy.arrays
Z  
levels Number of levels to use, defaults to 10. Can also be a tuple of specific levels.
extend3d Whether to extend contour in 3D (default: False)
stride Stride (step size) for extending contour

Other keyword arguments are passed on to contour()

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

Plot filled 3D contours.

X, Y, Z: data points.

Keyword arguments are passed on to contour()

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_xdata(x)
Return x string formatted. This function will use the attribute self.fmt_xdata if it is callable, else will fall back on the xaxis major formatter
format_ydata(y)
Return y string formatted. This function will use the attribute self.fmt_ydata if it is callable, else will fall back on the yaxis major formatter
format_zdata(z)
Return z string formatted. This function will use the attribute self.fmt_zdata if it is callable, else will fall back on the yaxis major formatter
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_xlim3d()
Get 3D x limits.
get_ylim3d()
Get 3D y limits.
get_zlim3d()
Get 3D z limits.
grid(on=True, **kwargs)
Set / unset 3D grid.
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()

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.

Argument Description
X, Y, Data values as numpy.arrays
Z  
rstride Array row stride (step size)
cstride Array column stride (step size)
color Color of the surface patches
cmap A colormap for the surface patches.
plot_wireframe(X, Y, Z, *args, **kwargs)

Plot a 3D wireframe.

Argument Description
X, Y, Data values as numpy.arrays
Z  
rstride Array row stride (step size)
cstride Array column stride (step size)

Keyword arguments are passed on to matplotlib.collections.LineCollection.__init__().

Returns a Line3DCollection

scatter(xs, ys, zs=0, zdir='z', *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.

Keyword arguments are passed on to scatter().

Returns a Patch3DCollection

set_xlabel(xlabel, fontdict=None, **kwargs)
Set xlabel.
set_xlim3d(*args, **kwargs)
Set 3D x limits.
set_ylabel(ylabel, fontdict=None, **kwargs)
Set ylabel.
set_ylim3d(*args, **kwargs)
Set 3D y limits.
set_zlabel(zlabel, fontdict=None, **kwargs)
Set zlabel.
set_zlim3d(*args, **kwargs)
Set 3D z limits.
text(x, y, z, s, zdir=None)
Add text to the plot.
text3D(x, y, z, s, zdir=None)
Add text to the plot.
mpl_toolkits.mplot3d.axes3d.get_test_data(delta=0.050000000000000003)
Return a tuple X, Y, Z with a test data set.
mpl_toolkits.mplot3d.axes3d.sensible_format_data(self, value)
Used to generate more comprehensible numbers in status bar

mpl_toolkits.mplot3d.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.

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

Bases: matplotlib.collections.LineCollection

A collection of 3D lines.

do_3d_projection(renderer)
Project the points according to renderer matrix.
set_segments(segments)
Set 3D segments
class mpl_toolkits.mplot3d.art3d.Patch3D(*args, **kwargs)

Bases: matplotlib.patches.Patch

3D patch object.

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

Bases: matplotlib.collections.PatchCollection

A collection of 3D patches.

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.

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.
get_vector(segments3d)
Optimize points for projection
set_verts(verts, closed=True)
Set 3D vertices.
class mpl_toolkits.mplot3d.art3d.Text3D(x=0, y=0, z=0, text='', zdir='z')

Bases: matplotlib.text.Text

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

mpl_toolkits.mplot3d.art3d.get_colors(c, num)
Stretch the color argument to provide the required number num
mpl_toolkits.mplot3d.art3d.juggle_axes(xs, ys, zs, zdir)
Reorder coordinates so that zdir
mpl_toolkits.mplot3d.art3d.line_2d_to_3d(line, zs=0, zdir='z')
Convert a 2D line to 3D.
mpl_toolkits.mplot3d.art3d.line_collection_2d_to_3d(col, zs=0, zdir='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='z')
Convert a Patch to a Patch3D object.
mpl_toolkits.mplot3d.art3d.patch_collection_2d_to_3d(col, zs=0, zdir='z')
Convert a PatchCollection to a Patch3DCollection object.
mpl_toolkits.mplot3d.art3d.path_to_3d_segment(path, zs=0, zdir='z')
Convert a path to a 3D segment.
mpl_toolkits.mplot3d.art3d.paths_to_3d_segments(paths, zs=0, zdir='z')
Convert paths from a collection object to 3D segments.
mpl_toolkits.mplot3d.art3d.poly_collection_2d_to_3d(col, zs=0, zdir='z')
Convert a PolyCollection to a Poly3DCollection object.
mpl_toolkits.mplot3d.art3d.text_2d_to_3d(obj, z=0, zdir='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

mpl_toolkits.mplot3d.proj3d

Various transforms used for by the 3D code

mpl_toolkits.mplot3d.proj3d.cross(a, b)
Cross product of two vectors A x B = <Ay*Bz - Az*By, Az*Bx - Ax*Bz, Ax*By - Ay*Bx> a x b = [a2b3 - a3b2, a3b1 - a1b3, a1b2 - a2b1]
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 segement if u is between 0 and 1

mpl_toolkits.mplot3d.proj3d.mod(v)
3d vector length
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.transform(xs, ys, zs, M)
Transform the points by the projection matrix