Plotting¶

When plotting with the interactive rendering windows in VTK, several keyboard shortcuts are available:

Key		Action
Linux/Windows	Mac
`q`		Close the rendering window
`f`		Focus and zoom in on a point
`v`		Isometric camera view
`w`		Switch all datasets to a wireframe representation
`r`		Reset the camera to view all datasets
`s`		Switch all datasets to a surface representation
`shift+click` or `middle-click`	`shift+click`	Pan the rendering scene
`left-click`	`cmd+click`	Rotate the rendering scene in 3D
`ctrl+click`		Rotate the rendering scene in 2D (view-plane)
`mouse-wheel` or `right-click`	`ctl+click`	Continuously zoom the rendering scene
`shift+s`		Save a screenhsot (only on `BackgroundPlotter`)
`shift+c`		Enable interactive cell selection/picking
`up`/`down`		Zoom in and out
`+`/`-`		Increase/decrease the point size and line widths

Plotting in a Jupyter Notebook¶

Static and interactive inline plots are possible using a Jupyter notebook. The code snippet below will create a static screenshot of the rendering and display it in the Jupyter notebook:

import pyvista as pv
sphere = pv.Sphere()
sphere.plot(jupyter_backend='static')

It is possible to use the Plotter class as well.

plotter = pv.Plotter(notebook=True)
plotter.add_mesh(sphere)
plotter.show(jupyter_backend='static')

Additionally, you can generate interactive plots by leveraging a jupyter plotting backend like panel or ipygany. You can even use it to create interactive documentations online.

plotter = pv.Plotter(notebook=True)
plotter.add_mesh(sphere)
plotter.show(jupyter_backend='ipygany')

For more details, see the section on Jupyter Notebook Plotting.

Background Plotting¶

PyVista provides a plotter that enables users to create a rendering window in the background that remains interactive while the user performs their processing. This creates the ability to make a rendering scene and interactively add or remove datasets from the scene as well as has some useful menu functions for common scene manipulation or export tasks. To get started, try instantiating the pyvistaqt.BackgroundPlotter:

import pyvista as pv
import pyvistaqt as pvqt
from pyvista import examples

dataset = examples.load_hexbeam()

p = pvqt.BackgroundPlotter()

p.add_mesh(dataset)

p.show_bounds(grid=True, location='back')

Plot Time Series Data¶

This example outlines how to plot data where the spatial reference and data values change through time:

from threading import Thread
import time
import numpy as np
import pyvista as pv
import pyvistaqt as pvqt
from pyvista import examples


globe = examples.load_globe()
globe.point_arrays['scalars'] = np.random.rand(globe.n_points)
globe.set_active_scalars('scalars')


plotter = pvqt.BackgroundPlotter()
plotter.add_mesh(globe, lighting=False, show_edges=True, texture=True, scalars='scalars')
plotter.view_isometric()

# shrink globe in the background
def shrink():
    for i in range(50):
        globe.points *= 0.95
        # Update scalars
        globe.point_arrays['scalars'] = np.random.rand(globe.n_points)
        time.sleep(0.5)

thread = Thread(target=shrink)
thread.start()

Convenience Functions¶

pyvista.plot(var_item, off_screen=None, full_screen=False, screenshot=None, interactive=True, cpos=None, window_size=None, show_bounds=False, show_axes=None, notebook=None, background=None, text='', return_img=False, eye_dome_lighting=False, volume=False, parallel_projection=False, use_ipyvtk=None, jupyter_backend=None, return_viewer=False, jupyter_kwargs={}, theme=None, **kwargs)¶

Plot a vtk or numpy object.

Parameters

item (vtk or numpy object) – VTK object or numpy array to be plotted.
off_screen (bool) – Plots off screen when True. Helpful for saving screenshots without a window popping up.
full_screen (bool, optional) – Opens window in full screen. When enabled, ignores window_size. Default False.
screenshot (str or bool, optional) –
Saves screenshot to file when enabled. See: help(pyvista.Plotter.screenshot). Default False.

When True, takes screenshot and returns numpy array of image.
window_size (list, optional) – Window size in pixels. Defaults to [1024, 768]
show_bounds (bool, optional) – Shows mesh bounds when True. Default False. Alias show_grid also accepted.
notebook (bool, optional) – When True, the resulting plot is placed inline a jupyter notebook. Assumes a jupyter console is active.
show_axes (bool, optional) – Shows a vtk axes widget. If None, enabled according to pyvista.global_theme.axes.show.
text (str, optional) – Adds text at the bottom of the plot.
volume (bool, optional) – Use the add_volume method for volume rendering.
use_ipyvtk (bool, optional) – Deprecated. Instead, set the backend either globally with pyvista.set_jupyter_backend('ipyvtklink') or with backend='ipyvtklink'.
jupyter_backend (str, optional) –
Jupyter notebook plotting backend to use. One of the following:
- 'none' : Do not display in the notebook.
- 'static' : Display a static figure.
- 'ipygany' : Show a ipygany widget
- 'panel' : Show a panel widget.
This can also be set globally with pyvista.set_jupyter_backend
jupyter_kwargs (dict, optional) – Keyword arguments for the Jupyter notebook plotting backend.
theme (pyvista.themes.DefaultTheme, optional) – Plot-specific theme.
**kwargs (optional keyword arguments) – See help(pyvista.Plotter.add_mesh) for additional options.

Returns

cpos (list) – List of camera position, focal point, and view up.
img (numpy.ndarray) – Array containing pixel RGB and optionally alpha values. Sized:
- [Window height x Window width x 3] if the theme sets transparent_background=False.
- [Window height x Window width x 4] if the theme sets transparent_background=True.
Returned only when screenshot=True.

Examples

Plot a simple sphere while showing its edges.

>>> import pyvista
>>> mesh = pyvista.Sphere()
>>> mesh.plot(show_edges=True)  

pyvista.plot_arrows(cent, direction, **kwargs)¶

Plot arrows as vectors.

Parameters

cent (np.ndarray) – Accepts a single 3d point or array of 3d points.
directions (np.ndarray) – Accepts a single 3d point or array of 3d vectors. Must contain the same number of items as cent.
**kwargs (additional arguments, optional) – See help(pyvista.plot).

Returns

Return type

Same as pyvista.plot. See help(pyvista.plot).

Examples

Plot a single random arrow.

>>> import numpy as np
>>> import pyvista
>>> cent = np.random.random(3)
>>> direction = np.random.random(3)
>>> cpos = pyvista.plot_arrows(cent, direction)

Plot 100 random arrows.

>>> import numpy as np
>>> import pyvista
>>> cent = np.random.random((100, 3))
>>> direction = np.random.random((100, 3))
>>> cpos = pyvista.plot_arrows(cent, direction)

pyvista.set_plot_theme(theme)¶

Set the plotting parameters to a predefined theme using a string.

Parameters: theme (str) – Theme name. Either 'default', 'document', 'dark', or 'paraview'.

Examples

Set to the default theme.

>>> import pyvista
>>> pyvista.set_plot_theme('default')

Set to the document theme.

>>> pyvista.set_plot_theme('document')

Set to the dark theme.

>>> pyvista.set_plot_theme('dark')

Set to the ParaView theme.

>>> pyvista.set_plot_theme('paraview')

pyvista.create_axes_orientation_box(line_width=1, text_scale=0.366667, edge_color='black', x_color=None, y_color=None, z_color=None, xlabel='X', ylabel='Y', zlabel='Z', x_face_color='red', y_face_color='green', z_face_color='blue', color_box=False, label_color=None, labels_off=False, opacity=0.5)¶: Create a Box axes orientation widget with labels.

Base Plotter¶

The base plotter class that all PyVista plotters inherit. Please note that the former BackgroundPlotter class has been moved to the pyvistaqt package.

Attributes

`background_color`	Return the background color of the active render window.
`bounds`	Return the bounds of the active renderer.
`camera`	Return the active camera of the active renderer.
`camera_position`	Return camera position of the active render window.
`camera_set`	Return if the camera of the active renderer has been set.
`center`	Return the center of the active renderer.
`click_position`
`image`	Return an image array of current render window.
`image_depth`	Return a depth image representing current render window.
`length`	Return the length of the diagonal of the bounding box of the scene.
`mouse_position`
`parallel_projection`	Return parallel projection state of active render window.
`parallel_scale`	Return parallel scale of active render window.
`renderer`	Return the active renderer.
`scalar_bar`	First scalar bar.
`scalar_bars`	Scalar bars.
`scale`	Return the scaling of the active renderer.
`shape`	Shape of the plotter.
`store_image`	Return if an image will be saved on close.
`theme`	Return or set the theme used for this plotter.
`window_size`	Return the render window size.

Methods

`add_actor`(uinput[, reset_camera, name, …])	Add an actor to render window.
`add_arrows`(cent, direction[, mag])	Add arrows to the plotter.
`add_axes`([interactive, line_width, color, …])	Add an interactive axes widget in the bottom left corner.
`add_axes_at_origin`([x_color, y_color, …])	Add axes actor at origin.
`add_background_image`(image_path[, scale, …])	Add a background image to a plot.
`add_bounding_box`([color, corner_factor, …])	Add an unlabeled and unticked box at the boundaries of plot.
`add_floor`([face, i_resolution, …])	Show a floor mesh.
`add_key_event`(key, callback)	Add a function to callback when the given key is pressed.
`add_legend`([labels, bcolor, border, size, …])	Add a legend to render window.
`add_light`(light[, only_active])	Add a Light to the scene.
`add_lines`(lines[, color, width, label, name])	Add lines to the plotting object.
`add_mesh`(mesh[, color, style, scalars, …])	Add any PyVista/VTK mesh or dataset that PyVista can wrap to the scene.
`add_orientation_widget`(actor[, interactive, …])	Use the given actor in an orientation marker widget.
`add_point_labels`(points, labels[, italic, …])	Create a point actor with one label from list labels assigned to each point.
`add_point_scalar_labels`(points, labels[, …])	Label the points from a dataset with the values of their scalars.
`add_points`(points, **kwargs)	Add points to a mesh.
`add_scalar_bar`([title, mapper, n_labels, …])	Create scalar bar using the ranges as set by the last input mesh.
`add_text`(text[, position, font_size, color, …])	Add text to plot object in the top left corner by default.
`add_volume`(volume[, scalars, clim, …])	Add a volume, rendered using a smart mapper by default.
`clear`()	Clear plot by removing all actors and properties.
`clear_events_for_key`(key)	Remove the callbacks associated to the key.
`close`([render])	Close the render window.
`deep_clean`()	Clean the plotter of the memory.
`disable`()	Disable this renderer’s camera from being interactive.
`disable_3_lights`()	Please use `enable_lightkit`, this method has been depreciated.
`disable_anti_aliasing`()	Disable anti-aliasing FXAA.
`disable_depth_peeling`()	Disable depth peeling.
`disable_eye_dome_lighting`()	Disable eye dome lighting (EDL).
`disable_parallel_projection`()	Reset the camera to use perspective projection.
`disable_shadows`()	Disable shadows.
`enable`()	Enable this renderer’s camera to be interactive.
`enable_3_lights`([only_active])	Enable 3-lights illumination.
`enable_anti_aliasing`()	Enable anti-aliasing FXAA.
`enable_depth_peeling`([number_of_peels, …])	Enable depth peeling to improve rendering of translucent geometry.
`enable_eye_dome_lighting`()	Enable eye dome lighting (EDL).
`enable_image_style`()	Set the interactive style to image.
`enable_joystick_style`()	Set the interactive style to joystick.
`enable_lightkit`([only_active])	Enable the default light-kit lighting.
`enable_parallel_projection`()	Enable parallel projection.
`enable_rubber_band_2d_style`()	Set the interactive style to rubber band 2d.
`enable_rubber_band_style`()	Set the interactive style to rubber band picking.
`enable_shadows`()	Enable shadows.
`enable_terrain_style`()	Set the interactive style to terrain.
`enable_trackball_actor_style`()	Set the interactive style to trackball actor.
`enable_trackball_style`()	Set the interactive style to trackball camera.
`enable_zoom_style`()	Set the interactive style to rubber band zoom.
`export_obj`(filename)	Export scene to OBJ format.
`export_vtkjs`(filename[, compress_arrays])	Export the current rendering scene as a VTKjs scene.
`fly_to`(point)	Move the current camera’s focal point to a position point.
`generate_orbital_path`([factor, n_points, …])	Generate an orbital path around the data scene.
`get_default_cam_pos`([negative])	Return the default focal points and viewup.
`get_image_depth`([fill_value, …])	Return a depth image representing current render window.
`hide_axes`()	Hide the axes orientation widget.
`hide_axes_all`()	Hide the axes orientation widget in all renderers.
`increment_point_size_and_line_width`(increment)	Increment point size and line width of all actors.
`isometric_view`()	Reset the camera to a default isometric view.
`isometric_view_interactive`()	Set the current interactive render window to isometric view.
`key_press_event`(obj, event)	Listen for key press event.
`left_button_down`(obj, event_type)	Register the event for a left button down click.
`link_views`([views])	Link the views’ cameras.
`open_gif`(filename)	Open a gif file.
`open_movie`(filename[, framerate])	Establish a connection to the ffmpeg writer.
`orbit_on_path`([path, focus, step, viewup, …])	Orbit on the given path focusing on the focus point.
`remove_actor`(actor[, reset_camera, render])	Remove an actor from the Renderer.
`remove_all_lights`([only_active])	Remove all lights from the scene.
`remove_background_image`()	Remove the background image from the current subplot.
`remove_bounding_box`([render])	Remove bounding box.
`remove_bounds_axes`()	Remove bounds axes.
`remove_floors`([clear_kwargs, render])	Remove all floor actors.
`remove_legend`()	Remove the legend actor.
`remove_scalar_bar`([title, render])	Remove a scalar bar.
`render`()	Render the main window.
`reset_camera`([render, bounds])	Reset the camera of the active render window.
`reset_camera_clipping_range`()	Reset camera clipping planes.
`reset_key_events`()	Reset all of the key press events to their defaults.
`save_graphic`(filename[, title, raster, painter])	Save a screenshot of the rendering window as a graphic file.
`screenshot`([filename, …])	Take screenshot at current camera position.
`set_background`(color[, top, all_renderers])	Set the background color.
`set_environment_texture`(texture)	Set the environment texture used for image based lighting.
`set_focus`(point)	Set focus to a point.
`set_position`(point[, reset])	Set camera position to a point.
`set_scale`([xscale, yscale, zscale, reset_camera])	Scale all the datasets in the scene.
`set_viewup`(vector)	Set camera viewup vector.
`show_axes`()	Show the axes orientation widget.
`show_axes_all`()	Show the axes orientation widget in all renderers.
`show_bounds`([mesh, bounds, show_xaxis, …])	Add bounds axes.
`show_grid`(**kwargs)	Show gridlines and axes labels.
`store_click_position`(*args)	Store click position in viewport coordinates.
`store_mouse_position`(*args)	Store mouse position.
`subplot`(index_row[, index_column])	Set the active subplot.
`track_click_position`([callback, side, viewport])	Keep track of the click position.
`track_mouse_position`()	Keep track of the mouse position.
`unlink_views`([views])	Unlink the views’ cameras.
`untrack_click_position`()	Stop tracking the click position.
`untrack_mouse_position`()	Stop tracking the mouse position.
`update`([stime, force_redraw])	Update window, redraw, process messages query.
`update_bounds_axes`()	Update the bounds axes of the render window.
`update_coordinates`(points[, mesh, render])	Update the points of an object in the plotter.
`update_scalar_bar_range`(clim[, name])	Update the value range of the active or named scalar bar.
`update_scalars`(scalars[, mesh, render])	Update scalars of an object in the plotter.
`view_isometric`([negative])	Reset the camera to a default isometric view.
`view_vector`(vector[, viewup])	Point the camera in the direction of the given vector.
`view_xy`([negative])	View the XY plane.
`view_xz`([negative])	View the XZ plane.
`view_yx`([negative])	View the YX plane.
`view_yz`([negative])	View the YZ plane.
`view_zx`([negative])	View the ZX plane.
`view_zy`([negative])	View the ZY plane.
`where_is`(name)	Return the subplot coordinates of a given actor.
`write_frame`()	Write a single frame to the movie file.

