Metadata-Version: 2.5
Name: visiongraph
Version: 1.2.0
Summary: Visiongraph is a computer vision pipeline that provides ready-to-use modules for quick prototyping of image-based algorithms.
Project-URL: Homepage, https://github.com/cansik/visiongraph
Project-URL: Documentation, https://cansik.github.io/visiongraph/
Project-URL: Repository, https://github.com/cansik/visiongraph.git
Author-email: Florian Bruggisser <github@broox.ch>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.10
Requires-Dist: numpy>2
Requires-Dist: opencv-python~=4.12; python_version > '3.9'
Requires-Dist: opencv-python~=4.7.0; python_version <= '3.9'
Requires-Dist: requests
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: vector~=1.6.3
Provides-Extra: all
Requires-Dist: depthai~=2.30; (platform_system != 'Darwin' or platform_machine == 'arm64') and extra == 'all'
Requires-Dist: faiss-cpu; extra == 'all'
Requires-Dist: filterpy; extra == 'all'
Requires-Dist: mediapipe-numpy2~=0.10.21; extra == 'all'
Requires-Dist: moviepy; extra == 'all'
Requires-Dist: numba~=0.61; extra == 'all'
Requires-Dist: onnxruntime~=1.23.0; extra == 'all'
Requires-Dist: openvino~=2025.4.1; extra == 'all'
Requires-Dist: pyk4a-bundle~=1.5.0.1; (platform_system == 'Windows' or platform_system == 'Linux') and extra == 'all'
Requires-Dist: pyopengl; (platform_system == 'Darwin' or platform_system == 'Windows') and extra == 'all'
Requires-Dist: pyrealsense2-macosx~=2.56.5; (platform_system == 'Darwin') and extra == 'all'
Requires-Dist: pyrealsense2~=2.56.5; (platform_system != 'Darwin') and extra == 'all'
Requires-Dist: spoutgl~=0.1.1; (platform_system == 'Windows') and extra == 'all'
Requires-Dist: syphon-python~=0.1.1; (platform_system == 'Darwin') and extra == 'all'
Requires-Dist: vidgear[core]~=0.3.3; extra == 'all'
Provides-Extra: azure
Requires-Dist: pyk4a-bundle~=1.5.0.1; (platform_system == 'Windows' or platform_system == 'Linux') and extra == 'azure'
Provides-Extra: depthai
Requires-Dist: depthai~=2.30; (platform_system != 'Darwin' or platform_machine == 'arm64') and extra == 'depthai'
Provides-Extra: faiss
Requires-Dist: faiss-cpu; extra == 'faiss'
Provides-Extra: fbs
Requires-Dist: pyopengl; (platform_system == 'Darwin' or platform_system == 'Windows') and extra == 'fbs'
Requires-Dist: spoutgl~=0.1.1; (platform_system == 'Windows') and extra == 'fbs'
Requires-Dist: syphon-python~=0.1.1; (platform_system == 'Darwin') and extra == 'fbs'
Provides-Extra: media
Requires-Dist: moviepy; extra == 'media'
Requires-Dist: vidgear[core]~=0.3.3; extra == 'media'
Provides-Extra: mediapipe
Requires-Dist: mediapipe-numpy2~=0.10.21; extra == 'mediapipe'
Provides-Extra: mot
Requires-Dist: filterpy; extra == 'mot'
Provides-Extra: numba
Requires-Dist: numba~=0.61; extra == 'numba'
Provides-Extra: onnx
Requires-Dist: onnxruntime~=1.23.0; extra == 'onnx'
Provides-Extra: onnx-directml
Requires-Dist: onnxruntime-directml~=1.23.0; (platform_system == 'Windows') and extra == 'onnx-directml'
Requires-Dist: onnxruntime~=1.23.0; (platform_system == 'Darwin' or platform_system == 'Linux') and extra == 'onnx-directml'
Provides-Extra: onnx-gpu
Requires-Dist: onnxruntime-gpu~=1.23.0; (platform_system != 'Darwin') and extra == 'onnx-gpu'
Requires-Dist: onnxruntime~=1.23.0; (platform_system == 'Darwin') and extra == 'onnx-gpu'
Provides-Extra: openvino
Requires-Dist: openvino~=2025.4.1; extra == 'openvino'
Provides-Extra: realsense
Requires-Dist: pyrealsense2-macosx~=2.56.5; (platform_system == 'Darwin') and extra == 'realsense'
Requires-Dist: pyrealsense2~=2.56.5; (platform_system != 'Darwin') and extra == 'realsense'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/f30f10ef-8058-4306-882f-6301226107be">
  <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/0ed34695-ca0e-47ff-aebb-eb59ff851770">
  <img src="https://github.com/user-attachments/assets/0ed34695-ca0e-47ff-aebb-eb59ff851770" alt="Visiongraph Logo Bright" width="75%">
</picture>

# Visiongraph

