harness.py

Part of Procedural Planets.

"""Procedural Planets: CPU-only harness.

Smoke test for the biome ramp, the quad-sphere mesh builder and the noise
rebuild budget, all without booting the GPU. Run with:

    uv run python examples/ports/procedural_planets/harness.py
"""

from __future__ import annotations

import sys
import time
from pathlib import Path

_PORT_DIR = Path(__file__).parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

import numpy as np  # noqa: E402
from nodes.colour import biome_percent_array, build_ramp_texture, default_colour_settings  # noqa: E402
from nodes.shape import (  # noqa: E402
    ShapeGenerator,
    default_shape_settings,
)
from nodes.terrain_face import FACE_DIRECTIONS, build_face_mesh  # noqa: E402


def _sphere_grid(direction, n: int) -> np.ndarray:
    up = np.asarray(direction, dtype=np.float32)
    axis_a = np.array([up[1], up[2], up[0]], dtype=np.float32)
    axis_b = np.cross(up, axis_a)
    coords = np.linspace(0.0, 1.0, n, dtype=np.float32) - 0.5
    yy, xx = np.meshgrid(coords, coords, indexing="ij")
    cube = (
        up[None, None, :]
        + (2.0 * xx)[..., None] * axis_a[None, None, :]
        + (2.0 * yy)[..., None] * axis_b[None, None, :]
    ).reshape(-1, 3)
    return cube / np.maximum(np.linalg.norm(cube, axis=1, keepdims=True), 1e-8)


def main() -> None:
    settings = default_shape_settings()
    colour = default_colour_settings()
    shape = ShapeGenerator(settings)

    # 1. Ramp texture builds at expected shape.
    ramp = build_ramp_texture(colour)
    assert ramp.shape == (4, 100, 4), ramp.shape
    assert ramp.dtype == np.uint8
    print(f"OK: ramp texture {ramp.shape} dtype={ramp.dtype}")

    # 2. Biome percent stays in [0, 1] for an arbitrary face.
    sphere = _sphere_grid((0, 1, 0), 32)
    pct = biome_percent_array(sphere, colour.biome)
    assert pct.min() >= 0.0 and pct.max() <= 1.0, (pct.min(), pct.max())
    print(f"OK: biome % range [{pct.min():.3f}, {pct.max():.3f}]")

    # 3. Quad-sphere mesh build matches expected vertex count + has UVs.
    for direction in FACE_DIRECTIONS:
        # Pre-flight pass to lock min/max BEFORE building the mesh, so UV.y maps cleanly.
        shape.calculate_unscaled_elevation(_sphere_grid(direction, 32))
    sample_mesh = build_face_mesh((0, 1, 0), 32, shape, colour.biome)
    assert sample_mesh.vertex_count == 32 * 32, sample_mesh.vertex_count
    assert sample_mesh.indices.size == 2 * 31 * 31 * 3, sample_mesh.indices.size
    assert sample_mesh.texcoords is not None
    assert sample_mesh.normals is not None
    print(f"OK: face mesh vertices={sample_mesh.vertex_count} tris={sample_mesh.indices.size // 3}")

    # 4. Timing report: a full six-face rebuild at 128², single-threaded. This is
    #    the budget the slider coalescing in main.py is sized against, so print it
    #    rather than assert a machine-specific threshold.
    n = 128
    shape = ShapeGenerator(settings)
    # Pass 1: preflight every face's elevation.
    for direction in FACE_DIRECTIONS:
        shape.calculate_unscaled_elevation(_sphere_grid(direction, n))
    t0 = time.perf_counter()
    for direction in FACE_DIRECTIONS:
        m = build_face_mesh(direction, n, shape, colour.biome)
        m.generate_normals()
    elapsed = (time.perf_counter() - t0) * 1000.0
    print(f"OK: 6-face rebuild at N={n}² took {elapsed:.1f} ms")

    print("harness OK")


if __name__ == "__main__":
    main()