pyvistaqml 0.2.4

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 6 Quick (QML) via PySide6.

⚠️ 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:

👉 Official Documentation 👈

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/PyVista 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/PyVista access when needed.
• Multi-Renderer & Camera Linking: Fully supports multiple viewports and camera synchronization.

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.

Prerequisites

pyvistaqml requires Python >= 3.10, PySide6 >= 6.4 (Qt5 not supported), and PyVista >= 0.44.

1. Standard Installation

For most users, installing via standard package managers is recommended.

# Via PyPI
pip install pyvistaqml

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

2. Development / From Source

If you want to contribute, run tests, or use the latest development version, clone the repository and use either Conda or Pixi:

git clone https://gitlab.inria.fr/mosaic/pyvistaqml.git
cd pyvistaqml

# Option A: Conda
conda create -n pyvistaqml python=3.12
conda activate pyvistaqml
pip install -e ".[test]"
pytest

# Option B: Pixi
pixi install -e py312
pixi run -e py312 pytest

🚀 Quick Start

For a detailed walkthrough on integrating Python backend logic with a QML interface using pyvistaqml, please refer to:

👉 Getting Started Tutorial 👈

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.