GitHub - vispy/GSP_API: Graphic Server Protocol Application User Interface
Graphic Server Protocol Application User Interface
A Python library that provides a unified API for scientific visualization across multiple renderers (Matplotlib, Datoviz).
Installation
Create a virtual environment and install the package in editable mode:
# Create a virtual environment python -m venv .venv source .venv/bin/activate # Install required packages pip install -e .
Python >=3.13 is required (see pyproject.toml).
Running
Run any of the bundled examples:
python examples/buffer_example.py
Select a renderer with the GSP_RENDERER environment variable:
# Matplotlib (default) GSP_RENDERER=matplotlib python examples/buffer_example.py # Datoviz GSP_RENDERER=datoviz python examples/buffer_example.py
Documentation
In-depth design documents live under docs/philosophy/:
- Whitepaper — backend-agnostic scene-description API for scientific visualization in Python.
- Philosophy: Packages — the seven-package split and how dependencies flow downward.
- Philosophy: GSP Core — the contract layer (
Canvas,Viewport,Camera,Buffer,Visual). - Philosophy: Renderers — the
RendererBasecontract and the Matplotlib / Datoviz / Network backends. - Philosophy: Examples — the shared skeleton behind every script in
examples/.
FAQ
Q. How do I install it?
A. Create a virtual environment, activate it, and run pip install -e . from the project root. See the Installation section above.
Q. How do I run an example?
A. After installation, run any script under examples/, e.g. python examples/buffer_example.py. See the Running section.
Q. How do I switch renderers?
A. Set the GSP_RENDERER environment variable to either matplotlib or datoviz before running your script:
GSP_RENDERER=datoviz python your_script.py
Q. How do I run the tests?
A. Tests live under tests/ and run with pytest:
Or run the full pipeline (lint + tests + examples + expected-output check) via the Makefile:
Q. How do I use the Makefile?
A. The Makefile is a task runner. List all targets with:
Common targets:
| Target | What it does |
|---|---|
make test |
Full pipeline: lint, pytest, run all examples, check expected output |
make pytest / make pytest_verbose |
Run pytest only |
make lint |
Run pyright + ruff |
make run_all_examples |
Execute every example script |
make clean_output |
Remove generated png/json/pdf/svg/mp4 from examples/output/ |
make stubs_gsp |
Regenerate type stubs |
make network_server |
Start the network renderer server |
make network_server_dev |
Start the server with auto-restart on file changes |
make mkdocs_serve |
Preview docs locally |
make mkdocs_build / make mkdocs_deploy |
Build / deploy docs to GitHub Pages |
Q. How do I remove datoviz logs?
A. Set the datoviz log level via the DVZ_LOG_LEVEL environment variable. See the datoviz docs.
DVZ_LOG_LEVEL=4 GSP_RENDERER=datoviz python your_script.py
Q. Where is the documentation?
A. Source documentation lives under mkdocs_source/. Build it locally with:
Q. Where do I report bugs or request features?
A. Open an issue on the project repository.