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
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

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=True, notebook=None, background=None, text='', return_img=False, eye_dome_lighting=False, use_panel=None, volume=False, **kwargs)

Convenience plotting function for 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(pyvistanterface.Plotter.screenshot). Default disabled.

  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. Enabled by default.

• text (str, optional) – Adds text at the bottom of the plot.

• volume (bool, optional) – Use the add_volume method for volume rendering.

• **kwargs (optional keyword arguments) – See help(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 alpha. Sized: [Window height x Window width x 3] for transparent_background=False [Window height x Window width x 4] for transparent_background=True Returned only when screenshot enabled

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

Plots 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 Plot. See help(pyvista.Plot)

pyvista.set_plot_theme(theme)

Set the plotting parameters to a predefined theme

pyvista.create_axes_orientation_box(line_width=1, text_scale=0.366667, edge_color='black', x_color='lightblue', y_color='seagreen', z_color='tomato', x_face_color=(255, 0, 0), y_face_color=(0, 255, 0), z_face_color=(0, 0, 255), color_box=False)

Create a Box axes orientation widget with labels.

Base Plotter

The base plotter class that all PyVista plotters inherit. Please note that the pyvista.BackgroundPlotter is documented under PyVista PyQt Interface.

Attributes

background_color	Returns background color of the first render window
bounds	Returns the bounds of the active renderer
camera	The active camera of the active renderer
camera_position	Returns camera position of the active render window
camera_set	Returns if the camera of the active renderer has been set
center	Returns the center of the active renderer
image	Returns an image array of current render window
image_depth	Returns an image array of current render window
length	Returns the length of the diagonal of the bounding box of the scene
renderer	simply returns the active renderer
scale	The scaling of the active renderer.
window_size	returns render window size

Methods

add_actor(uinput[, reset_camera, name, loc, …])	Adds an actor to render window.
add_arrows(cent, direction[, mag])	Adds arrows to plotting object
add_axes([interactive, color, box, …])	Add an interactive axes widget
add_axes_at_origin([loc])	Add axes actor at the origin of a render window.
add_bounding_box([color, corner_factor, …])	Adds an unlabeled and unticked box at the boundaries of plot.
add_bounds_axes(*args, **kwargs)	Deprecated
add_legend([labels, bcolor, border, size, name])	Adds a legend to render window.
add_lines(lines[, color, width, label, name])	Adds lines to the plotting object.
add_mesh(mesh[, color, style, scalars, rng, …])	Adds a unstructured, structured, or surface mesh to the plotting object.
add_point_labels(points, labels[, italic, …])	Creates a point actor with one label from list labels assigned to each point.
add_point_scalar_labels(points, labels[, …])	Wrapper for pyvista.BasePlotter.add_point_labels() that will label points from a dataset with their scalar values.
add_points(points, **kwargs)	Add points to a mesh
add_scalar_bar([title, n_labels, italic, …])	Creates scalar bar using the ranges as set by the last input mesh.
add_text(text[, position, font_size, color, …])	Adds text to plot object in the top left corner by default
add_volume(volume[, scalars, resolution, …])	Adds a volume, rendered using a fixed point ray cast mapper by default.
clear()	Clears plot by removing all actors and properties
close()	closes render window
disable()	Disable this renderer’s camera from being interactive
disable_eye_dome_lighting()	Disable eye dome lighting (EDL) for active renderer
enable()	Enable this renderer’s camera to be interactive
enable_cell_picking([mesh, callback, …])	Enables picking of cells.
enable_eye_dome_lighting()	Enable eye dome lighting (EDL) for active renderer
enable_image_style()	sets the interactive style to image
enable_joystick_style()	sets the interactive style to joystick
enable_rubber_band_style()	sets the interactive style to rubber band picking
enable_terrain_style()	sets the interactive style to terrain
enable_trackball_style()	sets the interactive style to trackball - the default syle
enable_zoom_style()	sets the interactive style to rubber band zoom
export_vtkjs(filename[, compress_arrays])	Export the current rendering scene as a VTKjs scene for rendering in a web browser
fly_to()	Given a position point, move the current camera’s focal point to that point.
generate_orbital_path([factor, n_points, …])	Genrates an orbital path around the data scene
get_default_cam_pos()	Return the default camera position of the active renderer
get_pick_position()	Get the pick position/area as x0, y0, x1, y1
hide_axes()	Hide the axes orientation widget
index_to_loc(index)	Convert a 1D index location to the 2D location on the plotting grid
isometric_view()	DEPRECATED: Please use view_isometric
isometric_view_interactive()	sets the current interactive render window to isometric view
key_press_event(obj, event)	Listens for key press event
left_button_down(obj, event_type)	Register the event for a left button down click
link_views([views])	Links the views’ cameras.
loc_to_index(loc)	Return index of the render window given a location index.
open_gif(filename)	Open a gif file.
open_movie(filename[, framerate])	Establishes 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])	Removes an actor from the Plotter.
remove_bounding_box([loc])	Removes bounding box from the active renderer.
remove_bounds_axes([loc])	Removes bounds axes from the active renderer.
remove_legend()	Removes legend actor
remove_scalar_bar()	Removes scalar bar
reset_camera()	Reset camera so it slides along the vector defined from camera position to focal point until all of the actors can be seen.
screenshot([filename, …])	Takes screenshot at current camera position
set_background(color[, loc])	Sets background color
set_focus(point)	sets focus to a point
set_position(point[, reset])	sets camera position to a point
set_scale([xscale, yscale, zscale, reset_camera])	Scale all the datasets in the scene of the active renderer.
set_viewup(vector)	sets camera viewup vector
show_axes()	Show the axes orientation widget
show_bounds([mesh, bounds, show_xaxis, …])	Adds bounds axes.
show_grid(**kwargs)	A wrapped implementation of show_bounds to change default behaviour to use gridlines and showing the axes labels on the outer edges.
subplot(index_x, index_y)	Sets the active subplot.
unlink_views([views])	Unlinks the views’ cameras.
update([stime, force_redraw])	Update window, redraw, process messages query
update_bounds_axes()	Update the bounds of the active renderer
update_coordinates(points[, mesh, render])	Updates the points of the 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])	Updates scalars of the an object in the plotter.
update_style()
view_isometric()	Resets the camera to a default isometric view showing all the actors in the scene.
view_vector(vector[, viewup])
view_xy([negative])	View the XY plane
view_xz([negative])	View the XZ plane
view_yz([negative])	View the YZ plane
write_frame()	Writes a single frame to the movie file

