Model Viewer

Load glTF models with PBR textures and orbit camera.

▶ Run in browser

Tags: 3d

Auto-downloads the Khronos BoomBox sample on first run.

Asset references use the canonical Resource(package, name) form, which resolves through :mod:importlib.resources. The BoomBox directory beside this file is a real Python package (it carries an empty __init__.py); we add that assets directory to sys.path so the package is importable however the demo is launched. See docs/package_resources.md.

The camera frames whatever it loads. glTF models are authored at real-world scale, and the samples differ by orders of magnitude: this radio is 20 cm across, and a fixed orbit distance that suits it shows nothing at all of a building. The orbit distance and the zoom limits are therefore read off the model’s own bounds, so pointing the viewer at another file needs no tuning.

The Khronos BoomBox sample is third-party and is not part of the installed library; if it is not beside this file it is fetched once into $XDG_CACHE_HOME/simvx/example-assets/. It is CC0-1.0; see assets/ATTRIBUTION.md.

Controls: Left-click drag: orbit camera Scroll wheel: zoom in/out Escape: quit

Usage: uv run python examples/features/3d/model_viewer.py uv run python examples/features/3d/model_viewer.py –test # headless self-check

Source

"""Model Viewer: Load glTF models with PBR textures and orbit camera.

# /// simvx
# web = { root = "ModelViewer" }
# ///

Auto-downloads the Khronos BoomBox sample on first run.

Asset references use the canonical ``Resource(package, name)`` form, which
resolves through :mod:`importlib.resources`. The ``BoomBox`` directory beside
this file is a real Python package (it carries an empty ``__init__.py``); we add
that ``assets`` directory to ``sys.path`` so the package is importable however
the demo is launched. See ``docs/package_resources.md``.

The camera frames whatever it loads. glTF models are authored at real-world
scale, and the samples differ by orders of magnitude: this radio is 20 cm
across, and a fixed orbit distance that suits it shows nothing at all of a
building. The orbit distance and the zoom limits are therefore read off the
model's own bounds, so pointing the viewer at another file needs no tuning.

The Khronos BoomBox sample is third-party and is not part of the installed
library; if it is not beside this file it is fetched once into
``$XDG_CACHE_HOME/simvx/example-assets/``. It is CC0-1.0; see
``assets/ATTRIBUTION.md``.

Controls:
    Left-click drag: orbit camera
    Scroll wheel: zoom in/out
    Escape: quit

Usage:
    uv run python examples/features/3d/model_viewer.py
    uv run python examples/features/3d/model_viewer.py --test   # headless self-check
"""

import math
import os
import sys
import urllib.request
from pathlib import Path

# Make ``examples/assets`` importable so ``Resource("BoomBox", ...)`` resolves
# to the package next door. Mirrors how a game project would ship its own
# assets dir on ``sys.path``; production games typically rely on their normal
# package install path instead.
_ASSETS_PARENT = (Path(__file__).parent / "assets").resolve()
if str(_ASSETS_PARENT) not in sys.path:
    sys.path.insert(0, str(_ASSETS_PARENT))

from simvx.core import (  # noqa: E402
    AnchorPreset,
    Camera3D,
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    Label,
    MouseButton,
    Node,
    Resource,
)
from simvx.graphics import App  # noqa: E402

# One canonical handle per asset. Construction is lazy: the underlying file
# is not touched until ``.path`` / ``.read_bytes()`` is accessed.
MODEL_GLTF = Resource("BoomBox", "BoomBox.gltf")
MODEL_BIN = Resource("BoomBox", "BoomBox.bin")
MODEL_TEXTURES = [
    Resource("BoomBox", "BoomBox_baseColor.png"),
    Resource("BoomBox", "BoomBox_normal.png"),
    Resource("BoomBox", "BoomBox_occlusionRoughnessMetallic.png"),
    Resource("BoomBox", "BoomBox_emissive.png"),
]

# Khronos glTF-Sample-Assets raw URLs
_BASE_URL = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/BoomBox/glTF"
_DOWNLOAD_TARGETS = [MODEL_GLTF, MODEL_BIN, *MODEL_TEXTURES]

# How much empty space to leave around the model once it is framed: 1.0 puts
# the bounding sphere exactly on the edges of the view, which crops the corners
# as the model turns.
_FRAME_MARGIN = 1.15


