Tidewater

an FFT sea meeting a mirror-calm river under golden-hour rain.

▶ Run in browser

Tags: 3d ocean water river rain sky reflections

A single coastal scene that exercises most of the renderer’s 3D feature set at once, each feature doing real work in the frame:

• An open FFT ocean (OceanSurface3D) fills the horizon: a Tessendorf spectrum inverse-transformed each frame into rolling swell, choppy crests and wind-laced foam that curls around the rock stacks out at sea.

• A mirror-calm river (WaterSurface3D + PlanarReflection3D) runs between two wet rocky banks toward the sea. Its surface is a true planar mirror: the banks, the rain-slicked stones and the golden sky invert in it every frame, rippled by a small Gerstner swell and Fresnel-blended over the refraction below.

• A procedural sky (sky_mode="procedural") is synthesized from the low golden-hour sun with a hazy turbidity, and drives both the sky background and the image-based lighting the whole scene reflects.

• Rain and weather (Rain3D plus the WorldEnvironment wetness and ripple channels): wind-slanted rain falls across the view while every wetness_affected rock darkens, drops roughness and gains an animated puddle ripple, so the slick banks mirror the golden sky back at you.

• Global illumination from both ends: a baked IrradianceVolume3D over the near shore lifts the shadowed undersides of the wet boulders with soft SH-L1 bounce, while screen-space GI (ssgi_*) adds the near-field, view-dependent colour bleed. Baked GI, SSGI, screen-space reflections (ssr_*) and the planar-mirror river all run in the same frame.

The whole scene is cross-backend: the FFT ocean, the planar-mirror river, SSR and SSGI all run on the web renderer too (the ocean via its WebGPU compute twin).

A slow cinematic camera sways over the river mouth, looking downstream at the sun-glinting sea. Press SPACE (or click / tap) to pause the whole scene: camera, ocean, river and rain all freeze together. ESC quits.

Usage: uv run python examples/demos/tidewater.py uv run python examples/demos/tidewater.py –test # headless self-check

Controls: SPACE / click / tap - Pause / resume the whole scene ESC - Quit

Source

"""Tidewater: an FFT sea meeting a mirror-calm river under golden-hour rain.

A single coastal scene that exercises most of the renderer's 3D feature set at
once, each feature doing real work in the frame:

* An open **FFT ocean** (``OceanSurface3D``) fills the horizon: a Tessendorf
  spectrum inverse-transformed each frame into rolling swell, choppy crests and
  wind-laced foam that curls around the rock stacks out at sea.
* A **mirror-calm river** (``WaterSurface3D`` + ``PlanarReflection3D``) runs
  between two wet rocky banks toward the sea. Its surface is a true planar
  mirror: the banks, the rain-slicked stones and the golden sky invert in it
  every frame, rippled by a small Gerstner swell and Fresnel-blended over the
  refraction below.
* A **procedural sky** (``sky_mode="procedural"``) is synthesized from the low
  golden-hour sun with a hazy turbidity, and drives both the sky background and
  the image-based lighting the whole scene reflects.
* **Rain and weather** (``Rain3D`` plus the ``WorldEnvironment`` wetness and
  ripple channels): wind-slanted rain falls across the view while every
  ``wetness_affected`` rock darkens, drops roughness and gains an animated
  puddle ripple, so the slick banks mirror the golden sky back at you.
* **Global illumination** from both ends: a baked ``IrradianceVolume3D`` over
  the near shore lifts the shadowed undersides of the wet boulders with soft
  SH-L1 bounce, while screen-space GI (``ssgi_*``) adds the near-field,
  view-dependent colour bleed. Baked GI, SSGI, screen-space reflections
  (``ssr_*``) and the planar-mirror river all run in the same frame.

The whole scene is cross-backend: the FFT ocean, the planar-mirror river, SSR
and SSGI all run on the web renderer too (the ocean via its WebGPU compute
twin).

A slow cinematic camera sways over the river mouth, looking downstream at the
sun-glinting sea. Press SPACE (or click / tap) to pause the whole scene:
camera, ocean, river and rain all freeze together. ESC quits.

# /// simvx
# tags = ["3d", "ocean", "water", "river", "rain", "sky", "reflections"]
# screenshot_frame = 54
# ///

Usage:
    uv run python examples/demos/tidewater.py
    uv run python examples/demos/tidewater.py --test   # headless self-check

Controls:
    SPACE / click / tap  - Pause / resume the whole scene
    ESC                  - Quit
"""