class pyvista.BasePlotter(shape=(1, 1), border=None, border_color='k', border_width=1.0, title=None)

Bases: object

To be used by the Plotter and 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.

• border (bool, optional) – Draw a border around each render window. Default False.

• border_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’

• border_width (float, optional) – Width of the border in pixels when enabled.

add_actor(uinput, reset_camera=False, name=None, loc=None, culling=False)

Adds 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.

• loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If None, selects the last active Renderer.

• culling (bool optional) – Does not render faces that should not be visible to the plotter. 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)

Adds arrows to plotting object

add_axes(interactive=None, color=None, box=False, box_arguments=None)

Add an interactive axes widget

add_axes_at_origin(loc=None)

Add axes actor at the origin of a render window.

Parameters

loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). When None, defaults to the active render window.

Returns

marker_actor – vtkAxesActor actor

Return type

vtk.vtkAxesActor

add_bounding_box(color=None, corner_factor=0.5, line_width=None, opacity=1.0, render_lines_as_tubes=False, lighting=None, reset_camera=None, loc=None)

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.

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

• loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If None, selects the last active Renderer.

add_bounds_axes(*args, **kwargs)

Deprecated

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

Adds 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 contianing 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.

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()
>>> plotter.show() # doctest:+SKIP

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)
>>> plotter.show() # doctest:+SKIP

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

Adds 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, rng=None, stitle=None, show_edges=None, point_size=5.0, opacity=1.0, line_width=None, flip_scalars=False, lighting=None, n_colors=256, interpolate_before_map=False, cmap=None, label=None, reset_camera=None, scalar_bar_args=None, multi_colors=False, name=None, texture=None, render_points_as_spheres=None, smooth_shading=False, render_lines_as_tubes=False, edge_color=None, ambient=0.0, show_scalar_bar=None, nan_color=None, nan_opacity=1.0, loc=None, backface_culling=False, rgb=False, categories=False, use_transparency=False, **kwargs)

