Do a visualisation gallery

[jeromeetienne]

• page to copy https://datoviz.org/gallery/
• script to build it https://github.com/datoviz/datoviz/blob/main/tools/build_gallery.py
• config script https://github.com/datoviz/datoviz/blob/main/mkdocs.yml

Description

• thumbnail from ./examples/output/
• link to https://github.com/vispy/GSP_API/blob/main/examples/groups_example.py

[jeromeetienne]

Examples Analysis — What ./examples Currently Provides

Ran a full analysis of the 60+ scripts in ./examples/. Here is what exists and what conventions they follow, as input for building the gallery.

---

Visual Types Covered

Category	Example Scripts
Points	points_example.py
Pixels	pixels_example.py, groups_example.py, dynamic_groups_example.py
Markers	markers_example.py
Segments	segments_example.py
Paths / Polylines	paths_example.py
Image / Texture	image_example.py
Text	texts_example.py, texts_animated_example.py
3D Mesh	(via object3d_example.py, transform_visual_example.py)

Higher-Level vispy2 API

Feature	Example Scripts
Scatter	vispy_basic_example.py, vispy_scatter_example.py
Plot (fmt strings)	vispy_plot_example.py
Imshow	vispy_imshow_example.py
Axes (managed)	vispy_axes_managed_example.py, vispy_axes_managed_multiple_example.py
Axes (pan/zoom)	vispy_axes_panzoom_example.py, vispy_axes_multiple_panzoom_example.py
Image pyramid	vispy_axes_image_pyramid.py

Other Feature Examples

Feature	Example Scripts
Animation	animator_example.py
Camera / trackball	camera_control_example.py
Viewport layout	viewport_multi_example.py, viewport_overlapping_example.py
NDC ↔ pixel ↔ cm	viewport_ndc_metric.py, viewport_inch_matplotlib.py
Model matrix / 3D transforms	simple_model_matrix.py, object3d_example.py
Serialization round-trip	pydantic_cycle_example.py, transform_serialization_example.py
Session record / playback	session_record_example.py, session_player_example.py
Network rendering	network_client_example.py
SVG / PDF output	svg_pdf_example.py
Event handling	viewport_events_example.py

---

How run_all_examples.py Drives Them

• Discovers every .py file in ./examples/ automatically
• Runs each against three renderer backends: matplotlib, datoviz, network-matplotlib
• Sets GSP_TEST=True (skips interactive display), GSP_UUID_COUNTER (deterministic UUIDs), GSP_RENDERER / GSP_REMOTE_RENDERER
• Saves rendered output to examples/output/<name>_<renderer>.png
• Reports OK / Failed per (example, renderer) pair

So every example that calls ExampleHelper.save_output_image() already produces a PNG — those images are the raw material for the gallery.

---

Common Conventions in Example Scripts

# Seed for reproducibility
np.random.seed(0)

# Canvas typically 100–512 px, 72–127.5 DPI
canvas = Canvas(width=512, height=512, dpi=72.0, background_color=...)

# Rendering always takes parallel lists
renderer.render([viewport], [visual], [model_matrix], [camera])

# Test-mode guard (used by run_all_examples.py)
if os.environ.get("GSP_TEST") != "True":
    renderer.show()

# Output image saved here
ExampleHelper.save_output_image(renderer, Path(__file__).stem)

---

Gaps / What the Gallery Script Will Need

1. Thumbnail generation — run_all_examples.py already produces PNGs; gallery build just needs to collect them from examples/output/.
2. Metadata per example — currently no title/description embedded in scripts; build_gallery.py (datoviz reference) reads a YAML/config for captions. We'll likely need either docstring extraction or a sidecar config.
3. Category grouping — examples aren't tagged by category; the gallery script will need a mapping (could be derived from filename prefixes: vispy_*, viewport_*, transform_*, etc.).
4. Multi-renderer thumbnails — each example has up to 3 output images (one per renderer). Decide whether to show all or just matplotlib as canonical.