pyvista.Plotter.add_mesh#
- Plotter.add_mesh(
- mesh,
- color=None,
- style=None,
- scalars=None,
- clim=None,
- show_edges=None,
- edge_color=None,
- point_size=None,
- line_width=None,
- opacity=None,
- flip_scalars=False,
- lighting=None,
- n_colors=256,
- interpolate_before_map=None,
- cmap=None,
- label=None,
- reset_camera=None,
- scalar_bar_args=None,
- show_scalar_bar=None,
- multi_colors=False,
- name=None,
- texture=None,
- render_points_as_spheres=None,
- render_lines_as_tubes=None,
- smooth_shading=None,
- split_sharp_edges=None,
- ambient=None,
- diffuse=None,
- specular=None,
- specular_power=None,
- nan_color=None,
- nan_opacity=1.0,
- culling=None,
- rgb=None,
- categories=False,
- silhouette=None,
- use_transparency=False,
- below_color=None,
- above_color=None,
- annotations=None,
- pickable=True,
- preference='point',
- log_scale=False,
- pbr=None,
- metallic=None,
- roughness=None,
- render=True,
- user_matrix=None,
- component=None,
- emissive=None,
- copy_mesh=False,
- backface_params=None,
- show_vertices=None,
- edge_opacity=None,
- **kwargs,
Add any PyVista/VTK mesh or dataset that PyVista can wrap to the scene.
This method is using a mesh representation to view the surfaces and/or geometry of datasets. For volume rendering, see
pyvista.Plotter.add_volume()
.To see the what most of the following parameters look like in action, please refer to
pyvista.Property
.- Parameters:
- mesh
pyvista.DataSet
orpyvista.MultiBlock
orvtk.vtkAlgorithm
Any PyVista or VTK mesh is supported. Also, any dataset that
pyvista.wrap()
can handle including NumPy arrays of XYZ points. Plotting also supports VTK algorithm objects (vtk.vtkAlgorithm
andvtk.vtkAlgorithmOutput
). When passing an algorithm, the rendering pipeline will be connected to the passed algorithm to dynamically update the scene.- color
ColorLike
,optional
Use to make the entire mesh have a single solid color. Either a string, RGB list, or hex color string. For example:
color='white'
,color='w'
,color=[1.0, 1.0, 1.0]
, orcolor='#FFFFFF'
. Color will be overridden if scalars are specified.Defaults to
pyvista.global_theme.color
.- style
str
,optional
Visualization style of the mesh. One of the following:
style='surface'
,style='wireframe'
,style='points'
,style='points_gaussian'
. Defaults to'surface'
. Note that'wireframe'
only shows a wireframe of the outer geometry.'points_gaussian'
can be modified with theemissive
,render_points_as_spheres
options.- scalars
str
|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 both
color
andscalars
areNone
, then the active scalars are used.- climsequence[
float
],optional
Two item color bar range for scalars. Defaults to minimum and maximum of scalars array. Example:
[-1, 2]
.rng
is also an accepted alias for this.- show_edgesbool,
optional
Shows the edges of a mesh. Does not apply to a wireframe representation.
- edge_color
ColorLike
,optional
The solid color to give the edges when
show_edges=True
. Either a string, RGB list, or hex color string.Defaults to
pyvista.global_theme.edge_color
.- point_size
float
,optional
Point size of any nodes in the dataset plotted. Also applicable when style=’points’. Default
5.0
.- line_width
float
,optional
Thickness of lines. Only valid for wireframe and surface representations. Default
None
.- opacity
float
| str| array_like Opacity of the mesh. If a single float value is given, it will be the global opacity of the mesh and uniformly applied everywhere - should be between 0 and 1. 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'
). A string could also be used to map a scalars array from the mesh to the opacity (must have same number of elements as thescalars
argument). Or you can pass a custom made transfer function that is an array eithern_colors
in length or shorter.- flip_scalarsbool, default:
False
Flip direction of cmap. Most colormaps allow
*_r
suffix to do this as well.- lightingbool,
optional
Enable or disable view direction lighting. Default
False
.- n_colors
int
,optional
Number of colors to use when displaying scalars. Defaults to 256. The scalar bar will also have this many colors.
- interpolate_before_mapbool,
optional
Enabling makes for a smoother scalars display. Default is
True
. WhenFalse
, OpenGL will interpolate the mapped colors which can result is showing colors that are not present in the color map.- cmap
str
|list
|pyvista.LookupTable
, default:pyvista.plotting.themes.Theme.cmap
If a string, this is the name of the
matplotlib
colormap to use when mapping thescalars
. See available Matplotlib colormaps. Only applicable for when displayingscalars
.colormap
is also an accepted alias for this. Ifcolorcet
orcmocean
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 liken_colors
will be ignored.- label
str
,optional
String label to use when adding a legend to the scene with
pyvista.Plotter.add_legend()
.- reset_camerabool,
optional
Reset the camera after adding this mesh to the scene. The default setting is
None
, where the camera is only reset if this plotter has already been shown. IfFalse
, the camera is not reset regardless of the state of thePlotter
. WhenTrue
, the camera is always reset.- scalar_bar_args
dict
,optional
Dictionary of keyword arguments to pass when adding the scalar bar to the scene. For options, see
pyvista.Plotter.add_scalar_bar()
.- show_scalar_barbool,
optional
If
False
, a scalar bar will not be added to the scene.- multi_colorsbool |
str
|cycler.Cycler
| sequence[ColorLike
], default:False
If a
pyvista.MultiBlock
dataset is given this will color each block by a solid color using a custom cycler.If
True
, the default ‘matplotlib’ color cycler is used.See
set_color_cycler
for usage of custom color cycles.- name
str
,optional
The name for the added mesh/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.
- texture
pyvista.Texture
ornp.ndarray
,optional
A texture to apply if the input mesh has texture coordinates. This will not work with MultiBlock datasets.
- render_points_as_spheresbool,
optional
Render points as spheres rather than dots.
- render_lines_as_tubesbool,
optional
Show lines as thick tubes rather than flat lines. Control the width with
line_width
.- smooth_shadingbool,
optional
Enable smooth shading when
True
using the Phong shading algorithm. WhenFalse
, use flat shading. Automatically enabled whenpbr=True
. See Types of Shading.- split_sharp_edgesbool,
optional
Split sharp edges exceeding 30 degrees when plotting with smooth shading. Control the angle with the optional keyword argument
feature_angle
. By default this isFalse
unless overridden by the global or plotter theme. Note that enabling this will create a copy of the input mesh within the plotter. See Types of Shading.- ambient
float
,optional
When lighting is enabled, this is the amount of light in the range of 0 to 1 (default 0.0) that reaches the actor when not directed at the light source emitted from the viewer.
- diffuse
float
,optional
The diffuse lighting coefficient. Default 1.0.
- specular
float
,optional
The specular lighting coefficient. Default 0.0.
- specular_power
float
,optional
The specular power. Between 0.0 and 128.0.
- nan_color
ColorLike
,optional
The color to use for all
NaN
values in the plotted scalar array.- nan_opacity
float
,optional
Opacity of
NaN
values. Should be between 0 and 1. Default 1.0.- culling
str
,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 toFalse
.- rgbbool,
optional
If an 2 dimensional array is passed as the scalars, plot those values as RGB(A) colors.
rgba
is also an accepted alias for this. Opacity (the A) is optional. If a scalars array ending with"_rgba"
is passed, the default becomesTrue
. This can be overridden by setting this parameter toFalse
.- categoriesbool,
optional
If set to
True
, then the number of unique values in the scalar array will be used as then_colors
argument.- silhouette
dict
, bool,optional
If set to
True
, plot a silhouette highlight for the mesh. This feature is only available for a triangulatedPolyData
. As adict
, it contains the properties of the silhouette to display:color
:ColorLike
, color of the silhouetteline_width
:float
, edge widthopacity
:float
between 0 and 1, edge transparencyfeature_angle
: If afloat
, display sharp edges exceeding that angle in degrees.decimate
:float
between 0 and 1, level of decimation
- use_transparencybool,
optional
Invert the opacity mappings and make the values correspond to transparency.
- below_color
ColorLike
,optional
Solid color for values below the scalars range (
clim
). This will automatically set the scalar barbelow_label
to'below'
.- above_color
ColorLike
,optional
Solid color for values below the scalars range (
clim
). This will automatically set the scalar barabove_label
to'above'
.- annotations
dict
,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 string annotations.
- pickablebool,
optional
Set whether this actor is pickable.
- preference
str
, default: “point” 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'
.- log_scalebool, default:
False
Use log scale when mapping data to colors. Scalars less than zero are mapped to the smallest representable positive float.
- pbrbool,
optional
Enable physics based rendering (PBR) if the mesh is
PolyData
. Use thecolor
argument to set the base color.- metallic
float
,optional
Usually this value is either 0 or 1 for a real material but any value in between is valid. This parameter is only used by PBR interpolation.
- roughness
float
,optional
This value has to be between 0 (glossy) and 1 (rough). A glossy material has reflections and a high specular part. This parameter is only used by PBR interpolation.
- renderbool, default:
True
Force a render when
True
.- user_matrix
np.ndarray
|vtk.vtkMatrix4x4
, default:np.eye
(4) Matrix passed to the Actor class before rendering. This affects the actor/rendering only, not the input volume itself. The user matrix is the last transformation applied to the actor before rendering. Defaults to the identity matrix.
- component
int
,optional
Set component of vector valued scalars to plot. Must be nonnegative, if supplied. If
None
, the magnitude of the vector is plotted.- emissivebool,
optional
Treat the points/splats as emissive light sources. Only valid for
style='points_gaussian'
representation.- copy_meshbool, default:
False
If
True
, a copy of the mesh will be made before adding it to the plotter. This is useful if you would like to add the same mesh to a plotter multiple times and display different scalars. Settingcopy_mesh
toFalse
is necessary if you would like to update the mesh after adding it to the plotter and have these updates rendered, e.g. by changing the active scalars or through an interactive widget. This should only be set toTrue
with caution. Defaults toFalse
. This is ignored if the input is avtkAlgorithm
subclass.- backface_params
dict
|pyvista.Property
,optional
A
pyvista.Property
or a dict of parameters to use for backface rendering. This is useful for instance when the inside of oriented surfaces has a different color than the outside. When apyvista.Property
, this is directly used for backface rendering. When a dict, valid keys arepyvista.Property
attributes, and values are corresponding values to use for the given property. Omitted keys (or the default ofbackface_params=None
) default to the corresponding frontface properties.- show_verticesbool,
optional
When
style
is not'points'
, render the external surface vertices. The following optional keyword arguments may be used to control the style of the vertices:vertex_color
- The color of the verticesvertex_style
- Change style to'points_gaussian'
vertex_opacity
- Control the opacity of the vertices
- edge_opacity
float
,optional
Edge opacity of the mesh. A single float value that will be applied globally edge opacity of the mesh and uniformly applied everywhere - should be between 0 and 1.
Note
edge_opacity uses
SetEdgeOpacity
as the underlying method which requires VTK version 9.3 or higher. IfSetEdgeOpacity
is not available, edge_opacity is set to 1.- **kwargs
dict
,optional
Optional keyword arguments.
- mesh
- Returns:
pyvista.plotting.actor.Actor
Actor of the mesh.
Examples
Add a sphere to the plotter and show it with a custom scalar bar title.
>>> import pyvista as pv >>> sphere = pv.Sphere() >>> sphere['Data'] = sphere.points[:, 2] >>> plotter = pv.Plotter() >>> _ = plotter.add_mesh( ... sphere, scalar_bar_args={'title': 'Z Position'} ... ) >>> plotter.show()
Plot using RGB on a single cell. Note that since the number of points and the number of cells are identical, we have to pass
preference='cell'
.>>> import pyvista as pv >>> import numpy as np >>> vertices = np.array( ... [ ... [0, 0, 0], ... [1, 0, 0], ... [0.5, 0.667, 0], ... [0.5, 0.33, 0.667], ... ] ... ) >>> faces = np.hstack( ... [[3, 0, 1, 2], [3, 0, 3, 2], [3, 0, 1, 3], [3, 1, 2, 3]] ... ) >>> mesh = pv.PolyData(vertices, faces) >>> mesh.cell_data['colors'] = [ ... [255, 255, 255], ... [0, 255, 0], ... [0, 0, 255], ... [255, 0, 0], ... ] >>> plotter = pv.Plotter() >>> _ = plotter.add_mesh( ... mesh, ... scalars='colors', ... lighting=False, ... rgb=True, ... preference='cell', ... ) >>> plotter.camera_position = 'xy' >>> plotter.show()
Note how this varies from
preference=='point'
. This is because each point is now being individually colored, versus inpreference=='point'
, each cell face is individually colored.>>> plotter = pv.Plotter() >>> _ = plotter.add_mesh( ... mesh, ... scalars='colors', ... lighting=False, ... rgb=True, ... preference='point', ... ) >>> plotter.camera_position = 'xy' >>> plotter.show()
Plot a plane with a constant color and vary its opacity by point.
>>> plane = pv.Plane() >>> plane.plot( ... color='b', ... opacity=np.linspace(0, 1, plane.n_points), ... show_edges=True, ... )
Plot the points of a sphere with Gaussian smoothing while coloring by z position.
>>> mesh = pv.Sphere() >>> mesh.plot( ... scalars=mesh.points[:, 2], ... style='points_gaussian', ... opacity=0.5, ... point_size=10, ... render_points_as_spheres=False, ... show_scalar_bar=False, ... )
Plot spheres using points_gaussian style and scale them by radius.
>>> N_SPHERES = 1_000_000 >>> rng = np.random.default_rng(seed=0) >>> pos = rng.random((N_SPHERES, 3)) >>> rad = rng.random(N_SPHERES) * 0.01 >>> pdata = pv.PolyData(pos) >>> pdata['radius'] = rad >>> pdata.plot( ... style='points_gaussian', ... emissive=False, ... render_points_as_spheres=True, ... )