from __future__ import annotations

import math
import sys

from simvx.core import (
    Camera3D,
    DirectionalLight3D,
    InputMap,
    IrradianceVolume3D,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    MouseButton,
    Node,
    OceanSurface3D,
    PlanarReflection3D,
    Rain3D,
    Text2D,
    WaterMaterial,
    WaterSurface3D,
    WorldEnvironment,
    on_input,
)
from simvx.graphics import App

WIDTH, HEIGHT = 1280, 720

# World layout. A calm river channel runs down the middle (surface at
# ``RIVER_LEVEL``) between two raised rocky banks, and spills over a low rock lip
# at ``SHELF_EDGE_Z`` into the open sea, whose surface sits a step lower at
# ``SEA_LEVEL``. The sea plane begins AT the shelf edge (never underlaps the
# foreground), so the two water bodies read as a river pouring into the sea with
# no z-fighting and no near-field sea foam poking through the banks.
RIVER_LEVEL = 0.5
SEA_LEVEL = -0.5
RIVER_HALF_WIDTH = 9.0
SHELF_EDGE_Z = -20.0  # where the banks end and the open sea begins

# Bank rock: base albedo kept readable so the wetness darkening (x0.55) still
# leaves a grey-brown wet stone rather than crushing it to black.
ROCK = (0.44, 0.41, 0.37, 1.0)
ROCK_MOSS = (0.38, 0.42, 0.32, 1.0)
ROCK_PALE = (0.54, 0.51, 0.47, 1.0)
RIVERBED = (0.16, 0.17, 0.15, 1.0)  # dark bed so the deep river reads rich, not muddy