Adds a unstructured, structured, or surface mesh to the plotting object.

Also accepts a 3D numpy.ndarray

Parameters

• mesh (vtk unstructured, structured, polymesh, or 3D numpy.ndarray) – A vtk unstructured, structured, or polymesh to plot.

• 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’

  Color will be overridden when scalars are input.

• style (string, optional) –

  Visualization style of the vtk mesh. One for the following:

  style=’surface’ style=’wireframe’ style=’points’

  Defaults to ‘surface’

• scalars (numpy array, optional) – Scalars used to “color” the mesh. Accepts 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

• rng (2 item list, optional) – Range of mapper for scalars. Defaults to minimum and maximum of scalars array. Example: [-1, 2]. clim is also an accepted alias for this.

• stitle (string, optional) – Scalar title. By default there is no scalar legend bar. Setting this creates the legend bar and adds a title to it. To create a bar with no title, use an empty string (i.e. ‘’).

• show_edges (bool, optional) – Shows the edges of a mesh. Does not apply to a wireframe representation.

• point_size (float, optional) – Point size. Applicable when style=’points’. Default 5.0

• opacity (float, str, array-like) – Opacity of mesh. Should be between 0 and 1. Default 1.0. A string option can also be specified to map the scalar range to a predefined opacity transfer function (options are: linear, linear_r, geom, geom_r). A string could also be used to map a scalar array to the the opacity (must have same number of elements as the scalars argument). Or you can pass custum made trasfer functions that are either n_colors in length or shorter.

• line_width (float, optional) – Thickness of lines. Only valid for wireframe and surface representations. Default None.

• flip_scalars (bool, optional) – Flip direction of cmap.

• lighting (bool, optional) – Enable or disable view direction lighting. Default False.

• n_colors (int, optional) – Number of colors to use when displaying scalars. Default 256.

• interpolate_before_map (bool, optional) – Enabling makes for a smoother scalar display. Default False

• cmap (str, optional) – cmap string. See available matplotlib cmaps. Only applicable for when displaying scalars. Defaults None (rainbow). Requires matplotlib.

• 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 avaialble 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.

• 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.2.

• 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

• backface_culling (bool optional) – Does not render faces that should not be visible to the plotter. This can be helpful for dense surface meshes, especially when edges are visible, but can cause flat meshes to be partially displayed. Default False.

• rgb (bool, optional) – If an 2 dimensional array is passed as the scalars, plot those values as RGB+A colors! rgba is also accepted alias for this.

• 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.

• use_transparency (bool, optional) – Invert the opacity mapping and make the values correspond to transperency.

Returns

actor – VTK actor of the mesh.

Return type

vtk.vtkActor

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, **kwargs)

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

Parameters

• points (np.ndarray or pyvista.Common) – 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.Common 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:

  text_color=’white’ text_color=’w’ text_color=[1, 1, 1] text_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_colorstring or 3 item list, optional. Color of points (if visible).

Either a string, rgb list, or hex color string. For example:

shapestr, optional

The string name of the shape to use. Options are 'rect' or 'rounded_rect'. If you want no shape, pass None

fill_shapebool, optional

Fill the shape with the shape_color. Outlines if False.

marginint, optional

The size of the margin on the label background shape. Default is 3.

shape_opacityflaot

The opacity of the shape between zero and one.

Returns

labelMapper – VTK label mapper. Can be used to change properties of the labels.

Return type

vtk.vtkvtkLabeledDataMapper

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

Wrapper for pyvista.BasePlotter.add_point_labels() that will label points from a dataset with their scalar values.

Parameters

• points (np.ndarray or pyvista.Common) – 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=None, n_labels=5, italic=False, bold=True, title_font_size=None, label_font_size=None, color=None, font_family=None, shadow=False, mapper=None, width=None, height=None, position_x=None, position_y=None, vertical=None, interactive=False, fmt=None, use_opacity=True, outline=False)

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

Parameters

• title (string, optional) – Title of the scalar bar. Default None

• 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 automatically.

• label_font_size (float, optional) – Sets the size of the title font. Defaults to None and is sized automatically.

• 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’

• 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

• width (float, optional) – The percentage (0 to 1) width of the window for the colorbar

• height (float, optional) – The percentage (0 to 1) height of the window for the colorbar

