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.
- 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
Artist
s 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.- auto_add_to_figurebool, default: False
Prior to Matplotlib 3.4 Axes3D would add themselves to their host Figure on init. Other Axes class do not do this.
This behavior is deprecated in 3.4, the default is changed to False in 3.6. The keyword will be undocumented and a non-False value will be an error in 3.7.
- 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
{'box', 'datalim'}
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
scalar or None
(float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}
bool
{'auto', 'equal', 'equalxy', 'equalxz', 'equalyz'}
bool
unknown
unknown
unknown
Callable[[Axes, Renderer], Bbox]
bool or 'line'
3-tuple of floats or None
bool
Patch or (Path, Transform) or None
facecolor
or fccolor
bool
str
bool
object
bool
bool
unknown
None or bool or float or callable
[left, bottom, width, height] or
Bbox
{'persp', 'ortho'}
unknown
float or None
bool
(scale: float, length: float, randomness: float)
bool or None
unknown
str
bool
unknown
str
xlim
or xlim3d(bottom: float, top: float)
(bottom: float, top: float)
float greater than -0.5
unknown
unknown
unknown
unknown
str
ylim
or ylim3d(bottom: float, top: float)
(bottom: float, top: float)
float greater than -0.5
unknown
unknown
unknown
unknown
unknown
zlim
or zlim3dunknown
float greater than -0.5
float
unknown
unknown
unknown
- add_collection3d(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.
Supported are:
PolyCollection
LineCollection
PatchCollection
- apply_aspect(position=None)[source]#
Adjust the Axes for a specified data aspect ratio.
Depending on
get_adjustable
this will modify either the Axes box (position) or the view limits. In the former case,get_anchor
will affect the position.- Parameters:
- positionNone or .Bbox
If not
None
, this defines the position of the Axes within the figure as a Bbox. Seeget_position
for further details.
See also
matplotlib.axes.Axes.set_aspect
For a description of aspect ratio handling.
matplotlib.axes.Axes.set_adjustable
Set how the Axes adjusts to achieve the required aspect ratio.
matplotlib.axes.Axes.set_anchor
Set the position in case of extra space.
Notes
This is called automatically when each Axes is drawn. You may need to call it yourself if you need to update the Axes position and/or view limits before the Figure is drawn.
- autoscale(enable=True, axis='both', tight=None)[source]#
Convenience method for simple axis view autoscaling.
See
Axes.autoscale
for full documentation. Because this function applies to 3D Axes, axis can also be set to 'z', and setting axis to 'both' autoscales all three axes.
- autoscale_view(tight=None, scalex=True, scaley=True, scalez=True)[source]#
Autoscale the view limits using the data limits.
See
Axes.autoscale_view
for full documentation. Because this function applies to 3D Axes, it also takes a scalez argument.
- bar(left, height, zs=0, zdir='z', *args, data=None, **kwargs)[source]#
Add 2D bar(s).
- Parameters:
- left1D array-like
The x coordinates of the left sides of the bars.
- height1D array-like
The height of the bars.
- zsfloat or 1D array-like
Z coordinate of bars; if a single value is specified, it will be used for all bars.
- zdir{'x', 'y', 'z'}, default: 'z'
When plotting 2D data, the direction to use as z ('x', 'y' or 'z').
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.bar
.
- Returns:
- mpl_toolkits.mplot3d.art3d.Patch3DCollection
- bar3d(x, y, z, dx, dy, dz, color=None, zsort='average', shade=True, lightsource=None, *args, data=None, **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:
- x, y, zarray-like
The coordinates of the anchor point of the bars.
- dx, dy, dzfloat or array-like
The width, depth, and height of the bars, respectively.
- colorsequence of colors, optional
The color of the bars can be specified globally or individually. This parameter can be:
A single color, 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:
-Z (bottom of box)
+Z (top of box)
-Y
+Y
-X
+X
- zsortstr, optional
The z-axis sorting scheme passed onto
Poly3DCollection
- shadebool, default: True
When true, this shades the dark sides of the bars (relative to the plot's source of light).
- lightsource
LightSource
The lightsource to use when shade is True.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- **kwargs
Any additional keyword arguments are passed onto
Poly3DCollection
.
- Returns:
- collection
Poly3DCollection
A collection of three dimensional polygons representing the bars.
- collection
- can_pan()[source]#
Return whether this Axes supports the pan/zoom button functionality.
Axes3d objects do not use the pan/zoom button.
- can_zoom()[source]#
Return whether this Axes supports the zoom box button functionality.
Axes3D objects do not use the zoom box button.
- contour(X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, data=None, **kwargs)[source]#
Create a 3D contour plot.
- Parameters:
- X, Y, Zarray-like,
Input data. See
Axes.contour
for supported data shapes.- extend3dbool, default: False
Whether to extend contour in 3D.
- strideint
Step size for extending contour.
- zdir{'x', 'y', 'z'}, default: 'z'
The direction to use.
- offsetfloat, optional
If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- *args, **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.contour
.
- Returns:
- matplotlib.contour.QuadContourSet
- contour3D(X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, data=None, **kwargs)[source]#
Create a 3D contour plot.
- Parameters:
- X, Y, Zarray-like,
Input data. See
Axes.contour
for supported data shapes.- extend3dbool, default: False
Whether to extend contour in 3D.
- strideint
Step size for extending contour.
- zdir{'x', 'y', 'z'}, default: 'z'
The direction to use.
- offsetfloat, optional
If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- *args, **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.contour
.
- Returns:
- matplotlib.contour.QuadContourSet
- contourf(X, Y, Z, *args, zdir='z', offset=None, data=None, **kwargs)[source]#
Create a 3D filled contour plot.
- Parameters:
- X, Y, Zarray-like
Input data. See
Axes.contourf
for supported data shapes.- zdir{'x', 'y', 'z'}, default: 'z'
The direction to use.
- offsetfloat, optional
If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- *args, **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.contourf
.
- Returns:
- matplotlib.contour.QuadContourSet
- contourf3D(X, Y, Z, *args, zdir='z', offset=None, data=None, **kwargs)[source]#
Create a 3D filled contour plot.
- Parameters:
- X, Y, Zarray-like
Input data. See
Axes.contourf
for supported data shapes.- zdir{'x', 'y', 'z'}, default: 'z'
The direction to use.
- offsetfloat, optional
If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- *args, **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.contourf
.
- Returns:
- matplotlib.contour.QuadContourSet
- convert_zunits(z)[source]#
For artists in an Axes, if the zaxis has units support, convert z using zaxis unit type
- draw(renderer)[source]#
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (
Artist.get_visible
returns False).- Parameters:
- renderer
RendererBase
subclass.
- renderer
Notes
This method is overridden in the Artist subclasses.
- errorbar(x, y, z, zerr=None, yerr=None, xerr=None, fmt='', barsabove=False, errorevery=1, ecolor=None, elinewidth=None, capsize=None, capthick=None, xlolims=False, xuplims=False, ylolims=False, yuplims=False, zlolims=False, zuplims=False, *, data=None, **kwargs)[source]#
Plot lines and/or markers with errorbars around them.
x/y/z define the data locations, and xerr/yerr/zerr define the errorbar sizes. By default, this draws the data markers/lines as well the errorbars. Use fmt='none' to draw errorbars only.
- Parameters:
- x, y, zfloat or array-like
The data positions.
- xerr, yerr, zerrfloat or array-like, shape (N,) or (2, N), optional
The errorbar sizes:
scalar: Symmetric +/- values for all data points.
shape(N,): Symmetric +/-values for each data point.
shape(2, N): Separate - and + values for each bar. First row contains the lower errors, the second row contains the upper errors.
None: No errorbar.
Note that all error arrays should have positive values.
- fmtstr, default: ''
The format for the data points / data lines. See
plot
for details.Use 'none' (case insensitive) to plot errorbars without any data markers.
- ecolorcolor, default: None
The color of the errorbar lines. If None, use the color of the line connecting the markers.
- elinewidthfloat, default: None
The linewidth of the errorbar lines. If None, the linewidth of the current style is used.
- capsizefloat, default:
rcParams["errorbar.capsize"]
(default:0.0
) The length of the error bar caps in points.
- capthickfloat, default: None
An alias to the keyword argument markeredgewidth (a.k.a. mew). This setting is a more sensible name for the property that controls the thickness of the error bar cap in points. For backwards compatibility, if mew or markeredgewidth are given, then they will over-ride capthick. This may change in future releases.
- barsabovebool, default: False
If True, will plot the errorbars above the plot symbols. Default is below.
- xlolims, ylolims, zlolimsbool, default: False
These arguments can be used to indicate that a value gives only lower limits. In that case a caret symbol is used to indicate this. lims-arguments may be scalars, or array-likes of the same length as the errors. To use limits with inverted axes,
set_xlim
orset_ylim
must be called beforeerrorbar
. Note the tricky parameter names: setting e.g. ylolims to True means that the y-value is a lower limit of the True value, so, only an upward-pointing arrow will be drawn!- xuplims, yuplims, zuplimsbool, default: False
Same as above, but for controlling the upper limits.
- erroreveryint or (int, int), default: 1
draws error bars on a subset of the data. errorevery =N draws error bars on the points (x[::N], y[::N], z[::N]). errorevery =(start, N) draws error bars on the points (x[start::N], y[start::N], z[start::N]). e.g. errorevery=(6, 3) adds error bars to the data at (x[6], x[9], x[12], x[15], ...). Used to avoid overlapping error bars when two series share x-axis values.
- Returns:
- errlineslist
List of
Line3DCollection
instances each containing an errorbar line.- caplineslist
List of
Line3D
instances each containing a capline object.- limmarkslist
List of
Line3D
instances each containing a marker with an upper or lower limit.
- Other Parameters:
- dataindexable object, optional
If given, the following parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception):x, y, z, xerr, yerr, zerr
- **kwargs
All other keyword arguments for styling errorbar lines are passed
Line3DCollection
.
Examples
(Source code, png)
- format_coord(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(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_tightbbox(renderer=None, call_axes_locator=True, bbox_extra_artists=None, *, for_layout_only=False)[source]#
Return the tight bounding box of the Axes, including axis and their decorators (xlabel, title, etc).
Artists that have
artist.set_in_layout(False)
are not included in the bbox.- Parameters:
- renderer
RendererBase
subclass renderer that will be used to draw the figures (i.e.
fig.canvas.get_renderer()
)- bbox_extra_artistslist of
Artist
orNone
List of artists to include in the tight bounding box. If
None
(default), then all artist children of the Axes are included in the tight bounding box.- call_axes_locatorbool, default: True
If call_axes_locator is
False
, it does not call the_axes_locator
attribute, which is necessary to get the correct bounding box.call_axes_locator=False
can be used if the caller is only interested in the relative size of the tightbbox compared to the Axes bbox.- for_layout_onlydefault: False
The bounding box will not include the x-extent of the title and the xlabel, or the y-extent of the ylabel.
- renderer
- Returns:
BboxBase
Bounding box in figure pixel coordinates.
- get_xlim()[source]#
Return the x-axis view limits.
- Returns:
- left, right(float, float)
The current x-axis limits in data coordinates.
See also
Axes.set_xlim
set_xbound
,get_xbound
invert_xaxis
,xaxis_inverted
Notes
The x-axis may be inverted, in which case the left value will be greater than the right value.
- get_ylim()[source]#
Return the y-axis view limits.
- Returns:
- bottom, top(float, float)
The current y-axis limits in data coordinates.
See also
Axes.set_ylim
set_ybound
,get_ybound
invert_yaxis
,yaxis_inverted
Notes
The y-axis may be inverted, in which case the bottom value will be greater than the top value.
- get_zticklabels(minor=False, which=None)[source]#
Get the zaxis' tick labels.
- Parameters:
- minorbool
Whether to return the minor or the major ticklabels.
- whichNone, ('minor', 'major', 'both')
Overrides minor.
Selects which ticklabels to return
- Returns:
- list of
Text
- list of
- get_zticks(*, minor=False)[source]#
Return the zaxis' tick locations in data coordinates.
The locations are not clipped to the current axis limits and hence may contain locations that are not visible in the output.
- Parameters:
- minorbool, default: False
True to return the minor tick directions, False to return the major tick directions.
- Returns:
- numpy array of tick locations
- grid(visible=True, **kwargs)[source]#
Set / unset 3D grid.
Note
Currently, this function does not behave the same as
axes.Axes.grid
, but it is intended to eventually support that behavior.
- margins(*margins, x=None, y=None, z=None, tight=True)[source]#
Set or retrieve autoscaling margins.
See
Axes.margins
for full documentation. Because this function applies to 3D Axes, it also takes a z argument, and returns(xmargin, ymargin, zmargin)
.
- mouse_init(rotate_btn=1, zoom_btn=3)[source]#
Set the mouse buttons for 3D rotation and zooming.
- Parameters:
- rotate_btnint or list of int, default: 1
The mouse button or buttons to use for 3D rotation of the axes.
- zoom_btnint or list of int, default: 3
The mouse button or buttons to use to zoom the 3D axes.
- name = '3d'#
- plot(xs, ys, *args, zdir='z', **kwargs)[source]#
Plot 2D or 3D data.
- Parameters:
- xs1D array-like
x coordinates of vertices.
- ys1D array-like
y coordinates of vertices.
- zsfloat or 1D array-like
z coordinates of vertices; either one for all points or one for each point.
- zdir{'x', 'y', 'z'}, default: 'z'
When plotting 2D data, the direction to use as z ('x', 'y' or 'z').
- **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.plot
.
- plot3D(xs, ys, *args, zdir='z', **kwargs)[source]#
Plot 2D or 3D data.
- Parameters:
- xs1D array-like
x coordinates of vertices.
- ys1D array-like
y coordinates of vertices.
- zsfloat or 1D array-like
z coordinates of vertices; either one for all points or one for each point.
- zdir{'x', 'y', 'z'}, default: 'z'
When plotting 2D data, the direction to use as z ('x', 'y' or 'z').
- **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.plot
.
- plot_surface(X, Y, Z, *, 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 colormapping 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.
Note
To maximize rendering speed consider setting rstride and cstride to divisors of the number of rows minus 1 and columns minus 1 respectively. For example, given 51 rows rstride can be any of the divisors of 50.
Similarly, a setting of rstride and cstride equal to 1 (or rcount and ccount equal the number of rows and columns) can use the optimized path.
- Parameters:
- X, Y, Z2D arrays
Data values.
- rcount, ccountint
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. Defaults to 50.
- rstride, cstrideint
Downsampling stride in each direction. These arguments are mutually exclusive with rcount and ccount. If only one of rstride or cstride is set, the other defaults to 10.
'classic' mode uses a default of
rstride = cstride = 10
instead of the new default ofrcount = ccount = 50
.- colorcolor-like
Color of the surface patches.
- cmapColormap
Colormap of the surface patches.
- facecolorsarray-like of colors.
Colors of each individual patch.
- normNormalize
Normalization for the colormap.
- vmin, vmaxfloat
Bounds for the normalization.
- shadebool, default: True
Whether to shade the facecolors. Shading is always disabled when cmap is specified.
- lightsource
LightSource
The lightsource to use when shade is True.
- **kwargs
Other arguments are forwarded to
Poly3DCollection
.
- plot_trisurf(*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:
- X, Y, Zarray-like
Data values as 1D arrays.
- color
Color of the surface patches.
- cmap
A colormap for the surface patches.
- normNormalize
An instance of Normalize to map values to colors.
- vmin, vmaxfloat, default: None
Minimum and maximum value to map.
- shadebool, default: True
Whether to shade the facecolors. Shading is always disabled when cmap is specified.
- lightsource
LightSource
The lightsource to use when shade is True.
- **kwargs
All other arguments are passed on to
Poly3DCollection
Examples
(Source code, png)
(Source code, png)
- plot_wireframe(X, Y, Z, **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:
- X, Y, Z2D arrays
Data values.
- rcount, ccountint
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. Setting a count to zero causes the data to be not sampled in the corresponding direction, producing a 3D line plot rather than a wireframe plot. Defaults to 50.
- rstride, cstrideint
Downsampling stride in each direction. These arguments are mutually exclusive with rcount and ccount. If only one of rstride or cstride is set, the other defaults to 1. Setting a stride to zero causes the data to be not sampled in the corresponding direction, producing a 3D line plot rather than a wireframe plot.
'classic' mode uses a default of
rstride = cstride = 1
instead of the new default ofrcount = ccount = 50
.- **kwargs
Other arguments are forwarded to
Line3DCollection
.
- 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:
- X, Y, Zarray-like
The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
- U, V, Warray-like
The x, y and z components of the arrow vectors.
- lengthfloat, default: 1
The length of each quiver.
- arrow_length_ratiofloat, default: 0.3
The ratio of the arrow head with respect to the quiver.
- pivot{'tail', 'middle', 'tip'}, default: 'tail'
The part of the arrow that is at the grid point; the arrow rotates about this point, hence the name pivot.
- normalizebool, default: False
Whether all arrows are normalized to have the same length, or keep the lengths defined by u, v, and w.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- **kwargs
Any additional keyword arguments are delegated to
LineCollection
- quiver3D(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:
- X, Y, Zarray-like
The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
- U, V, Warray-like
The x, y and z components of the arrow vectors.
- lengthfloat, default: 1
The length of each quiver.
- arrow_length_ratiofloat, default: 0.3
The ratio of the arrow head with respect to the quiver.
- pivot{'tail', 'middle', 'tip'}, default: 'tail'
The part of the arrow that is at the grid point; the arrow rotates about this point, hence the name pivot.
- normalizebool, default: False
Whether all arrows are normalized to have the same length, or keep the lengths defined by u, v, and w.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- **kwargs
Any additional keyword arguments are delegated to
LineCollection
- scatter(xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, data=None, **kwargs)[source]#
Create a scatter plot.
- Parameters:
- xs, ysarray-like
The data positions.
- zsfloat or array-like, default: 0
The z-positions. Either an array of the same length as xs and ys or a single value to place all points in the same plane.
- zdir{'x', 'y', 'z', '-x', '-y', '-z'}, default: 'z'
The axis direction for the zs. This is useful when plotting 2D data on a 3D Axes. The data must be passed as xs, ys. Setting zdir to 'y' then plots the data to the x-z-plane.
See also Plot 2D data on 3D plot.
- sfloat or array-like, default: 20
The marker size in points**2. Either an array of the same length as xs and ys or a single value to make all markers the same size.
- ccolor, sequence, or sequence of colors, optional
The marker color. Possible values:
A single color format string.
A sequence of colors of length n.
A sequence of n numbers to be mapped to colors using cmap and norm.
A 2D array in which the rows are RGB or RGBA.
For more details see the c argument of
scatter
.- depthshadebool, default: True
Whether to shade the scatter markers to give the appearance of depth. Each call to
scatter()
will perform its depthshading independently.- dataindexable object, optional
If given, the following parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception):xs, ys, zs, s, edgecolors, c, facecolor, facecolors, color
- **kwargs
All other arguments are passed on to
scatter
.
- Returns:
- paths
PathCollection
- paths
- scatter3D(xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, data=None, **kwargs)[source]#
Create a scatter plot.
- Parameters:
- xs, ysarray-like
The data positions.
- zsfloat or array-like, default: 0
The z-positions. Either an array of the same length as xs and ys or a single value to place all points in the same plane.
- zdir{'x', 'y', 'z', '-x', '-y', '-z'}, default: 'z'
The axis direction for the zs. This is useful when plotting 2D data on a 3D Axes. The data must be passed as xs, ys. Setting zdir to 'y' then plots the data to the x-z-plane.
See also Plot 2D data on 3D plot.
- sfloat or array-like, default: 20
The marker size in points**2. Either an array of the same length as xs and ys or a single value to make all markers the same size.
- ccolor, sequence, or sequence of colors, optional
The marker color. Possible values:
A single color format string.
A sequence of colors of length n.
A sequence of n numbers to be mapped to colors using cmap and norm.
A 2D array in which the rows are RGB or RGBA.
For more details see the c argument of
scatter
.- depthshadebool, default: True
Whether to shade the scatter markers to give the appearance of depth. Each call to
scatter()
will perform its depthshading independently.- dataindexable object, optional
If given, the following parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception):xs, ys, zs, s, edgecolors, c, facecolor, facecolors, color
- **kwargs
All other arguments are passed on to
scatter
.
- Returns:
- paths
PathCollection
- paths
- set(*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, autoscalez_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, facecolor=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, proj_type=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xlim3d=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ylim3d=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zbound=<UNSET>, zlabel=<UNSET>, zlim=<UNSET>, zlim3d=<UNSET>, zmargin=<UNSET>, zorder=<UNSET>, zscale=<UNSET>, zticklabels=<UNSET>, zticks=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
{'box', 'datalim'}
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
scalar or None
(float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}
bool
{'auto', 'equal', 'equalxy', 'equalxz', 'equalyz'}
bool
unknown
unknown
unknown
Callable[[Axes, Renderer], Bbox]
bool or 'line'
3-tuple of floats or None
bool
Patch or (Path, Transform) or None
facecolor
or fccolor
bool
str
bool
object
bool
bool
unknown
None or bool or float or callable
[left, bottom, width, height] or
Bbox
{'persp', 'ortho'}
unknown
float or None
bool
(scale: float, length: float, randomness: float)
bool or None
unknown
str
bool
unknown
str
(bottom: float, top: float)
(bottom: float, top: float)
float greater than -0.5
unknown
unknown
unknown
unknown
str
(bottom: float, top: float)
(bottom: float, top: float)
float greater than -0.5
unknown
unknown
unknown
unknown
unknown
unknown
unknown
float greater than -0.5
float
unknown
unknown
unknown
- set_aspect(aspect, adjustable=None, anchor=None, share=False)[source]#
Set the aspect ratios.
- Parameters:
- aspect{'auto', 'equal', 'equalxy', 'equalxz', 'equalyz'}
Possible values:
value
description
'auto'
automatic; fill the position rectangle with data.
'equal'
adapt all the axes to have equal aspect ratios.
'equalxy'
adapt the x and y axes to have equal aspect ratios.
'equalxz'
adapt the x and z axes to have equal aspect ratios.
'equalyz'
adapt the y and z axes to have equal aspect ratios.
- adjustableNone
Currently ignored by Axes3D
If not None, this defines which parameter will be adjusted to meet the required aspect. See
set_adjustable
for further details.- anchorNone or str or 2-tuple of float, optional
If not None, this defines where the Axes will be drawn if there is extra space due to aspect constraints. The most common way to to specify the anchor are abbreviations of cardinal directions:
value
description
'C'
centered
'SW'
lower left corner
'S'
middle of bottom edge
'SE'
lower right corner
etc.
See
set_anchor
for further details.- sharebool, default: False
If
True
, apply the settings to all shared Axes.
- set_autoscalez_on(b)[source]#
Set whether the zaxis is autoscaled when drawing or by
Axes.autoscale_view
.- Parameters:
- bbool
- set_axis_off()[source]#
Turn the x- and y-axis off.
This affects the axis lines, ticks, ticklabels, grid and axis labels.
- set_axis_on()[source]#
Turn the x- and y-axis on.
This affects the axis lines, ticks, ticklabels, grid and axis labels.
- set_box_aspect(aspect, *, zoom=1)[source]#
Set the Axes box aspect.
The box aspect is the ratio of height to width in display units for each face of the box when viewed perpendicular to that face. This is not to be confused with the data aspect (which for Axes3D is always 'auto'). The default ratios are 4:4:3 (x:y:z).
To simulate having equal aspect in data space, set the box aspect to match your data range in each dimension.
zoom controls the overall size of the Axes3D in the figure.
- Parameters:
- aspect3-tuple of floats or 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).
- zoomfloat, default: 1
Control overall size of the Axes3D in the figure. Must be > 0.
- set_proj_type(proj_type, focal_length=None)[source]#
Set the projection type.
- Parameters:
- proj_type{'persp', 'ortho'}
The projection type.
- 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. The focal length can be computed from a desired Field Of View via the equation: focal_length = 1/tan(FOV/2)
- set_title(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:
- labelstr
Text to use for the title
- fontdictdict
A dictionary controlling the appearance of the title text, the default fontdict is:
{'fontsize': rcParams['axes.titlesize'], 'fontweight': rcParams['axes.titleweight'], 'color': rcParams['axes.titlecolor'], 'verticalalignment': 'baseline', 'horizontalalignment': loc}
- loc{'center', 'left', 'right'}, default:
rcParams["axes.titlelocation"]
(default:'center'
) Which title to set.
- yfloat, default:
rcParams["axes.titley"]
(default:None
) Vertical Axes location for the title (1.0 is the top). If None (the default) and
rcParams["axes.titley"]
(default:None
) is also None, y is determined automatically to avoid decorators on the Axes.- padfloat, default:
rcParams["axes.titlepad"]
(default:6.0
) The offset of the title from the top of the Axes, in points.
- Returns:
Text
The matplotlib text instance representing the title
- Other Parameters:
- set_xlim3d(left=None, right=None, *, emit=True, auto=False, xmin=None, xmax=None)[source]#
Set the x-axis view limits.
- Parameters:
- leftfloat, optional
The left xlim in data coordinates. Passing None leaves the limit unchanged.
The left and right xlims may also be passed as the tuple (left, right) as the first positional argument (or as the left keyword argument).
- rightfloat, optional
The right xlim in data coordinates. Passing None leaves the limit unchanged.
- emitbool, default: True
Whether to notify observers of limit change.
- autobool or None, default: False
Whether to turn on autoscaling of the x-axis. True turns on, False turns off, None leaves unchanged.
- xmin, xmaxfloat, optional
They are equivalent to left and right respectively, and it is an error to pass both xmin and left or xmax and right.
- Returns:
- left, right(float, float)
The new x-axis limits in data coordinates.
See also
get_xlim
set_xbound
,get_xbound
invert_xaxis
,xaxis_inverted
Notes
The left value may be greater than the right value, in which case the x-axis values will decrease from left to right.
Examples
>>> set_xlim(left, right) >>> set_xlim((left, right)) >>> left, right = set_xlim(left, right)
One limit may be left unchanged.
>>> set_xlim(right=right_lim)
Limits may be passed in reverse order to flip the direction of the x-axis. For example, suppose x represents the number of years before present. The x-axis limits might be set like the following so 5000 years ago is on the left of the plot and the present is on the right.
>>> set_xlim(5000, 0)
- set_xscale(value, **kwargs)[source]#
Set the x-axis scale.
- Parameters:
- value{"linear"}
The axis scale type to apply. 3D axes currently only support linear scales; other scales yield nonsensical results.
- **kwargs
Keyword arguments are nominally forwarded to the scale class, but none of them is applicable for linear scales.
- set_ylim3d(bottom=None, top=None, *, emit=True, auto=False, ymin=None, ymax=None)[source]#
Set the y-axis view limits.
- Parameters:
- bottomfloat, optional
The bottom ylim in data coordinates. Passing None leaves the limit unchanged.
The bottom and top ylims may also be passed as the tuple (bottom, top) as the first positional argument (or as the bottom keyword argument).
- topfloat, optional
The top ylim in data coordinates. Passing None leaves the limit unchanged.
- emitbool, default: True
Whether to notify observers of limit change.
- autobool or None, default: False
Whether to turn on autoscaling of the y-axis. True turns on, False turns off, None leaves unchanged.
- ymin, ymaxfloat, optional
They are equivalent to bottom and top respectively, and it is an error to pass both ymin and bottom or ymax and top.
- Returns:
- bottom, top(float, float)
The new y-axis limits in data coordinates.
See also
get_ylim
set_ybound
,get_ybound
invert_yaxis
,yaxis_inverted
Notes
The bottom value may be greater than the top value, in which case the y-axis values will decrease from bottom to top.
Examples
>>> set_ylim(bottom, top) >>> set_ylim((bottom, top)) >>> bottom, top = set_ylim(bottom, top)
One limit may be left unchanged.
>>> set_ylim(top=top_lim)
Limits may be passed in reverse order to flip the direction of the y-axis. For example, suppose
y
represents depth of the ocean in m. The y-axis limits might be set like the following so 5000 m depth is at the bottom of the plot and the surface, 0 m, is at the top.>>> set_ylim(5000, 0)
- set_yscale(value, **kwargs)[source]#
Set the y-axis scale.
- Parameters:
- value{"linear"}
The axis scale type to apply. 3D axes currently only support linear scales; other scales yield nonsensical results.
- **kwargs
Keyword arguments are nominally forwarded to the scale class, but none of them is applicable for linear scales.
- set_zbound(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 autoscaling setting (
get_autoscalez_on()
).
- set_zlabel(zlabel, fontdict=None, labelpad=None, **kwargs)[source]#
Set zlabel. See doc for
set_ylabel
for description.
- set_zlim(bottom=None, top=None, *, emit=True, auto=False, zmin=None, zmax=None)[source]#
Set 3D z limits.
See
Axes.set_ylim
for full documentation
- set_zlim3d(bottom=None, top=None, *, emit=True, auto=False, zmin=None, zmax=None)[source]#
Alias for
set_zlim
.
- set_zmargin(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. If m is negative, this will clip the data range instead of expanding it.
For example, if your data is in the range [0, 2], a margin of 0.1 will result in a range [-0.2, 2.2]; a margin of -0.1 will result in a range of [0.2, 1.8].
- Parameters:
- mfloat greater than -0.5
- set_zscale(value, **kwargs)[source]#
Set the z-axis scale.
- Parameters:
- value{"linear"}
The axis scale type to apply. 3D axes currently only support linear scales; other scales yield nonsensical results.
- **kwargs
Keyword arguments are nominally forwarded to the scale class, but none of them is applicable for linear scales.
- set_zticklabels(labels, *, fontdict=None, minor=False, **kwargs)[source]#
Set the zaxis' labels with list of string labels.
Warning
This method should only be used after fixing the tick positions using
Axes3D.set_zticks
. Otherwise, the labels may end up in unexpected positions.- Parameters:
- labelslist of str
The label texts.
- fontdictdict, optional
A dictionary controlling the appearance of the ticklabels. The default fontdict is:
{'fontsize': rcParams['axes.titlesize'], 'fontweight': rcParams['axes.titleweight'], 'verticalalignment': 'baseline', 'horizontalalignment': loc}
- minorbool, default: False
Whether to set the minor ticklabels rather than the major ones.
- Returns:
- list of
Text
The labels.
- list of
- Other Parameters:
- **kwargs
Text
properties.
- **kwargs
- set_zticks(ticks, labels=None, *, minor=False, **kwargs)[source]#
Set the zaxis' tick locations and optionally labels.
If necessary, the view limits of the Axis are expanded so that all given ticks are visible.
- Parameters:
- tickslist of floats
List of tick locations. The axis
Locator
is replaced by aFixedLocator
.Some tick formatters will not label arbitrary tick positions; e.g. log formatters only label decade ticks by default. In such a case you can set a formatter explicitly on the axis using
Axis.set_major_formatter
or provide formatted labels yourself.- labelslist of str, optional
List of tick labels. If not set, the labels are generated with the axis tick
Formatter
.- minorbool, default: False
If
False
, set the major ticks; ifTrue
, the minor ticks.- **kwargs
Text
properties for the labels. These take effect only if you pass labels. In other cases, please usetick_params
.
Notes
The mandatory expansion of the view limits is an intentional design choice to prevent the surprise of a non-visible tick. If you need other limits, you should set the limits explicitly after setting the ticks.
Share the z-axis with other.
This is equivalent to passing
sharex=other
when constructing the Axes, and cannot be used if the z-axis is already being shared with another Axes.
- stem(x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-', bottom=0, label=None, orientation='z', data=None)[source]#
Create a 3D stem plot.
A stem plot draws lines perpendicular to a baseline, and places markers at the heads. By default, the baseline is defined by x and y, and stems are drawn vertically from bottom to z.
- Parameters:
- x, y, zarray-like
The positions of the heads of the stems. The stems are drawn along the orientation-direction from the baseline at bottom (in the orientation-coordinate) to the heads. By default, the x and y positions are used for the baseline and z for the head position, but this can be changed by orientation.
- linefmtstr, default: 'C0-'
A string defining the properties of the vertical lines. Usually, this will be a color or a color and a linestyle:
Character
Line Style
'-'
solid line
'--'
dashed line
'-.'
dash-dot line
':'
dotted line
Note: While it is technically possible to specify valid formats other than color or color and linestyle (e.g. 'rx' or '-.'), this is beyond the intention of the method and will most likely not result in a reasonable plot.
- markerfmtstr, default: 'C0o'
A string defining the properties of the markers at the stem heads.
- basefmtstr, default: 'C3-'
A format string defining the properties of the baseline.
- bottomfloat, default: 0
The position of the baseline, in orientation-coordinates.
- labelstr, default: None
The label to use for the stems in legends.
- orientation{'x', 'y', 'z'}, default: 'z'
The direction along which stems are drawn.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).
- Returns:
StemContainer
The container may be treated like a tuple (markerline, stemlines, baseline)
Examples
(Source code, png)
(png)
(png)
- stem3D(x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-', bottom=0, label=None, orientation='z', data=None)[source]#
Create a 3D stem plot.
A stem plot draws lines perpendicular to a baseline, and places markers at the heads. By default, the baseline is defined by x and y, and stems are drawn vertically from bottom to z.
- Parameters:
- x, y, zarray-like
The positions of the heads of the stems. The stems are drawn along the orientation-direction from the baseline at bottom (in the orientation-coordinate) to the heads. By default, the x and y positions are used for the baseline and z for the head position, but this can be changed by orientation.
- linefmtstr, default: 'C0-'
A string defining the properties of the vertical lines. Usually, this will be a color or a color and a linestyle:
Character
Line Style
'-'
solid line
'--'
dashed line
'-.'
dash-dot line
':'
dotted line
Note: While it is technically possible to specify valid formats other than color or color and linestyle (e.g. 'rx' or '-.'), this is beyond the intention of the method and will most likely not result in a reasonable plot.
- markerfmtstr, default: 'C0o'
A string defining the properties of the markers at the stem heads.
- basefmtstr, default: 'C3-'
A format string defining the properties of the baseline.
- bottomfloat, default: 0
The position of the baseline, in orientation-coordinates.
- labelstr, default: None
The label to use for the stems in legends.
- orientation{'x', 'y', 'z'}, default: 'z'
The direction along which stems are drawn.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).
- Returns:
StemContainer
The container may be treated like a tuple (markerline, stemlines, baseline)
Examples
(Source code, png)
(png)
(png)
- text(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(x, y, s, fontdict=None, **kwargs)[source]#
Add text to the Axes.
Add the text s to the Axes at location x, y in data coordinates.
- Parameters:
- x, yfloat
The position to place the text. By default, this is in data coordinates. The coordinate system can be changed using the transform parameter.
- sstr
The text.
- fontdictdict, default: None
A dictionary to override the default text properties. If fontdict is None, the defaults are determined by
rcParams
.
- Returns:
- Other Parameters:
- **kwargs
Text
properties. Other miscellaneous text parameters.
Property
Description
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
scalar or None
bool
color
dict with properties for
patches.FancyBboxPatch
unknown
unknown
unknown
color
or ccolor
fontfamily
or family{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties
or font or font_propertiesfontsize
or sizefloat or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch
or stretch{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle
or style{'normal', 'italic', 'oblique'}
fontvariant
or variant{'normal', 'small-caps'}
fontweight
or weight{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
str
horizontalalignment
or ha{'left', 'center', 'right'}
bool
object
float (multiple of font size)
str
bool
multialignment
or ma{'left', 'right', 'center'}
bool
None or bool or float or callable
(float, float)
bool
float or {'vertical', 'horizontal'}
{None, 'default', 'anchor'}
(scale: float, length: float, randomness: float)
bool or None
object
bool
str
bool or None
verticalalignment
or va{'bottom', 'baseline', 'center', 'center_baseline', 'top'}
bool
bool
float
float
float
- **kwargs
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)[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.
- tick_params(axis='both', **kwargs)[source]#
Convenience method for changing the appearance of ticks and tick labels.
See
Axes.tick_params
for full documentation. Because this function applies to 3D Axes, axis can also be set to 'z', and setting axis to 'both' autoscales all three axes.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
Axes3D currently ignores some of these settings.
- tricontour(*args, extend3d=False, stride=5, zdir='z', offset=None, data=None, **kwargs)[source]#
Create a 3D contour plot.
Note
This method currently produces incorrect output due to a longstanding bug in 3D PolyCollection rendering.
- Parameters:
- X, Y, Zarray-like
Input data. See
Axes.tricontour
for supported data shapes.- extend3dbool, default: False
Whether to extend contour in 3D.
- strideint
Step size for extending contour.
- zdir{'x', 'y', 'z'}, default: 'z'
The direction to use.
- offsetfloat, optional
If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- *args, **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.tricontour
.
- Returns:
- matplotlib.tri.tricontour.TriContourSet
- tricontourf(*args, zdir='z', offset=None, data=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:
- X, Y, Zarray-like
Input data. See
Axes.tricontourf
for supported data shapes.- zdir{'x', 'y', 'z'}, default: 'z'
The direction to use.
- offsetfloat, optional
If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which is interpreted asdata[s]
(unless this raises an exception).- *args, **kwargs
Other arguments are forwarded to
matplotlib.axes.Axes.tricontourf
.
- Returns:
- matplotlib.tri.tricontour.TriContourSet
- update_datalim(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:
- xys2D array-like
The points to include in the data limits Bbox. This can be either a list of (x, y) tuples or a Nx2 array.
- updatex, updateybool, default: True
Whether to update the x/y limits.
- view_init(elev=None, azim=None, roll=None, vertical_axis='z')[source]#
Set the elevation and azimuth of the axes in degrees (not radians).
This can be used to rotate the axes programmatically.
To look normal to the primary planes, the following elevation and azimuth angles can be used. A roll angle of 0, 90, 180, or 270 deg will rotate these views while keeping the axes at right angles.
view plane
elev
azim
XY
90
-90
XZ
0
-90
YZ
0
0
-XY
-90
90
-XZ
0
90
-YZ
0
180
- Parameters:
- elevfloat, default: None
The elevation angle in degrees rotates the camera above the plane pierced by the vertical axis, with a positive angle corresponding to a location above that plane. For example, with the default vertical axis of 'z', the elevation defines the angle of the camera location above the x-y plane. If None, then the initial value as specified in the
Axes3D
constructor is used.- azimfloat, default: None
The azimuthal angle in degrees rotates the camera about the vertical axis, with a positive angle corresponding to a right-handed rotation. For example, with the default vertical axis of 'z', a positive azimuth rotates the camera about the origin from its location along the +x axis towards the +y axis. If None, then the initial value as specified in the
Axes3D
constructor is used.- rollfloat, default: None
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. If None, then the initial value as specified in the
Axes3D
constructor is used.- vertical_axis{"z", "x", "y"}, default: "z"
The axis to align vertically. azim rotates about this axis.
- 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.- Parameters:
- filled3D np.array of bool
A 3D array of values, with truthy values indicating which voxels to fill
- x, y, z3D np.array, optional
The coordinates of the corners of the voxels. This should broadcast to a shape one larger in every dimension than the shape of filled. These can be used to plot non-cubic voxels.
If not specified, defaults to increasing integers along each axis, like those returned by
indices()
. As indicated by the/
in the function signature, these arguments can only be passed positionally.- facecolors, edgecolorsarray-like, optional
The color to draw the faces and edges of the voxels. Can only be passed as keyword arguments. These parameters can be:
A single color value, to color all voxels the same color. This can be either a string, or a 1D rgb/rgba array
None
, the default, to use a single color for the faces, and the style default for the edges.A 3D ndarray of color names, with each item the color for the corresponding voxel. The size must match the voxels.
A 4D ndarray of rgb/rgba data, with the components along the last axis.
- shadebool, default: True
Whether to shade the facecolors.
- lightsource
LightSource
The lightsource to use when shade is True.
- **kwargs
Additional keyword arguments to pass onto
Poly3DCollection
.
- Returns:
- facesdict
A dictionary indexed by coordinate, where
faces[i, j, k]
is aPoly3DCollection
of the faces drawn for the voxelfilled[i, j, k]
. If no faces were drawn for a given voxel, either because it was not asked to be drawn, or it is fully occluded, then(i, j, k) not in faces
.
Examples
(Source code, png)
(Source code, png)
(Source code, png)
(Source code, png)
- zaxis_date(tz=None)[source]#
Set up axis ticks and labels to treat data along the zaxis as dates.
- Parameters:
- tzstr or
datetime.tzinfo
, default:rcParams["timezone"]
(default:'UTC'
) The timezone used to create date labels.
- tzstr or
Notes
This function is merely provided for completeness, but 3D axes do not support dates for ticks, and so this may not work as expected.