Visiongraph
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, Google MediaPipe, and DepthAI. The library is designed with a focus on real-time applications and edge deployment.
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.
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.
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
- reconFIGURE: Confronting Audiences with Digital Doppelgängers
- Space Stream
- Kamituga | Digital Gold
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, run:
uv add "visiongraph[all]"
Alternatively, install it into the active Python environment with pip:
pip install "visiongraph[all]"
It is also possible, and usually preferable, to install only the extras you actually need:
# example: install RealSense and OpenVINO support only
uv add "visiongraph[realsense,openvino]"
The equivalent pip command is:
pip install "visiongraph[realsense,openvino]"
Please read more about the extra packages in the documentation.
Optional Mediapipe Support
Visiongraph can integrate Google’s 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 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 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.
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. Here is a selection of the current examples:
- SimpleVisionGraph - A minimal graph example for live object detection and tracking.
- VisionGraphExample - A face detection and tracking example with custom callbacks.
- InputExample - A basic input example that previews the stream and reports depth when available.
- DepthCameraExample - Display the depth map next to the color image for a supported depth camera.
- FaceDetectionExample - A face detection pipeline example.
- FindFaceExample - A face recognition example to find a target face.
- CascadeFaceDetectionExample - A face detection pipeline that also predicts facial landmarks.
- HandDetectionExample - A hand detection pipeline example.
- PoseEstimationExample - A pose estimation pipeline that annotates generic pose keypoints.
- ProjectedPoseExample - Project pose estimation into 3D space with a RealSense camera.
- ObjectDetectionExample - An object detection example.
- InstanceSegmentationExample - Instance segmentation based on the COCO dataset.
- InpaintExample - A GAN-based inpainting example.
- MidasDepthExample - Real-time monocular depth prediction with the midas-small network.
- RGBDSmoother - Smooth RGB-D depth map videos with a one-euro filter per pixel.
- FaceMeshVVADExample - Detect voice activation by landmark sequence classification.
There are also additional projects that use visiongraph in practice:
- Spout/Syphon RGB-D Example - Share RGB-D images over Spout or Syphon.
- NDI Input / Output - Receive and share video frames over NDI.
- WebRTC Input - WebRTC input example for visiongraph.
Development
To develop Visiongraph itself, clone this repository and install the dependencies with uv:
# 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:
make build
To download local copies of all model license texts referenced by repository-backed assets into ./build/licenses, run:
make download-model-licenses
Docs
Generate the deployable documentation in ./docs with:
make docs
To preview the documentation locally with pdoc's development server, run:
make docs-serve
Code Quality and Tests
Format the repository and apply auto-fixable Ruff rules:
make autoformat
Run the non-mutating lint and formatting checks individually, or run the full validation suite:
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.
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.
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.
Credits
Developed at the Immersive Arts Space,
Zurich University of the Arts (ZHdK).
Maintained by Florian Bruggisser.
Released under the MIT License. See LICENSE for details.
1 maintainer
Release files for visiongraph 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| visiongraph-1.2.0.tar.gz | 2.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| visiongraph-1.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.2 MB
Release files / visiongraph-1.2.0.tar.gz
| Download URL | visiongraph-1.2.0.tar.gz |
|---|---|
| Size | 2.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
42162ff04b04808841a3189ab09f3c10ed05ef2d909ec64dded0165691fc1d95
|
|
BLAKE2b-256 checksum How to use checksums |
b80361039690bceff9b155b91fd79c47f2e1e07471dabbbe9385ea711a05f783
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / visiongraph-1.2.0-py3-none-any.whl
| Download URL | visiongraph-1.2.0-py3-none-any.whl |
|---|---|
| Size | 395.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
297faac1f8486a95d5215fccb677aa49b0cca383149e8317fbec7ae1af9826a3
|
|
BLAKE2b-256 checksum How to use checksums |
debdd9185b46773f4c26570f0c4fff23e7fde59febdb83ea1deb4b49a3c5aaa8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency log