• position_x (float, optional) – The percentage (0 to 1) along the windows’s horizontal direction to place the bottom left corner of the colorbar

• position_y (float, optional) – The percentage (0 to 1) along the windows’s vertical direction to place the bottom left corner of the colorbar

• interactive (bool, optional) – Use a widget to control the size and location of the scalar bar.

• use_opacity (bool, optional) – Optionally disply the opacity mapping on the scalar bar

• outline (bool, optional) – Optionally outline the scalar bar to make opacity mappings more obvious.

Notes

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

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

Adds text to plot object in the top left corner by default

Parameters

• text (str) – The text to add the the rendering

• position (str, tuple(float)) – String name of the position or length 2 tuple of the pixelwise position to place the bottom left corner of the text box. If string name is used, returns a vtkCornerAnnotation object normally used for fixed labels (like title or xlabel). If tuple is used, returns a more general vtkOpenGLTextActor. Default is to find the top left corner of the renderering 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.

• loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1).

Returns

textActor – Text actor added to plot

Return type

vtk.vtkTextActor

add_volume(volume, scalars=None, resolution=None, opacity='linear', n_colors=256, cmap=None, flip_scalars=False, reset_camera=None, name=None, ambient=0.0, categories=False, loc=None, backface_culling=False, multi_colors=False, blending='composite', mapper='fixed_point', rng=None, stitle=None, scalar_bar_args=None, show_scalar_bar=None, **kwargs)

Adds a volume, rendered using a fixed point ray cast mapper by default.

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

Parameters

• data (3D numpy.ndarray or pyvista.UnformGrid) – The input array to visualize, assuming the array values denote scalar intensities.

• opacity (float or string, optional) – Opacity of input array. Options are: linear, linear_r, geom, geom_r. Defaults to ‘linear’. Can also be given as a scalar value between 0 and 1.

• flip_scalars (bool, optional) – Flip direction of cmap.

• n_colors (int, optional) – Number of colors to use when displaying scalars. Default 256.

• cmap (str, optional) – cmap string. See available matplotlib cmaps. Only applicable for when displaying scalars. Defaults to None (jet). Requires matplotlib. Will be overridden if multi_colors is set to True.

• 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) – 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.

• loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If None, selects the last active Renderer.

• backface_culling (bool optional) – Does not render faces that should not be visible to the plotter. This can be helpful for dense surface meshes, especially when edges are visible, but can cause flat meshes to be partially displayed. Default False.

• categories (bool, optional) – If fetching a colormap from matplotlib, this is the number of categories to use in that colormap. If set to True, then the number of unique values in the scalar array will be used.

• 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’.

Returns

actor – VTK volume of the input data.

Return type

vtk.vtkVolume

property background_color

Returns background color of the first render window

property bounds

Returns the bounds of the active renderer

property camera

The active camera of the active renderer

property camera_position

Returns camera position of the active render window

property camera_set

Returns if the camera of the active renderer has been set

property center

Returns the center of the active renderer

clear()

Clears plot by removing all actors and properties

close()

closes render window

disable()

Disable this renderer’s camera from being interactive

disable_eye_dome_lighting()

Disable eye dome lighting (EDL) for active renderer

enable()

Enable this renderer’s camera to be interactive

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

Enables picking of cells. Press r to enable retangle based selection. Press “r” again to turn it off. Selection will be saved to self.picked_cells. Uses last input mesh for input

Warning

Visible cell picking (through=False) is known to not perfrom well and produce incorrect selections on non-triangulated meshes if using any grpahics card other than NVIDIA. A warning will be thrown if the mesh is not purely triangles when using visible cell selection.

Parameters

• mesh (vtk.UnstructuredGrid, optional) – UnstructuredGrid grid to select cells from. Uses last input grid by default.

• 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

• show_message (bool, str) – Show the message about how to use the cell picking tool. If this is a string, that will be the message shown.

• kwargs (optional) – All remaining keyword arguments are used to control how the selection is intereactively displayed

enable_eye_dome_lighting()

Enable eye dome lighting (EDL) for active renderer

enable_image_style()

sets 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()

sets the interactive style to joystick

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_rubber_band_style()

sets 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_terrain_style()

sets 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_style()

