pyvistaqml 0.2.3

A Python library for seamless integration between PyVista (VTK) and modern Qt Quick (QML).

PyVistaQML

A robust, thread-safe bridge between PyVista (VTK) and modern Qt Quick (QML).

⚠️ Experimental Project ⚠️

PyVistaQML is currently an experimental library. It has been deeply tested and developed exclusively on macOS (Apple Silicon). While the underlying libraries are cross-platform, the OpenGL threading bridge may behave differently on Windows or Linux. Use with caution in production environments.

pyvistaqml is designed as a first attempt to mimic the behavior of pyvistaqt, but for the QML ecosystem. It allows you to embed high-performance 3D visualizations directly into QML applications using the familiar PyVista API.

Single Plotter API	Multi-Plotter Sync

Documentation

Full tutorials, API reference, and concept guides are available at:

👉 https://mosaic.gitlabpages.inria.fr/pyvistaqml 👈

Why pyvistaqml?

Integrating VTK into QML introduces two major architectural hurdles that this library handles automatically:

• The Thread Divide: QML separates UI logic from OpenGL rendering. Modifying VTK objects from the main thread usually causes a segmentation fault. We use a Proxy Engine to route commands safely.
• The Memory Trap: Python’s garbage collector often fails to see C++ circular references in VTK. We provide an aggressive Synchronous Teardown to prevent GPU memory leaks.

Installation

We highly recommend using pip to handle the underlying Qt and VTK binaries.

# Via PyPI
pip install pyvistaqml

# Via Anaconda
conda install -c mosaic -c conda-forge pyvistaqml

# Via Source
git clone https://gitlab.inria.fr/mosaic/pyvistaqml.git
cd pyvistaqml
conda create -n pyvistaqml python=3.12
conda activate pyvistaqml
python -m pip install -e .

You can also run the tests to verify your installation:

python -m pip install -e ".[test]"
pytest

Features

• Drop-in PyVista API: Inherits from pyvista.BasePlotter. Most of your existing PyVista code will work out of the box.
• Asynchronous Proxy Engine: Interact with VTK objects synchronously in Python; the library handles the async thread routing under the hood.
• Native QML Fbo Component: Renders directly into the Qt Quick Scene Graph using a custom Framebuffer Object.
• Advanced Render Control: Support for debounce_render, custom threading decorators, and direct synchronous VTK access when needed.
• Multi-Renderer & Camera Linking: Fully supports multiple viewports and hardware-accelerated camera synchronization.

Acknowledgments

This project is a higher-level framework built upon the foundational work of:

• Nicanor Romero: Original C++/QML integration.
• Dao Duc Tung: Initial Python port of the OpenGL framebuffer bridge.

pyvistaqml is distributed under the LGPLv3 license. See LICENSE.md for details.

Included Examples

The repository includes comprehensive examples to help you get started:

• examples/base_plotter_methods/: A fully featured test bench demonstrating how to use almost all BasePlotter capabilities inside a QML UI. It covers adding 3D geometry, applying VTK widgets (sliders, planes, boxes), handling complex picking events, and manipulating the camera.

• examples/multiplotter/: Demonstrates advanced architecture by dynamically spawning a grid of multiple 3D viewports. It highlights hardware-accelerated camera synchronization (link_cameras), dynamic QML Repeater integration, and memory tracking.

Troubleshooting

VTK & Conda-Forge Warnings / Crashes (Linux & macOS)

Recent Conda versions of VTK (>=9.5) use the viskores engine, which can cause warnings, errors, or even segfaults. While it tends to be robust on macOS Silicon, Linux systems (especially with CUDA) are highly prone to crashing.

Solution: We strongly recommend using pip to install vtk for maximum stability across all hardware. If you must use Conda, force the CPU-only VTK package to avoid these issues: conda install -c conda-forge "vtk=*=*cpu*"