Aethera/render_3D/third_party/datoviz/spec/scene/examples/PLANNING.md

Scene Example Planning

Status: active planning Updated on: 2026-06-03 Scope: worked example specs, release staging, gallery priorities, and current support gaps Purpose: keep one source of truth for which examples matter, when they matter, and what still blocks them.

This file replaces the previous split between north-star, release-staging, prioritization, and gap reports. Use it as the planning entry point. Keep detailed scenario shape in scenarios/, compact fixture coverage in FIXTURES.md, cross-repository placement in ORGANIZATION.md, scenario ID lookup in CATALOG.md, and shared cache/API policy in POLICIES.md. Python documentation tabs generated from C examples are governed by ../../bindings/EXAMPLE_PYTHON_GENERATION.md.

Gallery Thesis

The v0.4 gallery should make one argument quickly:

Datoviz is a fast, modern, scientific GPU visualization engine for dense data, interactive scenes, native applications, and portable rendering backends.

Examples should feel like credible scientific scenes first, with code and reference links attached afterward. Minimal examples remain executable truth; showcases are allowed to be composed and editorial as long as their release status is explicit.

Public Example Taxonomy

Use four public example categories for v0.4:

Category	Rule	Purpose
visuals	one visual family per example	Mechanical proof of the visual data contract.
features	one isolated feature or rendering technique per example	Mechanical proof of one capability with minimal scaffolding.
composites	one semantic object per example	Mechanical proof of objects that lower to one or more visuals.
showcases	one composed user goal per example	Combined workflows, scientific scenes, real or simulated data stories, and polished release media.

workflow, scientific, technique, real-data, fake-data, simulated, interactive, offscreen, and domain labels should be tags in manifest metadata, not additional public structural categories.

The active public C source directories are examples/c/visuals/, examples/c/features/, examples/c/composites/, and examples/c/showcases/. Do not add new structural folders for new concepts when tags would disambiguate the example.

Staging Vocabulary

Stage	Meaning
v0.4 required	Must exist as a polished C example, release fixture, or release narrative item.
v0.4 experimental	In v0.4 scope, but explicitly partial, stretch, or backend-limited.
v0.4 fixture-only	Deterministic validation example; not a public gallery promise.
v0.5	Important next release target after v0.4 semantics are stable.
later	Strategic/domain showcase or broad pressure test beyond v0.5.
external/GSP	Belongs primarily in GSP/VisPy2/Matplotlib, with Datoviz keeping only low-level fixtures.

Each example may also carry a readiness label:

Readiness	Meaning
ready-now	Can be implemented or polished with the current active stack.
needs-rc1-proof	First slice exists, but needs a runnable example, fixture, or screenshot smoke.
partial-now	A reduced version can run today, but the full staged promise needs more work.
blocked-by-v0.4-critical-path	Required for v0.4 but waiting on a feature-freeze item.
blocked-by-v0.5-feature	Should not be forced into v0.4.

WebGPU Live-Example Vocabulary

The v0.4 RC WebGPU goal is live browser coverage for most scene-level examples that do not require native desktop runtime facilities. Example metadata should classify browser status explicitly:

WebGPU status	Meaning
webgpu-live	Browser route is implemented, validated, and suitable for the website.
webgpu-planned	Intended for the v0.4 RC live-example target, but not current support yet.
webgpu-deferred	Good future browser target, but outside the RC browser promise.
native-only	Requires native app/window handles, GUI, video, CUDA interop, platform capture, or backend diagnostics.
browser-only	Exists specifically to test browser integration rather than normal scene portability.

webgpu-live and webgpu-planned rows should list requirement tags such as point, mesh, panzoom, arcball, frame-callbacks, continuous-frames, scene-buffers, scene-compute, query-readback, native-capture, gui, video, and cuda. Public docs and generated gallery pages should derive their live-example matrix from metadata instead of hand-maintained prose.

