API Reference#

Background Plotter #

Attributes

Methods

class pyvistaqt.BackgroundPlotter(show: bool = True, app: QApplication | None = None, window_size: tuple[int, int] | None = None, off_screen: bool | None = None, allow_quit_keypress: bool = True, toolbar: bool = True, menu_bar: bool = True, editor: bool = True, update_app_icon: bool | None = None, app_window_class: type[MainWindow] | None = None, **kwargs: Any)#

Bases: QtInteractor

Qt interactive plotter.

Background plotter for pyvista that allows you to maintain an interactive plotting window without blocking the main python thread.

Parameters:

show – Show the plotting window. If False, show this window by running show()
app (optional) – Creates a QApplication if left as None.
window_size – Window size in pixels. Defaults to [1024, 768]
off_screen – Renders off screen when True. Useful for automated screenshots or debug testing.
allow_quit_keypress – Allow user to exit by pressing "q".
toolbar (bool) – If True, display the default camera toolbar. Defaults to True.
menu_bar (bool) – If True, display the default main menu. Defaults to True.
editor (bool) – If True, display the VTK object editor. Defaults to True.
update_app_icon – If True, update_app_icon will be called automatically to update the Qt app icon based on the current rendering output. If None, the logo of PyVista will be used. If False, no icon will be set. Defaults to None.
title (str, optional) – Title of plotting window.
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 smothing
point_smoothing (bool, optional) – If True, enable point smothing
polygon_smoothing (bool, optional) – If True, enable polygon smothing
auto_update (float, bool, optional) – Automatic update rate in seconds. Useful for automatically updating the render window when actors are change without being automatically Modified. If set to True, update rate will be 1 second.
app_window_class (None, class, optional) – A subclass of MainWindow to use when creating the app window.

Examples

>>> import pyvista as pv
>>> from pyvistaqt import BackgroundPlotter
>>> plotter = BackgroundPlotter()
>>> _ = plotter.add_mesh(pv.Sphere())

ICON_TIME_STEP = 5.0#

add_callback(func: Callable, interval: int = 1000, count: int | None = None) → None#

Add a function that can update the scene in the background.

Parameters:

func – Function to be called with no arguments.
interval – Time interval between calls to func in milliseconds.
count – Number of times func will be called. If None, func will be called until the main window is closed.

add_editor() → None#: Add the editor.

add_menu_bar() → None#: Add the main menu bar.

add_toolbars() → None#: Add the toolbars.

clear_camera_positions() → None#: Clear all camera positions.

close() → None#

Close the plotter.

This function closes the window which in turn will close the plotter through signal_close.

reset_key_events() → None#

Reset all of the key press events to their defaults.

Handles closing configuration for q-key.

save_camera_position() → None#: Save camera position to saved camera menu for recall.

scale_axes_dialog(show: bool = True) → ScaleAxesDialog#: Open scale axes dialog.

set_icon(img: ndarray | str) → None#

Set the icon image.

Parameters:: img (numpy.ndarray, shape (w, h, c) | str) – The image. Should be uint8 and square (w == h). Can have 3 or 4 color/alpha channels (c). Can also be a string path that QIcon can load.

Notes

Currently string paths can silently fail, so make sure your path is something that produces a valid QIcon(img).

staticMetaObject = PySide6.QtCore.QMetaObject("BackgroundPlotter" inherits "QtInteractor": )#

update_app_icon() → None#: Update the app icon if the user is not trying to resize the window.

property window_size: tuple[int, int]#: Return render window size.

MultiPlotter #

Attributes

Methods

class pyvistaqt.MultiPlotter(app: QApplication | None = None, nrows: int = 1, ncols: int = 1, show: bool = True, window_size: tuple[int, int] | None = None, title: str | None = None, off_screen: bool | None = None, **kwargs: Any)#

Bases: object

Qt interactive plotter.

Multi plotter for pyvista that allows to maintain an interactive window with multiple plotters without blocking the main python thread.

Note

MultiPlotter is deprecated and will be removed in 0.14. Use BackgroundPlotter with its shape argument instead, or embed multiple QtInteractor instances directly in your own QLayout for full control.

Parameters:

app (optional) – Creates a QApplication if left as None.
nrows (int) – Number of rows. Defaults to 1.
ncols (int) – Number of columns. Defaults to 1.
show (bool) – Show the plotting window. If False, show this window by running show()
window_size (tuple, optional) – Window size in pixels. Defaults to [1024, 768]
off_screen (bool, optional) – Renders off screen when True. Useful for automated screenshots or debug testing.

close() → None#: Close the multi plotter.

show() → None#: Show the multi plotter.

QtInteractor #

