Widget API

The pyvista.BasePlotter class inherits all of the widget methods in pyvista.WidgetHelper, so all of the following methods are available from any PyVista plotter.

Attributes

Methods

add_box_widget(callback[, bounds, factor, …])

Add a box widget to the scene.

add_checkbox_button_widget(callback[, …])

Add a checkbox button widget to the scene.

add_line_widget(callback[, bounds, factor, …])

Add a line widget to the scene.

add_mesh_clip_box(mesh[, invert, …])

Clip a mesh using a box widget.

add_mesh_clip_plane(mesh[, normal, invert, …])

Clip a mesh using a plane widget.

add_mesh_isovalue(mesh[, scalars, …])

Create a contour of a mesh with a slider.

add_mesh_slice(mesh[, normal, …])

Slice a mesh using a plane widget.

add_mesh_slice_orthogonal(mesh[, …])

Slice a mesh with three interactive planes.

add_mesh_slice_spline(mesh[, …])

Slice a mesh with a spline widget.

add_mesh_threshold(mesh[, scalars, invert, …])

Apply a threshold on a mesh with a slider.

add_plane_widget(callback[, normal, origin, …])

Add a plane widget to the scene.

add_slider_widget(callback, rng[, value, …])

Add a slider bar widget.

add_sphere_widget(callback[, center, …])

Add one or many sphere widgets to a scene.

add_spline_widget(callback[, bounds, …])

Create and add a spline widget to the scene.

add_text_slider_widget(callback, data[, …])

Add a text slider bar widget.

clear_box_widgets()

Disable all of the box widgets.

clear_button_widgets()

Disable all of the button widgets.

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.

close()

Close the widgets.

class pyvista.WidgetHelper

Bases: object

An internal class to manage widgets.

It also manages and other helper methods involving widgets.

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_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_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_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_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) – The string label of the slider widget

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

  • pass_widget (bool) – If true, the widget will be passed as the last argument of the callback

  • 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 rcParams['slider_style']. 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 a XYZ coordinate.

  • center (tuple(float)) – 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) – The radius of the sphere

  • theta_resolution (int , optional) – Set the number of points in the longitude direction (ranging from start_theta to end_theta).

  • phi_resolution (int, optional) – Set the number of points in the latitude direction (ranging from start_phi to end_phi).

  • color (str) – The color of the sphere’s surface

  • style (str) – Representation style: surface or wireframe

  • selected_color (str) – Color of the widget when selected during interaction

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

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_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 rcParams['slider_style']. Defaults to None.

Returns

slider_widget – The VTK slider widget configured to display text.

Return type

vtk.vtkSliderWidget

clear_box_widgets()

Disable all of the box widgets.

clear_button_widgets()

Disable all of the button widgets.

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.

close()

Close the widgets.