The gallery is the preferred user-visible validation surface for WebGPU examples. A webgpu-live entry means the browser route is implemented from the same canonical C example or portable C scenario as the native route, is linked from the website, has browser smoke evidence, and has explicit diagnostics for unsupported browser requirements. Browser JavaScript may provide host glue, asset loading, browser event normalization, WebGPU setup, DRP2 execution, diagnostics, and page UI only. It must not reimplement example scene construction, visual state, animation, picking, selection, query/probe, or data semantics.

Browser smoke routes should stay minimal. For the RC path, keep one basic runtime smoke and one query/readback smoke, with an optional compute smoke only when compute-to-render is promoted. Broad wasm-* sampler pages are development aids; they should not define public WebGPU support or replace canonical live gallery routes.

Current Capability Snapshot

The active scene stack already covers retained figures and panels, per-panel viewport/scissor, offscreen and GLFW presentation, app callbacks, capture, retained resources, sampled fields, point/pixel/marker/primitive/mesh/path/image/visuals_volume/sphere/text visuals, panzoom/arcball/fly/ turntable controllers, EDL/SSAO/MSAA/WBOIT/depth-peeling-shaped passes, colorbars, legends, annotations, scale bars, and first GPU-backed point/marker/image/labels/volume request paths.

The main remaining polish, promotion, or feature gaps are:

1. short public feature examples for every public v0.4 scene/app feature, not only gallery-facing showcases;
2. release capture proof for the existing text, axes, colorbar, annotation/readout, scale-bar, and retained textured-mesh public examples;
3. gallery capture proof and public docs for the current C showcase/scientific set;
4. broader vector pressure beyond the first public dvz_vector() examples;
5. richer picking/probe payloads for marker exact hit tests, mesh regions, paths, labels, text, and volume ray hits;
6. large-data policies for ring buffers, visible ranges, LOD, sparse updates, and long live loops;
7. scene-level custom material/compute resources for Mandelbrot, Gray-Scott, particles, and custom postprocess work;
8. deterministic gallery capture conventions, asset/cache helpers, and Python binding smoke coverage.

v0.4 Required Set

