ReflectionProbe3D

Local cubemap reflections inside a probe box.

▶ Run in browser

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.

How it works:

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

• The engine’s 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.

Two further scenes live in this file, each selected with --scene:

• blend: distance-weighted blending of the two nearest probes (blend_distance edge falloff) so overlapping probes cross-fade instead of hard-switching. A mirror sphere in the overlap reflects both hues.

• dynamic: capture_mode=”always” with time_slicing=”round_robin”, so the probe cubemap refreshes over time (one cube face per frame) as the scene changes: the room flips blue to red and the reflection follows.

Run windowed: uv run python examples/features/3d/reflection_probe.py uv run python examples/features/3d/reflection_probe.py –scene blend uv run python examples/features/3d/reflection_probe.py –scene dynamic

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.

How it works:
  - Scene captured six times from the probe origin into a cubemap.
  - The engine's 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.

Two further scenes live in this file, each selected with ``--scene``:
  - ``blend``: distance-weighted blending of the two nearest probes
    (blend_distance edge falloff) so overlapping probes cross-fade instead of
    hard-switching. A mirror sphere in the overlap reflects both hues.
  - ``dynamic``: capture_mode="always" with time_slicing="round_robin", so the
    probe cubemap refreshes over time (one cube face per frame) as the scene
    changes: the room flips blue to red and the reflection follows.

Run windowed:   uv run python examples/features/3d/reflection_probe.py
                uv run python examples/features/3d/reflection_probe.py --scene blend
                uv run python examples/features/3d/reflection_probe.py --scene dynamic

Controls:
    Escape  - Quit