def _download_assets() -> None:
    """Fetch the BoomBox contents if they are not already available.

    Writes into a per-user cache rather than beside this file, so it works from
    a read-only install. The cache directory is put on ``sys.path`` so the
    ``Resource`` lookup above finds it exactly as it finds a checkout copy.
    """
    if all((_ASSETS_PARENT / "BoomBox" / r.name).exists() for r in _DOWNLOAD_TARGETS):
        return
    cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
    asset_dir = cache / "simvx" / "example-assets" / "BoomBox"
    asset_dir.mkdir(parents=True, exist_ok=True)
    (asset_dir / "__init__.py").touch()
    if str(asset_dir.parent) not in sys.path:
        sys.path.insert(0, str(asset_dir.parent))
    for resource in _DOWNLOAD_TARGETS:
        dest = asset_dir / resource.name
        if dest.exists():
            continue
        url = f"{_BASE_URL}/{resource.name}"
        print(f"Downloading {resource.name}...")
        urllib.request.urlretrieve(url, dest)


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

        # Orbit state. The distance and its limits are placeholders until the
        # model is loaded and framed; a model whose size is unknown until then
        # is exactly what this viewer exists to look at.
        self._yaw = 0.0
        self._pitch = 20.0
        self._distance = 3.5
        self._min_distance = 0.1
        self._max_distance = 20.0
        self._auto_rotate = True
        self._target = (0.0, 0.0, 0.0)

        # Camera
        self._cam = Camera3D(name="Camera", fov=45, near=0.1, far=100.0)
        self.add_child(self._cam)

        # Lighting: key + fill
        key = DirectionalLight3D(name="KeyLight", intensity=1.5)
        key.look_at((-1.0, -2.0, -1.0))
        self.add_child(key)

        fill = DirectionalLight3D(name="FillLight", intensity=0.4, colour=(0.6, 0.7, 1.0))
        fill.look_at((1.0, -1.0, 2.0))
        self.add_child(fill)

        # Load model. ``import_gltf`` is backend-agnostic: the same call
        # works on desktop (Vulkan texture uploads) and in the web runtime
        # (pixels streamed via the resource drain channel). In browser builds
        # the glTF assets must be bundled alongside the game; when they're
        # missing ``import_gltf`` returns an empty Node3D and the viewer
        # shows just the lit backdrop.
        self._load_model()

        # Bottom controls strip: anchored so it tracks the viewport on resize.
        hint = Label("Drag: orbit    Scroll: zoom    Esc: quit", name="Hint")
        hint.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
        hint.margin_left = 12.0
        hint.margin_bottom = 34.0
        hint.font_size = 15.0
        self.add_child(hint)

        self._update_camera()

    def _load_model(self) -> None:
        # Desktop-only: download the Khronos sample if it isn't cached.
        # ``urllib`` isn't available under Pyodide by default, so skip the
        # fetch in browser builds: the user must bundle assets themselves.
        from simvx.graphics.assets.scene_import import import_gltf

        if sys.platform != "emscripten":
            _download_assets()

        # ``Resource.path`` resolves the package handle through
        # importlib.resources to a real filesystem path the glTF parser can
        # open. Sibling .bin / .png files referenced from inside the .gltf
        # are picked up relative to that path automatically.
        model = import_gltf(str(MODEL_GLTF.path))
        model.name = "Model"
        self.add_child(model)
        self._frame(model)

    def _frame(self, model) -> None:
        """Point the orbit camera at ``model`` and pull back far enough to see it.

        The near and far planes move with it: a 20 cm object framed from 30 cm
        away needs a near plane a good deal closer than the 10 cm a
        person-scale scene wants, and clipping it away looks like a model that
        failed to load.
        """
        radius = _bounding_radius(model)
        if radius <= 0.0:
            return
        # Distance at which a sphere of that radius exactly fills the vertical
        # field of view, plus the margin.
        fit = radius / math.sin(math.radians(self._cam.fov) * 0.5)
        self._target = tuple(float(c) for c in model.world_position)
        self._distance = fit * _FRAME_MARGIN
        self._min_distance = radius * 1.05
        self._max_distance = fit * 8.0
        self._cam.near = radius * 0.01
        self._cam.far = self._max_distance + radius * 4.0

    def on_update(self, dt):
        # Auto-rotate
        if self._auto_rotate:
            self._yaw += 20.0 * dt

        # Mouse drag orbit (left button = mouse_1)
        if Input.is_mouse_button_pressed(MouseButton.LEFT):
            delta = Input.mouse_delta
            dx, dy = float(delta.x), float(delta.y)
            if abs(dx) > 0.1 or abs(dy) > 0.1:
                self._auto_rotate = False
                self._yaw -= dx * 0.3
                self._pitch += dy * 0.3
                self._pitch = max(-89.0, min(89.0, self._pitch))

        # Scroll zoom, in proportion to the distance: a fixed step is either
        # imperceptible on a large model or a jump past a small one.
        scroll = Input.scroll_delta
        if scroll[1] != 0.0:
            self._distance *= 0.9 ** scroll[1]
            self._distance = max(self._min_distance, min(self._max_distance, self._distance))

        # Escape to quit
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return

        self._update_camera()

    def _update_camera(self):
        yaw_rad = math.radians(self._yaw)
        pitch_rad = math.radians(self._pitch)
        cp = math.cos(pitch_rad)
        x = self._target[0] + self._distance * cp * math.sin(yaw_rad)
        y = self._target[1] + self._distance * math.sin(pitch_rad)
        z = self._target[2] + self._distance * cp * math.cos(yaw_rad)
        self._cam.position = (x, y, z)
        self._cam.look_at(self._target)