Scenario	Readiness	Required slice	Decision
visuals_point	ready-now	retained scene, point visual, panzoom/offscreen	Public proof lives in examples/c/visuals/point.c. Keep as the smallest retained-scene point visual smoke; examples/c/lab/point_stress.c remains non-public stress material.
features_axes_2d	ready-now	path, rendered text, 2D axes/ticks	Public proof lives in examples/c/features/axes_2d.c.
showcases_panel_linked_axes	ready-now	grid/layout, linked panzoom, axes	Public proof lives in examples/c/showcases/panel_linked_axes.c.
showcases_linked_probe_colorbar	ready-now	image probe, colorbar, annotation/readout, linked state	Public proof lives in examples/c/showcases/linked_probe_colorbar.c; focused proofs still cover the parts separately in features_image_probe, features_colorbar, and features_annotation_readout.
features_picking	ready-now	marker visual, item pick, hover feedback, selection highlight	Public proof lives in examples/c/features/picking.c.
features_isolines	ready-now	surface-grid geometry, scalar contours, segment overlay	Public proof lives in examples/c/features/isolines.c.
features_builtin_shapes_2d	ready-now	2D geometry builders, polygon with hole	Public proof lives in examples/c/features/builtin_shapes_2d.c.
features_builtin_shapes_3d	ready-now	cube, sphere, cylinder, cone, torus, arrow builders	Public proof lives in examples/c/features/builtin_shapes_3d.c; classic polyhedra remain planned.
features_obj_loading	ready-now	Wavefront OBJ file loading into retained mesh	Public proof lives in examples/c/features/obj_loading.c; PLY remains planned and glTF is v0.5.
visuals_sphere	ready-now	sphere visual, lighting/depth	Public proof lives in examples/c/visuals/sphere.c; molecule/protein semantics stay in the scientific protein example.
visuals_volume	ready-now	3D sampled field, slice/render, capture	Public proof lives in examples/c/visuals/volume.c.
features_scalebar	ready-now	retained scale bar, label, panzoom/domain updates	Minimal feature proof lives in examples/c/features/scalebar.c; unit conversion proof lives in examples/c/features/scalebar_units.c; richer overview/detail/3D measurement composition lives in examples/c/showcases/scalebar_measurement.c.
features_scalebar_units	ready-now	retained scale bar, non-spatial unit conversion	Public proof lives in examples/c/features/scalebar_units.c.
showcases_scalebar_measurement	ready-now	overview/detail/3D measurement composition	Public proof lives in examples/c/showcases/scalebar_measurement.c.
features_colorbar	ready-now	scalar field, continuous colorbar, range labels	Standalone feature proof lives in examples/c/features/colorbar.c; probing stays separate.
features_annotation_readout	ready-now	anchored text/readout, highlighted data target	Standalone feature proof lives in examples/c/features/annotation_readout.c; query behavior stays separate.
features_image_probe	ready-now	scalar sampled image, pixel query, probe marker, stdout readback	Focused public image-query proof lives in examples/c/features/image_probe.c; colorbar/readout and broader linked-panel pressure remain separate.
showcases_protein	ready-now	real PDB data, sphere impostors, materials, SSAO/MSAA, GUI, arcball	Public proof lives in examples/c/showcases/protein.c; defer labels/picking/molecular surface if needed.
showcases_wind_field	ready-now	image field, vector visual, paths, panzoom, colorbar	Public proof lives in examples/c/showcases/wind_field.c using the retained dvz_vector() visual plus streamlines.
showcases_gpu_particle_smoke	ready-now	scene compute, shared storage/vertex buffers, blended points	Public experimental compute-to-graphics showcase lives in examples/c/showcases/gpu_particle_smoke.c.
showcases_textured_planet	ready-now	retained textured mesh, UVs, texture sampling, lighting, animated point/path overlays, capture	Required textured-mesh proof lives in examples/c/showcases/textured_planet.c: Earth/Mars UV sphere with real sampled textures, a prepared SGP4 point ephemeris, closed full-period paths, shared display rotation, a translucent atmosphere, and a snapshot-oriented Gaia/2MASS sky. Full debris-environment modeling remains outside this slice.
showcases_brain_volume	ready-now	volume, occluded slice composition, arcball	Public proof lives in examples/c/showcases/brain_volume.c over the prepared Allen/IBL RGBA volume. The newer atlas-mesh bundle remains source material for a later mesh-overlay polish pass; full atlas explorer is v0.5.
showcases_point_cloud	ready-now	large RGB pixel cloud, direct colors, GUI-tunable EDL, fly camera, capture	Public proof lives in examples/c/showcases/point_cloud.c, with required RESEPI raw-LAZ preprocessing through tools/data/prepare_point_cloud.py; no synthetic or bundled-NPZ fallback is provided.
composites_polygon	ready-now	semantic polygon/polygon-set, fill+stroke composite, holes, region styling	Public proof lives in examples/c/composites/polygon.c; polygon is not a visual family even if it appears near visual examples.
composites_graph	ready-now	semantic graph, user-provided layout, nodes+edges composite, stable ids, Bezier edges	Public proof lives in examples/c/composites/graph.c. Keep layout user-supplied first; edge-mode comparisons belong in tests or lab examples.

v0.4 Short Feature Coverage Queue

Every public v0.4 scene feature should have one short C example in examples/c/features/, even when a showcase or workflow already composes the same feature. Runtime hosting, capture, recording, and export examples live in examples/c/runtime/. These are copy-safe API proofs first and gallery material second. Keep each file narrow: one feature or runtime path, deterministic data, no unrelated GUI or domain polish, and smoke/screenshot validation once runnable.

