Echelon Web Visualization Guide

Echelon Web Visualization Guide

Quick Start

1. Build the frontend:

   cd apps/web-viz
   npm install
   npm run build
   cd ../..

2. Run the server:

   cargo run --release -p studio-web

3. Open browser:
Navigate to http://localhost:8080

What You'll See

The Latent Orb 🔵

The central glowing sphere represents your position in latent space:

• Position: X/Y coordinates are the first two latent dimensions
• Size: Scales with latent energy (movement intensity)
• Glow: Residual solver error creates a blue aura
• Rotation: Spins based on beat phase

Motion Trails ✨

Blue particle trails fade behind the orb, showing the path through latent space.

Phase Indicator ⚪

White dot orbits the main sphere, showing the current beat phase (0-1).

Slow Attractor 🟠

Orange disk connected by a spring line:
- Shows the slow equilibrium position (DELL only)
- Size indicates coupling strength

Limb Satellites 🟡

Small yellow spheres orbit the main orb:
- One per tracked body part
- Size shows per-limb energy
- Positioned at fixed angles

Telemetry HUD 📊

Top-left overlay shows:
- Engine: Audio callback time
- Scheduler: Scheduling latency
- CPU: Process CPU usage
- XRuns: Audio dropouts

Bottom progress bars:
- Energy: Latent space energy
- Residual: Solver convergence
- Coupling: Slow-fast coupling (DELL)

Architecture Comparison

Old (egui)

┌─────────────────────┐
│  Rust egui Window   │
│  ┌───────────────┐  │
│  │ 2D Canvas     │  │
│  │ Simple shapes │  │
│  │ No shaders    │  │
│  └───────────────┘  │
└─────────────────────┘

New (Three.js)

┌─────────────────────────────┐
│  Browser (WebGL)            │
│  ┌───────────────────────┐  │
│  │ Three.js 3D Scene     │  │
│  │ ├─ GPU Shaders        │  │
│  │ ├─ Bloom Post-FX      │  │
│  │ ├─ Particle System    │  │
│  │ └─ Smooth Animation   │  │
│  └───────────────────────┘  │
│         ▲                   │
│         │ WebSocket         │
│         │                   │
│  ┌──────┴──────────────┐    │
│  │ Rust Backend        │    │
│  │ (viz-server crate)  │    │
│  └─────────────────────┘    │
└─────────────────────────────┘

Benefits Over egui

Next Steps

Audio Visualization

To add real-time audio waveforms:

1. Stream audio samples over WebSocket
2. Use Web Audio API's AnalyserNode
3. Add a `<Waveform>` component to the scene

Spectrogram

Create a time-frequency heatmap:

1. Compute FFT in Rust or browser
2. Render as a scrolling texture
3. Display below the main orb

VR Support

Three.js supports WebXR:

import { VRButton, XR } from '@react-three/xr'

<XR>
  <Scene />
</XR>

Recording

Use Canvas Capture API:

const stream = canvas.captureStream(60)
const recorder = new MediaRecorder(stream)

Troubleshooting

WebSocket won't connect:
- Check that `studio-web` is running
- Verify port 8080 is not in use
- Check browser console for errors

Black screen:
- Ensure `npm run build` completed successfully
- Check that `apps/web-viz/dist` exists
- Verify WebGL is enabled in your browser

Poor performance:
- Reduce bloom intensity
- Lower particle count in `TrailParticles.jsx`
- Disable post-processing effects

No data flowing:
- Verify motion bridge is running
- Check that ringbufs are being produced to
- Enable tracing: `RUST_LOG=debug cargo run -p studio-web`