# /// simvx
# tags = ["3d", "reflection", "ibl", "probe"]
# screenshot_frame = 8
# web = { root = "ReflectionProbeScene", width = 900, height = 600, responsive = true }
# ///
"""

import argparse
import math

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

ROOM = 9.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, -8.0, 1.2),
                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)

        # Fill light from the -X / +Y side. The single sun (on the +X side) lights
        # the red, blue and floor inner faces but leaves the green wall's inner
        # face (-X normal) in shadow, so it reflected almost black. This fill hits
        # the green wall without double-lighting the blue wall (whose -Y inner face
        # faces away from it), keeping the reflected colours balanced.
        fill = DirectionalLight3D(position=(-4, 6, 9))
        fill.colour = (0.95, 0.97, 1.0)
        fill.intensity = 1.0
        fill.look_at(Vec3(0, 0, 0))
        self.add_child(fill)

        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 * 2, ROOM * 2, ROOM * 2),
            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", position=(12, 12), font_scale=2.0))
        self.add_child(
            Text2D(text="Mirror sphere reflects the coloured room, not the sky", position=(12, 58), font_scale=1.6)
        )

        self._time = 0.0

    def _wall(self, colour, position, scale, emissive=None):
        mat = Material(colour=(*colour, 1.0), metallic=0.0, roughness=0.85, emissive_colour=emissive)
        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
        # A fully enclosed box so the mirror sphere reflects a wall in every
        # direction (no dark gap). The camera sits just inside the front wall,
        # which it never sees directly but the sphere reflects, so the sphere's
        # centre shows the magenta front wall instead of the dark opening. The
        # ceiling is an emissive skylight: its inner (-Z) face points away from
        # both directional lights, so without the glow the sphere's top reflects
        # a dark void. Neutral grey emissive adds no hue to bleed into the
        # coloured patches.
        ceiling = (0.80, 0.82, 0.88)
        self._wall((0.90, 0.80, 0.10), (0, 0, -ROOM), (ROOM, ROOM, t))  # floor = yellow
        self._wall(ceiling, (0, 0, ROOM), (ROOM, ROOM, t), emissive=(*ceiling, 0.8))  # ceiling skylight
        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
        self._wall((0.75, 0.15, 0.65), (0, -ROOM, 0), (ROOM, t, ROOM))  # front = magenta (behind camera)

    def on_update(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,
            -8.0,
            1.2 + math.sin(self._time * 0.5) * 1.0,
        )
        self._cam.look_at(Vec3(0, 0.5, 0.6), up=Vec3(0, 0, 1))


# ---------------------------------------------------------------------------
# Distance-weighted 2-probe blending
# ---------------------------------------------------------------------------


class BlendScene(Node):
    """Two overlapping probes: a red-lit box and a green-lit box.

    Each probe sits inside a fully-enclosed single-colour cube (all red / all
    green), so its cubemap is that colour in EVERY direction. A mirror sphere
    sits in the OVERLAP band where both probe influence boxes cover it (within
    each other's ``blend_distance``). With the old hard cutoff the sphere would
    reflect exactly one probe (pure red OR pure green); with distance-weighted
    blending it reflects a MIX, so both R and G are elevated regardless of the
    per-fragment reflection direction.
    """

    def on_ready(self):
        InputMap.add_action("quit", [Key.ESCAPE])
        self.add_child(WorldEnvironment(environment_map={"colour": (0.02, 0.02, 0.02)}))

        self.add_child(
            Camera3D(
                position=(0, -10.0, 1.2),
                fov=55,
                near=0.1,
                far=200.0,
                look_at=Vec3(0, 0, 0.6),
                up=Vec3(0, 0, 1),
            )
        )
        sun = DirectionalLight3D(position=(2, -6, 9))
        sun.colour = (1.0, 1.0, 1.0)
        sun.intensity = 1.1
        sun.look_at(Vec3(0, 0, 0))
        self.add_child(sun)

        # Two fully-closed single-colour cubes, off to either side, each enclosing
        # one probe so its cubemap is that colour in every direction.
        self._room((0.95, 0.05, 0.05), centre_x=-6.0)  # red cube around probe A
        self._room((0.05, 0.95, 0.05), centre_x=+6.0)  # green cube around probe B

        # Mirror sphere in the centre overlap band.
        sphere = Mesh.sphere(2.0, rings=48, segments=64)
        mirror = Material(colour=(0.95, 0.95, 0.95, 1.0), metallic=1.0, roughness=0.04)
        self.add_child(MeshInstance3D(mesh=sphere, material=mirror, position=(0, 1.0, 0.6)))

        # Two probes whose boxes overlap across the centre, each with a wide
        # blend_distance so the centre sits in the cross-fade region of both. The
        # influence box (18 across) reaches the sphere; the capture room (6 across) is
        # tight around each probe so the cubemap is a single saturated hue.
        for cx in (-6.0, 6.0):
            probe = ReflectionProbe3D(
                size=(18.0, 18.0, 18.0),
                box_projection=False,
                intensity=1.0,
                blend_distance=8.0,
                position=(cx, 0, 0.6),
            )
            self.add_child(probe)

        self.add_child(
            Text2D(
                text="ReflectionProbe3D blending: red probe + green probe overlap", position=(12, 12), font_scale=1.8
            )
        )

    def _room(self, colour, centre_x):
        t = 0.3
        hw = 3.0  # half-width of each closed colour cube
        c = (*colour, 1.0)

        def wall(pos, scale):
            # Self-lit walls (emissive): the closed cube blocks the sun and the
            # scene's environment is near-black, so emissive keeps the captured
            # cubemap a saturated hue regardless of the installed environment IBL.
            mat = Material(colour=c, metallic=0.0, roughness=0.85, emissive_colour=(*colour, 0.9))
            self.add_child(MeshInstance3D(mesh=Mesh.cube(1.0), material=mat, position=pos, scale=Vec3(*scale)))

        wall((centre_x, 0, -hw), (hw, hw, t))  # floor
        wall((centre_x, 0, hw), (hw, hw, t))  # ceiling
        wall((centre_x - hw, 0, 0), (t, hw, hw))  # outer side
        wall((centre_x + hw, 0, 0), (t, hw, hw))  # inner side
        wall((centre_x, -hw, 0), (hw, t, hw))  # front
        wall((centre_x, hw, 0), (hw, t, hw))  # back

    def on_update(self, dt):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()


# ---------------------------------------------------------------------------
# capture_mode="always" round-robin refresh
# ---------------------------------------------------------------------------


class AlwaysModeScene(Node):
    """An always-mode probe whose captured scene changes over time.

    The whole room (a closed cube enclosing both probe and camera) starts BLUE
    and flips to RED after the first capture settles. With round-robin refresh
    the probe re-captures over the following frames, so the mirror sphere's
    reflected hue migrates from blue toward red. A uniform-colour box makes the
    reflected hue direction-independent, so the test reads a clean blue->red
    shift regardless of which way each sphere fragment reflects.
    """

    def on_ready(self):
        InputMap.add_action("quit", [Key.ESCAPE])
        self.add_child(WorldEnvironment(environment_map={"colour": (0.02, 0.02, 0.02)}))
        # Camera INSIDE the closed cube, near the front wall, looking at the sphere.
        self.add_child(
            Camera3D(
                position=(0, -6.0, 0.6),
                fov=60,
                near=0.1,
                far=200.0,
                look_at=Vec3(0, 0, 0.6),
                up=Vec3(0, 0, 1),
            )
        )
        sun = DirectionalLight3D(position=(4, -6, 9))
        sun.colour = (1.0, 1.0, 1.0)
        sun.intensity = 1.2
        sun.look_at(Vec3(0, 0, 0))
        self.add_child(sun)

        t = 0.3
        hw = 7.0
        self._walls = []

        def wall(pos, scale):
            mat = Material(colour=(0.10, 0.20, 0.95, 1.0), metallic=0.0, roughness=0.85)
            self.add_child(MeshInstance3D(mesh=Mesh.cube(1.0), material=mat, position=pos, scale=Vec3(*scale)))
            self._walls.append(mat)

        # Fully-closed uniform-colour cube enclosing probe + camera + sphere.
        wall((0, 0, -hw), (hw, hw, t))  # floor
        wall((0, 0, hw), (hw, hw, t))  # ceiling
        wall((-hw, 0, 0), (t, hw, hw))  # left
        wall((hw, 0, 0), (t, hw, hw))  # right
        wall((0, hw, 0), (hw, t, hw))  # back
        wall((0, -hw, 0), (hw, t, hw))  # front (behind the camera)

        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.5, 0.6)))

        self.add_child(
            ReflectionProbe3D(
                size=(hw * 2, hw * 2, hw * 2),
                origin_offset=(0, 0, 0.6),
                box_projection=True,
                intensity=1.0,
                capture_mode="always",
                position=(0, 0, 0.0),
            )
        )
        self._frame = 0

    def on_update(self, dt):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
        self._frame += 1
        # After the initial capture settles, flip the whole room blue -> red.
        if self._frame == 8:
            for mat in self._walls:
                mat.colour = (0.95, 0.08, 0.08, 1.0)


SCENES = {"room": ReflectionProbeScene, "blend": BlendScene, "dynamic": AlwaysModeScene}


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="ReflectionProbe3D reference scenes")
    parser.add_argument("--scene", choices=tuple(SCENES), default="room", help="which probe scene to run")
    scene_name = parser.parse_args().scene
    App(title=f"ReflectionProbe Demo ({scene_name})", width=1280, height=720).run(SCENES[scene_name]())