atomsmltr.utils.plotter package#

The atomsmltr.utils.plotter subpackage defines the Plottable class.

See also

atomsmltr.utils.plotter.plotter

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

Bases: Axes

3D Axes object.

Note

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

add_collection3d(col, zs=0, zdir='z', autolim=True, *, axlim_clip=False)[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, zs and zdir.

Supported 2D collection types are:

.PolyCollection
.LineCollection
.PatchCollection (currently not supporting autolim)

Parameters:

col (.Collection) – A 2D collection object.
zs (float or array-like, default: 0) – The z-positions to be used for the 2D objects.
zdir ({'x', 'y', 'z'}, default: 'z') – The direction to use for the z-positions.
autolim (bool, default: True) – Whether to update the data limits.
axlim_clip (bool, default: False) –
Whether to hide the scatter points outside the axes view limits.

Added in version 3.10.

annotate3D(text, xyz, *args, **kwargs)#: Add anotation text to an Axes3d instance.

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, ~matplotlib.axes.Axes.get_anchor will affect the position.

Parameters:

position (None or .Bbox) –

Note

This parameter exists for historic reasons and is considered internal. End users should not use it.

If not None, this defines the position of the Axes within the figure as a Bbox. See ~.Axes.get_position for further details.

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.

An alternative with a broader scope is .Figure.draw_without_rendering, which updates all stale components of a figure, not only the positioning / view limits of a single Axes.

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.
matplotlib.figure.Figure.draw_without_rendering: Update all stale components of a figure.

Examples

A typical usage example would be the following. ~.Axes.imshow sets the aspect to 1, but adapting the Axes position and extent to reflect this is deferred until rendering for performance reasons. If you want to know the Axes size before, you need to call .apply_aspect to get the correct values.

>>> fig, ax = plt.subplots()
>>> ax.imshow(np.zeros((3, 3)))
>>> ax.bbox.width, ax.bbox.height
(496.0, 369.59999999999997)
>>> ax.apply_aspect()
>>> ax.bbox.width, ax.bbox.height
(369.59999999999997, 369.59999999999997)

arrow3D(x, y, z, dx, dy, dz, *args, **kwargs)#: Add an 3d arrow to an Axes3D instance.

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, axlim_clip=False, data=None, **kwargs)[source]#

Add 2D bar(s).

Parameters:

left (1D array-like) – The x coordinates of the left sides of the bars.
height (1D array-like) – The height of the bars.
zs (float or 1D array-like, default: 0) – 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’).
axlim_clip (bool, default: False) –
Whether to hide bars with points outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
**kwargs – Other keyword arguments are forwarded to matplotlib.axes.Axes.bar.

Return type:

mpl_toolkits.mplot3d.art3d.Patch3DCollection

