Ocean VFX Baker: Vector-to-Heightfield Displacement

A production-grade library for converting Lagrangian Vector Displacement (Gerstner, Stokes, FFT) into physically accurate Eulerian Heightfields.

This project solves the "Combination Problem" in water rendering: artists want the sharp, bunched crests of vector displacement, but large-scale ocean renderers require heightfields. Our Hierarchical Newton-Raphson Solver mathematically inverts the displacement mapping to preserve physical "choppiness" in a standard 2.5D heightmap.

Key Features

• Hierarchical Newton-Raphson Inversion: Resolves the $u + D(u) = x$ mapping with machine precision ($10^{-8}m$).
• Multi-Model Support: Native support for Gerstner (trochoidal) and Stokes (2nd-order irrotational) wave physics.
• Rayleigh Statistical Sampling: Automatically generate realistic random seas based on target Significant Wave Height ($H_s$).
• Strict Physics Validation: Built-in Jacobian analysis to detect and reject self-intersecting (breaking) waves.
• Path-Following Profiles: High-fidelity visualization that proves particles stay "locked" to the heightfield surface.

---

Visual Demonstrations

1. Hierarchical Multi-Scale Alignment

Proves that high-frequency chop remains perfectly registered while riding on massive, moving swells. The white particles (Lagrangian) are numerically locked to the cyan line (Eulerian).

2. Rayleigh Stochastic Storm

30 waves sampled from a Rayleigh distribution, resolved into a single stable heightmap. This demonstrates the library's ability to handle arbitrary spectral complexity.

3. The Stokes vs. Gerstner Difference

Comparison of physical profiles. Stokes waves implement irrotational harmonics, resulting in even sharper crests and flatter troughs than the circular Gerstner approximation.

Gerstner Profile (Trochoidal)	Stokes Profile (2nd Order Harmonic)

---

Technical Details

The "Bunching" Proof

In a choppy wave, water particles don't just move up and down; they cluster at the peaks. Traditional heightfield sampling misses this effect, resulting in "mushy" waves. Our baker find the exact rest coordinate $u$ for every render pixel $x$, effectively "baking" that horizontal cluster into the vertical height.

Mathematical Precision

The solver calculates the analytical Jacobian for the entire combined spectrum: $$J_F = I + \sum \nabla D_i(u)$$ By using a hierarchical wavelength-descending approach, we ensure the solver never "skips" a wave cycle, maintaining perfect registration even in turbulent cross-sea conditions.

---

Quick Start

from ocean_baker import StokesWaveModel, GerstnerWaveModel, bake_eulerian_heightfield

# 1. Define your spectrum
models = [
    StokesWaveModel(wavelength=100, amplitude=5.0, direction=[0.1, 0]),
    GerstnerWaveModel(wavelength=10, amplitude=0.5, steepness=0.8, direction=[0, 0.5])
]

# 2. Bake to a fixed grid
# Returns X, Z (grid) and Y (heightfield)
X, Z, Y = bake_eulerian_heightfield(target_res=512, domain_size=200.0, wave_models=models)

Repository Structure

• ocean_baker.py: Core modular library.
• test_scientific_alignment.py: Numerical proof of $10^{-15}$ precision.
• verify_ocean_scenarios.py: Validation of wavelength bunching.
• generate_demonstration_suite.py: Re-generates all high-fidelity GIFs.