Official Codebase of 3DCodeVerse
Python
frames gate: a hero that is in the scene but in no authored frame is measured (glb_frac mask render per GLB per camera) — D72
gaoypeng4a603ff9aa01
diff --git a/harness/codeverse/spatial/frame_metrics.py b/harness/codeverse/spatial/frame_metrics.pyindex a51590db..0a1f286e 100644--- a/harness/codeverse/spatial/frame_metrics.py+++ b/harness/codeverse/spatial/frame_metrics.py@@ -340,6 +340,62 @@ def _glb_findings(census: dict[str, Any]) -> list[GateFinding]:return out+HERO_MIN_FRAC = 0.005 # of the frame, best authored camera: below it no camera sees the hero+HERO_DETAIL_MIN_FRAC = 0.02 # of the frame, in the camera NAMED for the hero+++def _hero_key(url: str) -> str:+ """``/assets/longcase_clock.glb`` → ``longcaseclock`` (the plan's snake name, joined)."""+ return "".join(ch for ch in url.rsplit("/", 1)[-1].rsplit(".", 1)[0].lower() if ch.isalnum())+++def _hero_findings(checks: list[dict[str, Any]], census: dict[str, Any]) -> list[GateFinding]:+ """A Blender hero that is IN the scene but in no authored frame — or nearly absent from+ the camera named for it. ``camera_checks[].glb_frac`` (``glbCoverage``: a mask render+ per GLB per camera, occlusion included). cmp6's crypt (2026-09-09): the athanor stood+ behind a squat pillar in every authored shot, the judge called the HERO "a massive+ untextured grey box", and two refine rounds rebuilt the wrong thing — "in the scene"+ (``glb_assets``) was known, "in the frame" was not."""+ rows = census.get("glb_assets")+ if not isinstance(rows, list):+ return []+ authored = [c for c in checks if _view_kind(c) == "authored"]+ out: list[GateFinding] = []+ for r in rows:+ if not isinstance(r, dict) or not r.get("in_scene"):+ continue+ url = str(r.get("url", "?"))+ seen: dict[str, float] = {}+ for c in authored:+ fr = c.get("glb_frac")+ v = _num(fr, url) if isinstance(fr, dict) else None+ if v is not None:+ seen[str(c.get("name", "?"))] = v+ if not seen:+ continue # older census, or no authored camera+ base = url.rsplit("/", 1)[-1]+ best = max(seen.values())+ listing = ", ".join(f"{n} {v:.1%}" for n, v in list(seen.items())[:6])+ if best < HERO_MIN_FRAC:+ out.append(_f(Severity.ERROR, base,+ f"{base} is in the scene but fills at most {best:.1%} of any authored frame ({listing}) — "+ "no camera sees the hero",+ "aim the camera named for it at the hero's placement with a clear line of sight (a "+ "camera_target_blocked finding names what cuts it) or move the hero into a shot; a hero the "+ "frames never show cannot pass its must-have",+ kind="hero_unseen", url=url, best_frac=best, per_camera=seen))+ continue+ key = _hero_key(url)+ for cam, v in seen.items():+ if key and key in "".join(ch for ch in cam.lower() if ch.isalnum()) and v < HERO_DETAIL_MIN_FRAC:+ out.append(_f(Severity.WARN, cam,+ f"{cam} is named for {base} but shows it at {v:.1%} of the frame (its best view is {best:.1%})",+ "a detail shot fills 10-40% of the frame with its subject: move the camera closer along "+ "the sightline or clear what stands between",+ kind="hero_small_in_its_camera", url=url, frac=v, best_frac=best))+ return out++def frame_findings(metrics: dict[str, Any]) -> GateReport:"""``scene_frames`` gate from a ``metrics.json`` payload (``camera_checks`` + ``census`` + ``motion``)."""checks: list[dict[str, Any]] = [c for c in metrics.get("camera_checks") or [] if isinstance(c, dict)]@@ -360,6 +416,7 @@ def frame_findings(metrics: dict[str, Any]) -> GateReport:findings.append(cov)findings += _motion_findings(stored_motion(metrics))findings += _glb_findings(metrics.get("census") or {})+ findings += _hero_findings(checks, metrics.get("census") or {})if checks and not [f for f in findings if f.severity != Severity.INFO]:n = len(checks)findings.append(_f(Severity.INFO, "overall", f"{n} camera frame(s) checked: exposure, geometry and coverage within limits", "",diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.mdindex 4f99d3a8..d86330f4 100644--- a/harness/docs/DECISIONS.md+++ b/harness/docs/DECISIONS.md@@ -1173,6 +1173,25 @@ written) that were accepted because the code works that way and the tests pin itthe NaN is gone. Harness-owned starter geometry the agent edits, as `worldShell` and`roomShell` are; nothing here re-centres or grounds an authored object (L7).+* **D72 A camera and a hero are measured where they stand, not scene-wide (2026-09-09).** Four+ false or missing verdicts from one day's batteries, each repeated by the judge as a major issue+ and each costing a refine round: an "ant's-eye view" against the scene's HIGHEST ground (the+ lens was 1.6 m over a low patch of relief snow); a lens under the terrain whose frame rendered+ "fine" (a FrontSide terrain is back faces from beneath); a squat pillar 0.9 m before the hero+ camera, so the judge called the hidden HERO "a massive grey box"; and a hero that was in the+ scene but in no authored frame, which nothing could say. `nearGeometry` now measures per lens+ — the ray straight down (`ground_below_m`), the lowest terrain-scale ground surface straight+ above (`ground_above_m`, cast down from height so `material.side` cannot hide it), the sight rays+ ending within 1.5 m (`near_rays`) and the first surface on the eye → lookAt line+ (`target_hit_m`) — and `glbCoverage` renders each loaded GLB as a white mask against black solids+ per camera (`glb_frac`). The gate reads those: `camera_low` / `camera_high` under the lens,+ `camera_under_ground_mesh` (the repair lifts it to eye level), `camera_blocked` (≥ 6 of 9 near+ rays), `camera_target_blocked` (cut before half the distance; a close-up meets its own subject+ near the full distance), `hero_unseen` (< 0.5 % of every authored frame) and+ `hero_small_in_its_camera`. The rule behind all of it: a wrong deterministic finding is worse+ than none, because the judge repeats it — precision over recall, and every number names the+ surface it was measured against.+## Rejected / deferred* A versioned `Spec`/`RunRecord`/`RunState` load-normaliser (rejected 2026-08-30: of the sevendiff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 76aebabe..9114defe 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -269,6 +269,8 @@ frame_gate_from_renders(renders) -> GateReport # gate "scene_frames"; da# Δ camera_blocked (ERROR: ≥ 6 of the 9 sight rays end within near_limit_m 1.5) · camera_target_blocked (WARN: the line of# sight to the plan's lookAt is cut before half the distance, names the cutter) · camera_under_ground_mesh (WARN, ERROR# when the frame agrees: a terrain-scale ground surface straight above the eye, ground_above_m; the camera repair lifts it)+ # Δ hero_unseen (ERROR: a loaded GLB in the scene fills < 0.5 % of every authored frame — camera_checks[].glb_frac, one mask+ # render per GLB per camera, occlusion included) · hero_small_in_its_camera (WARN: < 2 % in the camera named for it)from codeverse.spatial.measure import measure_glb # link-hierarchy rule: metadata["links"] → each link is its own part# Δ Measurement.extra["complexity"] = ComplexityVector.model_dump() (additive, best-effort, never raises)from codeverse.spatial.complexity import (ComplexityVector, COMPLEXITY_WEIGHTS, COMPLEXITY_VERSION,diff --git a/harness/runtime_js/lib/host_coverage.mjs b/harness/runtime_js/lib/host_coverage.mjsindex 0a60008a..10ea4dee 100644--- a/harness/runtime_js/lib/host_coverage.mjs+++ b/harness/runtime_js/lib/host_coverage.mjs@@ -11,7 +11,7 @@* the content bbox (scatter across the whole ground) as backdrop.*/-import { classifyBackdrop } from './backdrop.mjs';+import { classifyBackdrop, nonSolid } from './backdrop.mjs';import { sampleFrame } from './host_metrics.mjs';export { classifyBackdrop }; // re-export: this module used to own the classifier@@ -42,35 +42,23 @@ function brightFraction(canvas) {return bright / n;}-/**- * Coverage of `camera`'s frame: {content_frac, ground_frac, sky_frac}.- * Restores every scene/renderer setting it touches.- */-export function frameCoverage(renderer, scene, camera, canvas, THREE, contentBox) {- const contentSpan = contentBox ? Math.max(contentBox.size[0], contentBox.size[2]) : 0;- const drawables = collectDrawables(scene, THREE, contentSpan);+/** Run `fn(mask)` with the scene set up for a mask render (no background, fog or tone+ * mapping, black clear, `mask` = flat white override) and restore everything after. */+function maskScope(renderer, scene, THREE, fn, override = true) {const saved = {background: scene.background, fog: scene.fog, override: scene.overrideMaterial,clear: renderer.getClearColor(new THREE.Color()), alpha: renderer.getClearAlpha(),toneMapping: renderer.toneMapping,};const mask = new THREE.MeshBasicMaterial({ color: 0xffffff, fog: false, side: THREE.DoubleSide });- const pass = (keep) => {- for (const d of drawables) d.obj.visible = keep.includes(d.kind);- renderer.render(scene, camera);- return brightFraction(canvas);- };- let content = 0, covered = 0;try {scene.background = null;scene.fog = null;- scene.overrideMaterial = mask;+ if (override) scene.overrideMaterial = mask;renderer.setClearColor(0x000000, 1);renderer.toneMapping = THREE.NoToneMapping;- content = pass(['content']);- covered = pass(['content', 'ground']); // ground pass includes content so hidden ground is not counted+ return fn(mask);} finally {- for (const d of drawables) d.obj.visible = true;scene.background = saved.background;scene.fog = saved.fog;scene.overrideMaterial = saved.override;@@ -78,9 +66,73 @@ export function frameCoverage(renderer, scene, camera, canvas, THREE, contentBoxrenderer.toneMapping = saved.toneMapping;mask.dispose();}+}++/**+ * Coverage of `camera`'s frame: {content_frac, ground_frac, sky_frac}.+ * Restores every scene/renderer setting it touches.+ */+export function frameCoverage(renderer, scene, camera, canvas, THREE, contentBox) {+ const contentSpan = contentBox ? Math.max(contentBox.size[0], contentBox.size[2]) : 0;+ const drawables = collectDrawables(scene, THREE, contentSpan);+ const pass = (keep) => {+ for (const d of drawables) d.obj.visible = keep.includes(d.kind);+ renderer.render(scene, camera);+ return brightFraction(canvas);+ };+ let content = 0, covered = 0;+ try {+ maskScope(renderer, scene, THREE, () => {+ content = pass(['content']);+ covered = pass(['content', 'ground']); // ground pass includes content so hidden ground is not counted+ });+ } finally {+ for (const d of drawables) d.obj.visible = true;+ }return {content_frac: +content.toFixed(4),ground_frac: +Math.max(0, covered - content).toFixed(4),sky_frac: +Math.max(0, 1 - covered).toFixed(4),};}++/**+ * How much of `camera`'s frame each loaded GLB fills, occlusion included: one render per+ * GLB with its meshes flat white and every other solid mesh flat black (see-through+ * volumetrics and points/lines/sprites hidden), then the bright fraction. `glbs` is the+ * host's load log [{url, geometry_uuids}]; a GLB none of whose geometry is in the scene+ * is skipped. cmp6's crypt (2026-09-09): the hero stood behind a pillar in every authored+ * frame and the judge blamed the hero — "in the scene" was known, "in the frame" was not.+ * @returns {{[url: string]: number}} fraction of the frame per GLB url+ */+export function glbCoverage(renderer, scene, camera, canvas, THREE, glbs) {+ const solids = [];+ const hidden = [];+ scene.traverse((o) => {+ if (!o.visible) return;+ if ((o.isMesh || o.isInstancedMesh) && o.geometry) {+ if (nonSolid(o)) hidden.push(o); else solids.push(o);+ } else if (o.isPoints || o.isLine || o.isSprite) hidden.push(o);+ });+ const out = {};+ const black = new THREE.MeshBasicMaterial({ color: 0x000000, fog: false, side: THREE.DoubleSide });+ const saved = solids.map((o) => o.material);+ try {+ maskScope(renderer, scene, THREE, (white) => {+ for (const o of hidden) o.visible = false;+ for (const g of glbs || []) {+ const ids = new Set(g.geometry_uuids || []);+ let n = 0;+ for (const o of solids) { const hit = ids.has(o.geometry.uuid); if (hit) n += 1; o.material = hit ? white : black; }+ if (!n) continue;+ renderer.render(scene, camera);+ out[g.url] = +brightFraction(canvas).toFixed(4);+ }+ }, false);+ } finally {+ solids.forEach((o, i) => { o.material = saved[i]; });+ for (const o of hidden) o.visible = true;+ black.dispose();+ }+ return out;+}diff --git a/harness/runtime_js/lib/scene_host.mjs b/harness/runtime_js/lib/scene_host.mjsindex 74b6e273..6a69337e 100644--- a/harness/runtime_js/lib/scene_host.mjs+++ b/harness/runtime_js/lib/scene_host.mjs@@ -20,7 +20,7 @@ import { ablationReport, frameSampler } from './host_ablation.mjs';import { sceneCensus } from './host_census.mjs';import { placementTable, settleScene } from './host_placement.mjs';import { frameStats, nearGeometry, repairCameraSpec } from './host_metrics.mjs';-import { frameCoverage } from './host_coverage.mjs';+import { frameCoverage, glbCoverage } from './host_coverage.mjs';import { installShaderErrorHook } from './host_shader_errors.mjs';import { attributeErrors, captured, captureMaterialSources, materialAudit } from './host_compile.mjs';import { makeRenderer, rendererString } from './browser/renderer.js';@@ -481,7 +481,15 @@ function cameraChecks(spec) {} catch (e) {state.hostWarnings.push(`coverage failed for ${spec.name}: ${e.message}`);}- return { name: spec.name, ...near, ...stats, ...coverage };+ let glbFrac = {};+ if (loadedGlbs.length) {+ try {+ glbFrac = glbCoverage(state.renderer, state.scene, cam, state.canvas, THREE, loadedGlbs);+ } catch (e) {+ state.hostWarnings.push(`glb coverage failed for ${spec.name}: ${e.message}`);+ }+ }+ return { name: spec.name, ...near, ...stats, ...coverage, glb_frac: glbFrac };}/** Force-compile every material as seen from spec (or the first camera). */diff --git a/harness/tests/scene_gates/test_frame_metrics.py b/harness/tests/scene_gates/test_frame_metrics.pyindex f579e170..6f2d0cef 100644--- a/harness/tests/scene_gates/test_frame_metrics.py+++ b/harness/tests/scene_gates/test_frame_metrics.py@@ -216,3 +216,25 @@ def test_a_loaded_glb_that_reaches_no_frame_is_flagged():assert rep.passed, "a WARN must not fail the gate"+++def test_a_hero_in_the_scene_but_in_no_authored_frame_is_an_error():+ """cmp6's crypt (2026-09-09): the athanor stood behind a pillar in every authored shot and+ the judge called the HERO a grey box — ``glb_frac`` is the mask render per GLB per camera."""+ url = "/assets/athanor.glb"+ census = {"ground_y": 0.0, "glb_assets": [{"url": url, "meshes": 9, "meshes_in_scene": 9, "in_scene": True}]}+ unseen = frame_findings({"census": census, "camera_checks": [+ _chk("AthanorDetail", glb_frac={url: 0.0}), _chk("StairsPushIn", glb_frac={url: 0.001}),+ _chk("overview_top", "orbit", glb_frac={url: 0.3})]}) # the rig sees it: not an authored shot+ kinds = _kinds(unseen)+ assert ("hero_unseen", Severity.ERROR, "athanor.glb") in kinds and not unseen.passed+ msg = next(f.message for f in unseen.findings if f.data["kind"] == "hero_unseen")+ assert "AthanorDetail 0.0%" in msg and "no camera sees the hero" in msg+ # seen well in one shot, but the camera NAMED for it barely shows it → WARN on that camera+ small = frame_findings({"census": census, "camera_checks": [+ _chk("AthanorDetail", glb_frac={url: 0.004}), _chk("StairsPushIn", glb_frac={url: 0.12})]})+ assert [(k, s, t) for k, s, t in _kinds(small)] == [("hero_small_in_its_camera", Severity.WARN, "AthanorDetail")]+ # a well-framed hero, and an older census without glb_frac, say nothing+ fine = frame_findings({"census": census, "camera_checks": [_chk("AthanorDetail", glb_frac={url: 0.2})]})+ old = frame_findings({"census": census, "camera_checks": [_chk("AthanorDetail")]})+ assert fine.passed and old.passed and not [k for k, _, _ in _kinds(fine) + _kinds(old) if k.startswith("hero_")]diff --git a/harness/tests/scene_gates/test_live_hero_in_frame.py b/harness/tests/scene_gates/test_live_hero_in_frame.pynew file mode 100644index 00000000..c1079d55--- /dev/null+++ b/harness/tests/scene_gates/test_live_hero_in_frame.py@@ -0,0 +1,78 @@+"""Browser-backed: a Blender hero (GLB) in the scene but in no authored frame is an ERROR.++cmp6's crypt (2026-09-09): the athanor stood behind a squat pillar in every authored shot; the+judge called the HERO "a massive untextured grey box" and two refine rounds rebuilt the wrong+thing. ``glbCoverage`` renders each loaded GLB as a white mask against black solids+(occlusion included) per camera; the gate reads ``camera_checks[].glb_frac``.+"""++from __future__ import annotations++import math++import pytest++from codeverse.spatial.frame_metrics import HERO_MIN_FRAC, frame_gate_from_renders+from codeverse.spatial.render_scene import read_metrics, render_scene+from codeverse.workspace import Workspace+from tests.scene_runtime.conftest import needs_browser+from tests.scene_runtime.glb_fixture import write_box_glb++pytestmark = [pytest.mark.node, needs_browser]++URL = "/assets/hero_cube.glb"++# the hero hangs at (10, 6, 14): on the overview camera's sightline ((26, 14, 34) → (0, 1.5, 0)) and+# outside the pond and windmill shots' frusta; the wall stands halfway between the overview and it+WALL = """+ const wall = new THREE.Mesh(new THREE.BoxGeometry(30, 16, 0.5), new THREE.MeshStandardMaterial({ color: 0x888888 }));+ wall.name = 'StoneWall'; wall.position.set(18, 10, 24); wall.rotation.y = Math.atan2(16, 20); scene.add(wall);+"""+++def _with_hero(ws: Workspace, *, hidden: bool) -> None:+ write_box_glb(ws.public / "assets" / "hero_cube.glb", size=(4.0, 4.0, 4.0))+ scene = ws.src / "scene.js"+ text = scene.read_text()+ text = text.replace("export function createScene(", "export async function createScene(")+ text = text.replace(" ctx.env = env;\n", " ctx.env = env;\n"+ " const hero = (await loaders.gltf.loadAsync('" + URL + "')).scene;\n"+ " hero.name = 'HeroCube'; hero.position.set(10, 6, 14);\n"+ " hero.traverse((o) => { if (o.geometry) o.geometry.computeVertexNormals(); });\n"+ " scene.add(hero);\n" + (WALL if hidden else ""), 1)+ assert "hero_cube.glb" in text and ("StoneWall" in text) == hidden+ scene.write_text(text)+++def test_a_hero_in_an_authored_frame_passes(starter_ws: Workspace):+ _with_hero(starter_ws, hidden=False)+ out = starter_ws.renders_dir(0)+ rs = render_scene(starter_ws, out, times=(0.0,), width=640, height=360, fps_seconds=0.2)+ assert rs.console_errors == []+ m = read_metrics(out)+ rows = {r["url"]: r for r in m["census"]["glb_assets"]}+ assert rows[URL]["in_scene"] is True+ chk = {c["name"]: c for c in m["camera_checks"]}+ seen = chk["overview"]["glb_frac"][URL]+ assert seen > HERO_MIN_FRAC, chk["overview"]["glb_frac"] # the establishing shot sees the cube+ others = [chk[n]["glb_frac"].get(URL, 0.0) for n in ("pond_low", "windmill")]+ assert max(others) < seen, (seen, others) # the other shots look away from it+ gate = frame_gate_from_renders(rs)+ assert not [f for f in gate.findings if f.data["kind"].startswith("hero_")], [f.message for f in gate.findings]+++def test_a_hero_behind_a_wall_in_every_authored_frame_is_an_error(starter_ws: Workspace):+ _with_hero(starter_ws, hidden=True)+ out = starter_ws.renders_dir(0)+ rs = render_scene(starter_ws, out, times=(0.0,), width=640, height=360, fps_seconds=0.2)+ m = read_metrics(out)+ chk = {c["name"]: c for c in m["camera_checks"]}+ assert chk["overview"]["glb_frac"].get(URL, 0.0) < 0.002, chk["overview"]["glb_frac"] # in the scene, behind the wall+ gate = frame_gate_from_renders(rs)+ unseen = [f for f in gate.findings if f.data["kind"] == "hero_unseen"]+ assert len(unseen) == 1 and unseen[0].target == "hero_cube.glb" and not gate.passed, [f.message for f in gate.findings]+ assert "overview 0.0%" in unseen[0].message+ # the sightline measure names the wall for the establishing shot (the wall sits ~47 % of the way)+ cut = [f for f in gate.findings if f.data["kind"] == "camera_target_blocked" and f.target == "overview"]+ assert cut and "StoneWall" in cut[0].message, [f.message for f in gate.findings]+ assert math.isfinite(cut[0].data["target_hit_m"])diff --git a/harness/tests/scene_runtime/glb_fixture.py b/harness/tests/scene_runtime/glb_fixture.pynew file mode 100644index 00000000..633a7254--- /dev/null+++ b/harness/tests/scene_runtime/glb_fixture.py@@ -0,0 +1,39 @@+"""A minimal binary glTF (one box mesh) for tests that need a real GLB on disk."""++from __future__ import annotations++import json+import struct+from pathlib import Path+++def write_box_glb(path: Path, size: tuple[float, float, float] = (2.0, 2.0, 2.0), name: str = "HeroCube") -> Path:+ """Write a GLB holding one box mesh (8 vertices, 12 triangles, no normals — the loader's+ consumer computes them) centred on the origin. Returns ``path``."""+ sx, sy, sz = (s / 2 for s in size)+ verts = [(-sx, -sy, -sz), (sx, -sy, -sz), (sx, sy, -sz), (-sx, sy, -sz),+ (-sx, -sy, sz), (sx, -sy, sz), (sx, sy, sz), (-sx, sy, sz)]+ faces = [(0, 2, 1), (0, 3, 2), (4, 5, 6), (4, 6, 7), (0, 1, 5), (0, 5, 4),+ (1, 2, 6), (1, 6, 5), (2, 3, 7), (2, 7, 6), (3, 0, 4), (3, 4, 7)]+ pos = struct.pack(f"<{len(verts) * 3}f", *[c for v in verts for c in v])+ idx = struct.pack(f"<{len(faces) * 3}H", *[i for f in faces for i in f])+ idx += b"\x00" * ((4 - len(idx) % 4) % 4)+ blob = pos + idx+ gltf = {+ "asset": {"version": "2.0"}, "scene": 0, "scenes": [{"nodes": [0]}], "nodes": [{"mesh": 0, "name": name}],+ "meshes": [{"name": name, "primitives": [{"attributes": {"POSITION": 0}, "indices": 1}]}],+ "buffers": [{"byteLength": len(blob)}],+ "bufferViews": [{"buffer": 0, "byteOffset": 0, "byteLength": len(pos), "target": 34962},+ {"buffer": 0, "byteOffset": len(pos), "byteLength": len(faces) * 6, "target": 34963}],+ "accessors": [{"bufferView": 0, "componentType": 5126, "count": len(verts), "type": "VEC3",+ "min": [-sx, -sy, -sz], "max": [sx, sy, sz]},+ {"bufferView": 1, "componentType": 5123, "count": len(faces) * 3, "type": "SCALAR"}],+ }+ js = json.dumps(gltf, separators=(",", ":")).encode()+ js += b" " * ((4 - len(js) % 4) % 4)+ total = 12 + 8 + len(js) + 8 + len(blob)+ out = (struct.pack("<III", 0x46546C67, 2, total) + struct.pack("<II", len(js), 0x4E4F534A) + js+ + struct.pack("<II", len(blob), 0x004E4942) + blob)+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_bytes(out)+ return path