def _bounding_radius(model) -> float:
    """Distance from ``model``'s own origin to the furthest vertex under it.

    A radius rather than a box, because it is what an orbit camera needs and
    because rotation cannot change it: every mesh under the model contributes
    its own bounding radius, scaled by that node's world scale and offset by
    how far the node sits from the model's origin. Returns 0.0 for a model
    that carries no mesh at all, which is what a failed import produces.
    """
    origin = tuple(float(c) for c in model.world_position)
    radius = 0.0
    stack = [model]
    while stack:
        node = stack.pop()
        stack.extend(node.children)
        mesh = getattr(node, "mesh", None)
        if mesh is None:
            continue
        scale = max(abs(float(c)) for c in node.world_scale)
        offset = math.dist(tuple(float(c) for c in node.world_position), origin)
        radius = max(radius, offset + scale * mesh.bounding_radius())
    return radius


def _selftest() -> bool:
    """Headless check: the model resolves, imports, and reaches the screen.

    The claim under test is the whole asset path, which is the part of this
    example a reader is most likely to copy: a ``Resource`` handle resolved
    through ``importlib.resources``, backed by a fetch into a per-user cache
    when the model is not beside this file. So the fetch runs first, and what
    the viewer built from it is then read back off the scene it drew.

    The model is third-party and is not part of the installed library, so this
    needs one of three things: a copy beside this file, a cache warmed by an
    earlier run, or the network. With none of them the question was never put
    to the code, which is what ``Unsupported`` reports.
    """
    from urllib.error import HTTPError, URLError

    from simvx.core import MeshInstance3D
    from simvx.core.testing.selftest import Unsupported
    from simvx.graphics.testing import assert_not_blank, save_png

    try:
        _download_assets()
    except HTTPError:
        # The server answered and refused: the fetch path itself is wrong.
        raise
    except URLError as exc:
        raise Unsupported(
            f"the BoomBox sample is neither beside this file nor cached, and it cannot be fetched: {exc.reason}"
        ) from exc

    app = App(title="Model Viewer: BoomBox", width=1280, height=720, visible=False)
    scene = ModelViewer(name="ModelViewer")
    frames = app.run_headless(scene, frames=8, capture_frames=[7])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/model_viewer_test.png")

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    check(
        "the Resource handle resolves to a file on disk",
        Path(MODEL_GLTF.path).is_file(),
        str(MODEL_GLTF.path),
    )

    model = next((child for child in scene.children if child.name == "Model"), None)
    check(
        "import_gltf hangs the model off the viewer",
        model is not None,
        f"children: {[c.name for c in scene.children]}",
    )

    # An empty Node3D is what import_gltf returns when it finds nothing to
    # import, and it draws exactly like a successful import of an empty file.
    meshes = []
    stack = [model] if model is not None else []
    while stack:
        node = stack.pop()
        if isinstance(node, MeshInstance3D) and node.mesh is not None:
            meshes.append(node)
        stack.extend(node.children)
    check(
        "and the model it built carries mesh geometry",
        bool(meshes),
        f"{len(meshes)} MeshInstance3D with a mesh under it",
    )

    # The framing is what makes the viewer independent of the model's scale:
    # this sample is about 20 cm across, so an orbit distance left at the
    # person-scale default would put the camera 15 model-widths away and draw
    # a speck. Assert the camera sits within a few radii of the model.
    radius = _bounding_radius(model) if model is not None else 0.0
    check(
        "the camera is framed on the model rather than on a fixed distance",
        0.0 < radius and radius < scene._distance < radius * 6.0,
        f"radius {radius:.4f}, orbit distance {scene._distance:.4f}",
    )

    print("screenshot: /tmp/model_viewer_test.png")
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    if "--test" in sys.argv:
        from simvx.core.testing.selftest import run_selftest

        sys.exit(run_selftest(_selftest))
    app = App(title="Model Viewer: BoomBox", width=1280, height=720)
    app.run(ModelViewer())