class TidewaterScene(Node):
    def on_ready(self):
        InputMap.add_action("quit", [Key.ESCAPE])
        # Left-click / tap also pauses, so the demo is fully operable with a
        # pointer alone (touch arrives as MouseButton.LEFT on web).
        InputMap.add_action("pause", [Key.SPACE, MouseButton.LEFT])

        self._build_environment()
        self._build_sun()
        self._build_camera()
        self._build_shelf_and_banks()
        self._build_gi()
        self._build_river()
        self._build_sea()
        self._build_rain()
        self._build_hud()

    # -- scene construction ------------------------------------------------
    def _build_environment(self):
        """One WorldEnvironment ties the whole showcase together.

        It enables the HDR chain the water refraction and SSR read, publishes the
        wind that drives both the ocean spectrum and the rain slant, sets the
        weather channels the wet rocks consume, and selects the procedural sky.
        """
        env = self.add_child(WorldEnvironment())
        # Wind: drives the FFT/Gerstner swell direction and the rain slant.
        env.wind_direction = (0.65, 0.42)
        env.wind_strength = 0.7
        # Weather: rain-slicked rock + subtle puddle ripples on up-faces. Kept
        # moderate so the wet banks gloss and darken without the ripple normal
        # tiling into a hard grid across the large surfaces.
        env.wetness = 0.6
        env.rain_intensity = 0.8
        env.ripple_strength = 0.25
        # Dynamic Preetham sky: a hazy golden-hour atmosphere driving IBL.
        env.sky_mode = "procedural"
        env.sky_turbidity = 3.6
        env.sky_ground_albedo = (0.18, 0.15, 0.12, 1.0)
        # SSR: screen-space reflections mirror the real scene geometry in the
        # rain-slicked shelf and boulders, which IBL alone cannot do, composited
        # over the golden-sky IBL specular without double-counting.
        env.ssr_enabled = True
        # SSGI: screen-space global illumination gathers one soft bounce of
        # indirect diffuse from the on-screen scene, so the wet shore and the
        # tumble of boulders pick up a subtle colour bleed from the warm banks and
        # the golden water beside them instead of sitting on flat ambient. Kept
        # tasteful (short range, gentle intensity) so it reads as ambient warmth
        # rather than a glow.
        env.ssgi_enabled = True
        env.ssgi_intensity = 0.55
        env.ssgi_max_distance = 10.0
        # A touch of bloom so the low sun's glint on the sea blooms warmly.
        env.bloom_enabled = True
        env.bloom_threshold = 1.15
        env.bloom_intensity = 0.45
        self._env = env

    def _build_sun(self):
        """A low, warm golden-hour sun. The procedural sky is built from it."""
        sun = self.add_child(DirectionalLight3D(intensity=3.4))
        sun.colour = (1.0, 0.78, 0.52)
        # Low over the sea (toward -Z), just off-centre: a long glint path down the
        # river and across the swell, and a warm golden-hour Preetham horizon. The
        # shallow elevation keeps the sun near the horizon for the golden mood.
        sun_to = (0.14, 0.11, -0.98)
        sun.direction = (-sun_to[0], -sun_to[1], -sun_to[2])
        self._sun = sun

    def _build_camera(self):
        # Elevated, at the head of the river channel, looking downstream (toward
        # -Z) at the sun-glinting sea. The height lets the calm river read as a
        # mirror ribbon leading the eye to the horizon.
        self._look_target = (0.0, 0.4, -30.0)
        self.camera = self.add_child(
            Camera3D(position=(0.0, 6.5, 24.0), look_at=self._look_target, up=(0, 1, 0), fov=55, near=0.1, far=900.0)
        )

    def _build_shelf_and_banks(self):
        """The two raised rocky banks framing the river, plus its dark bed.

        The banks are the wet-rock showcase surface: a solid ridge on each side
        with a scatter of boulders spilling toward the waterline, all
        ``wetness_affected`` so they darken, gloss (roughness drop) and pick up
        the animated ripple normal + the golden-sky IBL reflection under the rain.
        """
        hw = RIVER_HALF_WIDTH

        # A dark riverbed well below the surface, giving the river real depth for
        # the refraction + depth-fade (shallow->deep, transparent->opaque) to read
        # as calm clear water rather than a painted sheet.
        self.add_child(
            MeshInstance3D(
                mesh=Mesh.cube(1.0),
                material=Material(colour=RIVERBED, roughness=0.9),
                position=(0.0, SEA_LEVEL - 1.5, 4.0),
                scale=(2 * hw + 2.0, 3.0, 54.0),
            )
        )

        # The two bank ridges: a solid rock mass on each side of the channel,
        # top above the water, sloping out of frame. They occlude the sea plane
        # laterally so no near-field sea foam leaks past the channel.
        for side in (-1.0, 1.0):
            self.add_child(
                MeshInstance3D(
                    mesh=Mesh.cube(1.0),
                    material=Material(colour=ROCK, roughness=0.8, wetness_affected=True),
                    position=(side * (hw + 11.0), 0.2, 6.0),
                    scale=(24.0, 5.4, 52.0),
                )
            )
            # Break the flat slab top with a run of large boulders so each bank
            # reads as a natural rock mass, not a box. Deterministic placement.
            for i, (dz, r, colour) in enumerate(
                [(-14.0, 3.4, ROCK_PALE), (-4.0, 4.2, ROCK), (5.0, 3.0, ROCK_MOSS), (14.0, 3.8, ROCK_PALE)]
            ):
                ox = side * (hw + 8.0 + 2.2 * (i % 2))
                self.add_child(
                    MeshInstance3D(
                        mesh=Mesh.sphere(r, rings=16, segments=24),
                        material=Material(colour=colour, roughness=0.78, wetness_affected=True),
                        position=(ox, 2.9 + 0.25 * r, dz),
                    )
                )

        # Boulders spilling down each bank toward the waterline: varied stone,
        # size and roughness so the banks read as a natural tumble of wet rock.
        # Deterministic layout (no RNG) so the golden frame is stable.
        boulders = [
            (-hw - 0.5, 14.0, 2.4, ROCK_MOSS, 0.7),
            (-hw + 0.4, 6.0, 1.7, ROCK_PALE, 0.55),
            (-hw - 1.5, -2.0, 3.0, ROCK, 0.75),
            (-hw + 0.2, -11.0, 1.9, ROCK_MOSS, 0.6),
            (-hw - 0.8, -17.5, 2.3, ROCK_PALE, 0.5),
            (hw + 0.6, 12.0, 2.1, ROCK_PALE, 0.5),
            (hw - 0.3, 4.0, 1.6, ROCK, 0.7),
            (hw + 1.4, -4.0, 2.8, ROCK_MOSS, 0.75),
            (hw - 0.2, -12.0, 2.0, ROCK_PALE, 0.55),
            (hw + 0.9, -17.5, 2.5, ROCK, 0.6),
        ]
        for x, z, r, colour, rough in boulders:
            self.add_child(
                MeshInstance3D(
                    mesh=Mesh.sphere(r, rings=16, segments=24),
                    material=Material(colour=colour, roughness=rough, wetness_affected=True),
                    position=(x, RIVER_LEVEL + r * 0.45, z),
                )
            )

        # A low rock lip across the river mouth where it spills to the sea,
        # hiding the seam between the river plane and the (lower) sea plane.
        for x in range(-int(hw), int(hw) + 2, 3):
            self.add_child(
                MeshInstance3D(
                    mesh=Mesh.sphere(1.7, rings=12, segments=18),
                    material=Material(colour=ROCK, roughness=0.65, wetness_affected=True),
                    position=(float(x) + 0.5, RIVER_LEVEL - 0.5, SHELF_EDGE_Z + 0.8),
                )
            )

    def _build_gi(self):
        """Baked diffuse global illumination over the shore.

        An ``IrradianceVolume3D`` spans the whole near shore, so the boulders and
        bank ridges carry baked SH-L1 indirect light from the warm rock and golden
        sky around them: the shadowed undersides of the wet stones lift with soft
        bounced warmth instead of reading as flat ambient. This is the low-frequency
        static GI partner to the screen-space SSGI (which adds the near-field,
        view-dependent bleed); together they give the shore a grounded, lit-from-
        the-scene feel. Baked once over the first frames (``bake_mode="once"``),
        with a generous per-frame budget so it settles well before the golden frame.
        """
        vol = self.add_child(
            IrradianceVolume3D(name="ShoreGI", extents=(30.0, 7.0, 26.0), spacing=7.0, position=(0.0, 2.5, 0.0))
        )
        # A fragment inside the volume takes its ambient from the baked SH probes
        # instead of the golden-sky IBL. The probes carry directional warmth from the
        # rock and sky, but their diffuse capture is dimmer than the very bright
        # low-sun IBL, so the intensity is lifted so the boulders keep their midtone
        # (warm lit rock rather than crushed-black) while gaining the directional
        # bounce on their shadowed undersides.
        vol.intensity = 3.0
        vol.update_budget = 32  # ~216 probes -> fully baked in ~7 frames
        self._gi = vol

    def _build_river(self):
        """The calm river with a true planar-mirror reflection."""
        # The mirror on the river plane: re-renders the scene above it each frame.
        self.river_mirror = self.add_child(PlanarReflection3D(position=(0.0, RIVER_LEVEL, 4.0)))

        river = self.add_child(
            WaterSurface3D(position=(0.0, RIVER_LEVEL, 4.0), size=(2 * RIVER_HALF_WIDTH, 54.0), subdivisions=112)
        )
        # Mirror-calm: tiny slow swell + gentle detail ripples so the planar
        # reflection stays crisp, and a long depth-fade over the deep bed so the
        # channel darkens from a clear teal edge to near-black centre.
        river.material = WaterMaterial(
            shallow_colour=(0.12, 0.30, 0.34),
            deep_colour=(0.02, 0.07, 0.11),
            depth_fade_distance=3.2,
            wave_amplitude=0.03,
            wave_length=4.5,
            wave_steepness=0.22,
            foam_amount=0.12,
            refraction_strength=0.16,
            fresnel_power=5.0,
            normal_strength=0.25,
            opacity=0.9,
        )
        # A true mirror instead of the cubemap: the banks + sky invert in the river.
        river.reflection = self.river_mirror
        self.river = river

    def _build_sea(self):
        """The open sea: an FFT ocean, the same on desktop and web.

        The sea plane begins at the shelf edge and extends to the horizon, one
        step below the river, so the river visibly spills into it and the plane
        never underlaps the foreground channel.
        """
        # Centre the plane so its NEAR edge lands at the shelf lip: no near-field
        # sea surface pokes past the banks into the foreground.
        sea_size = 640.0
        sea_z = SHELF_EDGE_Z - sea_size * 0.5
        sea_mat = WaterMaterial(
            shallow_colour=(0.05, 0.24, 0.30),
            deep_colour=(0.01, 0.05, 0.10),
            depth_fade_distance=10.0,
            wave_amplitude=1.2,
            wave_steepness=0.72,
            foam_colour=(0.92, 0.96, 1.0),
            foam_amount=0.7,
            refraction_strength=0.35,
        )
        self.sea = self.add_child(
            OceanSurface3D(position=(0.0, SEA_LEVEL, sea_z), size=(sea_size, sea_size), subdivisions=320)
        )
        self.sea.material = sea_mat

        # A couple of rock stacks out at sea near the river mouth: they break the
        # horizon in the low sun and give the ocean foam something to curl around.
        self.add_child(
            MeshInstance3D(
                mesh=Mesh.sphere(6.5, rings=18, segments=28),
                material=Material(colour=(0.30, 0.28, 0.26, 1.0), roughness=0.85),
                position=(-26.0, SEA_LEVEL - 2.0, -55.0),
            )
        )
        self.add_child(
            MeshInstance3D(
                mesh=Mesh.sphere(4.5, rings=14, segments=22),
                material=Material(colour=(0.33, 0.31, 0.28, 1.0), roughness=0.8),
                position=(30.0, SEA_LEVEL - 1.0, -78.0),
            )
        )

    def _build_rain(self):
        # Rain particles are round camera-facing sprites, so smaller and denser
        # drops read as rain rather than as near-camera bokeh.
        self.add_child(
            Rain3D(
                radius=24.0,
                height=15.0,
                fall_speed=28.0,
                amount=7000,
                wind_response=1.2,
                start_scale=0.028,
                end_scale=0.028,
            )
        )

    def _build_hud(self):
        self.add_child(Text2D(text="TIDEWATER", position=(24, 20), font_scale=2.0))
        # Feature-list subtitle. Drawn in a rect spanning the live window width with
        # ``fit_to_width`` so the trailing entries never clip off the right edge on a
        # narrower window; the rect is re-fitted each frame in ``on_update``.
        self._subtitle = self.add_child(
            Text2D(
                text="FFT ocean  +  planar-mirror river  +  procedural sky  +  rain + wetness  +  GI",
                rect=(24, 58, WIDTH - 48, 22),
                fit_to_width=True,
                font_scale=1.1,
            )
        )
        # Bottom controls hint. Pinned to the live window bottom (see ``on_update``)
        # so it stays on screen at any window size, not just the launch resolution.
        self._controls = self.add_child(
            Text2D(text="SPACE / CLICK:Pause   ESC:Quit", position=(24, HEIGHT - 34), font_scale=1.1)
        )
        # Empty while running (keeps the golden unchanged); shows PAUSED on toggle.
        self._paused_label = self.add_child(Text2D(text="", position=(24, 92), font_scale=1.3))

    # -- input -------------------------------------------------------------
    # Pause and quit run through @on_input, not on_update polling: input
    # handlers fire regardless of ``tree.paused``, so the pause action still
    # resumes a frozen scene (a paused tree stops on_update on every PAUSABLE node).
    @on_input(action="quit")
    def _on_quit(self, event):
        self.app.quit()
        return True

    @on_input(action="pause")
    def _on_pause(self, event):
        # Freeze the whole scene, not just the camera: ``tree.paused`` halts the
        # scene clock (``tree.now``), which is what the FFT ocean, mirror river
        # and rain animate from, so pausing stops the water and rain too.
        tree = self.tree
        tree.paused = not tree.paused
        self._paused_label.text = "PAUSED" if tree.paused else ""
        return True

    # -- per-frame ---------------------------------------------------------
    def on_update(self, dt):
        # Keep the HUD glued to the live window: fit the subtitle to the current
        # width and pin the controls hint to the current bottom, so both stay on
        # screen and unclipped at any window size, not just the launch resolution.
        win_w, win_h = int(self.app.width), int(self.app.height)
        self._subtitle.rect = (24, 58, win_w - 48, 22)
        self._controls.position = (24, win_h - 34)

        # Slow cinematic sway + gentle dolly down the channel, always looking
        # downstream at the sun-glinting sea. Driven by the scene clock so it is
        # deterministic under the fixed headless clock and freezes with the rest
        # of the scene when ``tree.paused`` halts ``tree.now``.
        t = self.tree.now
        cam_x = 3.0 * math.sin(t * 0.13)
        cam_y = 6.5 + 0.5 * math.sin(t * 0.11)
        cam_z = 24.0 - 2.5 * math.sin(t * 0.09)
        self.camera.position = (cam_x, cam_y, cam_z)
        # Aim just ahead down the channel, easing toward the sea so the river
        # leads the eye to the horizon.
        self.camera.look_at((cam_x * 0.25, 0.4, -30.0))


