Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

10.3 KB
Raw Blame
"""Regenerate a character's crossSections.ts at a MEASURED per-node spoke budget (PIPELINE.md Stage 1).

WHY THIS SCRIPT EXISTS AT ALL. A hand-authored cross-sections file has no recorded density, so a
question like "is the triangle count too low" is unanswerable -- nothing can be re-run at a different
density to see whether the gap matters. It is a generator, not an artifact, on purpose.

ADAPTED FOR img2threejs (opt-in integration): this script's own location is no longer the showcase repo
root -- it lives in integrations/glb_character_pipeline/python/ inside the img2threejs tool repo. Every
showcase-side path resolves against IMG2THREEJS_SHOWCASE_ROOT, and every character-specific input --
which GLB, which node belongs to which region, and the final spoke count per node -- comes from
CHARACTER_* env vars / JSON config files, never hardcoded here, so the same script serves every
character.

THE BUDGET IS MEASURED, NOT CHOSEN, AND THIS SCRIPT DOES NOT MEASURE IT FOR YOU. Run
measure_density_convergence.py against each node first, read its printed convergence/density tables,
and decide the final per-node spoke count by hand: min(convergence, density), raised only where a
material-patch boundary genuinely needs finer cutting (a patch can only be cut along the (ring, spoke)
lattice). Put the RESULT of that judgment in CHARACTER_SPOKES_JSON as a plain {"<node>": <spokes>} map.
"Measured, not assumed" means a human/agent reads the actual error numbers for THIS character's own
GLB -- reusing another character's numbers, or a formula that skips reading them, is exactly the
mistake this script exists to prevent. See PIPELINE.md Stage 1 for the two failure modes measured on
girl-character (spokes under-sampled at low counts; naively maximising spokes bulges nodes whose point
density can't support them).

SLICES = 40 is carried over as a starting default from girl-character's own measurement (error against
a 320-slice-thin reference is U-shaped: worse at both 20 and 160 slices, best near 40, because a
thinner band holds fewer points and its per-bin percentile turns to sampling noise). Re-measure it with
measure_density_convergence.py for a new character if its proportions differ enough that this might not
hold; override via CHARACTER_SLICES.

UV IS LEFT EMPTY HERE ON PURPOSE. Populating real UVs from a baseline GLB's own texture atlas is a
separate, explicitly-gated step (bake_atlas_uvs.py) that departs from img2threejs's normal no-baseline-
assets rule -- see that script's own docstring before reaching for it. The default path for a new
character is per-region procedural material colour, which needs no UV at all.
"""
from __future__ import annotations

import json
import os
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from slice_node import read_node_positions, slice_node  # noqa: E402

ROOT = Path(os.environ.get('IMG2THREEJS_SHOWCASE_ROOT', '.')).resolve()
SLICES = int(os.environ.get('CHARACTER_SLICES', '40'))

HEADER_TEMPLATE = '''/**
 * Horizontal cross-sections of every measured GLB node, as stacked rings in world space.
 *
 * Rings are radial outlines of the node's actual point cloud, one per cluster per height band,
 * resampled onto a fixed set of rays from each slice's centroid so ring i point k always joins ring
 * i+1 point k and the lofted walls come out untwisted. Per-node spoke count is MEASURED, not shared
 * globally -- see measure_density_convergence.py and PIPELINE.md Stage 1.
 *
 * `uv` is intentionally empty ([]) unless a separate, explicitly-gated bake_atlas_uvs.py pass filled
 * it in from a baseline GLB's own texture atlas -- see that script's own docstring before reaching for
 * it; the default path needs no UV at all.
 *
 * Generated by build_cross_sections.py (integrations/glb_character_pipeline/python/); regenerate
 * rather than edit by hand.
 */

/**
 * `node` is load-bearing, not provenance. A region can span several GLB nodes, and rings from
 * different nodes must never be lofted into one another.
 */
export type Ring = {
  readonly node: number;
  readonly y: number;
  readonly centroid: readonly [number, number];
  readonly points: readonly (readonly [number, number])[];
  readonly uv: readonly (readonly [number, number])[];
};
export type CrossSections = readonly Ring[];
'''


def region_rings(nodes: list[int], glb: Path, spokes: dict[int, int]) -> list[dict]:
    rings = []
    for node in nodes:
        data = slice_node(glb, node, SLICES, spokes[node])
        for ring in data["rings"]:
            rings.append({"node": node, **ring})
    # Canonical order is load-bearing, not tidiness: the loft chains each ring onto the nearest strand
    # tip below it in ARRIVAL order, so an unspecified emission order can change the mesh with no
    # geometry changing. Sorting by height, then centroid, makes the input deterministic.
    rings.sort(key=lambda r: (r["y"], r["node"], r["centroid"][0], r["centroid"][1]))
    return rings


def emit(rings: list[dict]) -> str:
    lines = []
    for r in rings:
        pts = ",".join(f"[{x},{z}]" for x, z in r["points"])
        lines.append(f'  {{ node: {r["node"]}, y: {r["y"]}, '
                     f'centroid: [{r["centroid"][0]}, {r["centroid"][1]}], points: [{pts}], uv: [] }},')
    return "\n".join(lines)


