ReflectionProbe3D

Local cubemap reflections inside a probe box.

📄 Docs only

Tags: 3d reflection ibl probe

A mirror-finish sphere sits inside a ReflectionProbe3D placed in a room with vividly coloured interior walls (red/green/blue/yellow). The probe captures the room into a local cubemap, so the sphere reflects the room colours, clearly different from the faint global sky reflection a sphere would otherwise pick up.

Phase-1 desktop renderer feature:

• Scene captured six times from the probe origin into a cubemap.

• The engine’s existing split-sum IBL precompute (irradiance + prefiltered specular) runs per-probe; results land in a shared cubemap array.

• Fragments inside the probe box sample the local probe IBL (box-projected reflection); fragments outside fall back to the global environment IBL.

Run windowed: uv run python examples/features/3d/reflection_probe.py Run headless: uv run python examples/features/3d/reflection_probe.py –test

Controls: Escape - Quit

Source

"""
ReflectionProbe3D: Local cubemap reflections inside a probe box.

A mirror-finish sphere sits inside a ReflectionProbe3D placed in a room with
vividly coloured interior walls (red/green/blue/yellow). The probe captures the
room into a local cubemap, so the sphere reflects the *room* colours, clearly
different from the faint global sky reflection a sphere would otherwise pick up.

Phase-1 desktop renderer feature:
  - Scene captured six times from the probe origin into a cubemap.
  - The engine's existing split-sum IBL precompute (irradiance + prefiltered
    specular) runs per-probe; results land in a shared cubemap array.
  - Fragments inside the probe box sample the local probe IBL (box-projected
    reflection); fragments outside fall back to the global environment IBL.

Run windowed:   uv run python examples/features/3d/reflection_probe.py
Run headless:   uv run python examples/features/3d/reflection_probe.py --test

Controls:
    Escape  - Quit

# /// simvx
# tags = ["3d", "reflection", "ibl", "probe"]
# screenshot_frame = 8
# web = { disabled = true, reason = "Reflection probes are a desktop-only renderer feature." }
# ///
"""

import math
import sys

from simvx.core import (
    Camera3D,
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    ReflectionProbe3D,
    Text2D,
    Vec3,
    WorldEnvironment,
)
from simvx.graphics import App

ROOM = 8.0  # room half-extent


