Metadata-Version: 2.4
Name: pyvistaqml
Version: 0.2.2
Summary: A Python library for seamless integration between PyVista (VTK) and modern Qt Quick (QML).
Author-email: Manuel Petit <manuel.petit@inria.fr>
License-Expression: LGPL-3.0-or-later
Project-URL: Homepage, https://gitlab.inria.fr/mosaic/pyvistaqml
Project-URL: Source, https://gitlab.inria.fr/mosaic/pyvistaqml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pyvista>=0.44
Requires-Dist: PySide6>=6.4
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-qt; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: doc
Requires-Dist: mkdocs; extra == "doc"
Requires-Dist: mkdocs-material; extra == "doc"
Requires-Dist: mkdocstrings[python]; extra == "doc"
Requires-Dist: pymdown-extensions; extra == "doc"
Dynamic: license-file

# PyVistaQML

[![Pipeline Status](https://gitlab.inria.fr/mosaic/pyvistaqml/badges/develop/pipeline.svg)](https://gitlab.inria.fr/mosaic/pyvistaqml/-/commits/develop)
[![Coverage](https://gitlab.inria.fr/mosaic/pyvistaqml/badges/develop/coverage.svg)](https://gitlab.inria.fr/mosaic/pyvistaqml/-/commits/develop)

[![PyPI version](https://img.shields.io/pypi/v/pyvistaqml.svg)](https://pypi.org/project/pyvistaqml/)
[![Anaconda version](https://anaconda.org/mosaic/pyvistaqml/badges/version.svg)](https://anaconda.org/mosaic/pyvistaqml)
[![Latest release date](https://anaconda.org/mosaic/pyvistaqml/badges/latest_release_date.svg)](https://anaconda.org/mosaic/pyvistaqml)

[![Python Versions](https://img.shields.io/badge/python-3.10_%7C_3.11_%7C_3.12_%7C_3.13_%7C_3.14-blue.svg)](https://pypi.org/project/pyvistaqml/)
[![OS Support](https://img.shields.io/badge/OS-Linux_%7C_macOS-blue.svg)](https://gitlab.inria.fr/mosaic/pyvistaqml)
[![Platform availability](https://anaconda.org/mosaic/pyvistaqml/badges/platforms.svg)](https://anaconda.org/mosaic/pyvistaqml)

[![License](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)

**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                                                     |
|:-------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------:|
| [![Single Plotter](docs/assets/base_preview.png)](https://mosaic.gitlabpages.inria.fr/pyvistaqml/assets/base_plotter.mp4) | [![Multi-Plotter](docs/assets/multi_preview.png)](https://mosaic.gitlabpages.inria.fr/pyvistaqml/assets/multi_plotter.mp4) |
---

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

```bash
# 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:

```bash
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](https://github.com/nicanor-romero/QtVtk):** Original C++/QML integration.
* **[Dao Duc Tung](https://github.com/dao-duc-tung/qml-vtk-python?tab=readme-ov-file):** 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*"`