Attributes

Methods

class pyvistaqt.QtInteractor(parent: QWidget | None = None, title: str | None = None, off_screen: bool | None = None, multi_samples: int | None = None, line_smoothing: bool = False, point_smoothing: bool = False, polygon_smoothing: bool = False, auto_update: float | bool = 5.0, **kwargs: Any)#

Bases: QVTKRenderWindowInteractor, BasePlotter

Extend QVTKRenderWindowInteractor class.

This adds the methods available to pyvista.Plotter.

Parameters:

parent – Qt parent.
title – Title of plotting window.
multi_samples – 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 – If True, enable line smothing
point_smoothing – If True, enable point smothing
polygon_smoothing – If True, enable polygon smothing
auto_update – Number of updates per second. Useful for automatically updating the render window when actors are change without being automatically Modified.

close() → None#: Quit application (intentionally returns None, unlike QWidget.close).

closeEvent(evt: QCloseEvent) → None#: Stop the render timer before the widget is finalized (see #762).

disable() → None#: Disable this renderer’s camera from being interactive.

dragEnterEvent(event: QDragEnterEvent) → None#

Event is called when something is dropped onto the vtk window.

Only triggers event when event contains file paths that exist. User can drop anything in this window and we only want to allow files.

dropEvent(event: QDropEvent) → None#: Event is called after dragEnterEvent.

enable() → None#: Enable this renderer’s camera to be interactive.

enable_depth_peeling(*args: Any, **kwargs: Any) → bool#

Enable depth peeling, declaring the GL backend pyvista should probe with.

pyvista probes for depth peeling support by rendering into a throwaway render window whose class it infers from the environment, and that inference is wrong for a Qt application running on xcb inside a Wayland session. See _gl_backend_for.

gesture_event(event: QGestureEvent) → bool#: Handle gesture events.

key_press_event(obj: Any, event: Any) → None#: Call key_press_event using a signal.

key_press_event_signal#

link_views_across_plotters(other_plotter: Any, view: int = 0, other_views: Any = None) → None#

Link the views’ cameras across two plotters.

Parameters:

other_plotter (BackgroundPlotter) – The plotter whose views will be linked.
view (int) – Link the views in other_plotter to the this view index.
other_views (int | list of int) – Link these views from other_plotter to the reference view. The default is None, in which case all views from other_plotter will be linked to the reference view.

Note

For linking views belonging to a single plotter, please use pyvista’s Plotter.link_views method.

render() → None#: Override the render method to handle threading issues.

render_signal#

staticMetaObject = PySide6.QtCore.QMetaObject("QtInteractor" inherits "QVTKRenderWindowInteractor": Methods: #37 type=Signal, signature=render_signal() #38 type=Signal, signature=key_press_event_signal(PyObject,QString), parameters=PyObject, QString )#

Class inheritance #

This module contains the QtInteractor and BackgroundPlotter.

Diagram #

Inheritance:

BackgroundPlotter
+-- QtInteractor
    |-- QVTKRenderWindowInteractor  (pyvistaqt.rwi: FBO-based, no native
    |   +-- QOpenGLWidget            window handle -- Wayland-compatible)
    +-- BasePlotter

MainWindow
+-- QMainWindow

Implementation #

BackgroundPlotter.__init__(...) -> None
|-- self.app_window: MainWindow = app_window_class(title=...)
|-- self.frame: QFrame = QFrame(parent=self.app_window)
+-- QtInteractor.__init__(parent=self.frame)
    |-- with _no_base_plotter_init():
    |   +-- QVTKRenderWindowInteractor.__init__(parent=parent)
    |       +-- QOpenGLWidget.__init__(parent)
    |-- BasePlotter.__init__(**kwargs)
    +-- self.ren_win: vtkRenderWindow = self.GetRenderWindow()

Because QVTKRenderWindowInteractor.__init__ calls QOpenGLWidget.__init__ and the Qt bindings continue the cooperative super() chain past the Qt classes, this triggers a spurious BasePlotter.__init__ call with no arguments. This cannot be solved by using super() because QVTKRenderWindowInteractor.__init__ does not use super(), and the chaining happens inside Qt’s widget initialization, outside of our control. We therefore temporarily monkey-patch BasePlotter.__init__ with a no-op during the QVTKRenderWindowInteractor.__init__ call (see _no_base_plotter_init), then call BasePlotter.__init__ explicitly with the real arguments.

API Reference#

Background Plotter#

MultiPlotter#

QtInteractor#

Class inheritance#

Diagram#

Implementation#

Background Plotter #

MultiPlotter #

QtInteractor #

Class inheritance #

Diagram #

Implementation #