Focused examples now cover the first release slice of retained scenes, panels, axes, sampled fields, text, overlays, panzoom/arcball/fly/turntable controllers, textured/material mesh, lighting, GUI controls/viewports/raw cimgui, retained visual updates/transforms, visibility, picking/probing/selection, animation through scenario frames and retained tracks, marker symbols, color scales, colorbars, scale bars, alpha/depth toggles, EDL, SSAO, MSAA, depth cue, transparency ordering, volume occlusion, panel backgrounds, guide lines/spans, bars/bands, input events, scene JSON, external surface diagnostics, categorical legends, and Bezier paths. Runtime examples cover direct GLFW app hosting, offscreen capture, record/replay, and video export. Future broad coverage gaps should stay here only until the source file exists, then move into examples/c/MANIFEST.yaml with concrete metadata.

Tentative examples now exist for examples/c/features/legend_categorical.c and examples/c/runtime/video_export.c. video_export.c is the direct app-capture proof for writing a bounded offscreen MP4; runner-backed examples use the generic scenario runner --video N or --offscreen-record N modes for gallery video capture. Keep the legend feature and runtime video capture experimental/conditional until categorical legends, video capture, and runner-backed examples are explicitly included in the public v0.4 API. The staged scenario-runner migration order lives in PORTABLE_SCENARIO_RUNNER.md.

v0.4 Experimental Set

Scenario	Required slice	Decision
webgpu_browser_subset	DRP2 WebGPU subset, WGSL, browser runtime	Point, primitive, image, and basic mesh only; visible experimental status.
gallery_video_capture	frame callbacks, deterministic scenario capture/video	Use existing scenario-backed examples such as timer_animation; keep public video-export code on the direct app-capture API.
features_datetime_axis	UTC datetime tick formatting, data-to-timestamp axis mapping, duration scale bar	Experimental feature proof lives in examples/c/features/datetime_axis.c; not a v0.4 release blocker.
splat_cloud	retained splat visual, blend/depth policy, deterministic capture	Experimental visual proof lives in examples/c/visuals/splat.c; not a release blocker.
cpu_fluid_or_particles	dynamic image/point/path updates, panzoom, colorbar	CPU-side stretch only; GPU compute remains later.
dense_streaming_2d	path/pixel updates, axes/text, linked x panzoom	Pick one DAQ/physiology example if time allows.
spatial_omics	large point/pixel, basic selection, color mapping	Useful stress/example lane; napari integration remains external.
mouse_brain_slice	image/volume slice, colorbar, GUI controls	Narrow slice can be v0.4 experimental; full atlas exploration is v0.5.

v0.5 Set

Scenario	Missing feature driver	Decision
mesh_selection_link	mesh face/region picking, linked highlight styling	API sketch remains useful after marker/image selection lands.
mouse_brain_atlas_explorer	region picking, selection-driven mesh styling, linked 2D/3D panels	Full explorer is beyond v0.4.
streaming_signal_workbench	dense traces, ring buffers, many-trace layout, overlays	Merge physiology and DAQ into one workbench track.
toy_dicom_viewer	shared 3D texture slices, crosshairs, window/level, slice dragging	Good v0.5 medical-viewer target.
market_microstructure	bars/candles, LOD, tooltips, crosshair, streaming policy	Requires dashboard and large-data policies.
embedding_explorers	image thumbnail LOD, label LOD, search/query sidecar, overlay cards	Keep PD12M/Wikipedia as paired dashboard showcases.
napari_labels_orthoslices_clipping	label GPU probing, shared 3D texture slices, richer volume clipping	Datoviz proves primitives; full napari workflow remains external.
tracks_tractography_vectors	vector visual, packed ragged paths, per-track identity, selection	Combine napari tracks and diffusion tractography into one v0.5 lane.
galaxy_labels	large star cache, label overlay, marker/sprite polish	Keep C version engine-focused.
wind_projections	projection transforms, vector visual, graticule/coastline helpers	v0.4 wind field is the subset.
textured_surface_full_workflow	terrain/planet/Mars asset cache, camera-path polish, optional overlays	Follows the v0.4 textured_planet.c retained textured-mesh proof; real Mars DEM terrain remains outside the v0.4 slice.
finite_element_stress	mesh scalar fields, selection, colorbar, isolines	Applied mesh/field target.
crystal_phonon	sphere/mesh animation, selection, labels	Materials-science showcase after sphere/text/animation polish.