sets the interactive style to trackball - the default syle

enable_zoom_style()

sets 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_vtkjs(filename, compress_arrays=False)

Export the current rendering scene as a VTKjs scene for rendering in a web browser

fly_to()

Given a position point, move the current camera’s focal point to that point. The movement is animated over the number of frames specified in NumberOfFlyFrames. The LOD desired frame rate is used.

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

Genrates an orbital path around the data scene

Parameters

• facotr (float) – A scaling factor when biulding 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()

Return the default camera position of the active renderer

get_pick_position()

Get the pick position/area as x0, y0, x1, y1

hide_axes()

Hide the axes orientation widget

property image

Returns an image array of current render window

property image_depth

Returns an image array of current render window

index_to_loc(index)

Convert a 1D index location to the 2D location on the plotting grid

isometric_view()

DEPRECATED: Please use view_isometric

isometric_view_interactive()

sets the current interactive render window to isometric view

key_press_event(obj, event)

Listens for key press event

left_button_down(obj, event_type)

Register the event for a left button down click

property length

Returns the length of the diagonal of the bounding box of the scene

link_views(views=0)

Links 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.

loc_to_index(loc)

Return index of the render window given a location index.

Parameters

loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1).

Returns

idx – Index of the render window.

Return type

int

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)

Establishes 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, bkg=True, write_frames=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 ot 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.

remove_actor(actor, reset_camera=False)

Removes an actor from the Plotter.

Parameters

• actor (vtk.vtkActor) – Actor that has previously added to the Renderer.

• reset_camera (bool, optional) – Resets camera so all actors can be seen.

Returns

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

Return type

bool

remove_bounding_box(loc=None)

Removes bounding box from the active renderer.

Parameters

loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If None, selects the last active Renderer.

remove_bounds_axes(loc=None)

Removes bounds axes from the active renderer.

Parameters

loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If None, selects the last active Renderer.

remove_legend()

Removes legend actor

remove_scalar_bar()

Removes scalar bar

property renderer

simply returns the active renderer

reset_camera()

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

property scale

The scaling of the active renderer.

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

Takes screenshot at current camera position

Parameters

• filename (str, optional) – Location to write image to. If None, no image is written.

• transparent_background (bool, optional) – Makes the background transparent. Default False.

• return_img (bool, optional) – If a string filename is given and this is true, a NumPy array of the image will be returned.

Returns

img – Array containing pixel RGB and alpha. Sized: [Window height x Window width x 3] for transparent_background=False [Window height x Window width x 4] for transparent_background=True

Return type

numpy.ndarray

Examples

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> plotter = pyvista.Plotter()
>>> actor = plotter.add_mesh(sphere)
>>> plotter.screenshot('screenshot.png') # doctest:+SKIP

set_background(color, loc='all')

Sets 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’

• loc (int, tuple, list, or str, optional) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If loc='all' then all render windows will have their background set.

set_focus(point)

sets focus to a point

set_position(point, reset=False)

sets camera position to a point

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

Scale all the datasets in the scene of the active renderer.

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

Parameters

• xscale (float, optional) – Scaling of the x axis. Must be greater than zero.

• yscale (float, optional) – Scaling of the y axis. Must be greater than zero.

• zscale (float, optional) – Scaling of the z axis. Must be greater than zero.

• reset_camera (bool, optional) – Resets camera so all actors can be seen.

set_viewup(vector)

sets camera viewup vector

show_axes()

Show the axes orientation widget

show_bounds(mesh=None, bounds=None, show_xaxis=True, show_yaxis=True, show_zaxis=True, show_xlabels=True, show_ylabels=True, show_zlabels=True, italic=False, bold=True, shadow=False, 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, loc=None, padding=0.0)

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

Parameters

• mesh (vtkPolydata or unstructured grid, optional) – 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) – A bug with vtk 6.3 in Windows seems to cause this function to crash this can be enabled for smoother plotting for other enviornments.

• 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. Dafuault is 0.5 to show the full box.

• loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If None, selects the last active Renderer.

• padding (float, optional) – An optional percent padding along each axial direction to cushion the datasets in the scene from the axes annotations. Defaults to have 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()
>>> _ = plotter.add_mesh(mesh)
>>> _ = plotter.show_bounds(grid='front', location='outer', all_edges=True)
>>> plotter.show() # doctest:+SKIP