class pyvista.BasePlotter(*args, **kwargs)¶

Bases: pyvista.plotting.picking.PickingHelper, pyvista.plotting.widgets.WidgetHelper

To be used by the Plotter and pyvistaqt.QtInteractor classes.

Parameters

shape (list or tuple, optional) –
Number of sub-render windows inside of the main window. Specify two across with shape=(2, 1) and a two by two grid with shape=(2, 2). By default there is only one renderer. Can also accept a string descriptor as shape. E.g.:
- shape="3|1" means 3 plots on the left and 1 on the right,
- shape="4/2" means 4 plots on top and 2 at the bottom.
border (bool, optional) – Draw a border around each render window. Default False.
border_color (string or 3 item list, optional) –
Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
border_width (float, optional) – Width of the border in pixels when enabled.
title (str, optional) – Window title of the scalar bar
lighting (str, optional) –
What lighting to set up for the plotter. Accepted options:
- 'light_kit': a vtk Light Kit composed of 5 lights.
- 'three lights': illumination using 3 lights.
- 'none': no light sources at instantiation.
The default is a Light Kit (to be precise, 5 separate lights that act like a Light Kit).
theme (pyvista.themes.DefaultTheme, optional) – Plot-specific theme.

add_actor(uinput, reset_camera=False, name=None, culling=False, pickable=True, render=True)¶

Add an actor to render window.

Creates an actor if input is a mapper.

Parameters

uinput (vtk.vtkMapper or vtk.vtkActor) – vtk mapper or vtk actor to be added.
reset_camera (bool, optional) – Resets the camera when true.
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. Default False.

Returns

actor (vtk.vtkActor) – The actor.
actor_properties (vtk.Properties) – Actor properties.

add_arrows(cent, direction, mag=1, **kwargs)¶

Add arrows to the plotter.

Parameters

cent (np.ndarray) – Array of centers.
direction (np.ndarray) – Array of direction vectors.
mag (float, optional) – Amount to scale the direction vectors.

Examples

Plot a random field of vectors and save a screenshot of it.

>>> import numpy as np
>>> import pyvista
>>> cent = np.random.random((10, 3))
>>> direction = np.random.random((10, 3))
>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_arrows(cent, direction, mag=2)
>>> cpos = plotter.show()

add_axes(interactive=None, line_width=2, color=None, x_color=None, y_color=None, z_color=None, xlabel='X', ylabel='Y', zlabel='Z', labels_off=False, box=None, box_args=None)¶

Add an interactive axes widget in the bottom left corner.

Parameters

interacitve (bool) – Enable this orientation widget to be moved by the user.
line_width (int) – The width of the marker lines
box (bool) – Show a box orientation marker. Use box_args to adjust. See pyvista.create_axes_orientation_box for details.
opacity (int or float, optional) – The opacity of the marker.

add_axes_at_origin(x_color=None, y_color=None, z_color=None, xlabel='X', ylabel='Y', zlabel='Z', line_width=2, labels_off=False)¶

Add axes actor at origin.

Returns: marker_actor – vtkAxesActor actor
Return type: vtk.vtkAxesActor

add_background_image(image_path, scale=1, auto_resize=True, as_global=True)¶

Add a background image to a plot.

Parameters

image_path (str) – Path to an image file.
scale (float, optional) – Scale the image larger or smaller relative to the size of the window. For example, a scale size of 2 will make the largest dimension of the image twice as large as the largest dimension of the render window. Defaults to 1.
auto_resize (bool, optional) – Resize the background when the render window changes size.
as_global (bool, optional) – When multiple render windows are present, setting as_global=False will cause the background to only appear in one window.

Examples

>>> import pyvista
>>> from pyvista import examples
>>> plotter = pyvista.Plotter()
>>> actor = plotter.add_mesh(pyvista.Sphere())
>>> plotter.add_background_image(examples.mapfile)
>>> cpos = plotter.show()

add_bounding_box(color='grey', corner_factor=0.5, line_width=None, opacity=1.0, render_lines_as_tubes=False, lighting=None, reset_camera=None, outline=True, culling='front')¶

Add an unlabeled and unticked box at the boundaries of plot.

Useful for when wanting to plot outer grids while still retaining all edges of the boundary.

Parameters

corner_factor (float, optional) – If all_edges, this is the factor along each axis to draw the default box. Dafuault is 0.5 to show the full box.
corner_factor – This is the factor along each axis to draw the default box. Dafuault is 0.5 to show the full box.
line_width (float, optional) – Thickness of lines.
opacity (float, optional) – Opacity of mesh. Should be between 0 and 1. Default 1.0
outline (bool) – Default is True. when False, a box with faces is shown with the specified culling
culling (str, optional) – Does not render faces that are culled. Options are 'front' or 'back'. Default is 'front' for bounding box.

add_box_widget(callback, bounds=None, factor=1.25, rotation_enabled=True, color=None, use_planes=False, outline_translation=True, pass_widget=False)¶

Add a box widget to the scene.

This is useless without a callback function. You can pass a callable function that takes a single argument, the PolyData box output from this widget, and performs a task with that box.

Parameters

callback (callable) – The method called every time the box is updated. This has two options: Take a single argument, the PolyData box (default) or if use_planes=True, then it takes a single argument of the plane collection as a vtkPlanes object.
bounds (tuple(float)) – Length 6 tuple of the bounding box where the widget is placed.
factor (float, optional) – An inflation factor to expand on the bounds when placing
rotation_enabled (bool) – If False, the box widget cannot be rotated and is strictly orthogonal to the cartesian axes.
color (string or 3 item list, optional, defaults to white) – Either a string, rgb list, or hex color string.
use_planes (bool, optional) – Changes the arguments passed to the callback to the planes that make up the box.
outline_translation (bool) – If False, the box widget cannot be translated and is strictly placed at the given bounds.
pass_widget (bool) – If true, the widget will be passed as the last argument of the callback

add_checkbox_button_widget(callback, value=False, position=(10.0, 10.0), size=50, border_size=5, color_on='blue', color_off='grey', background_color='white')¶

Add a checkbox button widget to the scene.

This is useless without a callback function. You can pass a callable function that takes a single argument, the state of this button widget and performs a task with that value.

Parameters

callback (callable) – The method called every time the button is clicked. This should take a single parameter: the bool value of the button
value (bool) – The default state of the button
position (tuple(float)) – The absolute coordinates of the bottom left point of the button
size (int) – The size of the button in number of pixels
border_size (int) – The size of the borders of the button in pixels
color_on (string or 3 item list, optional) – The color used when the button is checked. Default is ‘blue’
color_off (string or 3 item list, optional) – The color used when the button is not checked. Default is ‘grey’
background_color (string or 3 item list, optional) – The background color of the button. Default is ‘white’

Returns

button_widget – The VTK button widget configured as a checkbox button.

Return type

vtk.vtkButtonWidget

add_floor(face='-z', i_resolution=10, j_resolution=10, color=None, line_width=None, opacity=1.0, show_edges=False, lighting=False, edge_color=None, reset_camera=None, pad=0.0, offset=0.0, pickable=False, store_floor_kwargs=True)¶

Show a floor mesh.

This generates planes at the boundaries of the scene to behave like floors or walls.

Parameters

face (str, optional) – The face at which to place the plane. Options are ('-z', '-y', '-x', '+z', '+y', and '+z'). Where the -/+ sign indicates on which side of the axis the plane will lie. For example, '-z' would generate a floor on the XY-plane and the bottom of the scene (minimum z).
i_resolution (int, optional) – Number of points on the plane in the i direction.
j_resolution (int, optional) – Number of points on the plane in the j direction.
color (string or 3 item list, optional) – Color of all labels and axis titles. Default gray. Either a string, rgb list, or hex color string.
line_width (int, optional) – Thickness of the edges. Only if show_edges is True.
opacity (float, optional) – The opacity of the generated surface.
show_edges (bool, optional) – Flag on whether to show the mesh edges for tiling.
ine_width (float, optional) – Thickness of lines. Only valid for wireframe and surface representations. Default None.
lighting (bool, optional) – Enable or disable view direction lighting. Default False.
edge_color (string or 3 item list, optional) – Color of of the edges of the mesh.
pad (float, optional) – Percentage padding between 0 and 1.
offset (float, optional) – Percentage offset along plane normal.

Examples

Add a floor below a sphere and plot it.

>>> import pyvista
>>> pl = pyvista.Plotter()
>>> actor = pl.add_mesh(pyvista.Sphere())
>>> actor = pl.add_floor()
>>> cpos = pl.show()

add_key_event(key, callback)¶

Add a function to callback when the given key is pressed.

These are non-unique - thus a key could map to many callback functions. The callback function must not have any arguments.

Parameters

key (str) – The key to trigger the event
callback (callable) – A callable that takes no arguments

add_legend(labels=None, bcolor=(0.5, 0.5, 0.5), border=False, size=None, name=None, origin=None)¶

Add a legend to render window.

Entries must be a list containing one string and color entry for each item.

Parameters

