Plotter.add_volume(volume, scalars=None, clim=None, resolution=None, opacity='linear', n_colors=256, cmap=None, flip_scalars=False, reset_camera=None, name=None, ambient=0.0, categories=False, culling=False, multi_colors=False, blending='composite', mapper=None, scalar_bar_args=None, show_scalar_bar=None, annotations=None, pickable=True, preference='point', opacity_unit_distance=None, shade=False, diffuse=0.7, specular=0.2, specular_power=10.0, render=True, **kwargs)#

Add a volume, rendered using a smart mapper by default.

Requires a 3D numpy.ndarray or pyvista.UniformGrid.

volume3D numpy.ndarray or pyvista.UniformGrid

The input volume to visualize. 3D numpy arrays are accepted.

scalarsstr or numpy.ndarray, optional

Scalars used to “color” the mesh. Accepts a string name of an array that is present on the mesh or an array equal to the number of cells or the number of points in the mesh. Array should be sized as a single vector. If scalars is None, then the active scalars are used.

clim2 item list, optional

Color bar range for scalars. Defaults to minimum and maximum of scalars array. Example: [-1, 2]. rng is also an accepted alias for this.

resolutionlist, optional

Block resolution.

opacitystr or numpy.ndarray, optional

Opacity mapping for the scalars array. A string can also be specified to map the scalars range to a predefined opacity transfer function (options include: ‘linear’, ‘linear_r’, ‘geom’, ‘geom_r’). Or you can pass a custom made transfer function that is an array either n_colors in length or shorter.

n_colorsint, optional

Number of colors to use when displaying scalars. Defaults to 256. The scalar bar will also have this many colors.

cmapstr, list, or pyvista.LookupTable, default: pyvista.themes.DefaultTheme.cmap

If a string, this is the name of the matplotlib colormap to use when mapping the scalars. See available Matplotlib colormaps. Only applicable for when displaying scalars. Requires Matplotlib to be installed. colormap is also an accepted alias for this. If colorcet or cmocean are installed, their colormaps can be specified by name.

You can also specify a list of colors to override an existing colormap with a custom one. For example, to create a three color colormap you might specify ['green', 'red', 'blue'].

This parameter also accepts a pyvista.LookupTable. If this is set, all parameters controlling the color map like n_colors will be ignored.

flip_scalarsbool, optional

Flip direction of cmap. Most colormaps allow *_r suffix to do this as well.

reset_camerabool, optional

Reset the camera after adding this mesh to the scene.

namestr, optional

The name for the added actor so that it can be easily updated. If an actor of this name already exists in the rendering window, it will be replaced by the new actor.

ambientfloat, optional

When lighting is enabled, this is the amount of light from 0 to 1 that reaches the actor when not directed at the light source emitted from the viewer. Default 0.0.

categoriesbool, optional

If set to True, then the number of unique values in the scalar array will be used as the n_colors argument.

cullingstr, optional

Does not render faces that are culled. Options are 'front' or 'back'. This can be helpful for dense surface meshes, especially when edges are visible, but can cause flat meshes to be partially displayed. Defaults False.

multi_colorsbool, optional

Whether or not to use multiple colors when plotting MultiBlock object. Blocks will be colored sequentially as ‘Reds’, ‘Greens’, ‘Blues’, and ‘Grays’.

blendingstr, optional

Blending mode for visualisation of the input object(s). Can be one of ‘additive’, ‘maximum’, ‘minimum’, ‘composite’, or ‘average’. Defaults to ‘additive’.

mapperstr, optional

Volume mapper to use given by name. Options include: 'fixed_point', 'gpu', 'open_gl', and 'smart'. If None the "volume_mapper" in the self._theme is used.

scalar_bar_argsdict, optional

Dictionary of keyword arguments to pass when adding the scalar bar to the scene. For options, see pyvista.BasePlotter.add_scalar_bar().


If False, a scalar bar will not be added to the scene. Defaults to True.

annotationsdict, optional

Pass a dictionary of annotations. Keys are the float values in the scalars range to annotate on the scalar bar and the values are the the string annotations.

pickablebool, optional

Set whether this mesh is pickable.

preferencestr, optional

When mesh.n_points == mesh.n_cells and setting scalars, this parameter sets how the scalars will be mapped to the mesh. Default 'point', causes the scalars will be associated with the mesh points. Can be either 'point' or 'cell'.


Set/Get the unit distance on which the scalar opacity transfer function is defined. Meaning that over that distance, a given opacity (from the transfer function) is accumulated. This is adjusted for the actual sampling distance during rendering. By default, this is the length of the diagonal of the bounding box of the volume divided by the dimensions.


Default off. If shading is turned on, the mapper may perform shading calculations - in some cases shading does not apply (for example, in a maximum intensity projection) and therefore shading will not be performed even if this flag is on.

diffusefloat, optional

The diffuse lighting coefficient. Default 1.0.

specularfloat, optional

The specular lighting coefficient. Default 0.0.

specular_powerfloat, optional

The specular power. Between 0.0 and 128.0.

renderbool, optional

Force a render when True. Default True.

**kwargsdict, optional

Optional keyword arguments.


Actor of the volume.


Show a built-in volume example with the coolwarm colormap.

>>> from pyvista import examples
>>> import pyvista as pv
>>> bolt_nut = examples.download_bolt_nut()
>>> pl = pv.Plotter()
>>> _ = pl.add_volume(bolt_nut, cmap="coolwarm")