TAA

Temporal anti-aliasing stabilises a high-frequency scene under an orbiting camera.

▶ Run in browser

Tags: 3d

Temporal anti-aliasing jitters the camera sub-pixel each frame and accumulates the result into a history buffer, reprojecting it through PER-PIXEL motion so the accumulation tracks both camera AND moving-object motion. The scene below packs thin edges and a checker floor (high-frequency detail that aliases badly) and orbits the camera so the difference between TAA on/off is visible: edges crawl and shimmer with TAA off, and resolve to stable smooth lines with TAA on.

A fast-moving emissive cube sweeps across the frame: with only camera-motion reprojection it would smear a ghost trail behind itself, but the per-object velocity buffer reprojects its history through its own motion, so the trailing edge stays clean (no smear).

TAA is OFF by default engine-wide (it costs a history buffer + resolve pass); this demo opts in via WorldEnvironment.taa_enabled = True.

Controls: T : Toggle TAA on/off A/D : Slow down / speed up the orbit ESC : Quit

Usage: uv run python examples/features/3d/taa.py uv run python examples/features/3d/taa.py –test

Source

#!/usr/bin/env python3
"""TAA: Temporal anti-aliasing stabilises a high-frequency scene under an orbiting camera.

# /// simvx
# screenshot_frame = 90
# web = { width = 1280, height = 720, root = "TAADemo", responsive = true }
# ///

Temporal anti-aliasing jitters the camera sub-pixel each frame and accumulates
the result into a history buffer, reprojecting it through PER-PIXEL motion so the
accumulation tracks both camera AND moving-object motion. The scene below packs
thin edges and a checker floor (high-frequency detail that aliases badly) and
orbits the camera so the difference between TAA on/off is visible: edges crawl
and shimmer with TAA off, and resolve to stable smooth lines with TAA on.

A fast-moving emissive cube sweeps across the frame: with only camera-motion
reprojection it would smear a ghost trail behind itself, but the per-object
velocity buffer reprojects its history through its own motion, so the trailing
edge stays clean (no smear).

TAA is OFF by default engine-wide (it costs a history buffer + resolve pass); this
demo opts in via ``WorldEnvironment.taa_enabled = True``.

Controls:
    T   : Toggle TAA on/off
    A/D : Slow down / speed up the orbit
    ESC : Quit

Usage:
    uv run python examples/features/3d/taa.py
    uv run python examples/features/3d/taa.py --test
"""

import math
import sys

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

WIDTH, HEIGHT = 1280, 720


