rheo · fluid lab

An interactive, real-time fluid simulation that runs entirely in the browser. Drag to stir luminous ink through a solved velocity field; every part of the physics and the look is exposed as a dial.

One file, zero dependencies — markup, styles, shaders, solver and UI all live in index.html; there is no build step. The physics is Jos Stam's Stable Fluids (1999), implemented from scratch in WebGL fragment shaders following the structure popularized by GPU Gems ch. 38, and steered by a collapsible control deck with roughly forty dials.

01Quick start

open index.html              # macOS — or just double-click the file
python3 -m http.server 8000  # optional: serve it → http://localhost:8000

Requirements: any current Chrome, Firefox, Safari or Edge with WebGL. WebGL2 is preferred; WebGL1 with half-float extensions works as a fallback. Fonts load from Google Fonts; offline, the app falls back to system fonts and is otherwise fully functional.

02Interaction

A status chip (top right) shows FPS, simulation grid size, ink texture size and a pause LED.

03The control deck

All settings persist to localStorage (key rheo-fluid-lab-v1) with a 200 ms debounce; the pause state is intentionally never persisted so the app never boots frozen. Reset settings clears storage and restores defaults.

Presets

Seven one-click moods. Touching any dial afterwards clears the active chip. Presets restore everything except resolutions and pause.

Simulation

Forces

The force pass is skipped entirely when all three are zero.

Brush

Each stroke in Palette mode picks a random swatch from the active set:

Auto bursts — periodic random splat showers: Enabled (off), Interval 0.1–5 s (1.0), Burst size 1–25 (6). Bursts respect the symmetry setting and use varied hues unless the color mode is Palette or Fixed.

Display

Glow & rays — a bloom pipeline applied to the ink view only: Glow (on), Intensity 0.1–3 (0.8), Threshold 0–1 (0.6) with a Soft knee 0–1 (0.7) quadratic roll-off below it; plus Sunrays — volumetric light shafts radially blurred from an ink-occlusion mask, modulating ink and glow.
Actions — Burst R · Clear C · Step S · Save PNG (downloads the frame as rheo.png) · Reset settings.

04Play & discovery

Useful modes

05How the solver works

The fluid is modelled by the incompressible Navier–Stokes equations on a 2D grid. Velocity and dye live in floating-point textures; every stage of the solve is one fragment-shader pass drawing a fullscreen quad into a framebuffer ("ping-pong" pairs swap read/write each pass). Per frame, in order:

1. Splat — pointer strokes (and bursts) add Gaussian blobs of momentum into the velocity texture and color into the dye texture.
2. Body forces (skipped when zero) — gravity, wind, and buoyancy (ink density × upward force) are added to velocity.
3. Curl — vorticity ω = ∂v/∂x − ∂u/∂y is measured into its own texture.
4. Vorticity confinement — a force perpendicular to the vorticity gradient, scaled by Swirl, is added back, keeping small eddies alive against numerical smearing.
5. Divergence of the velocity field is computed, with no-slip walls: boundary samples reflect the centre velocity so fluid cannot flow out of the domain.
6. Pressure solve — last frame's pressure (scaled by Pressure fade as a warm start) is relaxed with N Jacobi iterations of the Poisson equation ∇²p = ∇·u.
7. Projection — the pressure gradient is subtracted from velocity, making it (approximately) divergence-free, i.e. incompressible.
8. Advection — velocity transports itself, then the dye, by tracing each texel backwards along the flow (semi-Lagrangian: unconditionally stable, hence "Stable Fluids"). Dissipation here implements the two fade dials as value / (1 + fade·dt).

Rendering then composes the result: an optional glow pass (bright-pass prefilter with soft knee → 8-level downsample blur → additive upsample → intensity), the shading term, an ordered dither to defeat banding on dark gradients, and premultiplied-alpha blending over the background color.

Textures & formats

Robustness details

06Architecture

index.html
├── <style>      deck, chips, custom sliders, stats, hint, error overlay
├── <body>       canvas + deck skeleton (sections are built in JS)
└── <script>
    ├── Config + persistence     DEFAULTS, localStorage load/save
    ├── GL bootstrap             WebGL2→1 fallback, format probing
    ├── Shaders                  14 fragment programs + shared quad VS
    ├── Render targets           FBO/ping-pong helpers, resize logic
    ├── Solver step              forces→curl→vorticity→div→jacobi→project→advect
    ├── Rendering                display modes, glow pipeline
    ├── Splats / colors          symmetry, bursts, palettes, HSV
    ├── Input                    pointer + keyboard
    ├── Control deck             declarative slider/select/chip builders
    ├── Presets                  7 mood presets
    └── Main loop                dt clamping, auto bursts, stats, capture

07Performance

The dominant costs are the Jacobi iterations (N passes over the sim grid) and dye advection (one pass over the ink grid). Halving Sim resolution roughly quarters solver cost; Ink resolution only affects visual passes. Verified at 77 fps in software rendering (SwiftShader, 1440×900 headless Chromium); a real GPU runs the defaults far beyond display refresh. The timestep is clamped to 1/60 s · Time warp and frame gaps to 50 ms, so backgrounded tabs don't explode the integration on return.

08Provenance

The technique is Jos Stam's Stable Fluids (SIGGRAPH 1999) as adapted for GPUs in GPU Gems ch. 38; the interaction pattern (splat-driven dye + velocity) follows the well-known WebGL fluid-simulation lineage (e.g. Pavel Dobryakov's MIT implementation). This codebase is an independent, from-scratch implementation with its own UI ("the deck"), preset system, curated palettes, symmetry brush and field visualizers.