def _selftest() -> bool:
    """Headless self-check: render the flagship, assert it is non-blank and that
    the sea, river and rain animate frame to frame (the money shot is alive)."""
    import numpy as np

    from simvx.graphics.testing import assert_not_blank, save_png

    app = App(width=WIDTH, height=HEIGHT, title="Tidewater", visible=False, backend="glfw")
    scene = TidewaterScene(name="TidewaterScene")

    # Capture two settled frames a few frames apart and one full filmstrip stride
    # so we can prove motion (water/rain) and hand a filmstrip to the reviewer.
    strip = [10, 25, 40, 54, 70]
    frames = app.run_headless(scene, frames=72, capture_frames=strip)
    assert len(frames) == len(strip), f"expected {len(strip)} captures, got {len(frames)}"

    money = frames[3]  # frame 54 == the declared golden / screenshot frame
    assert_not_blank(money)
    save_png(money, "/tmp/tidewater_money.png")
    for fi, px in zip(strip, frames, strict=True):
        save_png(px, f"/tmp/tidewater_{fi:02d}.png")

    # Inter-frame delta over the whole frame proves the combined scene animates
    # (FFT/Gerstner swell + river + rain). Two well-separated frames.
    a = frames[1].astype(np.float32)
    b = frames[4].astype(np.float32)
    mean_delta = float(np.abs(a - b).mean())

    # A representative lower band (the water region) must be clearly non-flat
    # colour-wise (not a dead blue wash): count distinct-ish colours.
    lower = money[money.shape[0] // 2 :, :, :3]
    colours = np.unique(lower.reshape(-1, 3) // 8, axis=0).shape[0]

    checks = {
        "money frame non-blank": True,  # assert_not_blank above would have raised
        "scene animates frame-to-frame (water + rain)": mean_delta > 0.5,
        "water band has rich colour variation": colours > 400,
    }
    print(f"mean_delta={mean_delta:.3f}  water_colours={colours}")
    print("filmstrip: /tmp/tidewater_{10,25,40,54,70}.png  money: /tmp/tidewater_money.png")
    for name, ok in checks.items():
        print(f"  [{'PASS' if ok else 'FAIL'}] {name}")
    passed = all(checks.values())
    print("SELFTEST:", "PASS" if passed else "FAIL")
    return passed


def main():
    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(width=WIDTH, height=HEIGHT, title="SimVX - Tidewater").run(TidewaterScene())


if __name__ == "__main__":
    main()