def bboxes(path: Path) -> dict[str, tuple]:
    """Region bounding boxes in x/z, parsed back out of the emitted numbers."""
    import re
    out, region = {}, None
    for line in path.read_text().splitlines():
        if line.startswith("export const "):
            region = line.split()[2].rstrip(":")
            out[region] = [1e9, -1e9, 1e9, -1e9]
        elif region and line.lstrip().startswith("{ node:"):
            for x, z in re.findall(r"\[(-?[\d.]+),\s*(-?[\d.]+)\]", line.split("points: [")[1]):
                x, z, b = float(x), float(z), out[region]
                b[0], b[1] = min(b[0], x), max(b[1], x)
                b[2], b[3] = min(b[2], z), max(b[3], z)
    return {k: tuple(v) for k, v in out.items()}


def cloud_bboxes(region_nodes: dict[str, list[int]], glb: Path) -> dict[str, tuple]:
    """The same boxes taken from the GLB's own vertices -- the only ground truth available."""
    out = {}
    for region, nodes in region_nodes.items():
        x0 = z0 = 1e9
        x1 = z1 = -1e9
        for node in nodes:
            positions, _ = read_node_positions(glb, node)
            xs, zs = positions[0::3], positions[2::3]
            x0, x1 = min(x0, min(xs)), max(x1, max(xs))
            z0, z1 = min(z0, min(zs)), max(z1, max(zs))
        out[f"{region}_SECTIONS"] = (x0, x1, z0, z1)
    return out


def verify_frozen(target: Path, glb: Path, previous: Path, region_nodes: dict[str, list[int]]) -> int:
    """Did raising the spoke count CHANGE the dimensions, or shrink the sampling error?

    Comparing the new file against the old one cannot answer that: the old file is the coarser
    measurement, not ground truth, and wide angular bins are SUPPOSED to cut the corners off an
    extremity. The vertices are the authority. A freeze holds when every region's box sits closer to
    the point cloud than it did before, and overshoot past the cloud stays small.
    """
    truth, before, after = cloud_bboxes(region_nodes, glb), bboxes(previous), bboxes(target)
    failed = []
    print(f"{'region':20s}{'was':>10}{'now':>10}{'overshoot':>12}")
    for region, t in truth.items():
        b, a = before[region], after[region]
        eb = sum(abs(p - q) for p, q in zip(b, t)) / 4 * 1000
        ea = sum(abs(p - q) for p, q in zip(a, t)) / 4 * 1000
        over = max(a[1] - t[1], t[0] - a[0], a[3] - t[3], t[2] - a[2]) * 1000
        note = ""
        if ea > eb:
            note, _ = "  FAIL: further from the cloud", failed.append(
                f"{region}: bbox error rose {eb:.2f} -> {ea:.2f} mm")
        elif over > 5.0:
            note = "  overshoots the cloud"
        print(f"{region:20s}{eb:7.2f} mm{ea:7.2f} mm{over:+9.2f} mm{note}")
    if failed:
        print("\nFROZEN-DIMENSION CHECK FAILED:\n  " + "\n  ".join(failed))
        return 1
    print("\nFrozen dimensions hold: every region sits closer to its own point cloud than before, so "
          "the boxes grew toward the surface rather than being resized.")
    return 0


def main() -> int:
    glb = Path(os.environ.get('CHARACTER_GLB', str(ROOT / 'public/mesh/girl-character-baseline.glb')))
    target = Path(os.environ.get('CHARACTER_CROSS_SECTIONS', str(ROOT / 'work/crossSections.ts')))

    regions_path = os.environ.get('CHARACTER_SECTION_REGIONS_JSON')
    spokes_path = os.environ.get('CHARACTER_SPOKES_JSON')
    if not regions_path or not spokes_path:
        print("CHARACTER_SECTION_REGIONS_JSON and CHARACTER_SPOKES_JSON must both be set -- see PIPELINE.md "
              "Stage 1 and configs/example.env. Neither is auto-derived; both are a measured, "
              "per-character decision.", file=sys.stderr)
        return 1

    node_region: dict[int, str] = {int(k): v for k, v in
                                    json.loads(Path(regions_path).read_text()).items()}
    spokes: dict[int, int] = {int(k): v for k, v in json.loads(Path(spokes_path).read_text()).items()}
    region_nodes: dict[str, list[int]] = {}
    for node, region in sorted(node_region.items()):
        region_nodes.setdefault(region, []).append(node)

    if "--verify-frozen" in sys.argv:
        return verify_frozen(target, glb, Path(sys.argv[sys.argv.index("--verify-frozen") + 1]),
                              region_nodes)

    body = [HEADER_TEMPLATE]
    total_rings = total_points = 0
    for region, nodes in region_nodes.items():
        rings = region_rings(nodes, glb, spokes)
        points = sum(len(r["points"]) for r in rings)
        total_rings += len(rings)
        total_points += points
        spoke_note = ", ".join(f"node {n} at {spokes[n]}" for n in nodes)
        body.append(f"\n/**\n * {len(rings)} rings, {points} ring points, from node(s) "
                    f"{nodes}.\n * Spokes: {spoke_note}.\n */\n"
                    f"export const {region}_SECTIONS: CrossSections = [\n{emit(rings)}\n];")
        print(f"  {region:12s} {len(rings):4d} rings  {points:7d} points  ({spoke_note})")

    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text("\n".join(body) + "\n")
    size = target.stat().st_size
    print(f"\n{total_rings} rings, {total_points} ring points, {size / 1e6:.2f} MB -> {target}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())