Metadata-Version: 2.4
Name: pyvistaqml
Version: 0.2.5
Summary: A Python library for seamless integration between PyVista (VTK) and modern Qt Quick (QML).
Author-email: Manuel Petit <manuel.petit@inria.fr>, Jonathan Legrand <jonathan.legrand@ens-lyon.fr>
Maintainer-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: Operating System :: Unix
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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)
&nbsp;&nbsp;
[![PyPI version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fpyvistaqml%2Fjson&query=%24.info.version&label=pypi&color=orange)](https://pypi.org/project/pyvistaqml/)
[![Anaconda version](https://anaconda.org/mosaic/pyvistaqml/badges/version.svg)](https://anaconda.org/mosaic/pyvistaqml)
&nbsp;&nbsp;
[![Python Versions](https://img.shields.io/badge/python-3.10%2B-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)
[![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 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 |
| :---: | :---: |
| [![Preview](https://gitlab.inria.fr/mosaic/pyvistaqml/-/raw/main/docs/assets/base_preview.png)](https://mosaic.gitlabpages.inria.fr/pyvistaqml/assets/base_plotter.mp4) | [![Preview](https://gitlab.inria.fr/mosaic/pyvistaqml/-/raw/main/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:

👉 [**Official Documentation**](https://mosaic.gitlabpages.inria.fr/pyvistaqml) 👈

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

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

```bash
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](https://mosaic.gitlabpages.inria.fr/pyvistaqml/tutorials/getting_started/) 👈

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