[![Ruff](https://github.com/cansik/visiongraph/actions/workflows/code.yml/badge.svg)](https://github.com/cansik/visiongraph/actions/workflows/code.yml)
[![PyPI](https://img.shields.io/pypi/v/visiongraph)](https://pypi.org/project/visiongraph/)
![Pepy Total Downloads](https://img.shields.io/pepy/dt/visiongraph)
[![Documentation](https://img.shields.io/badge/read-documentation-blue)](https://cansik.github.io/visiongraph/visiongraph.html#documentation)

Visiongraph is a computer-vision pipeline library designed to simplify the prototyping of image-based algorithms with ready-to-use modules and composable graph nodes. Built on top of OpenCV, it also integrates popular frameworks such as [Intel OpenVINO](https://github.com/openvinotoolkit/openvino), [Google MediaPipe](https://github.com/google-ai-edge/mediapipe), and [DepthAI](https://pypi.org/project/depthai/). The library is designed with a focus on real-time applications and edge deployment.

![Readme Example](doc/visiongraph-readme-street.webp)

*Object detection, segmentation and pose estimation example.*

Here is a minimal example that opens a live webcam capture, runs SSD object detection, and displays the annotated result.

```python
import cv2
from visiongraph import vg

with (vg.VideoCaptureInput() as cam,
      vg.SSDDetector.create(vg.SSDConfig.SSDLiteMobileNetV2_FP32) as ssd):
    while True:
        _, frame = cam.read()
        if frame is None:
            break

        results = ssd.process(frame)
        results.annotate(frame)

        cv2.imshow("Frame", frame)
        cv2.waitKey(1)
```

Get started with `visiongraph` by reading the **[documentation](https://cansik.github.io/visiongraph/visiongraph.html#documentation)**.

## Research Origins

Visiongraph originated as a research codebase for rapid prototyping in computer vision. It has since supported a range of academic, artistic, and applied projects. Selected examples include:

* [Are You Talking to Me? A Case Study in Emotional Human-Machine Interaction](https://ojs.aaai.org/index.php/AIIDE/article/view/27538)
* [reconFIGURE: Confronting Audiences with Digital Doppelgängers](https://dl.acm.org/doi/abs/10.1145/3664208)
* [Space Stream](https://github.com/cansik/space-stream)
* [Kamituga | Digital Gold](https://blog.zhdk.ch/digitalgold/)

## Installation

Visiongraph supports Python 3.10, 3.11 and 3.12. Other versions may also work, but are not officially supported. In
practice, version compatibility is usually limited by third-party dependencies rather than by Visiongraph itself.

To add Visiongraph with all available optional dependencies to a project managed by
[uv](https://docs.astral.sh/uv/), run:

```bash
uv add "visiongraph[all]"
```

Alternatively, install it into the active Python environment with [pip](https://pip.pypa.io/):

```bash
pip install "visiongraph[all]"
```

It is also possible, and usually preferable, to install only the extras you actually need:

```bash
# example: install RealSense and OpenVINO support only
uv add "visiongraph[realsense,openvino]"
```

The equivalent pip command is:

```bash
pip install "visiongraph[realsense,openvino]"
```

Please read more about the extra packages in the [documentation](https://cansik.github.io/visiongraph/visiongraph.html#extras).

### Optional Mediapipe Support

Visiongraph can integrate Google’s [MediaPipe](https://github.com/google-ai-edge/mediapipe) for advanced hand, face, pose and tracking pipelines. Unfortunately, the official PyPI MediaPipe wheels declare a strict dependency on `numpy<2.0`, which prevents installation alongside NumPy 2.x, even though most functionality works fine with NumPy 2.0 and above. To work around this limitation, we maintain a custom [mediapipe-numpy2](https://github.com/cansik/mediapipe-numpy2) build that removes the `<2.0` pin.

When you install the `mediapipe` extra with uv or pip, the package manager automatically fetches the matching patched
wheel for your operating system and Python version.

#### Official MediaPipe Compatibility

The official `mediapipe` package currently declares `numpy<2.0`, while Visiongraph requires NumPy 2.x. Consequently,
standard uv and pip dependency resolution cannot install the two packages together. Use the `mediapipe` extra shown
above unless you deliberately manage and override dependency metadata in your own environment.

## Model Assets

Most estimators download their model files on demand and store them in `~/.visiongraph/assets/` by default. Set `VISIONGRAPH_ASSET_DIR` to use a different location.
Visiongraph itself is released under the MIT License, but individual downloadable models can use different licenses,
including copyleft terms such as AGPL or GPL. Check [MODEL_ATTRIBUTIONS.md](MODEL_ATTRIBUTIONS.md) for the license of
the specific model you plan to ship, redistribute, or use in a commercial product.

Images and project artwork stored in the repository's `assets` directory are documented in
[assets/ATTRIBUTIONS.md](assets/ATTRIBUTIONS.md).

## Examples
Run an example with `uv run examples/<ExampleFile>.py`, for example `uv run examples/SimpleVisionGraph.py`.

To demonstrate the possibilities of visiongraph, the repository already contains a number of ready-to-run [examples](examples). Here is a selection of the current examples:

- [SimpleVisionGraph](examples/SimpleVisionGraph.py) - A minimal graph example for live object detection and tracking.
- [VisionGraphExample](examples/VisionGraphExample.py) - A face detection and tracking example with custom callbacks.
- [InputExample](examples/InputExample.py) - A basic input example that previews the stream and reports depth when available.
- [DepthCameraExample](examples/DepthCameraExample.py) - Display the depth map next to the color image for a supported depth camera.
- [FaceDetectionExample](examples/FaceDetectionExample.py) - A face detection pipeline example.
- [FindFaceExample](examples/FindFaceExample.py) - A face recognition example to find a target face.
- [CascadeFaceDetectionExample](examples/CascadeFaceDetectionExample.py) - A face detection pipeline that also predicts facial landmarks.
- [HandDetectionExample](examples/HandDetectionExample.py) - A hand detection pipeline example.
- [PoseEstimationExample](examples/PoseEstimationExample.py) - A pose estimation pipeline that annotates generic pose keypoints.
- [ProjectedPoseExample](examples/ProjectedPoseExample.py) - Project pose estimation into 3D space with a RealSense camera.
- [ObjectDetectionExample](examples/ObjectDetectionExample.py) - An object detection example.
- [InstanceSegmentationExample](examples/InstanceSegmentationExample.py) - Instance segmentation based on the COCO dataset.
- [InpaintExample](examples/InpaintExample.py) - A GAN-based inpainting example.
- [MidasDepthExample](examples/MidasDepthExample.py) - Real-time monocular depth prediction with the [midas-small](https://github.com/isl-org/MiDaS) network.
- [RGBDSmoother](examples/RGBDSmoother.py) - Smooth RGB-D depth map videos with a one-euro filter per pixel.
- [FaceMeshVVADExample](examples/FaceMeshVVADExample.py) - Detect voice activation by landmark sequence classification.

There are also additional projects that use visiongraph in practice:

- [Spout/Syphon RGB-D Example](https://github.com/cansik/spout-rgbd-example) - Share RGB-D images over Spout or Syphon.
- [NDI Input / Output](https://github.com/cansik/visiongraph-ndi) - Receive and share video frames over NDI.
- [WebRTC Input](https://github.com/cansik/visiongraph-webrtc) - WebRTC input example for visiongraph.

## Development

To develop Visiongraph itself, clone this repository and install the dependencies with
[uv](https://docs.astral.sh/uv/getting-started/installation/):

```bash
# from the repository root
make sync
```

### Build

Build the source distribution and wheel from the repository root. The build regenerates the required repository
artifacts first and writes the packages to `./dist`:

```bash
make build
```

To download local copies of all model license texts referenced by repository-backed assets into `./build/licenses`, run:

```bash
make download-model-licenses
```

### Docs

Generate the deployable documentation in `./docs` with:

```bash
make docs
```

To preview the documentation locally with pdoc's development server, run:

```bash
make docs-serve
```

### Code Quality and Tests

Format the repository and apply auto-fixable Ruff rules:

```bash
make autoformat
```

Run the non-mutating lint and formatting checks individually, or run the full validation suite:

```bash
make lint       # run Ruff lint checks
make fmt-check  # check formatting without changing files
make test       # run the full unit test suite
make check      # run lint, formatting, and tests
```

## Dependencies

Parts of these libraries are directly included and adapted to work with visiongraph. For more information, please see the [third party notices](THIRD_PARTY_NOTICES.md).

Below is a list of visiongraph dependencies and their licenses, provided without guarantee of correctness:

```
depthai               MIT License
faiss-cpu             MIT License & BSD-3-Clause
filterpy              MIT License
mediapipe-numpy2      Apache License 2.0
moviepy               MIT License
numba                 BSD License
numpy                 MIT License
onnxruntime           MIT License
onnxruntime-directml  MIT License
onnxruntime-gpu       MIT License
opencv-python         Apache License 2.0
openvino              Apache License 2.0
pdoc                  MIT License
pyk4a                 MIT License
pyopengl              BSD License
pyrealsense2          Apache License 2.0
pyrealsense2-macosx   Apache License 2.0
pytest                MIT License
requests              Apache License 2.0
ruff                  MIT License
scipy                 MIT License
hatchling             MIT License
SpoutGL               BSD License
syphon-python         MIT License
tqdm                  MIT License
ty                    MIT License
vector                BSD License
vidgear               Apache License 2.0
wheel                 MIT License
```

For more information about the dependencies, see [pyproject.toml](pyproject.toml).

Please **note** that the library code is MIT-licensed, but some downloadable models, such as Ultralytics YOLOv8 and YOLOv11, use their own licenses (for example AGPLv3). Model provenance and license information is listed in [MODEL_ATTRIBUTIONS.md](MODEL_ATTRIBUTIONS.md).

## Credits

Developed at the [Immersive Arts Space](https://blog.zhdk.ch/immersivearts/),
[Zurich University of the Arts (ZHdK)](https://www.zhdk.ch/).  
Maintained by Florian Bruggisser.  

Released under the MIT License. See [LICENSE](LICENSE) for details.