show_grid(**kwargs)

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 silimar to matplotlib’s grid function.

subplot(index_x, index_y)

Sets the active subplot.

Parameters

• index_x (int) – Index of the subplot to activate in the x direction.

• index_y (int) – Index of the subplot to activate in the y direction.

unlink_views(views=None)

Unlinks 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.

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 vtkRenderWindowInteractor.Render() immediately.

update_bounds_axes()

Update the bounds of the active renderer

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

Updates the points of the 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) – Forces an update to the render window. 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)

Updates scalars of the 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) – Forces an update to the render window. Default True.

update_style()

view_isometric()

Resets the camera to a default isometric view showing all the actors in the scene.

view_vector(vector, viewup=None)

view_xy(negative=False)

View the XY plane

view_xz(negative=False)

View the XZ plane

view_yz(negative=False)

View the YZ plane

property window_size

returns render window size

write_frame()

Writes a single frame to the movie file

Plotter

Attributes

last_update_time
q_pressed
right_timer_id

Methods

plot(*args, **kwargs)	Present for backwards compatibility.
render()	renders main window
show([title, window_size, interactive, …])	Creates plotting window

class pyvista.Plotter(off_screen=None, notebook=None, shape=(1, 1), border=None, border_color='k', border_width=1.0, window_size=None)

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()
>>> _ = plotter.add_mesh(mesh, color='red')
>>> _ = plotter.add_mesh(another_mesh, color='blue')
>>> plotter.show() # doctest:+SKIP

Parameters

• off_screen (bool, optional) – Renders off screen when False. 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.

• border (bool, optional) – Draw a border around each render window. Default False.

• border_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’

• window_size (list, optional) – Window size in pixels. Defaults to [1024, 768]

last_update_time = 0.0

plot(*args, **kwargs)

Present for backwards compatibility. Use show() instead

q_pressed = False

render()

renders main window

right_timer_id = -1

show(title=None, window_size=None, interactive=True, auto_close=True, interactive_update=False, full_screen=False, screenshot=False, return_img=False, use_panel=None, cpos=None, height=400)

Creates plotting window

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.

• use_panel (bool, optional) – If False, the interactive rendering from panel will not be used in notebooks

• cpos (list(tuple(floats))) – The camera position to use

• height (int, optional) – height for panel pane. Only used with panel.

Returns

cpos – List of camera position, focal point, and view up

Return type

list

Renderer

Attributes

bounds	Bounds of all actors present in the rendering window
camera	The active camera for the rendering scene
camera_position	Returns camera position of active render window
center	Center of the bounding box around all data present in the scene

Methods

add_actor(uinput[, reset_camera, name, loc, …])	Adds an actor to render window.
add_axes_at_origin()	Add axes actor at origin
add_border([color, width])
add_bounding_box([color, corner_factor, …])	Adds an unlabeled and unticked box at the boundaries of plot.
add_bounds_axes(*args, **kwargs)	Deprecated
disable()	Disable this renderer’s camera from being interactive
disable_eye_dome_lighting()	Disable eye dome lighting (EDL)
enable()	Enable this renderer’s camera to be interactive
enable_eye_dome_lighting()	Enable eye dome lighting (EDL)
get_default_cam_pos()	Returns the default focal points and viewup.
get_pick_position()	Get the pick position/area as x0, y0, x1, y1
isometric_view()	DEPRECATED: Please use view_isometric
remove_actor(actor[, reset_camera])	Removes an actor from the Renderer.
remove_bounding_box()	Removes bounding box
remove_bounds_axes()	Removes bounds axes
reset_camera()	Reset camera so it slides along the vector defined from camera position to focal point until all of the actors can be seen.
set_scale([xscale, yscale, zscale, reset_camera])	Scale all the datasets in the scene.
show_bounds([mesh, bounds, show_xaxis, …])	Adds bounds axes.
update_bounds_axes()	Update the bounds axes of the render window
view_isometric()	Resets the camera to a default isometric view showing all the actors in the scene.
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_yz([negative])	View the YZ plane

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

Bases: vtkRenderingCorePython.vtkRenderer

add_actor(uinput, reset_camera=False, name=None, loc=None, culling=False)