class ReflectionProbeScene(Node):
    def on_ready(self):
        InputMap.add_action("quit", [Key.ESCAPE])

        # Faint neutral global skybox so surfaces OUTSIDE the probe box still
        # have an environment to reflect (a dim grey-blue sky). The local probe
        # reflection should look obviously different (saturated room colours).
        self.add_child(WorldEnvironment(environment_map={"colour": (0.20, 0.22, 0.28)}))

        # Camera sits INSIDE the room near the (low) front wall, looking at the
        # sphere, so the back/side coloured walls fill the view and reflect.
        cam = self.add_child(Camera3D(
            position=(0, -6.5, 1.0), fov=60, near=0.1, far=200.0,
            look_at=Vec3(0, 0, 0.6), up=Vec3(0, 0, 1),
        ))
        self._cam = cam

        sun = DirectionalLight3D(position=(4, -6, 9))
        sun.colour = (1.0, 0.98, 0.92)
        sun.intensity = 1.1
        sun.look_at(Vec3(0, 0, 0))
        self.add_child(sun)

        self._build_room()

        # Reflective sphere: full metallic, near-mirror finish so the local
        # reflection dominates the shading.
        sphere = Mesh.sphere(2.4, rings=48, segments=64)
        mirror = Material(colour=(0.95, 0.95, 0.95, 1.0), metallic=1.0, roughness=0.05)
        self.add_child(MeshInstance3D(mesh=sphere, material=mirror, position=(0, 1.0, 0.6)))

        # Reflection probe whose box encloses the whole room, capturing the
        # coloured walls. box_projection makes the flat walls reflect correctly.
        probe = ReflectionProbe3D(
            size=(ROOM, ROOM, ROOM),
            origin_offset=(0, 0, 0.6),
            box_projection=True,
            intensity=1.0,
            position=(0, 0, 0.0),
        )
        self.add_child(probe)
        self._probe = probe

        self.add_child(Text2D(text="ReflectionProbe3D: local cubemap reflections", x=12, y=12, font_scale=2.0))
        self.add_child(Text2D(text="Mirror sphere reflects the coloured room, not the sky", x=12, y=58, font_scale=1.6))

        self._time = 0.0

    def _wall(self, colour, position, scale):
        mat = Material(colour=(*colour, 1.0), metallic=0.0, roughness=0.85)
        self.add_child(MeshInstance3D(mesh=Mesh.cube(1.0), material=mat, position=position, scale=Vec3(*scale)))

    def _build_room(self):
        t = 0.3  # wall thickness
        # Yellow floor + light ceiling. The front (toward camera) wall is omitted
        # so the camera sees into the room; the other walls reflect off the sphere.
        self._wall((0.90, 0.80, 0.10), (0, 0, -ROOM), (ROOM, ROOM, t))  # floor = yellow
        self._wall((0.55, 0.55, 0.60), (0, 0, ROOM), (ROOM, ROOM, t))   # ceiling
        self._wall((0.85, 0.12, 0.12), (-ROOM, 0, 0), (t, ROOM, ROOM))  # left  = red
        self._wall((0.12, 0.75, 0.20), (ROOM, 0, 0), (t, ROOM, ROOM))   # right = green
        self._wall((0.12, 0.30, 0.90), (0, ROOM, 0), (ROOM, t, ROOM))   # back  = blue

    def on_process(self, dt):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        # Gentle side-to-side sway near the open front of the room, so the
        # reflected red/green/blue walls sweep across the mirror sphere while the
        # camera stays inside (never orbiting behind a wall).
        self._time += dt * 0.4
        self._cam.position = Vec3(
            math.sin(self._time) * 4.0,
            -6.5,
            1.0 + math.sin(self._time * 0.5) * 1.0,
        )
        self._cam.look_at(Vec3(0, 0.5, 0.6), up=Vec3(0, 0, 1))


def _run_test():
    """Headless smoke test: render a few frames and assert the sphere reflects the room."""
    import numpy as np

    from simvx.graphics import save_png

    app = App(title="ReflectionProbe", width=900, height=600, visible=False)
    frames = app.run_headless(ReflectionProbeScene(), frames=8, capture_frames=[7])
    img = frames[0]
    save_png("/tmp/verify/reflection_probe/with_probe.png", img)

    # The mirror sphere must reflect the SATURATED room walls (red left, green
    # right, yellow floor), not the flat grey global sky. Sample three patches
    # on the sphere's lower ring where those reflections land and assert each
    # carries a strong dominant hue (one channel clearly above the others).
    h, w = img.shape[:2]
    cx, cy = w // 2, h // 2
    # (patch, dominant channel index): red=0, green=1, yellow=>R&G over B.
    samples = [
        ("left/red", img[cy:cy + 50, cx - 110:cx - 70, :3], 0),
        ("right/green", img[cy:cy + 50, cx + 70:cx + 110, :3], 1),
        ("floor/yellow", img[cy + 90:cy + 130, cx - 30:cx + 30, :3], None),
    ]
    matched = 0
    for name, patch, dom in samples:
        r, g, b = patch.astype(np.float32).reshape(-1, 3).mean(axis=0)
        if dom == 0:
            ok = r > g * 1.5 and r > b * 1.5
        elif dom == 1:
            ok = g > r * 1.5 and g > b * 1.5
        else:  # yellow: red & green both dominate blue
            ok = r > b * 1.5 and g > b * 1.5
        print(f"[test] {name} reflection rgb=[{r:.1f},{g:.1f},{b:.1f}] hue_match={ok}")
        matched += int(bool(ok))
    print("[test] wrote /tmp/verify/reflection_probe/with_probe.png")
    assert matched >= 2, "mirror sphere is not reflecting the coloured room (probe IBL missing)"
    print(f"[test] PASS ({matched}/3 reflection patches match the expected room hue)")


if __name__ == "__main__":
    if "--test" in sys.argv:
        _run_test()
    else:
        App(title="ReflectionProbe Demo", width=1280, height=720).run(ReflectionProbeScene())