Later Set

Scenario	Reason
compute_and_custom_shaders	Mandelbrot, Gray-Scott, and GPU particles need scene-level compute/custom material resources.
tokamak_hep_field_lines	Needs field-line paths/tubes, complex event geometry, vector fields, labels, picking, and domain data policy.
geo_trajectories_regions_events	Migration, choropleth, earthquakes, and flight tracks need geographic transforms, topology helpers, timelines, and LOD.
many_labels_and_splats_full	Needs label LOD/collision or full Gaussian-splat asset pipelines beyond first slices.
advanced_runtime_export_diagnostics	Multi-window/fullscreen/HiDPI, high-resolution/transparent export, batch/server capture, remote/cloud, and visual diagnostics need dedicated design.
large_data_strategy_gallery	Density rendering, progressive refinement, tile streaming, GPU instancing, and out-of-core policies need explicit resource semantics.

Feature Priority

1. One short public feature example per public v0.4 feature.
2. Text, axes, annotations, legends, colorbars, and scale bars.
3. Retained textured-mesh proof capture.
4. Vector visual.
5. Large point/pixel/path partial-update policy.
6. Selection and picking beyond points/images.
7. Scene-level custom material and compute resources.
8. Textured sphere/cubemap asset lane.

Near-Term Gallery And Example Pressure

Recommended release-proof order:

1. gallery proof pass for protein, LiDAR, brain, labels, textured mesh or terrain/planet, colorbar and legend paths, and capture validation;
2. vector visual polish beyond the current visual/vector and wind-field proofs;
3. label probe hardening under transforms, larger fields, latest-request-wins hover, signed ids, high unsigned ids, and background misses;
4. explanatory layout proof combining axes, continuous colorbar, categorical legend, scale bar, and panel reserves;
5. splat showcase only if release-proof lanes stay stable.

Add a bezier_curve_path example when geometry helpers are ready: quadratic and cubic Bezier controls tessellated on CPU to ordinary dvz_path() data, control polygons through dvz_segment(), control points through dvz_marker() or dvz_point(), multiple curves through subpaths, and optional controls for tessellation quality, stroke width, join mode, and overlay visibility.

Pickup Order

1. visuals_point
2. features_axes_2d
3. showcases_panel_linked_axes
4. features_scalebar
5. features_scalebar_units
6. showcases_scalebar_measurement
7. features_colorbar
8. features_annotation_readout
9. features_image_probe
10. showcases_linked_probe_colorbar
11. features_picking
12. features_isolines
13. features_builtin_shapes_2d
14. features_builtin_shapes_3d
15. features_obj_loading
16. visuals_volume
17. showcases_protein
18. showcases_wind_field
19. showcases_gpu_particle_smoke
20. showcases_textured_planet
21. composites_polygon
22. composites_graph
23. showcases_point_cloud
24. showcases_brain_volume
25. features_controller_arcball
26. features_mesh_texture
27. Feature example validation and capture proof from examples/c/MANIFEST.yaml
28. webgpu_browser_subset

Promotion Rule

Worked scenario files are informative pressure tests. A scenario becomes a release commitment only when it appears in the staged tables above or in FIXTURES.md. When an individual scenario exposes a reusable rule, move that rule to POLICIES.md, STYLE.md, TECHNIQUES.md, or the canonical scene spec instead of copying it into more scenario files.