Live: meta-imaging.qiguo.org/visualization · Client: a computational-imaging research team at Purdue University · Apr–Aug 2026
A scroll-driven, ten-scene WebGL walkthrough of the MetaSpectra+ hyperspectral camera paper. Scroll position is the only input: it explodes the camera body, flies through the optical stack, animates the deflecting metasurface panels, traces light paths, and lands on the reconstructed datacube — with HTML labels and captions pinned to the moving 3D objects.
Adopted as the paper's official visualization and presented with the team's CVPR 2026 Oral.
The source is private under the client engagement; the deployed build ships inside the research group's site. This repository documents the architecture and the engineering decisions.
React 18 · Three.js 0.160 · React Three Fiber 8 · drei · Zustand · Vite 5 · Playwright 1.57
~9,200 lines across 85 JS/JSX files under src/; 40 commits.
page scroll
│
▼
useScrollProgress ──writes──▶ Zustand store { sceneLoc: { id, t, index } }
│
▼
useFrame consumers
(scene controllers, optic components, label projection)
│ write directly to
▼
THREE object refs (StageRefsContext)
│
▼
rendered frame
Scroll is the single source of truth. One hook maps DOM scroll to { scene id, local t } and writes it to a Zustand store. Nothing else owns animation state.
Zero React re-renders per animation frame. Scene controllers subscribe inside useFrame and write positions, quaternions, and material properties straight to Three.js object refs held in a central registry (StageRefsContext, replacing prop-drilling). React reconciles only when the scene set changes, never on scroll.
Ordered per-frame priority lanes. Multiple systems touch the same objects each frame, so useFrame priorities enforce a fixed order:
| Lane | Priority | Responsibility |
|---|---|---|
| EXPLODE | −5 | camera body and optical stack explode offsets |
| FOCUS | −4 | reads explode positions, applies fly-out and look-at |
| SUBANIM | −3 | panel-grid animation inside the focused element |
| VISIBILITY | 0 | opacity, material registers, visible flags — applied last |
| POST_VIS | +5 | read-only consumers: light beams, sensor tiles, neural-network diagram, datacube, lens FX |
| labels | +10 | HTML label projection, after the canvas frame is decided |
A later lane can always trust what an earlier lane wrote in the same frame. Adding a scene means adding a controller in the right lane, not reasoning about global ordering.
Geometry is mixed. Optical elements (lens profiles, metasurface panel grids, beam paths) are generated at runtime from parameters; the camera housing and reference objects are imported GLB models. Both live in the same ref registry and are animated the same way.
WebGL output is not deterministic across GPUs, which usually makes screenshot tests useless. Here they are made reproducible by:
- Sample points derived from the animation timeline (
src/config/timeline.js), so retiming a scene moves its samples with it instead of stranding them - Forcing SwiftShader (
--use-angle=swiftshader): software rasterization is slower than the GPU but identical across machines - Disabling CSS animations during capture, and sharing one booted page across all samples so wall-clock never enters the picture
- A separate mobile smoke suite across viewports
vite build → rsync into the research group's GitHub Pages repository under /visualization → commit and push, wrapped in a single script. The visualization is served from the group's own domain rather than a separate host.