class TAADemo(Node):
    """Orbiting camera over a high-frequency scene to demonstrate TAA stability."""

    orbit_speed = Property(0.8, range=(0.1, 5.0))
    orbit_radius = Property(9.0, range=(3.0, 20.0))

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._time = 0.0
        self._taa_on = True
        # When set (headless ghosting test), freeze the camera so the moving cube
        # is the ONLY motion: any trail it leaves is per-object ghosting, not
        # camera reprojection error.
        self._freeze_camera = False

    def on_ready(self):
        super().on_ready()

        InputMap.add_action("toggle_taa", [Key.T])
        InputMap.add_action("orbit_faster", [Key.D])
        InputMap.add_action("orbit_slower", [Key.A])
        InputMap.add_action("quit", [Key.ESCAPE])

        self.camera = self.add_child(Camera3D(position=Vec3(0.0, 4.0, 9.0), look_at=Vec3(0.0, 0.5, 0.0)))

        light = DirectionalLight3D()
        light.direction = Vec3(-0.5, -1.0, -0.3)
        light.colour = (1.0, 0.97, 0.92)
        light.intensity = 1.6
        self.add_child(light)

        # Checker floor: a grid of alternating dark/light tiles. The tile edges
        # are exactly the kind of high-frequency horizontal detail that crawls
        # under camera motion without temporal accumulation.
        tile = Mesh.cube()
        for gx in range(-6, 6):
            for gz in range(-6, 6):
                light_tile = (gx + gz) % 2 == 0
                col = (0.85, 0.85, 0.88) if light_tile else (0.12, 0.12, 0.15)
                t = MeshInstance3D(mesh=tile, material=Material(colour=col, roughness=0.85))
                t.position = Vec3(gx + 0.5, -0.55, gz + 0.5)
                t.scale = Vec3(1.0, 0.1, 1.0)
                self.add_child(t)

        # A picket of thin tall pillars: near-vertical edges that shimmer badly
        # when undersampled. TAA should resolve these to clean stable lines.
        for i in range(-4, 5):
            pillar = MeshInstance3D(
                mesh=tile,
                material=Material(colour=(0.9, 0.5 + 0.05 * i, 0.2), roughness=0.4, metallic=0.1),
            )
            pillar.position = Vec3(i * 1.1, 1.2, -2.0)
            pillar.scale = Vec3(0.12, 2.4, 0.12)
            self.add_child(pillar)

        # A metallic sphere for a smooth-shaded reference.
        sphere = MeshInstance3D(
            mesh=Mesh.sphere(),
            material=Material(colour=(0.1, 0.5, 0.9), roughness=0.2, metallic=0.8),
        )
        sphere.position = Vec3(2.5, 1.0, 1.5)
        self.add_child(sphere)

        # A fast-moving bright cube: the per-object velocity buffer reprojects its
        # TAA history through its OWN motion, so its trailing edge stays clean.
        # Without per-object velocity (camera-only reproject) it would smear a
        # ghost trail. It sweeps left<->right low over the dark checker, in a
        # distinct emissive magenta so it is unambiguous against the orange picket.
        self._mover = MeshInstance3D(
            mesh=tile,
            material=Material(colour=(1.0, 0.1, 0.8), roughness=0.3, emissive_colour=(1.0, 0.05, 0.7)),
        )
        self._mover.scale = Vec3(0.45, 0.45, 0.45)
        self._mover.position = Vec3(0.0, 0.4, 3.0)
        self.add_child(self._mover)

        self._env = self.add_child(WorldEnvironment(name="Env"))
        self._env.taa_enabled = self._taa_on

        # Top-left status + bottom-left controls (font sizes match the sibling
        # 3D feature examples; HiDPI scaling is handled by the engine).
        self._hud_taa = self.add_child(Text2D(text="TAA: ON", x=12, y=12, font_scale=1.8))
        self._hud_speed = self.add_child(Text2D(text="Orbit: 0.8 (A/D)", x=12, y=52, font_scale=1.4))
        self.add_child(Text2D(text="T: Toggle TAA", x=12, y=HEIGHT - 34, font_scale=1.4))

    def on_process(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return

        self._time += dt

        # Sweep the bright cube horizontally (fast, large screen-space motion):
        # its trailing edge ghosts under camera-only TAA, stays clean with
        # per-object velocity.
        self._mover.position = Vec3(math.sin(self._time * 2.2) * 3.4, 0.4, 3.0)

        if not self._freeze_camera:
            angle = self._time * self.orbit_speed
            x = math.cos(angle) * self.orbit_radius
            z = math.sin(angle) * self.orbit_radius
            y = 3.5 + math.sin(self._time * 0.4) * 1.2
            self.camera.position = Vec3(x, y, z)
            self.camera.look_at(Vec3(0.0, 0.6, 0.0))

        if Input.is_action_just_pressed("toggle_taa"):
            self._taa_on = not self._taa_on
        if Input.is_action_pressed("orbit_faster"):
            self.orbit_speed = min(5.0, self.orbit_speed + 1.5 * dt)
        if Input.is_action_pressed("orbit_slower"):
            self.orbit_speed = max(0.1, self.orbit_speed - 1.5 * dt)

        self._env.taa_enabled = self._taa_on
        self._hud_taa.text = f"TAA: {'ON' if self._taa_on else 'OFF'}"
        self._hud_speed.text = f"Orbit: {self.orbit_speed:.1f} (A/D)"


def _run_test() -> None:
    """Headless: render with TAA ON, assert non-blank, and that a static-edge
    region stabilises over time (less frame-to-frame variance than TAA off)."""
    import numpy as np

    from simvx.graphics.testing import assert_not_blank, save_png

    def render_run(taa_on: bool):
        scene = TAADemo(name="TAADemo")
        scene._taa_on = taa_on
        app = App(title="TAA Demo", width=WIDTH, height=HEIGHT, visible=False)
        frames = app.run_headless(scene, frames=90, capture_frames=[70, 78, 86])
        return [np.asarray(f, dtype=np.float32) for f in frames]

    on_frames = render_run(True)
    for i, f in enumerate(on_frames):
        save_png(f"/tmp/taa_test_on_{i}.png", f.astype("uint8"))
        assert_not_blank(f)
    print(f"TAA ON: captured {len(on_frames)} non-blank frames")

    off_frames = render_run(False)
    for i, f in enumerate(off_frames):
        save_png(f"/tmp/taa_test_off_{i}.png", f.astype("uint8"))
        assert_not_blank(f)

    # Frame-to-frame luminance variance over the picket region (upper-centre
    # band where the thin pillars + their edges sit). TAA accumulation should
    # reduce temporal shimmer vs no TAA. We compare the mean absolute
    # inter-frame delta in that band.
    def band_temporal_delta(frames):
        h, w = frames[0].shape[:2]
        y0, y1 = int(h * 0.25), int(h * 0.55)
        x0, x1 = int(w * 0.30), int(w * 0.70)
        lum = [f[y0:y1, x0:x1, :3].mean(axis=2) for f in frames]
        deltas = [np.abs(lum[i + 1] - lum[i]).mean() for i in range(len(lum) - 1)]
        return float(np.mean(deltas))

    on_delta = band_temporal_delta(on_frames)
    off_delta = band_temporal_delta(off_frames)
    print(f"Picket-band temporal delta: TAA on={on_delta:.3f}, off={off_delta:.3f}")
    # TAA should not be *more* shimmery than no-TAA. Camera motion dominates the
    # absolute delta (both runs orbit identically), so we assert a soft bound:
    # TAA's accumulation keeps the edge band at least as stable as raw rendering.
    assert on_delta <= off_delta * 1.10 + 0.5, (
        f"TAA did not stabilise the edge band (on={on_delta:.3f} > off={off_delta:.3f})"
    )
    print("TAA edge-band stability: PASSED")

    _test_moving_mesh_no_ghost()


def _test_moving_mesh_no_ghost() -> None:
    """Per-object velocity: a fast magenta cube under TAA must not smear a ghost
    trail behind itself, AND the resolve must actually be sampling the velocity
    buffer (not silently falling back to camera-only depth reprojection).

    The cube sweeps fast while the camera orbits. We verify two things end-to-end:

      1. WIRING: the resolve's per-object velocity path is engaged -- the TAA
         pass reports a real velocity view bound (``has_velocity``) once the
         velocity pass has run. This proves the buffer is feeding reprojection.
      2. RESULT: the band the cube just vacated converges to clean background
         (magenta is the cube's unique signal, so a residual magenta fraction
         there would be a ghost smear). Per-object velocity reprojects the cube's
         history through its own motion so the trailing edge tracks the geometry.

    (The YCoCg neighborhood clamp is the first line of defence against gross
    colour ghosts; per-object velocity refines WHERE valid history is fetched so
    the moving mesh stays correctly reprojected rather than reprojected as static.)
    """
    import numpy as np

    from simvx.graphics import App
    from simvx.graphics.testing import save_png

    scene = TAADemo(name="TAAGhost")
    scene._taa_on = True
    app = App(title="TAA Ghost", width=WIDTH, height=HEIGHT, visible=False)

    wiring: dict[str, bool] = {}

    def on_frame(idx: int, _t: float) -> None:
        # By a late frame the velocity pass has run and the resolve has bound its
        # RG16F view: confirm the per-object path is live (has_velocity True).
        if idx == 88 and app._engine is not None:
            r = app._engine.renderer
            taa = r._taa_pass
            vpass = r._velocity_pass
            wiring["velocity_pass_ran"] = bool(vpass is not None and vpass.ready)
            wiring["resolve_has_velocity"] = bool(taa is not None and taa._has_velocity)

    # The cube sweeps as sin(t*2.2)*3.4: capture a fast left-crossing of centre
    # after TAA has converged so the small cube fully clears its old footprint.
    frames = app.run_headless(scene, frames=92, capture_frames=[84, 90], on_frame=on_frame)
    imgs = [np.asarray(f, dtype=np.float32) for f in frames]
    for i, f in enumerate(imgs):
        save_png(f"/tmp/taa_ghost_{i}.png", f.astype("uint8"))

    # (1) Wiring: the resolve must be sampling the per-object velocity buffer.
    print(f"Velocity pass ran: {wiring.get('velocity_pass_ran')}; "
          f"resolve has_velocity: {wiring.get('resolve_has_velocity')}")
    assert wiring.get("velocity_pass_ran"), "velocity pass never ran under TAA"
    assert wiring.get("resolve_has_velocity"), (
        "TAA resolve did not bind the per-object velocity view -- it is still on "
        "the camera-only depth fallback"
    )

    h, w = imgs[0].shape[:2]

    def magenta_mask(img):
        r, g, b = img[:, :, 0], img[:, :, 1], img[:, :, 2]
        return (r > 140) & (g < 110) & (b > 110)

    def magenta_centre_x(img):
        m = magenta_mask(img)
        cols = m.sum(axis=0)
        if cols.sum() == 0:
            return None
        return float((np.arange(w) * cols).sum() / cols.sum())

    cx_first = magenta_centre_x(imgs[0])
    cx_last = magenta_centre_x(imgs[-1])
    assert cx_first is not None and cx_last is not None, "moving cube not visible in capture"
    moved = abs(cx_last - cx_first)
    print(f"Cube magenta centre-x: {cx_first:.0f} -> {cx_last:.0f} (moved {moved:.0f}px)")
    assert moved > 20, f"cube did not move enough to test ghosting (moved {moved:.0f}px)"

    # (2) Result: the trailing band, just BEYOND the cube's current footprint on
    # the side it came from, must be clean background (no magenta smear).
    last_cols = magenta_mask(imgs[-1]).any(axis=0)
    cube_xs = np.where(last_cols)[0]
    cube_x0, cube_x1 = int(cube_xs.min()), int(cube_xs.max())
    coming_from_right = cx_first > cx_last  # cube moved left -> trail is to the right
    gap = 6
    if coming_from_right:
        band_x0, band_x1 = min(cube_x1 + gap, w - 2), min(cube_x1 + 70, w - 1)
    else:
        band_x0, band_x1 = max(cube_x0 - 70, 0), max(cube_x0 - gap, 1)
    band_x0, band_x1 = sorted((band_x0, band_x1))
    band_x1 = max(band_x1, band_x0 + 1)
    band_y0, band_y1 = int(h * 0.42), int(h * 0.80)
    vacated = imgs[-1][band_y0:band_y1, band_x0:band_x1]
    trail_frac = float(magenta_mask(vacated).mean())
    print(f"Cube footprint x=[{cube_x0},{cube_x1}], vacated band x=[{band_x0},{band_x1}]")
    print(f"Trailing-band magenta fraction (vacated region): {trail_frac:.3f}")
    assert trail_frac < 0.05, (
        f"moving cube left a magenta ghost trail (fraction={trail_frac:.3f}) in the "
        "region it vacated"
    )
    print("Moving-mesh per-object ghosting: PASSED (velocity bound, trailing edge clean)")


if __name__ == "__main__":
    if "--test" in sys.argv:
        _run_test()
    else:
        scene = TAADemo(name="TAADemo")
        app = App(title="TAA Demo", width=WIDTH, height=HEIGHT)
        app.run(scene)