Adds 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.

• loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1).

• culling (bool optional) – Does not render faces that should not be visible to the plotter. 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_axes_at_origin()

Add axes actor at origin

Returns

marker_actor – vtkAxesActor actor

Return type

vtk.vtkAxesActor

add_border(color=[1, 1, 1], width=2.0)

add_bounding_box(color=None, corner_factor=0.5, line_width=None, opacity=1.0, render_lines_as_tubes=False, lighting=None, reset_camera=None)

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.

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.

add_bounds_axes(*args, **kwargs)

Deprecated

property bounds

Bounds of all actors present in the rendering window

property camera

The active camera for the rendering scene

property camera_position

Returns camera position of active render window

property center

Center of the bounding box around all data present in the scene

disable()

Disable this renderer’s camera from being interactive

disable_eye_dome_lighting()

Disable eye dome lighting (EDL)

enable()

Enable this renderer’s camera to be interactive

enable_eye_dome_lighting()

Enable eye dome lighting (EDL)

get_default_cam_pos()

Returns 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

isometric_view()

DEPRECATED: Please use view_isometric

remove_actor(actor, reset_camera=False)

Removes an actor from the Renderer.

Parameters

• actor (vtk.vtkActor) – Actor that has previously added to the Renderer.

• reset_camera (bool, optional) – Resets camera so all actors can be seen.

Returns

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

Return type

bool

remove_bounding_box()

Removes bounding box

remove_bounds_axes()

Removes bounds axes

reset_camera()

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

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.

show_bounds(mesh=None, bounds=None, show_xaxis=True, show_yaxis=True, show_zaxis=True, show_xlabels=True, show_ylabels=True, show_zlabels=True, italic=False, bold=True, shadow=False, 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, loc=None, fmt=None, minor_ticks=False, padding=0.0)

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

Parameters

• mesh (vtkPolydata or unstructured grid, optional) – 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) – A bug with vtk 6.3 in Windows seems to cause this function to crash this can be enabled for smoother plotting for other enviornments.

• 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. Dafuault is 0.5 to show the full box.

• loc (int, tuple, or list) – Index of the renderer to add the actor to. For example, loc=2 or loc=(1, 1). If None, selects the last active Renderer.

• padding (float, optional) – An optional percent padding along each axial direction to cushion the datasets in the scene from the axes annotations. Defaults to have 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()
>>> _ = plotter.add_mesh(mesh)
>>> _ = plotter.show_bounds(grid='front', location='outer', all_edges=True)
>>> plotter.show() # doctest:+SKIP

update_bounds_axes()

Update the bounds axes of the render window

view_isometric()

Resets the camera to a default isometric view showing 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_yz(negative=False)

View the YZ plane

Plotting in a Jupyter Notebook

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()

# short example
cpos, image = sphere.plot(notebook=True)

# long example
plotter = pv.Plotter(notebook=True)
plotter.add_mesh(sphere)
plotter.show()

Jupyter Inline Plotting

To display interactive plots in Jupyter notebooks, use the pyvista.BackgroundPlotter to open a rendering window in the background that you can manipulate in real time from the Jupyter notebook:

import pyvista as pv
from pyvista import examples

dataset = examples.load_uniform()

plotter = pv.BackgroundPlotter()
plotter.add_mesh(dataset)

# Then in another cell, you can add more to the plotter
plotter.show_bounds()

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 pyvista.BackgroundPlotter:

import pyvista as pv
from pyvista import examples

dataset = examples.load_hexbeam()

p = pv.BackgroundPlotter()

p.add_mesh(dataset)

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

IPython Interactive Plotting Tools

PyVista comes packed with several interactive plotting tools to make using the filters a bit more intuitive (see IPython Tools). If in an IPython environment, call one of the tools on an input dataset to yield widgets that will control a filter or task in an interactive rendering scene. These tools create an pyvista.BackgroundPlotter instance which can be accessed under the .plotter attribute for further scene manipulation:

import pyvista as pv
from pyvista import examples

dataset = examples.load_hexbeam()

# Use the slicer tool
tool = pv.OrthogonalSlicer(dataset)

# Get the plotter for adding more datasets:
p = tool.plotter
p.show_grid()

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
from pyvista import examples


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


plotter = pv.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()