labels (list, optional) –
When set to None, uses existing labels as specified by
- add_mesh
- add_lines
- add_points
List containing one entry for each item to be added to the legend. Each entry must contain two strings, [label, color], where label is the name of the item to add, and color is the color of the label to add.
bcolor (list or string, optional) – Background color, either a three item 0 to 1 RGB color list, or a matplotlib color string (e.g. ‘w’ or ‘white’ for a white color). If None, legend background is disabled.
border (bool, optional) – Controls if there will be a border around the legend. Default False.
size (list, optional) – Two float list, each float between 0 and 1. For example [0.1, 0.1] would make the legend 10% the size of the entire figure window.
name (str, 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.
origin (list, optional) – If used, specifies the x and y position of the lower left corner of the legend.

Returns

legend – Actor for the legend.

Return type

vtk.vtkLegendBoxActor

Examples

>>> import pyvista
>>> from pyvista import examples
>>> mesh = examples.load_hexbeam()
>>> othermesh = examples.load_uniform()
>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_mesh(mesh, label='My Mesh')
>>> _ = plotter.add_mesh(othermesh, 'k', label='My Other Mesh')
>>> _ = plotter.add_legend()
>>> cpos = plotter.show()

Alternative manual example

>>> import pyvista
>>> from pyvista import examples
>>> mesh = examples.load_hexbeam()
>>> othermesh = examples.load_uniform()
>>> legend_entries = []
>>> legend_entries.append(['My Mesh', 'w'])
>>> legend_entries.append(['My Other Mesh', 'k'])
>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_mesh(mesh)
>>> _ = plotter.add_mesh(othermesh, 'k')
>>> _ = plotter.add_legend(legend_entries)
>>> cpos = plotter.show()

add_light(light, only_active=False)¶

Add a Light to the scene.

Parameters

light (Light or vtkLight) – The light to be added.
only_active (bool, optional) – If True, only add the light to the active renderer. The default is that every renderer adds the light. To add the light to an arbitrary renderer, see the add_light method of the Renderer class.

Examples

Create a plotter that we initialize with no lights, and add a cube and a single headlight to it.

>>> import pyvista as pv
>>> plotter = pv.Plotter(lighting='none')
>>> _ = plotter.add_mesh(pv.Cube())
>>> light = pv.Light(color='cyan', light_type='headlight')
>>> plotter.add_light(light)
>>> cpos = plotter.show()

add_line_widget(callback, bounds=None, factor=1.25, resolution=100, color=None, use_vertices=False, pass_widget=False)¶

Add a line widget to the scene.

This is useless without a callback function. You can pass a callable function that takes a single argument, the PolyData line output from this widget, and performs a task with that line.

Parameters

callback (callable) – The method called every time the line is updated. This has two options: Take a single argument, the PolyData line (default) or if use_vertices=True, then it can take two arguments of the coordinates of the line’s end points.
bounds (tuple(float)) – Length 6 tuple of the bounding box where the widget is placed.
factor (float, optional) – An inflation factor to expand on the bounds when placing
resolution (int) – The number of points in the line created
color (string or 3 item list, optional, defaults to white) – Either a string, rgb list, or hex color string.
use_vertices (bool, optional) – Changess the arguments of the callback method to take the end points of the line instead of a PolyData object.
pass_widget (bool) – If true, the widget will be passed as the last argument of the callback

add_lines(lines, color=(1, 1, 1), width=5, label=None, name=None)¶

Add lines to the plotting object.

Parameters

lines (np.ndarray or pyvista.PolyData) –
Points representing line segments. For example, two line segments would be represented as:

np.array([[0, 0, 0], [1, 0, 0], [1, 0, 0], [1, 1, 0]])
color (string or 3 item list, optional, defaults to white) –
Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
width (float, optional) – Thickness of lines
name (str, 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.

Returns

actor – Lines actor.

Return type

vtk.vtkActor

add_mesh(mesh, color=None, style=None, scalars=None, clim=None, show_edges=None, edge_color=None, point_size=5.0, line_width=None, opacity=1.0, flip_scalars=False, lighting=None, n_colors=256, interpolate_before_map=True, 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=False, smooth_shading=None, ambient=0.0, diffuse=1.0, specular=0.0, specular_power=100.0, nan_color=None, nan_opacity=1.0, culling=None, rgb=False, categories=False, silhouette=False, use_transparency=False, below_color=None, above_color=None, annotations=None, pickable=True, preference='point', log_scale=False, pbr=False, metallic=0.0, roughness=0.5, render=True, component=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.BasePlotter.add_volume().

Parameters

mesh (pyvista.DataSet or pyvista.MultiBlock) – Any PyVista or VTK mesh is supported. Also, any dataset that pyvista.wrap() can handle including NumPy arrays of XYZ points.
color (string or 3 item list, optional, defaults to white) – 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, 1, 1], or color='#FFFFFF'. Color will be overridden if scalars are specified.
style (string, optional) – Visualization style of the mesh. One of the following: style='surface', style='wireframe', style='points'. Defaults to 'surface'. Note that 'wireframe' only shows a wireframe of the outer geometry.
scalars (str 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 both color and scalars are None, then the active scalars are used.
clim (2 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.
show_edges (bool, optional) – Shows the edges of a mesh. Does not apply to a wireframe representation.
edge_color (string or 3 item list, optional, defaults to black) – The solid color to give the edges when show_edges=True. Either a string, RGB list, or hex color string.
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 the scalars argument). Or you can pass a custom made transfer function that is an array either n_colors in length or shorter.
flip_scalars (bool, optional) – Flip direction of cmap. Most colormaps allow *_r suffix to do this as well.
lighting (bool, 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_map (bool, optional) – Enabling makes for a smoother scalars display. Default is True. When False, OpenGL will interpolate the mapped colors which can result is showing colors that are not present in the color map.
cmap (str, list, optional) –
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']
label (str, optional) – String label to use when adding a legend to the scene with pyvista.BasePlotter.add_legend()
reset_camera (bool, optional) – Reset the camera after adding this mesh to the scene
scalar_bar_args (dict, optional) – Dictionary of keyword arguments to pass when adding the scalar bar to the scene. For options, see pyvista.BasePlotter.add_scalar_bar().
show_scalar_bar (bool) – If False, a scalar bar will not be added to the scene. Defaults to True.
multi_colors (bool, optional) – If a MultiBlock dataset is given this will color each block by a solid color using matplotlib’s color cycler.
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 (vtk.vtkTexture or np.ndarray or boolean, optional) – A texture to apply if the input mesh has texture coordinates. This will not work with MultiBlock datasets. If set to True, the first available texture on the object will be used. If a string name is given, it will pull a texture with that name associated to the input mesh.
render_points_as_spheres (bool, optional) – Render points as spheres rather than dots.
render_lines_as_tubes (bool, optional) – Show lines as thick tubes rather than flat lines. Control the width with line_width.
smooth_shading (bool, optional) – Enable smooth shading when True using either the Gouraud or Phong shading algorithm. When False, use flat shading. Automatically enabled when pbr=True.
ambient (float, 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
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 (string or 3 item list, optional, defaults to gray) – 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 to False.
rgb (bool, 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.
categories (bool, optional) – If set to True, then the number of unique values in the scalar array will be used as the n_colors argument.
silhouette (dict, bool, optional) –
If set to True, plot a silhouette highlight for the mesh. This feature is only available for a triangulated PolyData. As a dict, it contains the properties of the silhouette to display:
- color: str or 3-item list, color of the silhouette
- line_width: float, edge width
- opacity: float between 0 and 1, edge transparency
- feature_angle: If a float, display sharp edges exceeding that angle in degrees.
- decimate: float between 0 and 1, level of decimation
use_transparency (bool, optional) – Invert the opacity mappings and make the values correspond to transparency.
below_color (string or 3 item list, optional) – Solid color for values below the scalars range (clim). This will automatically set the scalar bar below_label to 'Below'.
above_color (string or 3 item list, optional) – Solid color for values below the scalars range (clim). This will automatically set the scalar bar above_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 the string annotations.
pickable (bool, optional) – Set whether this mesh is pickable.
log_scale (bool, optional) – Use log scale when mapping data to colors. Scalars less than zero are mapped to the smallest representable positive float. Default: True.
pbr (bool, optional) – Enable physics based rendering (PBR) if the mesh is PolyData. Use the color argument to set the base color. This is only available in VTK>=9.
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. Default value is 0.0.
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. Default value is 0.5.
render (bool, optional) – Force a render when True. Default True.
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.

Returns

actor – VTK actor of the mesh.

Return type

vtk.vtkActor

Examples

Add a sphere to the plotter and show it with a custom scalar bar title.

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> sphere['Data'] = sphere.points[:, 2]
>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_mesh(sphere,
...                      scalar_bar_args={'title': 'Z Position'})
>>> cpos = plotter.show()

add_mesh_clip_box(mesh, invert=False, rotation_enabled=True, widget_color=None, outline_translation=True, **kwargs)¶

Clip a mesh using a box widget.

Add a mesh to the scene with a box widget that is used to clip the mesh interactively.

The clipped mesh is saved to the .box_clipped_meshes attribute on the plotter.

Parameters

mesh (pyvista.DataSet) – The input dataset to add to the scene and clip
invert (bool) – Flag on whether to flip/invert the clip
rotation_enabled (bool) – If False, the box widget cannot be rotated and is strictly orthogonal to the cartesian axes.
kwargs (dict) – All additional keyword arguments are passed to add_mesh to control how the mesh is displayed.

add_mesh_clip_plane(mesh, normal='x', invert=False, widget_color=None, value=0.0, assign_to_axis=None, tubing=False, origin_translation=True, outline_translation=False, implicit=True, normal_rotation=True, **kwargs)¶

Clip a mesh using a plane widget.

Add a mesh to the scene with a plane widget that is used to clip the mesh interactively.

The clipped mesh is saved to the .plane_clipped_meshes attribute on the plotter.

Parameters

mesh (pyvista.DataSet) – The input dataset to add to the scene and clip
normal (str or tuple(float)) – The starting normal vector of the plane
invert (bool) – Flag on whether to flip/invert the clip
widget_color (string or 3 item list, optional, defaults to white) – Either a string, rgb list, or hex color string.
value (float, optional) – Set the clipping value along the normal direction. The default value is 0.0.
assign_to_axis (str or int) – Assign the normal of the plane to be parallel with a given axis: options are (0, ‘x’), (1, ‘y’), or (2, ‘z’).
tubing (bool) – When using an implicit plane wiget, this controls whether or not tubing is shown around the plane’s boundaries.
outline_translation (bool) – If False, the plane widget cannot be translated and is strictly placed at the given bounds. Only valid when using an implicit plane.
origin_translation (bool) – If False, the plane widget cannot be translated by its origin and is strictly placed at the given origin. Only valid when using an implicit plane.
implicit (bool) – When True, a vtkImplicitPlaneWidget is used and when False, a vtkPlaneWidget is used.
normal_rotation (bool) – Set the opacity of the normal vector arrow to 0 such that it is effectively disabled. This prevents the user from rotating the normal. This is forced to False when assign_to_axis is set.
kwargs (dict) – All additional keyword arguments are passed to add_mesh to control how the mesh is displayed.

add_mesh_isovalue(mesh, scalars=None, compute_normals=False, compute_gradients=False, compute_scalars=True, preference='point', title=None, pointa=(0.4, 0.9), pointb=(0.9, 0.9), widget_color=None, **kwargs)¶

Create a contour of a mesh with a slider.

Add a mesh to the scene with a slider widget that is used to contour at an isovalue of the point data on the mesh interactively.

The isovalue mesh is saved to the .isovalue_meshes attribute on the plotter.

Parameters

mesh (pyvista.DataSet) – The input dataset to add to the scene and contour
scalars (str) – The string name of the scalars on the mesh to contour and display
kwargs (dict) – All additional keyword arguments are passed to add_mesh to control how the mesh is displayed.

add_mesh_slice(mesh, normal='x', generate_triangles=False, widget_color=None, assign_to_axis=None, tubing=False, origin_translation=True, outline_translation=False, implicit=True, normal_rotation=True, **kwargs)¶

Slice a mesh using a plane widget.

Add a mesh to the scene with a plane widget that is used to slice the mesh interactively.

The sliced mesh is saved to the .plane_sliced_meshes attribute on the plotter.

Parameters

mesh (pyvista.DataSet) – The input dataset to add to the scene and slice
normal (str or tuple(float)) – The starting normal vector of the plane
generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.
widget_color (string or 3 item list, optional, defaults to white) – Either a string, rgb list, or hex color string.
assign_to_axis (str or int) – Assign the normal of the plane to be parallel with a given axis: options are (0, ‘x’), (1, ‘y’), or (2, ‘z’).
tubing (bool) – When using an implicit plane wiget, this controls whether or not tubing is shown around the plane’s boundaries.
outline_translation (bool) – If False, the plane widget cannot be translated and is strictly placed at the given bounds. Only valid when using an implicit plane.
origin_translation (bool) – If False, the plane widget cannot be translated by its origin and is strictly placed at the given origin. Only valid when using an implicit plane.
implicit (bool) – When True, a vtkImplicitPlaneWidget is used and when False, a vtkPlaneWidget is used.
normal_rotation (bool) – Set the opacity of the normal vector arrow to 0 such that it is effectively disabled. This prevents the user from rotating the normal. This is forced to False when assign_to_axis is set.

kwargsdict: All additional keyword arguments are passed to add_mesh to control how the mesh is displayed.

add_mesh_slice_orthogonal(mesh, generate_triangles=False, widget_color=None, tubing=False, **kwargs)¶

Slice a mesh with three interactive planes.

Adds three interactive plane slicing widgets for orthogonal slicing along each cartesian axis.

add_mesh_slice_spline(mesh, generate_triangles=False, n_handles=5, resolution=25, widget_color=None, show_ribbon=False, ribbon_color='pink', ribbon_opacity=0.5, initial_points=None, closed=False, **kwargs)¶

Slice a mesh with a spline widget.

Add a mesh to the scene with a spline widget that is used to slice the mesh interactively.

The sliced mesh is saved to the .spline_sliced_meshes attribute on the plotter.

Parameters

mesh (pyvista.DataSet) – The input dataset to add to the scene and slice along the spline
generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.
kwargs (dict) – All additional keyword arguments are passed to add_mesh to control how the mesh is displayed.

add_mesh_threshold(mesh, scalars=None, invert=False, widget_color=None, preference='cell', title=None, pointa=(0.4, 0.9), pointb=(0.9, 0.9), continuous=False, **kwargs)¶

Apply a threshold on a mesh with a slider.

Add a mesh to the scene with a slider widget that is used to threshold the mesh interactively.

The threshold mesh is saved to the .threshold_meshes attribute on the plotter.

Parameters

mesh (pyvista.DataSet) – The input dataset to add to the scene and threshold
scalars (str) – The string name of the scalars on the mesh to threshold and display
invert (bool) – Invert/flip the threshold
kwargs (dict) – All additional keyword arguments are passed to add_mesh to control how the mesh is displayed.

add_orientation_widget(actor, interactive=None, color=None, opacity=1.0)¶

Use the given actor in an orientation marker widget.

Color and opacity are only valid arguments if a mesh is passed.

Parameters

actor (vtk.vtkActor or pyvista.DataSet) – The mesh or actor to use as the marker.
color (string, optional) – The color of the actor.
opacity (int or float, optional) – Opacity of the marker.

add_plane_widget(callback, normal='x', origin=None, bounds=None, factor=1.25, color=None, assign_to_axis=None, tubing=False, outline_translation=False, origin_translation=True, implicit=True, pass_widget=False, test_callback=True, normal_rotation=True)¶

Add a plane widget to the scene.

This is useless without a callback function. You can pass a callable function that takes two arguments, the normal and origin of the plane in that order output from this widget, and performs a task with that plane.

Parameters

callback (callable) – The method called every time the plane is updated. Takes two arguments, the normal and origin of the plane in that order.
normal (str or tuple(float)) – The starting normal vector of the plane
origin (tuple(float)) – The starting coordinate of the center of the place
bounds (tuple(float)) – Length 6 tuple of the bounding box where the widget is placed.
factor (float, optional) – An inflation factor to expand on the bounds when placing
color (string or 3 item list, optional, defaults to white) – Either a string, rgb list, or hex color string.
assign_to_axis (str or int) – Assign the normal of the plane to be parallel with a given axis: options are (0, ‘x’), (1, ‘y’), or (2, ‘z’).
tubing (bool) – When using an implicit plane wiget, this controls whether or not tubing is shown around the plane’s boundaries.
outline_translation (bool) – If False, the plane widget cannot be translated and is strictly placed at the given bounds. Only valid when using an implicit plane.
origin_translation (bool) – If False, the plane widget cannot be translated by its origin and is strictly placed at the given origin. Only valid when using an implicit plane.
implicit (bool) – When True, a vtkImplicitPlaneWidget is used and when False, a vtkPlaneWidget is used.
pass_widget (bool) – If true, the widget will be passed as the last argument of the callback
test_callback (bool) – If true, run the callback function after the widget is created.
normal_rotation (bool) – Set the opacity of the normal vector arrow to 0 such that it is effectively disabled. This prevents the user from rotating the normal. This is forced to False when assign_to_axis is set.

add_point_labels(points, labels, italic=False, bold=True, font_size=None, text_color=None, font_family=None, shadow=False, show_points=True, point_color=None, point_size=5, name=None, shape_color='grey', shape='rounded_rect', fill_shape=True, margin=3, shape_opacity=1.0, pickable=False, render_points_as_spheres=False, tolerance=0.001, reset_camera=None, always_visible=False, render=True)¶

Create a point actor with one label from list labels assigned to each point.

Parameters

points (np.ndarray or pyvista.DataSet) – n x 3 numpy array of points or pyvista dataset with points
labels (list or str) – List of labels. Must be the same length as points. If a string name is given with a pyvista.DataSet input for points, then these are fetched.
italic (bool, optional) – Italicises title and bar labels. Default False.
bold (bool, optional) – Bolds title and bar labels. Default True
font_size (float, optional) – Sets the size of the title font. Defaults to 16.
text_color (string or 3 item list, optional) –
Color of text. Either a string, rgb list, or hex color string.

text_color=’white’ text_color=’w’ text_color=[1, 1, 1] text_color=’#FFFFFF’
font_family (string, optional) – Font family. Must be either courier, times, or arial.
shadow (bool, optional) – Adds a black shadow to the text. Defaults to False
show_points (bool, optional) – Controls if points are visible. Default True
point_color (string or 3 item list, optional. Color of points (if visible)) –
Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
point_size (float, optional) – Size of points (if visible)
name (str, 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.
shape_color (string or 3 item list, optional. Color of points (if visible)) – Either a string, rgb list, or hex color string. For example:
shape (str, optional) – The string name of the shape to use. Options are 'rect' or 'rounded_rect'. If you want no shape, pass None
fill_shape (bool, optional) – Fill the shape with the shape_color. Outlines if False.
margin (int, optional) – The size of the margin on the label background shape. Default is 3.
shape_opacity (float) – The opacity of the shape between zero and one.
tolerance (float) – a tolerance to use to determine whether a point label is visible. A tolerance is usually required because the conversion from world space to display space during rendering introduces numerical round-off.
reset_camera (bool, optional) – Reset the camera after adding the points to the scene.
always_visible (bool, optional) – Skip adding the visibility filter. Default False.
render (bool, optional) – Force a render when True (default).

Returns

labelActor – VTK label actor. Can be used to change properties of the labels.

Return type

vtk.vtkActor2D

add_point_scalar_labels(points, labels, fmt=None, preamble='', **kwargs)¶

Label the points from a dataset with the values of their scalars.

Wrapper for pyvista.BasePlotter.add_point_labels().

Parameters

points (np.ndarray or pyvista.DataSet) – n x 3 numpy array of points or pyvista dataset with points
labels (str) – String name of the point data array to use.
fmt (str) – String formatter used to format numerical data.

add_points(points, **kwargs)¶: Add points to a mesh.

add_scalar_bar(title='', mapper=None, n_labels=5, italic=False, bold=False, title_font_size=None, label_font_size=None, color=None, font_family=None, shadow=False, width=None, height=None, position_x=None, position_y=None, vertical=None, interactive=None, fmt=None, use_opacity=True, outline=False, nan_annotation=False, below_label=None, above_label=None, background_color=None, n_colors=None, fill=False, render=False)¶

Create scalar bar using the ranges as set by the last input mesh.

Parameters

title (string, optional) – Title of the scalar bar. Default '' which is rendered as an empty title.
mapper (vtkMapper, optional) – Mapper used for the scalar bar. Defaults to the last mapper created by the plotter.
n_labels (int, optional) – Number of labels to use for the scalar bar.
italic (bool, optional) – Italicises title and bar labels. Default False.
bold (bool, optional) – Bolds title and bar labels. Default True
title_font_size (float, optional) – Sets the size of the title font. Defaults to None and is sized according to pyvista.global_theme.
label_font_size (float, optional) – Sets the size of the title font. Defaults to None and is sized according to pyvista.global_theme.
color (string or 3 item list, optional) –
Either a string, rgb list, or hex color string. Defaults to white. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
font_family ({'courier', 'times', 'arial'}) – Font family. Default is set by pyvista.global_theme.
shadow (bool, optional) – Adds a black shadow to the text. Defaults to False.
width (float, optional) – The percentage (0 to 1) width of the window for the colorbar. Default set by pyvista.global_theme.
height (float, optional) – The percentage (0 to 1) height of the window for the colorbar. Default set by pyvista.global_theme.
position_x (float, optional) – The percentage (0 to 1) along the windows’s horizontal direction to place the bottom left corner of the colorbar. Default is automatic placement.
position_y (float, optional) – The percentage (0 to 1) along the windows’s vertical direction to place the bottom left corner of the colorbar. Default is automatic placement.
vertical (bool, optional) – Use vertical or horizontal scalar bar. Default set by pyvista.global_theme.
interactive (bool, optional) – Use a widget to control the size and location of the scalar bar. Default set by pyvista.global_theme.
fmt (str, optional) – printf format for labels. Default set by pyvista.global_theme.
use_opacity (bool, optional) – Optionally display the opacity mapping on the scalar bar.
outline (bool, optional) – Optionally outline the scalar bar to make opacity mappings more obvious.
nan_annotation (bool, optional) – Annotate the NaN color.
below_label (str, optional) – String annotation for values below the scalars range.
above_label (str, optional) – String annotation for values above the scalars range.
background_color (array, optional) – The color used for the background in RGB format.
n_colors (int, optional) – The maximum number of color displayed in the scalar bar.
fill (bool, optional) – Draw a filled box behind the scalar bar with the background_color.
render (bool, optional) – Force a render when True. Default True.

Examples

Add a custom interactive scalar bar that is horizontal, has an outline, and has a custom formatting.

>>> import pyvista as pv
>>> sphere = pv.Sphere()
>>> sphere['Data'] = sphere.points[:, 2]
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(sphere, show_scalar_bar=False)
>>> _ = plotter.add_scalar_bar('Data', interactive=True, vertical=False,
...                            outline=True, fmt='%10.5f')

Notes

Setting title_font_size, or label_font_size disables automatic font sizing for both the title and label.

add_slider_widget(callback, rng, value=None, title=None, pointa=(0.4, 0.9), pointb=(0.9, 0.9), color=None, pass_widget=False, event_type='end', style=None, title_height=0.03, title_opacity=1.0, title_color=None, fmt=None)¶

Add a slider bar widget.

This is useless without a callback function. You can pass a callable function that takes a single argument, the value of this slider widget, and performs a task with that value.

Parameters

callback (callable) – The method called every time the slider is updated. This should take a single parameter: the float value of the slider.
rng (tuple(float)) – Length two tuple of the minimum and maximum ranges of the slider.
value (float, optional) – The starting value of the slider.
title (str, optional) – The string label of the slider widget.
pointa (tuple(float), optional) – The relative coordinates of the left point of the slider on the display port.
pointb (tuple(float)) – The relative coordinates of the right point of the slider on the display port
color (string or 3 item list, optional) – Either a string, rgb list, or hex color string.
pass_widget (bool, optional) – If True, the widget will be passed as the last argument of the callback.
event_type (str, optional) – Either 'start', 'end' or 'always', this defines how often the slider interacts with the callback.
style (str, optional) – The name of the slider style. The list of available styles are in pyvista.global_theme.slider_styles. Defaults to None.
title_height (float, optional) – Relative height of the title as compared to the length of the slider.
title_opacity (str, optional) – Opacity of title. Defaults to 1.0.
title_color (string or 3 item list, optional) – Either a string, rgb list, or hex color string. Defaults to the value given in color.
fmt (str, optional) – String formatter used to format numerical data. Defaults to None.

Examples

>>> import pyvista as pv
>>> pl = pv.Plotter()
>>> def create_mesh(value):
...     res = int(value)
...     sphere = pv.Sphere(phi_resolution=res, theta_resolution=res)
...     pl.add_mesh(sphere, name="sphere", show_edges=True)
>>> slider = pl.add_slider_widget(
...     create_mesh,
...     [5, 100],
...     title="Resolution",
...     title_opacity=0.5,
...     title_color="red",
...     fmt="%0.9f",
...     title_height=0.08,
... )
>>> cpos = pl.show()

add_sphere_widget(callback, center=(0, 0, 0), radius=0.5, theta_resolution=30, phi_resolution=30, color=None, style='surface', selected_color='pink', indices=None, pass_widget=False, test_callback=True)¶

Add one or many sphere widgets to a scene.

Use a sphere widget to control a vertex location.

Parameters

callback (callable) – The function to call back when the widget is modified. It takes a single argument: the center of the sphere as an XYZ coordinate (a 3-length sequence). If multiple centers are passed in the center parameter, the callback must also accept an index of that widget.
center (tuple(float), optional) – Length 3 array for the XYZ coordinate of the sphere’s center when placing it in the scene. If more than one location is passed, then that many widgets will be added and the callback will also be passed the integer index of that widget.
radius (float, optional) – The radius of the sphere.
theta_resolution (int, optional) – Set the number of points in the longitude direction.
phi_resolution (int, optional) – Set the number of points in the latitude direction.
color (string or 3 item iterable, optional) –
The color of the sphere’s surface. If multiple centers are passed, then this must be a list of colors. Each color is either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
style (str, optional) – Representation style: 'surface' or 'wireframe'.
selected_color (str, optional) – Color of the widget when selected during interaction.
pass_widget (bool, optional) – If True, the widget will be passed as the last argument of the callback.
test_callback (bool, optional) – if True, run the callback function after the widget is created.

add_spline_widget(callback, bounds=None, factor=1.25, n_handles=5, resolution=25, color='yellow', show_ribbon=False, ribbon_color='pink', ribbon_opacity=0.5, pass_widget=False, closed=False, initial_points=None)¶

Create and add a spline widget to the scene.

Use the bounds argument to place this widget. Several “handles” are used to control a parametric function for building this spline. Click directly on the line to translate the widget.

Note

This widget has trouble displaying certain colors. Use only simple colors (white, black, yellow).

Parameters

callback (callable) – The method called every time the spline is updated. This passes a pyvista.PolyData object to the callback function of the generated spline.
bounds (tuple(float)) – Length 6 tuple of the bounding box where the widget is placed.
factor (float, optional) – An inflation factor to expand on the bounds when placing
n_handles (int) – The number of interactive spheres to control the spline’s parametric function.
resolution (int) – The number of points in the spline created between all the handles
color (string or 3 item list, optional, defaults to white) – Either a string, rgb list, or hex color string.
show_ribbon (bool) – If True, the poly plane used for slicing will also be shown.
pass_widget (bool) – If true, the widget will be passed as the last argument of the callback
closed (bool) – Make the spline a closed loop.
initial_points (np.ndarray) – The points to initialize the widget placement. Must have same number of elements as n_handles. If the first and last point are the same, this will be a closed loop spline.

add_text(text, position='upper_left', font_size=18, color=None, font=None, shadow=False, name=None, viewport=False)¶

Add text to plot object in the top left corner by default.

Parameters

text (str) – The text to add the rendering
position (str, tuple(float)) – Position to place the bottom left corner of the text box. If tuple is used, the position of the text uses the pixel coordinate system (default). In this case, it returns a more general vtkOpenGLTextActor. If string name is used, it returns a vtkCornerAnnotation object normally used for fixed labels (like title or xlabel). Default is to find the top left corner of the rendering window and place text box up there. Available position: 'lower_left', 'lower_right', 'upper_left', 'upper_right', 'lower_edge', 'upper_edge', 'right_edge', and 'left_edge'
font (string, optional) – Font name may be courier, times, or arial
shadow (bool, optional) – Adds a black shadow to the text. Defaults to False
name (str, 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.
viewport (bool) – If True and position is a tuple of float, uses the normalized viewport coordinate system (values between 0.0 and 1.0 and support for HiDPI).

Returns

textActor – Text actor added to plot

Return type

vtk.vtkTextActor

add_text_slider_widget(callback, data, value=None, pointa=(0.4, 0.9), pointb=(0.9, 0.9), color=None, event_type='end', style=None)¶

Add a text slider bar widget.

This is useless without a callback function. You can pass a callable function that takes a single argument, the value of this slider widget, and performs a task with that value.

Parameters

callback (callable) – The method called every time the slider is updated. This should take a single parameter: the float value of the slider
data (list) – The list of possible values displayed on the slider bar
value (float, optional) – The starting value of the slider
pointa (tuple(float)) – The relative coordinates of the left point of the slider on the display port
pointb (tuple(float)) – The relative coordinates of the right point of the slider on the display port
color (string or 3 item list, optional, defaults to white) – Either a string, rgb list, or hex color string.
event_type (str) – Either ‘start’, ‘end’ or ‘always’, this defines how often the slider interacts with the callback.
style (str, optional) – The name of the slider style. The list of available styles are in pyvista.global_theme.slider_styles. Defaults to None.

Returns

slider_widget – The VTK slider widget configured to display text.

Return type

vtk.vtkSliderWidget

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.

Parameters

volume (3D numpy.ndarray or pyvista.UniformGrid) – The input volume to visualize. 3D numpy arrays are accepted.
scalars (str 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.
clim (2 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.
opacity (string 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_colors (int, optional) – Number of colors to use when displaying scalars. Defaults to 256. The scalar bar will also have this many colors.
cmap (str, optional) – Name of the Matplotlib colormap to us 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.
flip_scalars (bool, optional) – Flip direction of cmap. Most colormaps allow *_r suffix to do this as well.
reset_camera (bool, optional) – Reset the camera after adding this mesh to the scene
name (str, 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.
ambient (float, 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.
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 False.
categories (bool, optional) – If set to True, then the number of unique values in the scalar array will be used as the n_colors argument.
multi_colors (bool, optional) – Whether or not to use multiple colors when plotting MultiBlock object. Blocks will be colored sequentially as ‘Reds’, ‘Greens’, ‘Blues’, and ‘Grays’.
blending (str, optional) – Blending mode for visualisation of the input object(s). Can be one of ‘additive’, ‘maximum’, ‘minimum’, ‘composite’, or ‘average’. Defaults to ‘additive’.
mapper (str, 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_args (dict, optional) – Dictionary of keyword arguments to pass when adding the scalar bar to the scene. For options, see pyvista.BasePlotter.add_scalar_bar().
show_scalar_bar (bool) – If False, a scalar bar will not be added to the scene. Defaults to True.
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 the string annotations.
opacity_unit_distance (float) – 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.
shade (bool) – 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.
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
render (bool, optional) – Force a render when True. Default True.

Returns

actor – VTK volume of the input data.

Return type

vtk.vtkVolume

property background_color¶: Return the background color of the active render window.

property bounds¶: Return the bounds of the active renderer.

property camera¶: Return the active camera of the active renderer.

property camera_position¶: Return camera position of the active render window.

property camera_set¶: Return if the camera of the active renderer has been set.

property center¶: Return the center of the active renderer.

clear()¶: Clear plot by removing all actors and properties.

clear_box_widgets()¶: Disable all of the box widgets.

clear_button_widgets()¶: Disable all of the button widgets.

clear_events_for_key(key)¶: Remove the callbacks associated to the key.

clear_line_widgets()¶: Disable all of the line widgets.

clear_plane_widgets()¶: Disable all of the plane widgets.

clear_slider_widgets()¶: Disable all of the slider widgets.

clear_sphere_widgets()¶: Disable all of the sphere widgets.

clear_spline_widgets()¶: Disable all of the spline widgets.

click_position = None¶

close(render=False)¶: Close the render window.

deep_clean()¶: Clean the plotter of the memory.

disable()¶: Disable this renderer’s camera from being interactive.

disable_3_lights()¶: Please use enable_lightkit, this method has been depreciated.

disable_anti_aliasing()¶: Disable anti-aliasing FXAA.

disable_depth_peeling()¶: Disable depth peeling.

disable_eye_dome_lighting()¶: Disable eye dome lighting (EDL).

disable_parallel_projection()¶: Reset the camera to use perspective projection.

disable_shadows()¶: Disable shadows.

enable()¶: Enable this renderer’s camera to be interactive.

enable_3_lights(only_active=False)¶

Enable 3-lights illumination.

This will replace all pre-existing lights in the scene.

Parameters: only_active (bool) – If True, only change the active renderer. The default is that every renderer is affected.

enable_anti_aliasing()¶: Enable anti-aliasing FXAA.

enable_cell_picking(mesh=None, callback=None, through=True, show=True, show_message=True, style='wireframe', line_width=5, color='pink', font_size=18, start=False, **kwargs)¶

Enable picking at cells.

Press "r" to enable retangle based selection. Press "r" again to turn it off. Selection will be saved to self.picked_cells. Also press "p" to pick a single cell under the mouse location.

When using through=False, and multiple meshes are being picked, the picked cells in ``self.picked_cells will be a MultiBlock dataset for each mesh’s selection.

Uses last input mesh for input by default.

Warning

Visible cell picking (through=False) will only work if the mesh is displayed with a 'surface' representation style (the default).

Parameters

mesh (pyvista.DataSet, optional) – Mesh to select cells from. When through is True, uses last input mesh by default. When through is False, all meshes in the scene are available for picking and this argument is ignored. If you would like to only pick a single mesh in the scene, use the pickable=False argument when adding the other meshes to the scene.
callback (function, optional) – When input, calls this function after a selection is made. The picked_cells are input as the first parameter to this function.
through (bool, optional) – When True (default) the picker will select all cells through the mesh. When False, the picker will select only visible cells on the mesh’s surface.
show (bool) – Show the selection interactively.
style (str) – Visualization style of the selection. One of the following: style='surface', style='wireframe', or style='points'. Defaults to 'wireframe'.
line_width (float, optional) – Thickness of selected mesh edges. Default 5.
color (str, optional) – The color of the selected mesh is shown.
show_message (bool or str, optional) – Show the message about how to use the cell picking tool. If this is a string, that will be the message shown.
font_size (int, optional) – Sets the font size of the message.
start (bool, optional) – Automatically start the cell selection tool.
kwargs (optional) – All remaining keyword arguments are used to control how the selection is interactively displayed.

enable_depth_peeling(number_of_peels=None, occlusion_ratio=None)¶

Enable depth peeling to improve rendering of translucent geometry.

Parameters

number_of_peels (int) – The maximum number of peeling layers. Initial value is 4 and is set in the pyvista.global_theme. A special value of 0 means no maximum limit. It has to be a positive value.
occlusion_ratio (float) – The threshold under which the depth peeling algorithm stops to iterate over peel layers. This is the ratio of the number of pixels that have been touched by the last layer over the total number of pixels of the viewport area. Initial value is 0.0, meaning rendering has to be exact. Greater values may speed up the rendering with small impact on the quality.

enable_eye_dome_lighting()¶: Enable eye dome lighting (EDL).

enable_fly_to_right_click(callback=None)¶

Set the camera to track right click positions.

A convenience method to track right click positions and fly to the picked point in the scene. The callback will be passed the point in 3D space.

enable_geodesic_picking(callback=None, show_message=True, font_size=18, color='pink', point_size=10, line_width=5, tolerance=0.025, show_path=True, **kwargs)¶

Enable picking at geodesic paths.

This is a convenience method for enable_point_picking to keep track of the picked points and create a geodesic path using those points.

The geodesic path is saved to the .picked_geodesic attribute of this plotter

Parameters

callback (callable, optional) – When given, calls this function after a pick is made. The entire picked, geodesic path is passed as the only parameter to this function.
show_path (bool, optional) – Show the picked path interactively
show_message (bool or str, optional) – Show the message about how to use the point picking tool. If this is a string, that will be the message shown.
font_size (int, optional) – Sets the size of the message.
point_size (int, optional) – Size of picked points if show_path is True. Default 10.
color (str, optional) – The color of the selected mesh is shown.
line_width (float, optional) – Thickness of path representation if show_path is True. Default 5.
tolerance (float) – Specify tolerance for performing pick operation. Tolerance is specified as fraction of rendering window size. Rendering window size is measured across diagonal.
kwargs (optional) – All remaining keyword arguments are used to control how the picked path is interactively displayed

enable_horizon_picking(callback=None, normal=(0, 0, 1), width=None, show_message=True, font_size=18, color='pink', point_size=10, line_width=5, show_path=True, opacity=0.75, show_horizon=True, **kwargs)¶

Enable horizon picking.

Helper for the enable_path_picking method to also show a ribbon surface along the picked path. Ribbon is saved under .picked_horizon.

Parameters

callback (callable, optional) – When given, calls this function after a pick is made. The entire picked path is passed as the only parameter to this function.
normal (tuple(float), optional) – The normal to the horizon surface’s projection plane
width (float, optional) – The width of the horizon surface. Default behaviour will dynamically change the surface width depending on its length.
show_horizon (bool, optional) – Show the picked horizon surface interactively.
show_path (bool, optional) – Show the picked path that the horizon is built from interactively.
show_message (bool or str, optional) – Show the message about how to use the horizon picking tool. If this is a string, that will be the message shown.
font_size (int, optional) – Sets the font size of the message.
point_size (int, optional) – Size of picked points if show_horizon is True. Default 10.
color (str, optional) – The color of the horizon surface if shown.
line_width (float, optional) – Thickness of path representation if show_horizon is True. Default 5.
opacity (float, optional) – The opacity of the horizon surface if shown.
tolerance (float, optional) – Specify tolerance for performing pick operation. Tolerance is specified as fraction of rendering window size. Rendering window size is measured across diagonal.
kwargs (optional) – All remaining keyword arguments are used to control how the picked path is interactively displayed

enable_image_style()¶

Set the interactive style to image.

Controls:

Left Mouse button triggers window level events
CTRL Left Mouse spins the camera around its view plane normal
SHIFT Left Mouse pans the camera
CTRL SHIFT Left Mouse dollys (a positional zoom) the camera
Middle mouse button pans the camera
Right mouse button dollys the camera.
SHIFT Right Mouse triggers pick events

enable_joystick_style()¶

Set the interactive style to joystick.

It allows the user to move (rotate, pan, etc.) the camera, the point of view for the scene. The position of the mouse relative to the center of the scene determines the speed at which the camera moves, and the speed of the mouse movement determines the acceleration of the camera, so the camera continues to move even if the mouse if not moving.

For a 3-button mouse, the left button is for rotation, the right button for zooming, the middle button for panning, and ctrl + left button for spinning. (With fewer mouse buttons, ctrl + shift + left button is for zooming, and shift + left button is for panning.)

enable_lightkit(only_active=False)¶

Enable the default light-kit lighting.

See: https://www.researchgate.net/publication/2926068

This will replace all pre-existing lights in the renderer.

Parameters: only_active (bool) – If True, only change the active renderer. The default is that every renderer is affected.

enable_parallel_projection()¶

Enable parallel projection.

The camera will have a parallel projection. Parallel projection is often useful when viewing images or 2D datasets.

enable_path_picking(callback=None, show_message=True, font_size=18, color='pink', point_size=10, line_width=5, show_path=True, tolerance=0.025, **kwargs)¶

Enable picking at paths.

This is a convenience method for enable_point_picking to keep track of the picked points and create a line using those points.

The line is saved to the .picked_path attribute of this plotter

Parameters

callback (callable) – When given, calls this function after a pick is made. The entire picked path is passed as the only parameter to this function.
show_message (bool or str, optional) – Show the message about how to use the point picking tool. If this is a string, that will be the message shown.
show_path (bool, optional) – Show the picked path interactively
font_size (int, optional) – Sets the size of the message.
point_size (int, optional) – Size of picked points if show_path is True. Default 10.
color (str, optional) – The color of the selected mesh is shown.
line_width (float, optional) – Thickness of path representation if show_path is True. Default 5.
tolerance (float, optional) – Specify tolerance for performing pick operation. Tolerance is specified as fraction of rendering window size. Rendering window size is measured across diagonal.
kwargs (optional) – All remaining keyword arguments are used to control how the picked path is interactively displayed

enable_point_picking(callback=None, show_message=True, font_size=18, color='pink', point_size=10, use_mesh=False, show_point=True, tolerance=0.025, **kwargs)¶

Enable picking at points.

Enable picking a point at the mouse location in the render view using the P key. This point is saved to the .picked_point attrbute on the plotter. Pass a callback function that takes that point as an argument. The picked point can either be a point on the first intersecting mesh, or a point in the 3D window.

Parameters

callback (function, optional) – When input, calls this function after a pick is made. The picked point is input as the first parameter to this function. If use_mesh is True, the callback function will be passed a pointer to the picked mesh and the point ID of the selected mesh.
use_mesh (bool, optional) – If True, the callback function will be passed a pointer to the picked mesh and the point ID of the selected mesh.
show_message (bool or str, optional) – Show the message about how to use the point picking tool. If this is a string, that will be the message shown.
font_size (int, optional) – Sets the size of the message.
point_size (int, optional) – Size of picked points if show_point is True. Default 10.
color (str, optional) – The color of the selected mesh is shown.
tolerance (float, optional) – Specify tolerance for performing pick operation. Tolerance is specified as fraction of rendering window size. (Rendering window size is measured across diagonal.)
kwargs (optional, optional) – All remaining keyword arguments are used to control how the picked point is interactively displayed

enable_rubber_band_2d_style()¶

Set the interactive style to rubber band 2d.

Camera rotation is not allowed with this interactor style. Zooming affects the camera’s parallel scale only, and assumes that the camera is in parallel projection mode. The style also allows draws a rubber band using the left button. All camera changes invoke StartInteractionEvent when the button is pressed, InteractionEvent when the mouse (or wheel) is moved, and EndInteractionEvent when the button is released. The bindings are as follows: Left mouse - Select (invokes a SelectionChangedEvent). Right mouse - Zoom. Middle mouse - Pan. Scroll wheel - Zoom.

enable_rubber_band_style()¶

Set the interactive style to rubber band picking.

This interactor style allows the user to draw a rectangle in the render window by hitting ‘r’ and then using the left mouse button. When the mouse button is released, the attached picker operates on the pixel in the center of the selection rectangle. If the picker happens to be a vtkAreaPicker it will operate on the entire selection rectangle. When the ‘p’ key is hit the above pick operation occurs on a 1x1 rectangle. In other respects it behaves the same as its parent class.

enable_shadows()¶: Enable shadows.

enable_terrain_style()¶

Set the interactive style to terrain.

Used to manipulate a camera which is viewing a scene with a natural view up, e.g., terrain. The camera in such a scene is manipulated by specifying azimuth (angle around the view up vector) and elevation (the angle from the horizon).

enable_trackball_actor_style()¶

Set the interactive style to trackball actor.

This allows to rotate actors around the scene.

enable_trackball_style()¶

Set the interactive style to trackball camera.

The trackball camera is the default interactor style.

enable_zoom_style()¶

Set the interactive style to rubber band zoom.

This interactor style allows the user to draw a rectangle in the render window using the left mouse button. When the mouse button is released, the current camera zooms by an amount determined from the shorter side of the drawn rectangle.

export_obj(filename)¶: Export scene to OBJ format.

export_vtkjs(filename, compress_arrays=False)¶

Export the current rendering scene as a VTKjs scene.

It can be used for rendering in a web browser.

fly_to(point)¶

Move the current camera’s focal point to a position point.

The movement is animated over the number of frames specified in NumberOfFlyFrames. The LOD desired frame rate is used.

fly_to_mouse_position(focus=False)¶: Focus on last stored mouse position.

generate_orbital_path(factor=3.0, n_points=20, viewup=None, shift=0.0)¶

Generate an orbital path around the data scene.

Parameters

factor (float) – A scaling factor when building the orbital extent.
n_points (int) – Number of points on the orbital path.
viewup (list(float)) – The normal to the orbital plane.
shift (float, optional) – Shift the plane up/down from the center of the scene by this amount.

get_default_cam_pos(negative=False)¶

Return the default focal points and viewup.

Uses ResetCamera to make a useful view.

get_image_depth(fill_value=nan, reset_camera_clipping_range=True)¶

Return a depth image representing current render window.

Parameters

fill_value (float, optional) – Fill value for points in image that do not include objects in scene. To not use a fill value, pass None.
reset_camera_clipping_range (bool, optional) – Reset the camera clipping range to include data in view.

Returns

image_depth – Image of depth values from camera orthogonal to image plane.

Return type

numpy.ndarray

Examples

>>> import pyvista
>>> plotter = pyvista.Plotter()
>>> actor = plotter.add_mesh(pyvista.Sphere())
>>> plotter.store_image = True
>>> cpos = plotter.show()
>>> zval = plotter.get_image_depth()

Notes

Values in image_depth are negative to adhere to a right-handed coordinate system.

get_pick_position()¶: Get the pick position/area as x0, y0, x1, y1.

hide_axes()¶: Hide the axes orientation widget.

hide_axes_all()¶: Hide the axes orientation widget in all renderers.

property image¶

Return an image array of current render window.

To retrieve an image after the render window has been closed, set: plotter.store_image = True before closing the plotter.

property image_depth¶

Return a depth image representing current render window.

Helper attribute for get_image_depth.

increment_point_size_and_line_width(increment)¶

Increment point size and line width of all actors.

For every actor in the scene, increment both its point size and line width by the given value.

isometric_view()¶

Reset the camera to a default isometric view.

DEPRECATED: Please use view_isometric.

isometric_view_interactive()¶: Set the current interactive render window to isometric view.

key_press_event(obj, event)¶: Listen for key press event.

left_button_down(obj, event_type)¶: Register the event for a left button down click.

property length¶: Return the length of the diagonal of the bounding box of the scene.

link_views(views=0)¶

Link the views’ cameras.

Parameters: views (int | tuple or list) – If views is int, link the views to the given view index or if views is a tuple or a list, link the given views cameras.

mouse_position = None¶

open_gif(filename)¶

Open a gif file.

Parameters: filename (str) – Filename of the gif to open. Filename must end in gif.

open_movie(filename, framerate=24)¶

Establish a connection to the ffmpeg writer.

Parameters

filename (str) – Filename of the movie to open. Filename should end in mp4, but other filetypes may be supported. See “imagio.get_writer”
framerate (int, optional) – Frames per second.

orbit_on_path(path=None, focus=None, step=0.5, viewup=None, write_frames=False, threaded=False)¶

Orbit on the given path focusing on the focus point.

Parameters

path (pyvista.PolyData) – Path of orbital points. The order in the points is the order of travel
focus (list(float) of length 3, optional) – The point of focus the camera.
step (float, optional) – The timestep between flying to each camera position
viewup (list(float)) – the normal to the orbital plane
write_frames (bool) – Assume a file is open and write a frame on each camera view during the orbit.
threaded (bool, optional) – Run this as a background thread. Generally used within a GUI (i.e. PyQt).

property parallel_projection¶: Return parallel projection state of active render window.

property parallel_scale¶: Return parallel scale of active render window.

pick_click_position()¶: Get corresponding click location in the 3D plot.

pick_mouse_position()¶: Get corresponding mouse location in the 3D plot.

picked_cells = None¶

picked_geodesic = None¶

picked_horizon = None¶

picked_path = None¶

picked_point = None¶

remove_actor(actor, reset_camera=False, render=True)¶

Remove an actor from the Renderer.

Parameters

actor (str, vtk.vtkActor, list or tuple) – If the type is str, removes the previously added actor with the given name. If the type is vtk.vtkActor, removes the actor if it’s previously added to the Renderer. If list or tuple, removes iteratively each actor.
reset_camera (bool, optional) – Resets camera so all actors can be seen.
render (bool, optional) – Render upon actor removal. Set this to False to stop the render window from rendering when an actor is removed.

Returns

success – True when actor removed. False when actor has not been removed.

Return type

bool

remove_all_lights(only_active=False)¶

Remove all lights from the scene.

Parameters: only_active (bool) – If True, only remove lights from the active renderer. The default is that lights are stripped from every renderer.

Examples

Create a plotter, forget to initialize it without default lighting, correct the mistake after instantiation.

>>> import pyvista as pv
>>> plotter = pv.Plotter()
>>> plotter.remove_all_lights()
>>> plotter.renderer.lights
[]

remove_background_image()¶: Remove the background image from the current subplot.

remove_bounding_box(render=True)¶: Remove bounding box.

remove_bounds_axes()¶: Remove bounds axes.

remove_floors(clear_kwargs=True, render=True)¶: Remove all floor actors.

remove_legend()¶: Remove the legend actor.

remove_scalar_bar(title=None, render=True)¶

Remove a scalar bar.

Parameters

title (str, optional) – Title of the scalar bar to remove. Required if there is more than one scalar bar.
render (bool, optional) – Render upon scalar bar removal. Set this to False to stop the render window from rendering when an scalar bar is removed.

render()¶

Render the main window.

Does nothing until show has been called.

property renderer¶: Return the active renderer.

reset_camera(render=True, bounds=None)¶

Reset the camera of the active render window.

The camera slides along the vector defined from camera position to focal point until all of the actors can be seen.

Parameters

render (bool) – Trigger a render after resetting the camera.
bounds (iterable(int)) – Automatically set up the camera based on a specified bounding box (xmin, xmax, ymin, ymax, zmin, zmax).

reset_camera_clipping_range()¶: Reset camera clipping planes.

reset_key_events()¶: Reset all of the key press events to their defaults.

save_graphic(filename, title='PyVista Export', raster=True, painter=True)¶

Save a screenshot of the rendering window as a graphic file.

The supported formats are: ‘.svg’, ‘.eps’, ‘.ps’, ‘.pdf’, ‘.tex’

property scalar_bar¶: First scalar bar. Kept for backwards compatibility.

property scalar_bars¶

Scalar bars.

Examples

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> sphere['Data'] = sphere.points[:, 2]
>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_mesh(sphere)
>>> plotter.scalar_bars
Scalar Bar Title     Interactive
"Data"               False

Select a scalar bar actor based on the title of the bar.

>>> plotter.scalar_bars['Data']  
(vtkmodules.vtkRenderingAnnotation.vtkScalarBarActor)0x7fcd3567ca00

property scale¶: Return the scaling of the active renderer.

screenshot(filename=None, transparent_background=None, return_img=True, window_size=None)¶

Take screenshot at current camera position.

Parameters

filename (str, optional) – Location to write image to. If None, no image is written.
transparent_background (bool, optional) – Whether to make the background transparent. The default is looked up on the plotter’s theme.
return_img (bool, optional) – If True (the default), a NumPy array of the image will be returned.
window_size (2-length tuple, optional) – Set the plotter’s size to this (width, height) before taking the screenshot.

Returns

img – Array containing pixel RGB and alpha. Sized:

[Window height x Window width x 3] if transparent_background is set to False.
[Window height x Window width x 4] if transparent_background is set to True.

Return type

numpy.ndarray

Examples

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> plotter = pyvista.Plotter(off_screen=True)
>>> actor = plotter.add_mesh(sphere)
>>> plotter.screenshot('screenshot.png')  

set_background(color, top=None, all_renderers=True)¶

Set the background color.

Parameters

color (string or 3 item list, optional, defaults to white) –
Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
top (string or 3 item list, optional, defaults to None) – If given, this will enable a gradient background where the color argument is at the bottom and the color given in top will be the color at the top of the renderer.
all_renderers (bool) – If True, applies to all renderers in subplots. If False, then only applies to the active renderer.

Examples

Set the background color to black.

>>> import pyvista
>>> plotter = pyvista.Plotter()
>>> plotter.set_background('black')
>>> plotter.background_color
(0.0, 0.0, 0.0)

Set the background color to white.

>>> import pyvista
>>> plotter = pyvista.Plotter()
>>> plotter.set_background('white')
>>> plotter.background_color
(1.0, 1.0, 1.0)

set_environment_texture(texture)¶

Set the environment texture used for image based lighting.

This texture is supposed to represent the scene background. If it is not a cubemap, the texture is supposed to represent an equirectangular projection. If used with raytracing backends, the texture must be an equirectangular projection and must be constructed with a valid vtkImageData. Warning, this texture must be expressed in linear color space. If the texture is in sRGB color space, set the color flag on the texture or set the argument isSRGB to true.

set_focus(point)¶: Set focus to a point.

set_position(point, reset=False)¶: Set camera position to a point.

set_scale(xscale=None, yscale=None, zscale=None, reset_camera=True)¶

Scale all the datasets in the scene.

Scaling in performed independently on the X, Y and Z axis. A scale of zero is illegal and will be replaced with one.

set_viewup(vector)¶: Set camera viewup vector.

property shape¶

Shape of the plotter.

Examples

Return the plotter shape.

>>> import pyvista
>>> plotter = pyvista.Plotter(shape=(2, 2))
>>> plotter.shape
(2, 2)

show_axes()¶: Show the axes orientation widget.

show_axes_all()¶: Show the axes orientation widget in all renderers.

show_bounds(mesh=None, bounds=None, show_xaxis=True, show_yaxis=True, show_zaxis=True, show_xlabels=True, show_ylabels=True, show_zlabels=True, bold=True, font_size=None, font_family=None, color=None, xlabel='X Axis', ylabel='Y Axis', zlabel='Z Axis', use_2d=False, grid=None, location='closest', ticks=None, all_edges=False, corner_factor=0.5, fmt=None, minor_ticks=False, padding=0.0, render=None)¶

Add bounds axes.

Shows the bounds of the most recent input mesh unless mesh is specified.

Parameters

mesh (pyvista.DataSet or pyvista.MultiBlock) – Input mesh to draw bounds axes around.
bounds (list or tuple, optional) – Bounds to override mesh bounds. [xmin, xmax, ymin, ymax, zmin, zmax]
show_xaxis (bool, optional) – Makes x axis visible. Default True.
show_yaxis (bool, optional) – Makes y axis visible. Default True.
show_zaxis (bool, optional) – Makes z axis visible. Default True.
show_xlabels (bool, optional) – Shows x labels. Default True.
show_ylabels (bool, optional) – Shows y labels. Default True.
show_zlabels (bool, optional) – Shows z labels. Default True.
italic (bool, optional) – Italicises axis labels and numbers. Default False.
bold (bool, optional) – Bolds axis labels and numbers. Default True.
shadow (bool, optional) – Adds a black shadow to the text. Default False.
font_size (float, optional) – Sets the size of the label font. Defaults to 16.
font_family (string, optional) – Font family. Must be either 'courier', 'times', or 'arial'.
color (string or 3 item list, optional) –
Color of all labels and axis titles. Default white. Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
xlabel (string, optional) – Title of the x axis. Default "X Axis".
ylabel (string, optional) – Title of the y axis. Default "Y Axis".
zlabel (string, optional) – Title of the z axis. Default "Z Axis".
use_2d (bool, optional) –
This can be enabled for smoother plotting.

Warning

A bug with vtk 6.3 in Windows seems to cause this function to crash.
grid (bool or str, optional) – Add grid lines to the backface (True, 'back', or 'backface') or to the frontface ('front', 'frontface') of the axes actor.
location (str, optional) – Set how the axes are drawn: either static ('all'), closest triad (front), furthest triad ('back'), static closest to the origin ('origin'), or outer edges ('outer') in relation to the camera position. Options include: 'all', 'front', 'back', 'origin', 'outer'.
ticks (str, optional) – Set how the ticks are drawn on the axes grid. Options include: 'inside', 'outside', 'both'.
all_edges (bool, optional) – Adds an unlabeled and unticked box at the boundaries of plot. Useful for when wanting to plot outer grids while still retaining all edges of the boundary.
corner_factor (float, optional) – If all_edges``, this is the factor along each axis to draw the default box. Default is 0.5 to show the full box.
padding (float, optional) – An optional percent padding along each axial direction to cushion the datasets in the scene from the axes annotations. Defaults to 0 (no padding).

Returns

cube_axes_actor – Bounds actor.

Return type

vtk.vtkCubeAxesActor

Examples

>>> import pyvista
>>> from pyvista import examples
>>> mesh = pyvista.Sphere()
>>> plotter = pyvista.Plotter()
>>> actor = plotter.add_mesh(mesh)
>>> actor = plotter.show_bounds(grid='front', location='outer', all_edges=True)
>>> cpos = plotter.show()

show_grid(**kwargs)¶

Show gridlines and axes labels.

A wrapped implementation of show_bounds to change default behaviour to use gridlines and showing the axes labels on the outer edges. This is intended to be similar to matplotlib’s grid function.

store_click_position(*args)¶: Store click position in viewport coordinates.

property store_image¶: Return if an image will be saved on close.

store_mouse_position(*args)¶: Store mouse position.

subplot(index_row, index_column=None)¶

Set the active subplot.

Parameters

index_row (int) – Index of the subplot to activate along the rows.
index_column (int) – Index of the subplot to activate along the columns.

property theme¶

Return or set the theme used for this plotter.

Examples

Use the dark theme for a plotter.

>>> import pyvista
>>> from pyvista import themes
>>> pl = pyvista.Plotter()
>>> pl.theme = themes.DarkTheme()

track_click_position(callback=None, side='right', viewport=False)¶

Keep track of the click position.

By default, it only tracks right clicks.

Parameters

callback (callable, optional) – A callable method that will use the click position. Passes the click position as a length two tuple.
side (str, optional) – The side of the mouse for the button to track (left or right). Default is left. Also accepts 'r' or 'l'.
viewport (bool, optional) – If True, uses the normalized viewport coordinate system (values between 0.0 and 1.0 and support for HiDPI) when passing the click position to the callback.

track_mouse_position()¶

Keep track of the mouse position.

This will potentially slow down the interactor. No callbacks supported here - use pyvista.BasePlotter.track_click_position() instead.

unlink_views(views=None)¶

Unlink the views’ cameras.

Parameters: views (None | int | tuple or list) – If views is None unlink all the views, if views is int unlink the selected view’s camera or if views is a tuple or a list, unlink the given views cameras.

untrack_click_position()¶: Stop tracking the click position.

untrack_mouse_position()¶: Stop tracking the mouse position.

update(stime=1, force_redraw=True)¶

Update window, redraw, process messages query.

Parameters

stime (int, optional) – Duration of timer that interrupt vtkRenderWindowInteractor in milliseconds.
force_redraw (bool, optional) – Call render immediately.

update_bounds_axes()¶: Update the bounds axes of the render window.

update_coordinates(points, mesh=None, render=True)¶

Update the points of an object in the plotter.

Parameters

points (np.ndarray) – Points to replace existing points.
mesh (vtk.PolyData or vtk.UnstructuredGrid, optional) – Object that has already been added to the Plotter. If None, uses last added mesh.
render (bool, optional) – Force a render when True. Default True.

update_scalar_bar_range(clim, name=None)¶

Update the value range of the active or named scalar bar.

Parameters

item list (2) – The new range of scalar bar. Example: [-1, 2].
name (str, optional) – The title of the scalar bar to update

update_scalars(scalars, mesh=None, render=True)¶

Update scalars of an object in the plotter.

Parameters

scalars (np.ndarray) – Scalars to replace existing scalars.
mesh (vtk.PolyData or vtk.UnstructuredGrid, optional) – Object that has already been added to the Plotter. If None, uses last added mesh.
render (bool, optional) – Force a render when True. Default True.

view_isometric(negative=False)¶

Reset the camera to a default isometric view.

The view will show all the actors in the scene.

view_vector(vector, viewup=None)¶: Point the camera in the direction of the given vector.

view_xy(negative=False)¶: View the XY plane.

view_xz(negative=False)¶: View the XZ plane.

view_yx(negative=False)¶: View the YX plane.

view_yz(negative=False)¶: View the YZ plane.

view_zx(negative=False)¶: View the ZX plane.

view_zy(negative=False)¶: View the ZY plane.

where_is(name)¶

Return the subplot coordinates of a given actor.

Parameters: name (str) – Actor’s name.
Returns: places – A list with the subplot coordinates of the actor.
Return type: list(tuple(int))

Examples

>>> import pyvista as pv
>>> plotter = pv.Plotter(shape=(2, 2))
>>> plotter.subplot(0, 0)
>>> _ = plotter.add_mesh(pv.Box(), name='box')
>>> plotter.subplot(0, 1)
>>> _ = plotter.add_mesh(pv.Sphere(), name='sphere')
>>> plotter.subplot(1, 0)
>>> _ = plotter.add_mesh(pv.Box(), name='box')
>>> plotter.subplot(1, 1)
>>> _ = plotter.add_mesh(pv.Cone(), name='cone')
>>> plotter.where_is('box')
[(0, 0), (1, 0)]

property window_size¶: Return the render window size.

write_frame()¶: Write a single frame to the movie file.

Plotter¶

Attributes

`last_update_time`
`right_timer_id`

Methods

`add_title`(title[, font_size, color, font, …])	Add text to the top center of the plot.
`show`([title, window_size, interactive, …])	Display the plotting window.

class pyvista.Plotter(*args, **kwargs)¶

Bases: pyvista.plotting.plotting.BasePlotter

Plotting object to display vtk meshes or numpy arrays.

Example

>>> import pyvista
>>> from pyvista import examples
>>> mesh = examples.load_hexbeam()
>>> another_mesh = examples.load_uniform()
>>> plotter = pyvista.Plotter()
>>> actor = plotter.add_mesh(mesh, color='red')
>>> actor = plotter.add_mesh(another_mesh, color='blue')
>>> cpos = plotter.show()

Parameters

off_screen (bool, optional) – Renders off screen when True. Useful for automated screenshots.
notebook (bool, optional) – When True, the resulting plot is placed inline a jupyter notebook. Assumes a jupyter console is active. Automatically enables off_screen.
shape (list or tuple, optional) –
Number of sub-render windows inside of the main window. Specify two across with shape=(2, 1) and a two by two grid with shape=(2, 2). By default there is only one render window. Can also accept a string descriptor as shape. E.g.:
- shape="3|1" means 3 plots on the left and 1 on the right,
- shape="4/2" means 4 plots on top and 2 at the bottom.
border (bool, optional) – Draw a border around each render window. Default False.
border_color (string or 3 item list, optional) –
Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
window_size (list, optional) – Window size in pixels. Defaults to [1024, 768], unless set differently in the relevant theme’s window_size property.
multi_samples (int, optional) – The number of multi-samples used to mitigate aliasing. 4 is a good default but 8 will have better results with a potential impact on performance.
line_smoothing (bool, optional) – If True, enable line smoothing.
point_smoothing (bool, optional) – If True, enable point smoothing.
polygon_smoothing (bool, optional) – If True, enable polygon smoothing.
lighting (str, optional) –
What lighting to set up for the plotter. Accepted options:
- 'light_kit': a vtk Light Kit composed of 5 lights.
- 'three lights': illumination using 3 lights.
- 'none': no light sources at instantiation.
The default is a 'light_kit' (to be precise, 5 separate lights that act like a Light Kit).
theme (pyvista.themes.DefaultTheme, optional) – Plot-specific theme.

add_title(title, font_size=18, color=None, font=None, shadow=False)¶

Add text to the top center of the plot.

This is merely a convenience method that calls add_text with position='upper_edge'.

Parameters

text (str) – The text to add the rendering.
font (string, optional) – Font name may be courier, times, or arial.
shadow (bool, optional) – Adds a black shadow to the text. Defaults to False
name (str, 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.

Returns

textActor – Text actor added to plot.

Return type

vtk.vtkTextActor

last_update_time = 0.0¶

right_timer_id = -1¶

show(title=None, window_size=None, interactive=True, auto_close=None, interactive_update=False, full_screen=None, screenshot=False, return_img=False, cpos=None, use_ipyvtk=None, jupyter_backend=None, return_viewer=False, **kwargs)¶

Display the plotting window.

Notes

Please use the q-key to close the plotter as some operating systems (namely Windows) will experience issues saving a screenshot if the exit button in the GUI is pressed.

Parameters

title (string, optional) – Title of plotting window.
window_size (list, optional) – Window size in pixels. Defaults to [1024, 768]
interactive (bool, optional) – Enabled by default. Allows user to pan and move figure.
auto_close (bool, optional) – Enabled by default. Exits plotting session when user closes the window when interactive is True.
interactive_update (bool, optional) – Disabled by default. Allows user to non-blocking draw, user should call Update() in each iteration.
full_screen (bool, optional) – Opens window in full screen. When enabled, ignores window_size. Default False.
cpos (list(tuple(floats))) – The camera position. You can also set this with Plotter.camera_position.
screenshot (str or bool, optional) – Take a screenshot of the initial state of the plot. If a string, it specifies the path to which the screenshot is saved. If True, the screenshot is returned as an array. Defaults to False. For interactive screenshots it’s recommended to first call show() with auto_close=False to set the scene, then save the screenshot in a separate call to show() or screenshot().
return_img (bool) – Returns a numpy array representing the last image along with the camera position.
use_ipyvtk (bool, optional) – Deprecated. Instead, set the backend either globally with pyvista.set_jupyter_backend('ipyvtklink') or with backend='ipyvtklink'.
jupyter_backend (str, optional) –
Jupyter notebook plotting backend to use. One of the following:
- 'none' : Do not display in the notebook.
- 'static' : Display a static figure.
- 'ipygany' : Show a ipygany widget
- 'panel' : Show a panel widget.
This can also be set globally with pyvista.set_jupyter_backend
return_viewer (bool, optional) – Return the jupyterlab viewer, scene, or display object when plotting with jupyter notebook.

Returns

cpos (list) – List of camera position, focal point, and view up.
image (np.ndarray) – Numpy array of the last image when either return_img=True or screenshot=True is set. Optionally contains alpha values. Sized:
- [Window height x Window width x 3] if the theme sets transparent_background=False.
- [Window height x Window width x 4] if the theme sets transparent_background=True.
widget – IPython widget when return_viewer=True.

Examples

Simply show the plot of a mesh.

>>> import pyvista as pv
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(pv.Cube())
>>> pl.show()  

Take a screenshot interactively. Screenshot will be of the first image shown, so use the first call with auto_close=False to set the scene before taking the screenshot.

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(pv.Cube())
>>> pl.show(auto_close=False)  
>>> pl.show(screenshot='my_image.png')  

Display an ipygany scene within a jupyter notebook

>>> pl.show(jupyter_backend='ipygany')  

Return an ipygany scene.

>>> pl.show(jupyter_backend='ipygany', return_viewer=True)  

Renderer¶

Attributes

`CAMERA_STR_ATTR_MAP`
`actors`	Return a dictionary of actors assigned to this renderer.
`axes_enabled`	Return `True` when axes are enabled.
`background_color`	Return the background color of this renderer.
`bounds`	Return the bounds of all actors present in the rendering window.
`camera`	Return the active camera for the rendering scene.
`camera_position`	Return camera position of active render window.
`center`	Return the center of the bounding box around all data present in the scene.
`length`	Return the length of the diagonal of the bounding box of the scene.
`lights`	Return a list of all lights in the renderer.
`parallel_projection`	Return parallel projection state of active render window.
`parallel_scale`	Return parallel scale of active render window.

Methods

`add_actor`(uinput[, reset_camera, name, …])	Add an actor to render window.
`add_axes`([interactive, line_width, color, …])	Add an interactive axes widget in the bottom left corner.
`add_axes_at_origin`([x_color, y_color, …])	Add axes actor at origin.
`add_border`([color, width])	Add borders around the frame.
`add_bounding_box`([color, corner_factor, …])	Add an unlabeled and unticked box at the boundaries of plot.
`add_floor`([face, i_resolution, …])	Show a floor mesh.
`add_light`(light)	Add a light to the renderer.
`add_orientation_widget`(actor[, interactive, …])	Use the given actor in an orientation marker widget.
`clear`()	Remove all actors and properties.
`close`()	Close out widgets and sensitive elements.
`deep_clean`([render])	Clean the renderer of the memory.
`disable`()	Disable this renderer’s camera from being interactive.
`disable_anti_aliasing`()	Disable anti-aliasing FXAA.
`disable_depth_peeling`()	Disable depth peeling.
`disable_eye_dome_lighting`()	Disable eye dome lighting (EDL).
`disable_parallel_projection`()	Reset the camera to use perspective projection.
`disable_shadows`()	Disable shadows.
`enable`()	Enable this renderer’s camera to be interactive.
`enable_anti_aliasing`()	Enable anti-aliasing FXAA.
`enable_depth_peeling`([number_of_peels, …])	Enable depth peeling to improve rendering of translucent geometry.
`enable_eye_dome_lighting`()	Enable eye dome lighting (EDL).
`enable_parallel_projection`()	Enable parallel projection.
`enable_shadows`()	Enable shadows.
`get_default_cam_pos`([negative])	Return the default focal points and viewup.
`get_pick_position`()	Get the pick position/area as x0, y0, x1, y1.
`hide_axes`()	Hide the axes orientation widget.
`isometric_view`()	Reset the camera to a default isometric view.
`remove_actor`(actor[, reset_camera, render])	Remove an actor from the Renderer.
`remove_all_lights`()	Remove all lights from the renderer.
`remove_bounding_box`([render])	Remove bounding box.
`remove_bounds_axes`()	Remove bounds axes.
`remove_floors`([clear_kwargs, render])	Remove all floor actors.
`reset_camera`([render, bounds])	Reset the camera of the active render window.
`set_background`(color[, top])	Set the background color.
`set_environment_texture`(texture)	Set the environment texture used for image based lighting.
`set_focus`(point)	Set focus to a point.
`set_position`(point[, reset])	Set camera position to a point.
`set_scale`([xscale, yscale, zscale, reset_camera])	Scale all the datasets in the scene.
`set_viewup`(vector)	Set camera viewup vector.
`show_axes`()	Show the axes orientation widget.
`show_bounds`([mesh, bounds, show_xaxis, …])	Add bounds axes.
`show_grid`(**kwargs)	Show gridlines and axes labels.
`update_bounds_axes`()	Update the bounds axes of the render window.
`view_isometric`([negative])	Reset the camera to a default isometric view.
`view_vector`(vector[, viewup])	Point the camera in the direction of the given vector.
`view_xy`([negative])	View the XY plane.
`view_xz`([negative])	View the XZ plane.
`view_yx`([negative])	View the YX plane.
`view_yz`([negative])	View the YZ plane.
`view_zx`([negative])	View the ZX plane.
`view_zy`([negative])	View the ZY plane.

class pyvista.Renderer(parent, border=True, border_color=(1, 1, 1), border_width=2.0)¶

Bases: vtkmodules.vtkRenderingCore.vtkRenderer

Renderer class.

CAMERA_STR_ATTR_MAP = {'iso': 'view_isometric', 'xy': 'view_xy', 'xz': 'view_xz', 'yx': 'view_yx', 'yz': 'view_yz', 'zx': 'view_zx', 'zy': 'view_zy'}¶

property actors¶: Return a dictionary of actors assigned to this renderer.

add_actor(uinput, reset_camera=False, name=None, culling=False, pickable=True, render=True)¶

Add an actor to render window.

Creates an actor if input is a mapper.

Parameters

uinput (vtk.vtkMapper or vtk.vtkActor) – vtk mapper or vtk actor to be added.
reset_camera (bool, optional) – Resets the camera when true.
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. Default False.

Returns

actor (vtk.vtkActor) – The actor.
actor_properties (vtk.Properties) – Actor properties.

Add an interactive axes widget in the bottom left corner.

Parameters

interacitve (bool) – Enable this orientation widget to be moved by the user.
line_width (int) – The width of the marker lines
box (bool) – Show a box orientation marker. Use box_args to adjust. See pyvista.create_axes_orientation_box for details.
opacity (int or float, optional) – The opacity of the marker.

add_axes_at_origin(x_color=None, y_color=None, z_color=None, xlabel='X', ylabel='Y', zlabel='Z', line_width=2, labels_off=False)¶

Add axes actor at origin.

Returns: marker_actor – vtkAxesActor actor
Return type: vtk.vtkAxesActor

add_border(color=[1, 1, 1], width=2.0)¶: Add borders around the frame.

add_bounding_box(color='grey', corner_factor=0.5, line_width=None, opacity=1.0, render_lines_as_tubes=False, lighting=None, reset_camera=None, outline=True, culling='front')¶

Add an unlabeled and unticked box at the boundaries of plot.

Useful for when wanting to plot outer grids while still retaining all edges of the boundary.

Parameters

corner_factor (float, optional) – If all_edges, this is the factor along each axis to draw the default box. Dafuault is 0.5 to show the full box.
corner_factor – This is the factor along each axis to draw the default box. Dafuault is 0.5 to show the full box.
line_width (float, optional) – Thickness of lines.
opacity (float, optional) – Opacity of mesh. Should be between 0 and 1. Default 1.0
outline (bool) – Default is True. when False, a box with faces is shown with the specified culling
culling (str, optional) – Does not render faces that are culled. Options are 'front' or 'back'. Default is 'front' for bounding box.

Show a floor mesh.

This generates planes at the boundaries of the scene to behave like floors or walls.

Parameters

face (str, optional) – The face at which to place the plane. Options are ('-z', '-y', '-x', '+z', '+y', and '+z'). Where the -/+ sign indicates on which side of the axis the plane will lie. For example, '-z' would generate a floor on the XY-plane and the bottom of the scene (minimum z).
i_resolution (int, optional) – Number of points on the plane in the i direction.
j_resolution (int, optional) – Number of points on the plane in the j direction.
color (string or 3 item list, optional) – Color of all labels and axis titles. Default gray. Either a string, rgb list, or hex color string.
line_width (int, optional) – Thickness of the edges. Only if show_edges is True.
opacity (float, optional) – The opacity of the generated surface.
show_edges (bool, optional) – Flag on whether to show the mesh edges for tiling.
ine_width (float, optional) – Thickness of lines. Only valid for wireframe and surface representations. Default None.
lighting (bool, optional) – Enable or disable view direction lighting. Default False.
edge_color (string or 3 item list, optional) – Color of of the edges of the mesh.
pad (float, optional) – Percentage padding between 0 and 1.
offset (float, optional) – Percentage offset along plane normal.

Examples

Add a floor below a sphere and plot it.

>>> import pyvista
>>> pl = pyvista.Plotter()
>>> actor = pl.add_mesh(pyvista.Sphere())
>>> actor = pl.add_floor()
>>> cpos = pl.show()

add_light(light)¶: Add a light to the renderer.

add_orientation_widget(actor, interactive=None, color=None, opacity=1.0)¶

Use the given actor in an orientation marker widget.

Color and opacity are only valid arguments if a mesh is passed.

Parameters

actor (vtk.vtkActor or pyvista.DataSet) – The mesh or actor to use as the marker.
color (string, optional) – The color of the actor.
opacity (int or float, optional) – Opacity of the marker.

property axes_enabled¶: Return True when axes are enabled.

property background_color¶: Return the background color of this renderer.

property bounds¶: Return the bounds of all actors present in the rendering window.

property camera¶: Return the active camera for the rendering scene.

property camera_position¶: Return camera position of active render window.

property center¶: Return the center of the bounding box around all data present in the scene.

clear()¶: Remove all actors and properties.

close()¶: Close out widgets and sensitive elements.

deep_clean(render=False)¶: Clean the renderer of the memory.

disable()¶: Disable this renderer’s camera from being interactive.

disable_anti_aliasing()¶: Disable anti-aliasing FXAA.

disable_depth_peeling()¶: Disable depth peeling.

disable_eye_dome_lighting()¶: Disable eye dome lighting (EDL).

disable_parallel_projection()¶: Reset the camera to use perspective projection.

disable_shadows()¶: Disable shadows.

enable()¶: Enable this renderer’s camera to be interactive.

enable_anti_aliasing()¶: Enable anti-aliasing FXAA.

enable_depth_peeling(number_of_peels=None, occlusion_ratio=None)¶

Enable depth peeling to improve rendering of translucent geometry.

Parameters

number_of_peels (int) – The maximum number of peeling layers. Initial value is 4 and is set in the pyvista.global_theme. A special value of 0 means no maximum limit. It has to be a positive value.
occlusion_ratio (float) – The threshold under which the depth peeling algorithm stops to iterate over peel layers. This is the ratio of the number of pixels that have been touched by the last layer over the total number of pixels of the viewport area. Initial value is 0.0, meaning rendering has to be exact. Greater values may speed up the rendering with small impact on the quality.

enable_eye_dome_lighting()¶: Enable eye dome lighting (EDL).

enable_parallel_projection()¶

Enable parallel projection.

The camera will have a parallel projection. Parallel projection is often useful when viewing images or 2D datasets.

enable_shadows()¶: Enable shadows.

get_default_cam_pos(negative=False)¶

Return the default focal points and viewup.

Uses ResetCamera to make a useful view.

get_pick_position()¶: Get the pick position/area as x0, y0, x1, y1.

hide_axes()¶: Hide the axes orientation widget.

isometric_view()¶

Reset the camera to a default isometric view.

DEPRECATED: Please use view_isometric.

property length¶: Return the length of the diagonal of the bounding box of the scene.

property lights¶: Return a list of all lights in the renderer.

property parallel_projection¶: Return parallel projection state of active render window.

property parallel_scale¶: Return parallel scale of active render window.

remove_actor(actor, reset_camera=False, render=True)¶

Remove an actor from the Renderer.

Parameters

actor (str, vtk.vtkActor, list or tuple) – If the type is str, removes the previously added actor with the given name. If the type is vtk.vtkActor, removes the actor if it’s previously added to the Renderer. If list or tuple, removes iteratively each actor.
reset_camera (bool, optional) – Resets camera so all actors can be seen.
render (bool, optional) – Render upon actor removal. Set this to False to stop the render window from rendering when an actor is removed.

Returns

success – True when actor removed. False when actor has not been removed.

Return type

bool

remove_all_lights()¶: Remove all lights from the renderer.

remove_bounding_box(render=True)¶: Remove bounding box.

remove_bounds_axes()¶: Remove bounds axes.

remove_floors(clear_kwargs=True, render=True)¶: Remove all floor actors.

reset_camera(render=True, bounds=None)¶

Reset the camera of the active render window.

The camera slides along the vector defined from camera position to focal point until all of the actors can be seen.

Parameters

render (bool) – Trigger a render after resetting the camera.
bounds (iterable(int)) – Automatically set up the camera based on a specified bounding box (xmin, xmax, ymin, ymax, zmin, zmax).

set_background(color, top=None)¶

Set the background color.

Parameters

color (string or 3 item list, optional, defaults to white) –
Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
top (string or 3 item list, optional, defaults to None) – If given, this will enable a gradient background where the color argument is at the bottom and the color given in top will be the color at the top of the renderer.

set_environment_texture(texture)¶

Set the environment texture used for image based lighting.

set_focus(point)¶: Set focus to a point.

set_position(point, reset=False)¶: Set camera position to a point.

set_scale(xscale=None, yscale=None, zscale=None, reset_camera=True)¶

Scale all the datasets in the scene.

Scaling in performed independently on the X, Y and Z axis. A scale of zero is illegal and will be replaced with one.

set_viewup(vector)¶: Set camera viewup vector.

show_axes()¶: Show the axes orientation widget.

Add bounds axes.

Shows the bounds of the most recent input mesh unless mesh is specified.

Parameters

mesh (pyvista.DataSet or pyvista.MultiBlock) – Input mesh to draw bounds axes around.
bounds (list or tuple, optional) – Bounds to override mesh bounds. [xmin, xmax, ymin, ymax, zmin, zmax]
show_xaxis (bool, optional) – Makes x axis visible. Default True.
show_yaxis (bool, optional) – Makes y axis visible. Default True.
show_zaxis (bool, optional) – Makes z axis visible. Default True.
show_xlabels (bool, optional) – Shows x labels. Default True.
show_ylabels (bool, optional) – Shows y labels. Default True.
show_zlabels (bool, optional) – Shows z labels. Default True.
italic (bool, optional) – Italicises axis labels and numbers. Default False.
bold (bool, optional) – Bolds axis labels and numbers. Default True.
shadow (bool, optional) – Adds a black shadow to the text. Default False.
font_size (float, optional) – Sets the size of the label font. Defaults to 16.
font_family (string, optional) – Font family. Must be either 'courier', 'times', or 'arial'.
color (string or 3 item list, optional) –
Color of all labels and axis titles. Default white. Either a string, rgb list, or hex color string. For example:
- color='white'
- color='w'
- color=[1, 1, 1]
- color='#FFFFFF'
xlabel (string, optional) – Title of the x axis. Default "X Axis".
ylabel (string, optional) – Title of the y axis. Default "Y Axis".
zlabel (string, optional) – Title of the z axis. Default "Z Axis".
use_2d (bool, optional) –
This can be enabled for smoother plotting.

Warning

A bug with vtk 6.3 in Windows seems to cause this function to crash.
grid (bool or str, optional) – Add grid lines to the backface (True, 'back', or 'backface') or to the frontface ('front', 'frontface') of the axes actor.
location (str, optional) – Set how the axes are drawn: either static ('all'), closest triad (front), furthest triad ('back'), static closest to the origin ('origin'), or outer edges ('outer') in relation to the camera position. Options include: 'all', 'front', 'back', 'origin', 'outer'.
ticks (str, optional) – Set how the ticks are drawn on the axes grid. Options include: 'inside', 'outside', 'both'.
all_edges (bool, optional) – Adds an unlabeled and unticked box at the boundaries of plot. Useful for when wanting to plot outer grids while still retaining all edges of the boundary.
corner_factor (float, optional) – If all_edges``, this is the factor along each axis to draw the default box. Default is 0.5 to show the full box.
padding (float, optional) – An optional percent padding along each axial direction to cushion the datasets in the scene from the axes annotations. Defaults to 0 (no padding).

Returns

cube_axes_actor – Bounds actor.

Return type

vtk.vtkCubeAxesActor

Examples

>>> import pyvista
>>> from pyvista import examples
>>> mesh = pyvista.Sphere()
>>> plotter = pyvista.Plotter()
>>> actor = plotter.add_mesh(mesh)
>>> actor = plotter.show_bounds(grid='front', location='outer', all_edges=True)
>>> cpos = plotter.show()

show_grid(**kwargs)¶

Show gridlines and axes labels.

update_bounds_axes()¶: Update the bounds axes of the render window.

view_isometric(negative=False)¶

Reset the camera to a default isometric view.

The view will show all the actors in the scene.

view_vector(vector, viewup=None)¶: Point the camera in the direction of the given vector.

view_xy(negative=False)¶: View the XY plane.

view_xz(negative=False)¶: View the XZ plane.

view_yx(negative=False)¶: View the YX plane.

view_yz(negative=False)¶: View the YZ plane.

view_zx(negative=False)¶: View the ZX plane.

view_zy(negative=False)¶: View the ZY plane.