meshshader-engine 0.2.0__py3-none-any.whl

meshshader_engine/__init__.py

@@ -0,0 +1,12 @@
+"""MeshShaderEngine: a didactic engine for classical and
+NVIDIA mesh-shader render paths.
+
+The package wraps PyOpenGL boilerplate and gives students a small,
+explicit interface made of TOML configuration, shader files, and
+optional model animation. Importing this package must not trigger any
+OpenGL or display side effects.
+"""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

meshshader_engine/__main__.py

@@ -0,0 +1,6 @@
+"""Allows invocation via ``python -m meshshader_engine``."""
+
+from meshshader_engine.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

meshshader_engine/application.py

@@ -0,0 +1,278 @@
+"""Application loop: connects window, mouse input, scene state, and
+render path.
+
+This module is the only place that registers ``glfw`` input callbacks
+and thereby binds the pure, window-system-independent
+:class:`~meshshader_engine.camera.OrbitCamera` to actual mouse events.
+The interaction sensitivities
+(``_ORBIT_SENSITIVITY_RAD_PER_PIXEL``, ``_SCROLL_ZOOM_SENSITIVITY``,
+``_DRAG_ZOOM_SENSITIVITY_PER_PIXEL``) are engine constants, not
+configuration values -- only *whether* orbit/zoom are active is
+configurable via ``interaction.orbit_enabled``/``zoom_enabled`` (see
+README, section "TOML reference").
+
+``run_experiment`` blocks until the window is closed and is therefore
+deliberately not covered by automated tests (a test would either have
+to run forever or artificially interrupt the event loop, without
+still being meaningful). The individual building blocks (camera,
+SceneState, ``ClassicBackend``, ``MeshNVBackend``, ``gl.context.window``)
+are already tested independently; the backend choice itself is a
+simple dictionary lookup via ``_RENDER_BACKENDS``, whose keys exactly
+match the ``pipeline.backend`` values already validated in
+``config.py``. The effect-applying part of the mouse callbacks
+(``_apply_orbit_delta``, ``_apply_zoom_delta``) is factored out as a
+pure function so that the acceptance criterion "disabled interaction
+produces no unexpected input effects" (PLAN_SHADER_ENGINE.md, Phase 13)
+is testable without a real context -- only the glfw callback
+registration itself remains untested and is kept correspondingly
+small.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from meshshader_engine.camera import OrbitCamera
+from meshshader_engine.config import ExperimentConfig
+from meshshader_engine.gl.backends.classic import ClassicBackend
+from meshshader_engine.gl.backends.mesh_nv import MeshNVBackend
+from meshshader_engine.gl.context import window
+from meshshader_engine.scene_state import SceneState
+
+__all__ = ["run_experiment"]
+
+# Backend selection via pipeline.backend (see config.py,
+# _ALLOWED_BACKENDS -- already validated there against exactly these
+# two values, so a KeyError here would be an internal consistency bug,
+# not a user error).
+_RENDER_BACKENDS = {"classic": ClassicBackend, "mesh_nv": MeshNVBackend}
+
+_ORBIT_SENSITIVITY_RAD_PER_PIXEL = 0.005
+_SCROLL_ZOOM_SENSITIVITY = 0.5
+_DRAG_ZOOM_SENSITIVITY_PER_PIXEL = 0.02
+
+
+class _MouseState:
+    """Pure state of the last known mouse position and button status."""
+
+    def __init__(self) -> None:
+        self.orbit_dragging = False
+        self.zoom_dragging = False
+        self.last_x = 0.0
+        self.last_y = 0.0
+
+
+def _apply_orbit_delta(
+    camera: OrbitCamera, dx: float, dy: float, *, enabled: bool
+) -> None:
+    """Apply a mouse-movement delta as an orbit, if ``enabled``.
+
+    Pure function with no glfw/GL dependency: with ``enabled=False``,
+    ``camera`` is not touched at all, instead of merely being called
+    with a delta of 0 -- this makes "no unexpected input effects" when
+    interaction is disabled directly testable.
+
+    ``dy`` is a GLFW screen-coordinate delta (Y grows downward), while
+    ``OrbitCamera.orbit`` expects a world-space elevation delta (Y
+    grows upward, see ``math3d.py``). The sign of ``dy`` is therefore
+    NOT flipped: dragging upward (``dy`` negative in screen
+    coordinates) should lower the camera (negative elevation change)
+    -- the familiar "trackball" feel, where the front edge of the
+    object follows the mouse movement instead of running opposite to
+    it.
+    """
+    if enabled:
+        camera.orbit(
+            -dx * _ORBIT_SENSITIVITY_RAD_PER_PIXEL,
+            dy * _ORBIT_SENSITIVITY_RAD_PER_PIXEL,
+        )
+
+
+def _apply_zoom_delta(
+    camera: OrbitCamera, delta: float, *, enabled: bool, sensitivity: float
+) -> None:
+    """Apply a zoom delta, if ``enabled``.
+
+    Pure function, shared by scroll-wheel and right-click-drag zoom
+    (see :func:`run_experiment`); the two input sources have very
+    different magnitudes (scroll "notches" vs. screen pixels), hence
+    the explicit ``sensitivity`` parameter instead of a shared
+    constant.
+    """
+    if enabled:
+        camera.zoom(-delta * sensitivity)
+
+
+def _apply_resize(
+    camera: OrbitCamera, viewport_size: list[float], width: int, height: int
+) -> None:
+    """Update the camera aspect ratio and viewport size on a resize
+    event.
+
+    Pure function with no GL call (the actual ``glViewport()`` call
+    stays in the callback in :func:`run_experiment`). Non-positive
+    sizes (e.g. when minimizing the window under some window managers)
+    are silently ignored instead of raising an error --
+    ``OrbitCamera.set_viewport`` itself would raise a ``ValueError``
+    for that, which would crash a window handler.
+
+    Parameters
+    ----------
+    camera : meshshader_engine.camera.OrbitCamera
+    viewport_size : list[float]
+        Two-element list ``[width, height]``, updated in place (not a
+        tuple, since the caller must keep the current value across
+        frames).
+    width, height : int
+        New framebuffer size in pixels.
+    """
+    if width <= 0 or height <= 0:
+        return
+    camera.set_viewport(width, height)
+    viewport_size[0] = float(width)
+    viewport_size[1] = float(height)
+
+
+def run_experiment(config: ExperimentConfig, *, visible: bool = True) -> None:
+    """Run an experiment interactively in a window (blocking).
+
+    Left-click-drag orbits the camera (if ``interaction.orbit_enabled``).
+    Zoom (if ``interaction.zoom_enabled``) is possible in two ways, so
+    it also works on notebooks without a scroll wheel: scrolling, or
+    right-click-drag up/down (up = move closer, down = move farther --
+    symmetric to scrolling up/forward). Disabled interaction is already
+    checked in the respective callbacks before ``OrbitCamera.orbit``/
+    ``zoom`` is called -- no mouse events are then forwarded to the
+    camera at all.
+
+    Parameters
+    ----------
+    config : meshshader_engine.config.ExperimentConfig
+    visible : bool
+        Whether the window is created visibly. Default ``True`` for
+        real use via ``mse run``; Level B tests (see
+        ``tests/integration``) set ``False`` to check the success path
+        without a flashing window.
+
+    Raises
+    ------
+    GraphicsContextError
+        If no OpenGL context can be created, or (only for
+        ``pipeline.backend = "mesh_nv"``) if ``GL_NV_mesh_shader`` is
+        not available.
+    ShaderCompilationError
+        If the configured shaders fail to compile/link, or violate the
+        shader ABI.
+    """
+    import glfw
+
+    camera = OrbitCamera.from_config(config.camera, config.interaction)
+    scene = SceneState.from_config(config.light, config.animation, camera)
+    mouse = _MouseState()
+
+    with window(
+        width=config.window.width,
+        height=config.window.height,
+        title=config.window.title,
+        debug=True,
+        visible=visible,
+    ) as handle:
+        camera.set_viewport(handle.width, handle.height)
+        viewport_size = [float(handle.width), float(handle.height)]
+
+        backend_factory = _RENDER_BACKENDS[config.pipeline.backend]
+        backend = backend_factory(config)
+        messenger = None
+        if handle.debug_context:
+            from meshshader_engine.gl.debug import DebugMessenger
+
+            messenger = DebugMessenger()
+
+        def _on_cursor_pos(_glfw_window: Any, x: float, y: float) -> None:
+            dx = x - mouse.last_x
+            dy = y - mouse.last_y
+            if mouse.orbit_dragging:
+                _apply_orbit_delta(
+                    camera, dx, dy, enabled=config.interaction.orbit_enabled
+                )
+            if mouse.zoom_dragging:
+                # Dragging upward (dy < 0 in screen coordinates) should
+                # zoom in, see the run_experiment docstring; hence -dy.
+                _apply_zoom_delta(
+                    camera,
+                    -dy,
+                    enabled=config.interaction.zoom_enabled,
+                    sensitivity=_DRAG_ZOOM_SENSITIVITY_PER_PIXEL,
+                )
+            mouse.last_x = x
+            mouse.last_y = y
+
+        def _on_mouse_button(
+            _glfw_window: Any, button: int, action: int, _mods: int
+        ) -> None:
+            if button == glfw.MOUSE_BUTTON_LEFT:
+                mouse.orbit_dragging = action == glfw.PRESS
+            elif button == glfw.MOUSE_BUTTON_RIGHT:
+                mouse.zoom_dragging = action == glfw.PRESS
+
+        def _on_scroll(
+            _glfw_window: Any, _x_offset: float, y_offset: float
+        ) -> None:
+            _apply_zoom_delta(
+                camera,
+                y_offset,
+                enabled=config.interaction.zoom_enabled,
+                sensitivity=_SCROLL_ZOOM_SENSITIVITY,
+            )
+
+        def _on_framebuffer_size(
+            _glfw_window: Any, fb_width: int, fb_height: int
+        ) -> None:
+            _apply_resize(camera, viewport_size, fb_width, fb_height)
+            if fb_width > 0 and fb_height > 0:
+                from OpenGL.GL import glViewport
+
+                glViewport(0, 0, fb_width, fb_height)
+
+        glfw.set_cursor_pos_callback(handle.glfw_window, _on_cursor_pos)
+        glfw.set_mouse_button_callback(handle.glfw_window, _on_mouse_button)
+        glfw.set_scroll_callback(handle.glfw_window, _on_scroll)
+        glfw.set_framebuffer_size_callback(
+            handle.glfw_window, _on_framebuffer_size
+        )
+
+        from OpenGL.GL import (
+            GL_COLOR_BUFFER_BIT,
+            GL_DEPTH_BUFFER_BIT,
+            GL_DEPTH_TEST,
+            glClear,
+            glClearColor,
+            glEnable,
+        )
+
+        # Depth testing (z-buffering): each fragment's depth is compared
+        # against the per-pixel depth buffer so that nearer geometry
+        # correctly occludes farther geometry, regardless of draw order.
+        glEnable(GL_DEPTH_TEST)
+        glClearColor(0.1, 0.1, 0.12, 1.0)
+
+        start_time = time.perf_counter()
+        try:
+            while not glfw.window_should_close(handle.glfw_window):
+                scene.time_seconds = time.perf_counter() - start_time
+                # Polling instead of an additional file watcher (see
+                # PLAN_SHADER_ENGINE.md, Phase 21, task 1); a failed
+                # reload logs itself and leaves the current program
+                # untouched (task 3).
+                backend.reload_shaders_if_changed()
+                glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
+                backend.draw(
+                    scene, viewport_size=(viewport_size[0], viewport_size[1])
+                )
+                glfw.swap_buffers(handle.glfw_window)
+                glfw.poll_events()
+        finally:
+            if messenger is not None:
+                messenger.close()
+            backend.close()

meshshader_engine/assets/__init__.py

@@ -0,0 +1,107 @@
+"""Geometry generation and vertex data model.
+
+Covers the shared ``MeshData`` contract, procedural primitives
+(plane/cube), pre-built assets loaded from disk (teapot/bunny/a
+student's custom mesh), and meshlet partitioning for the mesh-shader
+render path.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Final
+
+from meshshader_engine.assets.bunny import load_bunny
+from meshshader_engine.assets.mesh_data import MeshData
+from meshshader_engine.assets.primitives import build_cube, build_plane
+from meshshader_engine.assets.serialization import load_mesh_data
+from meshshader_engine.assets.teapot import load_teapot
+from meshshader_engine.errors import MeshDataError
+
+__all__ = ["OBJECT_BUILDERS", "build_object", "load_custom_mesh"]
+
+#: ``object.type`` (see :mod:`meshshader_engine.config`) -> a
+#: zero-argument builder producing its ``MeshData``. Covers every
+#: built-in object type; ``"custom"`` is handled separately by
+#: :func:`build_object`, since it additionally needs a path. Single
+#: source of truth shared by both render-path backends
+#: (:mod:`meshshader_engine.gl.backends.classic`,
+#: :mod:`meshshader_engine.gl.backends.mesh_nv`), which both need to
+#: build the same object regardless of which backend renders it --
+#: keeping one copy here instead of one per backend avoids the two
+#: falling out of sync if a new object type is ever added.
+OBJECT_BUILDERS: Final[dict[str, Callable[[], MeshData]]] = {
+    "plane": build_plane,
+    "cube": build_cube,
+    "teapot": load_teapot,
+    "bunny": load_bunny,
+}
+
+
+def load_custom_mesh(path: Path) -> MeshData:
+    """Load a student-provided custom mesh.
+
+    The file must already be in the engine's versioned ``MeshData``
+    ``.npz`` format (see :mod:`meshshader_engine.assets.serialization`)
+    -- produced ahead of time from a student's OBJ file by
+    ``tools/import_mesh.py`` (see README, section "Custom Student
+    Meshes"). This function does no format conversion itself, exactly
+    like :func:`meshshader_engine.assets.teapot.load_teapot`/
+    :func:`meshshader_engine.assets.bunny.load_bunny`.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Already-resolved path to the ``.npz`` file (see
+        :mod:`meshshader_engine.config`, "Path safety").
+
+    Returns
+    -------
+    MeshData
+
+    Raises
+    ------
+    MeshDataError
+        If the file is missing (names the exact ``tools/import_mesh.py``
+        invocation to fix it) or invalid (see
+        :func:`meshshader_engine.assets.serialization.load_mesh_data`).
+    """
+    if not path.exists():
+        raise MeshDataError(
+            f"Custom mesh not found: {path}. Convert your OBJ file first "
+            f"with 'python tools/import_mesh.py <model.obj> {path}' (see "
+            "README, section 'Custom Student Meshes')."
+        )
+    return load_mesh_data(path)
+
+
+def build_object(object_type: str, mesh_path: Path | None = None) -> MeshData:
+    """Build or load the ``MeshData`` for one ``[object]`` entry,
+    regardless of whether it is procedural, a pre-built engine asset,
+    or a student's custom mesh.
+
+    Deliberately takes plain parameters rather than a
+    :class:`meshshader_engine.config.ObjectConfig`, so this module
+    stays importable and testable without depending on
+    :mod:`meshshader_engine.config` (same reasoning as
+    :func:`meshshader_engine.assets.texture_image.decode_texture_image`).
+
+    Parameters
+    ----------
+    object_type : str
+        One of the keys in :data:`OBJECT_BUILDERS`, or ``"custom"``.
+    mesh_path : pathlib.Path or None
+        Required if and only if ``object_type == "custom"`` (already
+        enforced by :mod:`meshshader_engine.config`, so a violation
+        here would be an internal consistency bug, not a user error --
+        see the ``assert`` below).
+
+    Returns
+    -------
+    MeshData
+    """
+    if object_type == "custom":
+        assert mesh_path is not None  # already guaranteed by config.py
+        return load_custom_mesh(mesh_path)
+    return OBJECT_BUILDERS[object_type]()

meshshader_engine/assets/bunny.py

@@ -0,0 +1,46 @@
+"""Loading the Stanford Bunny from the pre-built asset.
+
+Like the teapot (see :mod:`meshshader_engine.assets.teapot`), the
+bunny is not generated procedurally but loaded from a file that
+``tools/build_assets.py`` generates once from the official Stanford
+source -- see README, section "Assets", for provenance and license
+terms (notably: research/educational use and free redistribution are
+permitted, commercial use is not, without Stanford's permission --
+unlike this engine's own GPLv3 license).
+
+At 34,834 vertices / 69,451 triangles (after dropping the source's
+1,113 unreferenced vertices, see ``tools/build_assets.py``), this is
+by far the highest-resolution object the engine ships, meant to make
+meshlet partitioning (:mod:`meshshader_engine.assets.meshlets`)
+visibly more interesting than the teapot's ~40 meshlets.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Final
+
+from meshshader_engine.assets.mesh_data import MeshData
+from meshshader_engine.assets.serialization import _load_prebuilt_asset
+
+__all__ = ["BUNNY_ASSET_PATH", "load_bunny"]
+
+#: Location of the pre-built bunny asset (see ``tools/build_assets.py``).
+BUNNY_ASSET_PATH: Final[Path] = Path(__file__).parent / "data" / "bunny.npz"
+
+
+def load_bunny() -> MeshData:
+    """Load the pre-built Stanford Bunny geometry.
+
+    Returns
+    -------
+    MeshData
+
+    Raises
+    ------
+    MeshDataError
+        If the asset is missing (generate it with
+        ``python tools/build_assets.py``, see README, section
+        "Assets") or invalid.
+    """
+    return _load_prebuilt_asset(BUNNY_ASSET_PATH, "Bunny")

meshshader_engine/assets/mesh_data.py

@@ -0,0 +1,188 @@
+"""Immutable, validated vertex data model for triangulated meshes.
+
+Data conventions (see ``PLAN_SHADER_ENGINE.md``, section 4.4, and
+README, section "Vertex layout"):
+
+- ``positions``: ``float32[N, 3]``, object-space (local/model-space)
+  position -- i.e. before the ``mse_Model`` transform; only becomes a
+  world-space position once multiplied by it in the shader (see
+  README, section "Coordinate Spaces for Lighting").
+- ``normals``: ``float32[N, 3]``, row-wise unit vectors.
+- ``uvs``: ``float32[N, 2]``, texture coordinates (no value range is
+  enforced, since repeating/tiled UVs outside [0, 1] are allowed).
+- ``tangents``: ``float32[N, 4]``; ``tangents[:, :3]`` is row-wise
+  normalized, ``tangents[:, 3]`` holds the handedness (exactly +1 or
+  -1). The bitangent is NOT stored, but reconstructed in the shader:
+  ``bitangent = cross(normal, tangent.xyz) * tangent.w``.
+- ``indices``: ``uint32[M]`` with ``M % 3 == 0`` (a plain triangle
+  list, no fans/strips); every value lies in ``[0, N)``.
+- Right-handed coordinate system, consistent with
+  :mod:`meshshader_engine.math3d`; triangles are wound
+  counter-clockwise (CCW) when viewed from the front (i.e. from the
+  direction the normal points).
+
+``MeshData`` fully validates this contract in ``__post_init__`` and
+then locks all referenced NumPy arrays against writes
+(``flags.writeable = False``), so that a once-constructed instance
+can no longer be accidentally mutated even via a shared array
+reference.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from meshshader_engine.errors import MeshDataError
+
+__all__ = ["MeshData"]
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class MeshData:
+    """Triangulated, fully validated vertex data model.
+
+    ``eq=False`` because the default comparison generated by
+    ``@dataclass`` would compare NumPy arrays element-wise, raising a
+    ``ValueError`` ("truth value of an array is ambiguous"); instance
+    identity is sufficient for this model.
+
+    Attributes
+    ----------
+    positions : numpy.ndarray
+        Vertex positions, shape (N, 3), dtype float32.
+    normals : numpy.ndarray
+        Unit normals, shape (N, 3), dtype float32.
+    uvs : numpy.ndarray
+        Texture coordinates, shape (N, 2), dtype float32.
+    tangents : numpy.ndarray
+        Tangents, shape (N, 4), dtype float32; see the module
+        docstring for the convention used for ``tangents[:, 3]``
+        (handedness).
+    indices : numpy.ndarray
+        Triangle index list, shape (M,) with M % 3 == 0, dtype
+        uint32.
+
+    Raises
+    ------
+    MeshDataError
+        If any array violates shape, dtype, value range (finite
+        values, normalized normals/tangents, valid handedness), or
+        index bounds.
+    """
+
+    positions: np.ndarray
+    normals: np.ndarray
+    uvs: np.ndarray
+    tangents: np.ndarray
+    indices: np.ndarray
+
+    def __post_init__(self) -> None:
+        _validate(self)
+        for array in (
+            self.positions,
+            self.normals,
+            self.uvs,
+            self.tangents,
+            self.indices,
+        ):
+            array.flags.writeable = False
+
+    @property
+    def vertex_count(self) -> int:
+        """Number of vertices (rows in ``positions``)."""
+        return self.positions.shape[0]
+
+    @property
+    def triangle_count(self) -> int:
+        """Number of triangles (``len(indices) // 3``)."""
+        return self.indices.shape[0] // 3
+
+
+# --- Internal validation -----------------------------------------------------
+
+
+def _validate(mesh: MeshData) -> None:
+    _require_float_array(mesh.positions, "positions", ncols=3)
+    _require_float_array(mesh.normals, "normals", ncols=3)
+    _require_float_array(mesh.uvs, "uvs", ncols=2)
+    _require_float_array(mesh.tangents, "tangents", ncols=4)
+
+    n = mesh.positions.shape[0]
+    if n == 0:
+        raise MeshDataError("positions: must not be empty")
+    for name, array in (
+        ("normals", mesh.normals),
+        ("uvs", mesh.uvs),
+        ("tangents", mesh.tangents),
+    ):
+        if array.shape[0] != n:
+            raise MeshDataError(
+                f"{name}: expected {n} rows (like positions), got: "
+                f"{array.shape[0]}"
+            )
+
+    _require_unit_rows(mesh.normals, "normals")
+    _require_unit_rows(mesh.tangents[:, :3], "tangents[:, :3]")
+
+    handedness = mesh.tangents[:, 3]
+    if not np.all(np.isclose(np.abs(handedness), 1.0, atol=1e-6)):
+        raise MeshDataError("tangents[:, 3] (handedness) must be +1 or -1")
+
+    _validate_indices(mesh.indices, vertex_count=n)
+
+
+def _require_float_array(array: np.ndarray, name: str, *, ncols: int) -> None:
+    if not isinstance(array, np.ndarray):
+        raise MeshDataError(
+            f"{name}: must be a numpy.ndarray, got: {type(array).__name__}"
+        )
+    if array.dtype != np.float32:
+        raise MeshDataError(
+            f"{name}: expected dtype float32, got: {array.dtype}"
+        )
+    if array.ndim != 2 or array.shape[1] != ncols:
+        raise MeshDataError(
+            f"{name}: expected shape (N, {ncols}), got: shape={array.shape}"
+        )
+    if not np.all(np.isfinite(array)):
+        raise MeshDataError(f"{name}: contains non-finite values (NaN/Inf)")
+
+
+def _require_unit_rows(
+    array: np.ndarray, name: str, *, atol: float = 1e-4
+) -> None:
+    norms = np.linalg.norm(array, axis=1)
+    if not np.all(np.isclose(norms, 1.0, atol=atol)):
+        bad_row = int(np.argmax(np.abs(norms - 1.0)))
+        raise MeshDataError(
+            f"{name}: must contain row-wise unit vectors; "
+            f"row {bad_row} has length {norms[bad_row]:.6f}"
+        )
+
+
+def _validate_indices(indices: np.ndarray, *, vertex_count: int) -> None:
+    if not isinstance(indices, np.ndarray):
+        raise MeshDataError(
+            f"indices: must be a numpy.ndarray, got: {type(indices).__name__}"
+        )
+    if indices.dtype != np.uint32:
+        raise MeshDataError(
+            f"indices: expected dtype uint32, got: {indices.dtype}"
+        )
+    if indices.ndim != 1:
+        raise MeshDataError(
+            f"indices: expected a 1D array, got: shape={indices.shape}"
+        )
+    if indices.shape[0] == 0 or indices.shape[0] % 3 != 0:
+        raise MeshDataError(
+            f"indices: length must be a positive multiple of 3, "
+            f"got: {indices.shape[0]}"
+        )
+    max_index = int(indices.max())
+    if max_index >= vertex_count:
+        raise MeshDataError(
+            f"indices: value {max_index} is outside the valid range "
+            f"[0, {vertex_count - 1}]"
+        )