bar3d(x, y, z, dx, dy, dz, color=None, zsort='average', shade=True, lightsource=None, *args, axlim_clip=False, 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 (array-like) – The coordinates of the anchor point of the bars.
y (array-like) – The coordinates of the anchor point of the bars.
z (array-like) – The coordinates of the anchor point of the bars.
dx (float or array-like) – The width, depth, and height of the bars, respectively.
dy (float or array-like) – The width, depth, and height of the bars, respectively.
dz (float or array-like) – The width, depth, and height of the bars, respectively.
color (sequence 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:
1. -Z (bottom of box)
2. +Z (top of box)
3. -Y
4. +Y
5. -X
6. +X
zsort ({'average', 'min', 'max'}, default: 'average') – The z-axis sorting scheme passed onto ~.art3d.Poly3DCollection
shade (bool, default: True) – When true, this shades the dark sides of the bars (relative to the plot’s source of light).
lightsource (~matplotlib.colors.LightSource, optional) – The lightsource to use when shade is True.
axlim_clip (bool, default: False) –
Whether to hide the bars with points outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
**kwargs – Any additional keyword arguments are passed onto ~.art3d.Poly3DCollection.

Returns:

collection – A collection of three-dimensional polygons representing the bars.

Return type:

~.art3d.Poly3DCollection

can_pan()[source]#: Return whether this Axes supports any pan/zoom button functionality.

can_zoom()[source]#: Return whether this Axes supports the zoom box button functionality.

clabel(*args, **kwargs)[source]#: Currently not implemented for 3D Axes, and returns None.

clear()[source]#: Clear the Axes.

contour(X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, axlim_clip=False, data=None, **kwargs)[source]#

Create a 3D contour plot.

Parameters:

X (array-like,) – Input data. See .Axes.contour for supported data shapes.
Y (array-like,) – Input data. See .Axes.contour for supported data shapes.
Z (array-like,) – Input data. See .Axes.contour for supported data shapes.
extend3d (bool, default: False) – Whether to extend contour in 3D.
stride (int, default: 5) – Step size for extending contour.
zdir ({'x', 'y', 'z'}, default: 'z') – The direction to use.
offset (float, optional) – If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
axlim_clip (bool, default: False) –
Whether to hide lines with a vertex outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
*args – Other arguments are forwarded to matplotlib.axes.Axes.contour.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.contour.

Return type:

matplotlib.contour.QuadContourSet

contour3D(X, Y, Z, *args, extend3d=False, stride=5, zdir='z', offset=None, axlim_clip=False, data=None, **kwargs)#

Create a 3D contour plot.

Parameters:

X (array-like,) – Input data. See .Axes.contour for supported data shapes.
Y (array-like,) – Input data. See .Axes.contour for supported data shapes.
Z (array-like,) – Input data. See .Axes.contour for supported data shapes.
extend3d (bool, default: False) – Whether to extend contour in 3D.
stride (int, default: 5) – Step size for extending contour.
zdir ({'x', 'y', 'z'}, default: 'z') – The direction to use.
offset (float, optional) – If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
axlim_clip (bool, default: False) –
Whether to hide lines with a vertex outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
*args – Other arguments are forwarded to matplotlib.axes.Axes.contour.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.contour.

Return type:

matplotlib.contour.QuadContourSet

contourf(X, Y, Z, *args, zdir='z', offset=None, axlim_clip=False, data=None, **kwargs)[source]#

Create a 3D filled contour plot.

Parameters:

X (array-like) – Input data. See .Axes.contourf for supported data shapes.
Y (array-like) – Input data. See .Axes.contourf for supported data shapes.
Z (array-like) – Input data. See .Axes.contourf for supported data shapes.
zdir ({'x', 'y', 'z'}, default: 'z') – The direction to use.
offset (float, optional) – If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
axlim_clip (bool, default: False) –
Whether to hide lines with a vertex outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
*args – Other arguments are forwarded to matplotlib.axes.Axes.contourf.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.contourf.

Return type:

matplotlib.contour.QuadContourSet

contourf3D(X, Y, Z, *args, zdir='z', offset=None, axlim_clip=False, data=None, **kwargs)#

Create a 3D filled contour plot.

Parameters:

X (array-like) – Input data. See .Axes.contourf for supported data shapes.
Y (array-like) – Input data. See .Axes.contourf for supported data shapes.
Z (array-like) – Input data. See .Axes.contourf for supported data shapes.
zdir ({'x', 'y', 'z'}, default: 'z') – The direction to use.
offset (float, optional) – If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
axlim_clip (bool, default: False) –
Whether to hide lines with a vertex outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
*args – Other arguments are forwarded to matplotlib.axes.Axes.contourf.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.contourf.

Return type:

matplotlib.contour.QuadContourSet

convert_zunits(z)[source]#: For artists in an Axes, if the zaxis has units support, convert z using zaxis unit type

disable_mouse_rotation()[source]#: Disable mouse buttons for 3D rotation, panning, and zooming.

drag_pan(button, key, x, y)[source]#

Called when the mouse moves during a pan operation.

Parameters:

button (.MouseButton) – The pressed mouse button.
key (str or None) – The pressed key, if any.
x (float) – The mouse coordinates in display coords.
y (float) – The mouse coordinates in display coords.

Notes

This is intended to be overridden by new projection types.

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 (~matplotlib.backend_bases.RendererBase subclass.)

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, axlim_clip=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 (float or array-like) – The data positions.
y (float or array-like) – The data positions.
z (float or array-like) – The data positions.
xerr (float 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.
yerr (float 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.
zerr (float 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.
fmt (str, default: '') –
The format for the data points / data lines. See .plot for details.

Use ‘none’ (case-insensitive) to plot errorbars without any data markers.
ecolor (:mpltype:`color`, default: None) – The color of the errorbar lines. If None, use the color of the line connecting the markers.
elinewidth (float, default: None) – The linewidth of the errorbar lines. If None, the linewidth of the current style is used.
capsize (float, default: :rc:`errorbar.capsize`) – The length of the error bar caps in points.
capthick (float, 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.
barsabove (bool, default: False) – If True, will plot the errorbars above the plot symbols. Default is below.
xlolims (bool, 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, ~.set_ylim, or ~.set_zlim must be called before errorbar. 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!
ylolims (bool, 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, ~.set_ylim, or ~.set_zlim must be called before errorbar. 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!
zlolims (bool, 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, ~.set_ylim, or ~.set_zlim must be called before errorbar. 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 (bool, default: False) – Same as above, but for controlling the upper limits.
yuplims (bool, default: False) – Same as above, but for controlling the upper limits.
zuplims (bool, default: False) – Same as above, but for controlling the upper limits.
errorevery (int 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.
axlim_clip (bool, default: False) –
Whether to hide error bars that are outside the axes limits.

Added in version 3.10.
data (indexable object, optional) –
If given, the following parameters also accept a string s, which is interpreted as data[s] if s is a key in data:

x, y, z, xerr, yerr, zerr
**kwargs – All other keyword arguments for styling errorbar lines are passed ~mpl_toolkits.mplot3d.art3d.Line3DCollection.

Returns:

errlines (list) – List of ~mpl_toolkits.mplot3d.art3d.Line3DCollection instances each containing an errorbar line.
caplines (list) – List of ~mpl_toolkits.mplot3d.art3d.Line3D instances each containing a capline object.
limmarks (list) – List of ~mpl_toolkits.mplot3d.art3d.Line3D instances each containing a marker with an upper or lower limit.

Examples

fill_between(x1, y1, z1, x2, y2, z2, *, where=None, mode='auto', facecolors=None, shade=None, axlim_clip=False, **kwargs)[source]#

Fill the area between two 3D curves.

The curves are defined by the points (x1, y1, z1) and (x2, y2, z2). This creates one or multiple quadrangle polygons that are filled. All points must be the same length N, or a single value to be used for all points.

Parameters:

x1 (float or 1D array-like) – x, y, and z coordinates of vertices for 1st line.
y1 (float or 1D array-like) – x, y, and z coordinates of vertices for 1st line.
z1 (float or 1D array-like) – x, y, and z coordinates of vertices for 1st line.
x2 (float or 1D array-like) – x, y, and z coordinates of vertices for 2nd line.
y2 (float or 1D array-like) – x, y, and z coordinates of vertices for 2nd line.
z2 (float or 1D array-like) – x, y, and z coordinates of vertices for 2nd line.
where (array of bool (length N), optional) – Define where to exclude some regions from being filled. The filled regions are defined by the coordinates pts[where], for all x, y, and z pts. More precisely, fill between pts[i] and pts[i+1] if where[i] and where[i+1]. Note that this definition implies that an isolated True value between two False values in where will not result in filling. Both sides of the True position remain unfilled due to the adjacent False values.
mode ({'quad', 'polygon', 'auto'}, default: 'auto') –
The fill mode. One of:
- ’quad’: A separate quadrilateral polygon is created for each pair of subsequent points in the two lines.
- ’polygon’: The two lines are connected to form a single polygon. This is faster and can render more cleanly for simple shapes (e.g. for filling between two lines that lie within a plane).
- ’auto’: If the points all lie on the same 3D plane, ‘polygon’ is used. Otherwise, ‘quad’ is used.
facecolors (list of :mpltype:`color`, default: None) – Colors of each individual patch, or a single color to be used for all patches.
shade (bool, default: None) – Whether to shade the facecolors. If None, then defaults to True for ‘quad’ mode and False for ‘polygon’ mode.
axlim_clip (bool, default: False) –
Whether to hide data that is outside the axes view limits.

Added in version 3.10.
**kwargs – All other keyword arguments are passed on to .Poly3DCollection.

Returns:

A .Poly3DCollection containing the plotted polygons.

Return type:

.Poly3DCollection

format_coord(xv, yv, renderer=None)[source]#: Return a string giving the current view rotation angles, or the x, y, z coordinates of the point on the nearest axis pane underneath the mouse cursor, depending on the mouse button pressed.

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_autoscalez_on()#: Return whether the zaxis is autoscaled.

get_proj()[source]#: Create the projection matrix from the current viewing position.

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_artists (list of .Artist or None) – 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_locator (bool, 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_only (default: False) – The bounding box will not include the x-extent of the title and the xlabel, or the y-extent of the ylabel.

Returns:

Bounding box in figure pixel coordinates.

Return type:

.BboxBase

See also

matplotlib.axes.Axes.get_window_extent, matplotlib.axis.Axis.get_tightbbox, matplotlib.spines.Spine.get_window_extent

get_w_lims()[source]#: Get 3D world limits.

get_xlim()[source]#

Return the x-axis view limits.

Returns:: left, right – The current x-axis limits in data coordinates.
Return type:: (float, float)

See also

Axes.set_xlim, Axes.set_xbound, Axes.get_xbound, Axes.invert_xaxis, Axes.xaxis_inverted

Notes

The x-axis may be inverted, in which case the left value will be greater than the right value.

get_xlim3d()#: Alias for get_xlim.

get_ylim()[source]#

Return the y-axis view limits.

Returns:: bottom, top – The current y-axis limits in data coordinates.
Return type:: (float, float)

See also

Axes.set_ylim, Axes.set_ybound, Axes.get_ybound, Axes.invert_yaxis, Axes.yaxis_inverted

Notes

The y-axis may be inverted, in which case the bottom value will be greater than the top value.

get_ylim3d()#: Alias for get_ylim.

get_zaxis()[source]#: Return the ZAxis (~.axis3d.Axis) instance.

get_zbound()[source]#: Return the lower and upper z-axis bounds, in increasing order.

See also

set_zbound, get_zlim, set_zlim, invert_zaxis, zaxis_inverted

get_zgridlines()#: Return the zaxis’ grid lines as a list of .Line2Ds.

get_zlabel()[source]#: Get the z-label text string.

get_zlim()[source]#

Return the 3D z-axis view limits.

Returns:: left, right – The current z-axis limits in data coordinates.
Return type:: (float, float)

Notes

The z-axis may be inverted, in which case the left value will be greater than the right value.

get_zlim3d()#: Alias for get_zlim.

get_zmajorticklabels()#: Return the zaxis’ major tick labels, as a list of ~.text.Text.

get_zmargin()[source]#

Retrieve autoscaling margin of the z-axis.

Added in version 3.9.

Returns:: zmargin
Return type:: float

See also

mpl_toolkits.mplot3d.axes3d.Axes3D.set_zmargin

get_zminorticklabels()#: Return the zaxis’ minor tick labels, as a list of ~.text.Text.

get_zscale()#: Return the zaxis’ scale (as a str).

get_zticklabels(minor=False, which=None)#

Get the zaxis’ tick labels.

Parameters:

minor (bool) – Whether to return the minor or the major ticklabels.
which (None, ('minor', 'major', 'both')) –
Overrides minor.

Selects which ticklabels to return

Return type:

list of ~matplotlib.text.Text

get_zticklines(minor=False)#: Return the zaxis’ tick lines as a list of .Line2Ds.

get_zticks(*, minor=False)#

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:: minor (bool, default: False) – True to return the minor tick directions, False to return the major tick directions.
Return type:: 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.

invert_zaxis()[source]#: Invert the z-axis.

See also

zaxis_inverted, get_zlim, set_zlim, get_zbound, set_zbound

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, pan_btn=2, zoom_btn=3)[source]#

Set the mouse buttons for 3D rotation and zooming.

Parameters:

rotate_btn (int or list of int, default: 1) – The mouse button or buttons to use for 3D rotation of the Axes.
pan_btn (int or list of int, default: 2) – The mouse button or buttons to use to pan the 3D Axes.
zoom_btn (int or list of int, default: 3) – The mouse button or buttons to use to zoom the 3D Axes.

plot(xs, ys, *args, zdir='z', axlim_clip=False, **kwargs)[source]#

Plot 2D or 3D data.

Parameters:

xs (1D array-like) – x coordinates of vertices.
ys (1D array-like) – y coordinates of vertices.
zs (float 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.
axlim_clip (bool, default: False) –
Whether to hide data that is outside the axes view limits.

Added in version 3.10.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.plot.

plot3D(xs, ys, *args, zdir='z', axlim_clip=False, **kwargs)#

Plot 2D or 3D data.

Parameters:

xs (1D array-like) – x coordinates of vertices.
ys (1D array-like) – y coordinates of vertices.
zs (float 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.
axlim_clip (bool, default: False) –
Whether to hide data that is outside the axes view limits.

Added in version 3.10.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.plot.

plot_surface(X, Y, Z, *, norm=None, vmin=None, vmax=None, lightsource=None, axlim_clip=False, **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 (2D arrays) – Data values.
Y (2D arrays) – Data values.
Z (2D arrays) – Data values.
rcount (int) – 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.
ccount (int) – 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 (int) –
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 of rcount = ccount = 50.
cstride (int) –
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 of rcount = ccount = 50.
color (:mpltype:`color`) – Color of the surface patches.
cmap (Colormap, optional) – Colormap of the surface patches.
facecolors (list of :mpltype:`color`) – Colors of each individual patch.
norm (~matplotlib.colors.Normalize, optional) – Normalization for the colormap.
vmin (float, optional) – Bounds for the normalization.
vmax (float, optional) – Bounds for the normalization.
shade (bool, default: True) – Whether to shade the facecolors. Shading is always disabled when cmap is specified.
lightsource (~matplotlib.colors.LightSource, optional) – The lightsource to use when shade is True.
axlim_clip (bool, default: False) –
Whether to hide patches with a vertex outside the axes view limits.

Added in version 3.10.
**kwargs – Other keyword arguments are forwarded to .Poly3DCollection.

plot_trisurf(*args, color=None, norm=None, vmin=None, vmax=None, lightsource=None, axlim_clip=False, **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 ~matplotlib.tri.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 an 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 (array-like) – Data values as 1D arrays.
Y (array-like) – Data values as 1D arrays.
Z (array-like) – Data values as 1D arrays.
color – Color of the surface patches.
cmap – A colormap for the surface patches.
norm (~matplotlib.colors.Normalize, optional) – An instance of Normalize to map values to colors.
vmin (float, optional) – Minimum and maximum value to map.
vmax (float, optional) – Minimum and maximum value to map.
shade (bool, default: True) – Whether to shade the facecolors. Shading is always disabled when cmap is specified.
lightsource (~matplotlib.colors.LightSource, optional) – The lightsource to use when shade is True.
axlim_clip (bool, default: False) –
Whether to hide patches with a vertex outside the axes view limits.

Added in version 3.10.
**kwargs – All other keyword arguments are passed on to Poly3DCollection

Examples

plot_wireframe(X, Y, Z, *, axlim_clip=False, **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 (2D arrays) – Data values.
Y (2D arrays) – Data values.
Z (2D arrays) – Data values.
axlim_clip (bool, default: False) –
Whether to hide lines and patches with vertices outside the axes view limits.

Added in version 3.10.
rcount (int) – 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.
ccount (int) – 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 (int) –
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 of rcount = ccount = 50.
cstride (int) –
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 of rcount = ccount = 50.
**kwargs – Other keyword arguments are forwarded to .Line3DCollection.

quiver(X, Y, Z, U, V, W, *, length=1, arrow_length_ratio=0.3, pivot='tail', normalize=False, axlim_clip=False, data=None, **kwargs)[source]#

Plot a 3D field of arrows.

The arguments can be array-like or scalars, so long as 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 (array-like) – The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
Y (array-like) – The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
Z (array-like) – The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
U (array-like) – The x, y and z components of the arrow vectors.
V (array-like) – The x, y and z components of the arrow vectors.
W (array-like) – The x, y and z components of the arrow vectors.
length (float, default: 1) – The length of each quiver.
arrow_length_ratio (float, 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.
normalize (bool, default: False) – Whether all arrows are normalized to have the same length, or keep the lengths defined by u, v, and w.
axlim_clip (bool, default: False) –
Whether to hide arrows with points outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
**kwargs – Any additional keyword arguments are delegated to Line3DCollection

quiver3D(X, Y, Z, U, V, W, *, length=1, arrow_length_ratio=0.3, pivot='tail', normalize=False, axlim_clip=False, data=None, **kwargs)#

Plot a 3D field of arrows.

The arguments can be array-like or scalars, so long as 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 (array-like) – The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
Y (array-like) – The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
Z (array-like) – The x, y and z coordinates of the arrow locations (default is tail of arrow; see pivot kwarg).
U (array-like) – The x, y and z components of the arrow vectors.
V (array-like) – The x, y and z components of the arrow vectors.
W (array-like) – The x, y and z components of the arrow vectors.
length (float, default: 1) – The length of each quiver.
arrow_length_ratio (float, 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.
normalize (bool, default: False) – Whether all arrows are normalized to have the same length, or keep the lengths defined by u, v, and w.
axlim_clip (bool, default: False) –
Whether to hide arrows with points outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
**kwargs – Any additional keyword arguments are delegated to Line3DCollection

scatter(xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, axlim_clip=False, data=None, **kwargs)[source]#

Create a scatter plot.

Parameters:

xs (array-like) – The data positions.
ys (array-like) – The data positions.
zs (float 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 /gallery/mplot3d/2dcollections3d.
s (float 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.
c (:mpltype:`color`, 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 ~.axes.Axes.scatter.
depthshade (bool, default: True) – Whether to shade the scatter markers to give the appearance of depth. Each call to scatter() will perform its depthshading independently.
axlim_clip (bool, default: False) –
Whether to hide the scatter points outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) –
If given, the following parameters also accept a string s, which is interpreted as data[s] if s is a key in data:

xs, ys, zs, s, edgecolors, c, facecolor, facecolors, color
**kwargs – All other keyword arguments are passed on to ~.axes.Axes.scatter.

Returns:

paths

Return type:

~matplotlib.collections.PathCollection

scatter3D(xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=True, *args, axlim_clip=False, data=None, **kwargs)#

Create a scatter plot.

Parameters:

xs (array-like) – The data positions.
ys (array-like) – The data positions.
zs (float 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 /gallery/mplot3d/2dcollections3d.
s (float 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.
c (:mpltype:`color`, 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 ~.axes.Axes.scatter.
depthshade (bool, default: True) – Whether to shade the scatter markers to give the appearance of depth. Each call to scatter() will perform its depthshading independently.
axlim_clip (bool, default: False) –
Whether to hide the scatter points outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) –
If given, the following parameters also accept a string s, which is interpreted as data[s] if s is a key in data:

xs, ys, zs, s, edgecolors, c, facecolor, facecolors, color
**kwargs – All other keyword arguments are passed on to ~.axes.Axes.scatter.

Returns:

paths

Return type:

~matplotlib.collections.PathCollection

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>, forward_navigation_events=<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>, subplotspec=<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>)#

Set multiple properties at once.

Supported properties are

Properties:: adjustable: {‘box’, ‘datalim’} agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: scalar or None anchor: (float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …} animated: bool aspect: {‘auto’, ‘equal’, ‘equalxy’, ‘equalxz’, ‘equalyz’} autoscale_on: bool autoscalex_on: unknown autoscaley_on: unknown autoscalez_on: unknown axes_locator: Callable[[Axes, Renderer], Bbox] axisbelow: bool or ‘line’ box_aspect: 3-tuple of floats or None clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None facecolor or fc: :mpltype:`color` figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure forward_navigation_events: bool or “auto” gid: str in_layout: bool label: object mouseover: bool navigate: bool navigate_mode: unknown path_effects: list of .AbstractPathEffect picker: None or bool or float or callable position: [left, bottom, width, height] or ~matplotlib.transforms.Bbox proj_type: {‘persp’, ‘ortho’} prop_cycle: ~cycler.Cycler rasterization_zorder: float or None rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None subplotspec: unknown title: unknown transform: ~matplotlib.transforms.Transform url: str visible: bool xbound: unknown xlabel: str xlim: (left: float, right: float) xlim3d: (left: float, right: float) xmargin: float greater than -0.5 xscale: unknown xticklabels: unknown xticks: unknown ybound: unknown ylabel: str ylim: (bottom: float, top: float) ylim3d: (bottom: float, top: float) ymargin: float greater than -0.5 yscale: unknown yticklabels: unknown yticks: unknown zbound: unknown zlabel: unknown zlim: (bottom: float, top: float) zlim3d: (bottom: float, top: float) zmargin: float greater than -0.5 zorder: float zscale: unknown zticklabels: unknown zticks: 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.

adjustable (None or {'box', 'datalim'}, optional) – If not None, this defines which parameter will be adjusted to meet the required aspect. See .set_adjustable for further details.
anchor (None 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 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 ~.Axes.set_anchor for further details.
share (bool, default: False) – If True, apply the settings to all shared Axes.

See also

mpl_toolkits.mplot3d.axes3d.Axes3D.set_box_aspect

set_autoscalez_on(b)#

Set whether the zaxis is autoscaled when drawing or by .Axes.autoscale_view.

If b is None, then the value is not changed.

Parameters:: b (bool)

set_axis_off()[source]#

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

This sets a flag to suppress drawing of all axis decorations, i.e. axis labels, axis spines, and the axis tick component (tick markers, tick labels, and grid lines). Individual visibility settings of these components are ignored as long as set_axis_off() is in effect.

set_axis_on()[source]#

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

This reverts the effect of a prior .set_axis_off() call. Whether the individual axis decorations are drawn is controlled by their respective visibility settings.

This is on by default.

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 (see ~.Axes3D.set_aspect). 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:

aspect (3-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).
zoom (float, 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_length (float, 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:

label (str) – Text to use for the title
fontdict (dict) –

Discouraged

The use of fontdict is discouraged. Parameters should be passed as individual keyword arguments or using dictionary-unpacking set_title(..., **fontdict).

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: :rc:`axes.titlelocation`) – Which title to set.
y (float, default: :rc:`axes.titley`) – Vertical Axes location for the title (1.0 is the top). If None (the default) and :rc:`axes.titley` is also None, y is determined automatically to avoid decorators on the Axes.
pad (float, default: :rc:`axes.titlepad`) – The offset of the title from the top of the Axes, in points.
**kwargs (~matplotlib.text.Text properties) – Other keyword arguments are text properties, see .Text for a list of valid text properties.

Returns:

The matplotlib text instance representing the title

Return type:

.Text

set_xbound(lower=None, upper=None, view_margin=None)[source]#

Set the lower and upper numerical bounds of the x-axis.

This method will honor axis inversion regardless of parameter order. It will not change the autoscaling setting (.get_autoscalex_on()).

Parameters:

lower (float or None) – The lower and upper bounds. If None, the respective axis bound is not modified.
upper (float or None) – The lower and upper bounds. If None, the respective axis bound is not modified.
view_margin (float or None) – The margin to apply to the bounds. If None, the margin is handled by .set_xlim.

See also

get_xbound, get_xlim, set_xlim, invert_xaxis, xaxis_inverted

set_xlim(left=None, right=None, *, emit=True, auto=False, view_margin=None, xmin=None, xmax=None)[source]#

Set the 3D x-axis view limits.

Parameters:

left (float, 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).
right (float, optional) – The right xlim in data coordinates. Passing None leaves the limit unchanged.
emit (bool, default: True) – Whether to notify observers of limit change.
auto (bool or None, default: False) – Whether to turn on autoscaling of the x-axis. True turns on, False turns off, None leaves unchanged.
view_margin (float, optional) – The additional margin to apply to the limits.
xmin (float, optional) – They are equivalent to left and right respectively, and it is an error to pass both xmin and left or xmax and right.
xmax (float, 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 – The new x-axis limits in data coordinates.

Return type:

(float, float)

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 depth of the ocean in m. The x-axis limits might be set like the following so 5000 m depth is at the left of the plot and the surface, 0 m, is at the right.

>>> set_xlim(5000, 0)

set_xlim3d(left=None, right=None, *, emit=True, auto=False, view_margin=None, xmin=None, xmax=None)#: Alias for set_xlim.

set_xscale(value, **kwargs)#

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_ybound(lower=None, upper=None, view_margin=None)[source]#

Set the lower and upper numerical bounds of the y-axis.

This method will honor axis inversion regardless of parameter order. It will not change the autoscaling setting (.get_autoscaley_on()).

Parameters:

lower (float or None) – The lower and upper bounds. If None, the respective axis bound is not modified.
upper (float or None) – The lower and upper bounds. If None, the respective axis bound is not modified.
view_margin (float or None) – The margin to apply to the bounds. If None, the margin is handled by .set_ylim.

See also

get_ybound, get_ylim, set_ylim, invert_yaxis, yaxis_inverted

set_ylim(bottom=None, top=None, *, emit=True, auto=False, view_margin=None, ymin=None, ymax=None)[source]#

Set the 3D y-axis view limits.

Parameters:

bottom (float, 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).
top (float, optional) – The top ylim in data coordinates. Passing None leaves the limit unchanged.
emit (bool, default: True) – Whether to notify observers of limit change.
auto (bool or None, default: False) – Whether to turn on autoscaling of the y-axis. True turns on, False turns off, None leaves unchanged.
view_margin (float, optional) – The additional margin to apply to the limits.
ymin (float, optional) – They are equivalent to bottom and top respectively, and it is an error to pass both ymin and bottom or ymax and top.
ymax (float, 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 – The new y-axis limits in data coordinates.

Return type:

(float, float)

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_ylim3d(bottom=None, top=None, *, emit=True, auto=False, view_margin=None, ymin=None, ymax=None)#: Alias for set_ylim.

set_yscale(value, **kwargs)#

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, view_margin=None)[source]#

Set the lower and upper numerical bounds of the z-axis. This method will honor axis inversion regardless of parameter order. It will not change the autoscaling setting (.get_autoscaley_on()).

Parameters:

lower (float or None) – The lower and upper bounds. If None, the respective axis bound is not modified.
upper (float or None) – The lower and upper bounds. If None, the respective axis bound is not modified.
view_margin (float or None) – The margin to apply to the bounds. If None, the margin is handled by .set_zlim.

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, view_margin=None, zmin=None, zmax=None)[source]#

Set the 3D z-axis view limits.

Parameters:

bottom (float, optional) –
The bottom zlim in data coordinates. Passing None leaves the limit unchanged.

The bottom and top zlims may also be passed as the tuple (bottom, top) as the first positional argument (or as the bottom keyword argument).
top (float, optional) – The top zlim in data coordinates. Passing None leaves the limit unchanged.
emit (bool, default: True) – Whether to notify observers of limit change.
auto (bool or None, default: False) – Whether to turn on autoscaling of the z-axis. True turns on, False turns off, None leaves unchanged.
view_margin (float, optional) – The additional margin to apply to the limits.
zmin (float, optional) – They are equivalent to bottom and top respectively, and it is an error to pass both zmin and bottom or zmax and top.
zmax (float, optional) – They are equivalent to bottom and top respectively, and it is an error to pass both zmin and bottom or zmax and top.

Returns:

bottom, top – The new z-axis limits in data coordinates.

Return type:

(float, float)

Notes

The bottom value may be greater than the top value, in which case the z-axis values will decrease from bottom to top.

Examples

>>> set_zlim(bottom, top)
>>> set_zlim((bottom, top))
>>> bottom, top = set_zlim(bottom, top)

One limit may be left unchanged.

>>> set_zlim(top=top_lim)

Limits may be passed in reverse order to flip the direction of the z-axis. For example, suppose z represents depth of the ocean in m. The z-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_zlim(5000, 0)

set_zlim3d(bottom=None, top=None, *, emit=True, auto=False, view_margin=None, zmin=None, zmax=None)#: 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:: m (float greater than -0.5)

set_zscale(value, **kwargs)#

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, *, minor=False, fontdict=None, **kwargs)#

[Discouraged] Set the zaxis’ tick labels with list of string labels.

Discouraged

The use of this method is discouraged, because of the dependency on tick positions. In most cases, you’ll want to use Axes.set_[x/y/z]ticks(positions, labels) or Axes3D.set_zticks instead.

If you are using this method, you should always fix the tick positions before, e.g. by using .Axes3D.set_zticks or by explicitly setting a ~.ticker.FixedLocator. Otherwise, ticks are free to move and the labels may end up in unexpected positions.

Parameters:

labels (sequence of str or of .Texts) – Texts for labeling each tick location in the sequence set by .Axes3D.set_zticks; the number of labels must match the number of locations. The labels are used as is, via a .FixedFormatter (without further formatting).
minor (bool) – If True, set minor ticks instead of major ticks.
fontdict (dict, optional) –

Discouraged

The use of fontdict is discouraged. Parameters should be passed as individual keyword arguments or using dictionary-unpacking set_ticklabels(..., **fontdict).

A dictionary controlling the appearance of the ticklabels. The default fontdict is:
```
{'fontsize': rcParams['axes.titlesize'],
 'fontweight': rcParams['axes.titleweight'],
 'verticalalignment': 'baseline',
 'horizontalalignment': loc}
```
**kwargs –
Text properties.

Warning

This only sets the properties of the current ticks, which is only sufficient for static plots.

Ticks are not guaranteed to be persistent. Various operations can create, delete and modify the Tick instances. There is an imminent risk that these settings can get lost if you work on the figure further (including also panning/zooming on a displayed figure).

Use .set_tick_params instead if possible.

Returns:

For each tick, includes tick.label1 if it is visible, then tick.label2 if it is visible, in that order.

Return type:

list of .Texts

set_zticks(ticks, labels=None, *, minor=False, **kwargs)#

Set the zaxis’ tick locations and optionally tick labels.

If necessary, the view limits of the Axis are expanded so that all given ticks are visible.

Parameters:

ticks (1D array-like) –
Array of tick locations (either floats or in axis units). The axis .Locator is replaced by a ~.ticker.FixedLocator.

Pass an empty list (set_ticks([])) to remove all ticks.

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.
labels (list of str, optional) – Tick labels for each location in ticks; must have the same length as ticks. If set, the labels are used as is, via a .FixedFormatter. If not set, the labels are generated using the axis tick .Formatter.
minor (bool, default: False) – If False, set only the major ticks; if True, only the minor ticks.
**kwargs – .Text properties for the labels. Using these is only allowed if you pass labels. In other cases, please use ~.Axes.tick_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.

shareview(other)[source]#

Share the view angles with other.

This is equivalent to passing shareview=other when constructing the Axes, and cannot be used if the view angles are already being shared with another Axes. Note that it is not possible to unshare axes.

sharez(other)[source]#

Share the z-axis with other.

This is equivalent to passing sharez=other when constructing the Axes, and cannot be used if the z-axis is already being shared with another Axes. Note that it is not possible to unshare axes.

stem(x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-', bottom=0, label=None, orientation='z', axlim_clip=False, 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 (array-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.
y (array-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.
z (array-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.
linefmt (str, 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.
markerfmt (str, default: 'C0o') – A string defining the properties of the markers at the stem heads.
basefmt (str, default: 'C3-') – A format string defining the properties of the baseline.
bottom (float, default: 0) – The position of the baseline, in orientation-coordinates.
label (str, optional) – The label to use for the stems in legends.
orientation ({'x', 'y', 'z'}, default: 'z') – The direction along which stems are drawn.
axlim_clip (bool, default: False) –
Whether to hide stems that are outside the axes limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.

Returns:

The container may be treated like a tuple (markerline, stemlines, baseline)

Return type:

.StemContainer

Examples

stem3D(x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-', bottom=0, label=None, orientation='z', axlim_clip=False, data=None)#

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 (array-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.
y (array-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.
z (array-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.
linefmt (str, 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.
markerfmt (str, default: 'C0o') – A string defining the properties of the markers at the stem heads.
basefmt (str, default: 'C3-') – A format string defining the properties of the baseline.
bottom (float, default: 0) – The position of the baseline, in orientation-coordinates.
label (str, optional) – The label to use for the stems in legends.
orientation ({'x', 'y', 'z'}, default: 'z') – The direction along which stems are drawn.
axlim_clip (bool, default: False) –
Whether to hide stems that are outside the axes limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.

Returns:

The container may be treated like a tuple (markerline, stemlines, baseline)

Return type:

.StemContainer

Examples

text(x, y, z, s, zdir=None, *, axlim_clip=False, **kwargs)[source]#

Add the text s to the 3D Axes at location x, y, z in data coordinates.

Parameters:

x (float) – The position to place the text.
y (float) – The position to place the text.
z (float) – The position to place the text.
s (str) – The text.
zdir ({'x', 'y', 'z', 3-tuple}, optional) – The direction to be used as the z-direction. Default: ‘z’. See .get_dir_vector for a description of the values.
axlim_clip (bool, default: False) –
Whether to hide text that is outside the axes view limits.

Added in version 3.10.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.text.

Returns:

The created .Text3D instance.

Return type:

.Text3D

text2D(x, y, s, fontdict=None, **kwargs)#

Add text to the Axes.

Add the text s to the Axes at location x, y in data coordinates, with a default horizontalalignment on the left and verticalalignment at the baseline. See /gallery/text_labels_and_annotations/text_alignment.

Parameters:

x (float) – The position to place the text. By default, this is in data coordinates. The coordinate system can be changed using the transform parameter.
y (float) – The position to place the text. By default, this is in data coordinates. The coordinate system can be changed using the transform parameter.
s (str) – The text.
fontdict (dict, default: None) –

Discouraged

The use of fontdict is discouraged. Parameters should be passed as individual keyword arguments or using dictionary-unpacking text(..., **fontdict).

A dictionary to override the default text properties. If fontdict is None, the defaults are determined by .rcParams.
**kwargs (~matplotlib.text.Text properties.) –
Other miscellaneous text parameters.

Properties: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: scalar or None animated: bool antialiased: bool backgroundcolor: :mpltype:`color` bbox: dict with properties for .patches.FancyBboxPatch clip_box: unknown clip_on: unknown clip_path: unknown color or c: :mpltype:`color` figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure fontfamily or family or fontname: {FONTNAME, ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, ‘monospace’} fontproperties or font or font_properties: .font_manager.FontProperties or str or pathlib.Path fontsize or size: float 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’} gid: str horizontalalignment or ha: {‘left’, ‘center’, ‘right’} in_layout: bool label: object linespacing: float (multiple of font size) math_fontfamily: str mouseover: bool multialignment or ma: {‘left’, ‘right’, ‘center’} parse_math: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable position: (float, float) rasterized: bool rotation: float or {‘vertical’, ‘horizontal’} rotation_mode: {None, ‘default’, ‘anchor’} sketch_params: (scale: float, length: float, randomness: float) snap: bool or None text: object transform: ~matplotlib.transforms.Transform transform_rotates_text: bool url: str usetex: bool, default: :rc:`text.usetex` verticalalignment or va: {‘baseline’, ‘bottom’, ‘center’, ‘center_baseline’, ‘top’} visible: bool wrap: bool x: float y: float zorder: float

Returns:

The created .Text instance.

Return type:

.Text

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 ~matplotlib.patches.Rectangle properties. For example:

>>> text(x, y, s, bbox=dict(facecolor='red', alpha=0.5))

text3D(x, y, z, s, zdir=None, *, axlim_clip=False, **kwargs)#

Add the text s to the 3D Axes at location x, y, z in data coordinates.

Parameters:

x (float) – The position to place the text.
y (float) – The position to place the text.
z (float) – The position to place the text.
s (str) – The text.
zdir ({'x', 'y', 'z', 3-tuple}, optional) – The direction to be used as the z-direction. Default: ‘z’. See .get_dir_vector for a description of the values.
axlim_clip (bool, default: False) –
Whether to hide text that is outside the axes view limits.

Added in version 3.10.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.text.

Returns:

The created .Text3D instance.

Return type:

.Text3D

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, axlim_clip=False, 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 (array-like) – Input data. See .Axes.tricontour for supported data shapes.
Y (array-like) – Input data. See .Axes.tricontour for supported data shapes.
Z (array-like) – Input data. See .Axes.tricontour for supported data shapes.
extend3d (bool, default: False) – Whether to extend contour in 3D.
stride (int, default: 5) – Step size for extending contour.
zdir ({'x', 'y', 'z'}, default: 'z') – The direction to use.
offset (float, optional) – If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
axlim_clip (bool, default: False) –
Whether to hide lines with a vertex outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
*args – Other arguments are forwarded to matplotlib.axes.Axes.tricontour.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.tricontour.

Return type:

matplotlib.tri._tricontour.TriContourSet

tricontourf(*args, zdir='z', offset=None, axlim_clip=False, 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 (array-like) – Input data. See .Axes.tricontourf for supported data shapes.
Y (array-like) – Input data. See .Axes.tricontourf for supported data shapes.
Z (array-like) – Input data. See .Axes.tricontourf for supported data shapes.
zdir ({'x', 'y', 'z'}, default: 'z') – The direction to use.
offset (float, optional) – If specified, plot a projection of the contour lines at this position in a plane normal to zdir.
axlim_clip (bool, default: False) –
Whether to hide lines with a vertex outside the axes view limits.

Added in version 3.10.
data (indexable object, optional) – If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.
*args – Other arguments are forwarded to matplotlib.axes.Axes.tricontourf.
**kwargs – Other arguments are forwarded to matplotlib.axes.Axes.tricontourf.

Return type:

matplotlib.tri._tricontour.TriContourSet

update_datalim(xys, **kwargs)[source]#: Not implemented in ~mpl_toolkits.mplot3d.axes3d.Axes3D.

view_init(elev=None, azim=None, roll=None, vertical_axis='z', share=False)[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:

elev (float, 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.
azim (float, 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.
roll (float, 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.
share (bool, default: False) – If True, apply the settings to all Axes with shared views.

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:

filled (3D np.array of bool) – A 3D array of values, with truthy values indicating which voxels to fill
x (3D 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.
y (3D 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.
z (3D 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 (array-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 ~numpy.ndarray of color names, with each item the color for the corresponding voxel. The size must match the voxels.
- A 4D ~numpy.ndarray of RGB/RGBA data, with the components along the last axis.
edgecolors (array-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 ~numpy.ndarray of color names, with each item the color for the corresponding voxel. The size must match the voxels.
- A 4D ~numpy.ndarray of RGB/RGBA data, with the components along the last axis.
shade (bool, default: True) – Whether to shade the facecolors.
lightsource (~matplotlib.colors.LightSource, optional) – The lightsource to use when shade is True.
axlim_clip (bool, default: False) –
Whether to hide voxels with points outside the axes view limits.

Added in version 3.10.
**kwargs – Additional keyword arguments to pass onto ~mpl_toolkits.mplot3d.art3d.Poly3DCollection.

Returns:

faces – A dictionary indexed by coordinate, where faces[i, j, k] is a .Poly3DCollection of the faces drawn for the voxel filled[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.

Return type:

dict

Examples

zaxis_date(tz=None)#

Set up axis ticks and labels to treat data along the zaxis as dates.

Parameters:: tz (str or datetime.tzinfo, default: :rc:`timezone`) – The timezone used to create date labels.

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.

zaxis_inverted()#

Return whether the zaxis is oriented in the “inverse” direction.

The “normal” direction is increasing to the right for the x-axis and to the top for the y-axis; the “inverse” direction is increasing to the left for the x-axis and to the bottom for the y-axis.

class atomsmltr.utils.plotter.Plottable[source]#

Bases: ABC

This class defines several methods that should be common to all objects that contain data to be plotted

atomsmltr.utils.plotter package#

Submodules#

This Page

value	description
’C’	centered
’SW’	lower left corner
’S’	middle of bottom edge
’SE’	lower right corner
etc.

Character	Line Style
`'-'`	solid line
`'--'`	dashed line
`'-.'`	dash-dot line
`':'`	dotted line