Skip to content

Official Codebase of 3DCodeVerse

Python

camera repair: a camera named for a hero is re-aimed at the hero when its centre is out of frame

gaoypengf4772d67ad20
diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.md
index 655256b1..93450bcf 100644
--- a/harness/docs/DECISIONS.md
+++ b/harness/docs/DECISIONS.md
@@ -1200,8 +1200,10 @@ written) that were accepted because the code works that way and the tests pin it
judge's noise) `src/` is restored to the best round and the tasks come from ITS verdict
(`round.refine_from_best`); `repairCameraSpec` counts a lens staring at a surface
(`near_rays`), a sightline cut before half the distance and a terrain overhead as "not
- clear" and searches back, up and sideways out of it. Same rule as D72's: the harness fixes
- what it can measure, deterministically, before a session is paid to guess.
+ clear" and searches back, up and sideways out of it; a camera NAMED for a hero whose hero
+ centre is outside its frustum is re-aimed at it first (loop 25's `LanternDetail` shot the
+ tower wall for three rounds while `hero_unseen` read 0.0 %). Same rule as D72's: the harness
+ fixes what it can measure, deterministically, before a session is paid to guess.
## Rejected / deferred
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 39d80662..a7c1da41 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -273,7 +273,9 @@ frame_gate_from_renders(renders) -> GateReport # gate "scene_frames"; da
# render per GLB per camera, occlusion included) · hero_small_in_its_camera (WARN: < 2 % in the camera named for it)
# Δ scene_placement stamped_ring (WARN): census groups[].stamps — per family of ≥ 8 copies {n, radius_m, radius_cv,
# gap_cv, size_cv}; ≥ 8 same-size copies evenly on a ring at ≥ 0.6 × the plan's half-extent (host_census stampStats)
- # Δ census.camera_repair rows carry moved_side_m, blocked_before, cut_before, under_before (D73); the overview rig
+ # Δ census.camera_repair rows carry moved_side_m, blocked_before, cut_before, under_before, aimed_at (D73: a camera named
+ # for a hero — a name word of its GLB file in the camera name — is re-aimed at the hero's centre when that centre is
+ # outside its frustum, before the retreat search); the overview rig
# (noFog views) hides see-through sky layers whose box lies below the eye; roomShell tags userData.placement='free'
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)
diff --git a/harness/runtime_js/lib/scene_host.mjs b/harness/runtime_js/lib/scene_host.mjs
index 70f0d802..2d578501 100644
--- a/harness/runtime_js/lib/scene_host.mjs
+++ b/harness/runtime_js/lib/scene_host.mjs
@@ -145,20 +145,49 @@ function makeLoaders(manager) {
* exactly the case this exists to catch. A deep `geometry.clone()` would read as unused;
* that is why the finding is a WARN and says "no geometry from it", not "not used".
*/
+/** geometry uuid -> world box of every mesh drawing it (the GLB bookkeeping's one traversal). */
+function geometryBoxes(scene) {
+ const used = new Map();
+ const box = new THREE.Box3();
+ scene.traverse((o) => {
+ if (!o.geometry || !o.geometry.uuid || !(o.isMesh || o.isInstancedMesh)) return;
+ if (!o.geometry.boundingBox) o.geometry.computeBoundingBox();
+ if (!used.has(o.geometry.uuid)) used.set(o.geometry.uuid, new THREE.Box3());
+ if (o.geometry.boundingBox && !o.geometry.boundingBox.isEmpty()) {
+ box.copy(o.geometry.boundingBox).applyMatrix4(o.matrixWorld);
+ used.get(o.geometry.uuid).union(box);
+ }
+ });
+ return used;
+}
+
+/** Words of a GLB's file name that can name a camera for it: `lantern_room.glb` → ['lantern']. */
+const GENERIC_HERO_WORDS = new Set(['room', 'detail', 'hero', 'main', 'view', 'shot', 'camera', 'asset', 'model', 'close', 'closeup', 'wide', 'zone', 'prop']);
+function heroWords(url) {
+ const base = String(url).split('/').pop().replace(/\.glb$/i, '');
+ return base.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/)
+ .map((w) => w.toLowerCase()).filter((w) => w.length >= 4 && !GENERIC_HERO_WORDS.has(w));
+}
+
+/** The loaded GLB a camera is named for (a name word of the file in the camera's name), with its
+ * world box as placed — or null. */
+function heroForCamera(name) {
+ if (!loadedGlbs.length) return null;
+ const lower = String(name || '').toLowerCase();
+ let boxes = null;
+ for (const g of loadedGlbs) {
+ if (!heroWords(g.url).some((w) => lower.includes(w))) continue;
+ if (!boxes) { try { boxes = geometryBoxes(state.scene); } catch (e) { return null; } }
+ const all = new THREE.Box3();
+ for (const u of g.geometry_uuids) { const b = boxes.get(u); if (b && !b.isEmpty()) all.union(b); }
+ if (!all.isEmpty()) return { url: g.url, box: all };
+ }
+ return null;
+}
+
function glbUsage(scene) {
- const used = new Map(); // geometry uuid -> world boxes of the meshes that draw it
- try {
- const box = new THREE.Box3();
- scene.traverse((o) => {
- if (!o.geometry || !o.geometry.uuid || !(o.isMesh || o.isInstancedMesh)) return;
- if (!o.geometry.boundingBox) o.geometry.computeBoundingBox();
- if (!used.has(o.geometry.uuid)) used.set(o.geometry.uuid, new THREE.Box3());
- if (o.geometry.boundingBox && !o.geometry.boundingBox.isEmpty()) {
- box.copy(o.geometry.boundingBox).applyMatrix4(o.matrixWorld);
- used.get(o.geometry.uuid).union(box);
- }
- });
- } catch { return []; }
+ let used;
+ try { used = geometryBoxes(scene); } catch { return []; }
return loadedGlbs.map((g) => {
const all = new THREE.Box3();
let n = 0;
@@ -392,14 +421,30 @@ function buildCamera(spec) {
if (state.cameraRepair && spec && spec.name && Array.isArray(spec.position) && Array.isArray(spec.lookAt)) {
const key = spec.name + '|' + spec.position.join(',');
if (!state.repairedSpecs.has(key)) {
+ // A camera NAMED for a hero whose hero is out of its frame is re-aimed at the hero first:
+ // loop 25's lighthouse (2026-09-09) shot `LanternDetail` at the tower wall for three rounds
+ // while `hero_unseen` said 0.0 % each time and no session moved the plan's camera. Only
+ // when the hero's centre is outside the frustum — a small or far hero is the author's shot.
+ let base = spec;
+ let aimed = '';
+ try {
+ const hero = heroForCamera(spec.name);
+ if (hero) {
+ const c = hero.box.getCenter(new THREE.Vector3());
+ const cam0 = buildCameraRaw(spec);
+ const inFront = c.clone().applyMatrix4(cam0.matrixWorldInverse).z < 0;
+ const ndc = c.clone().project(cam0);
+ if (!(inFront && Math.abs(ndc.x) <= 1 && Math.abs(ndc.y) <= 1)) { base = { ...spec, lookAt: [c.x, c.y, c.z] }; aimed = hero.url; }
+ }
+ } catch (e) { base = spec; aimed = ''; }
let fix = null;
- try { fix = repairCameraSpec(state.scene, spec, THREE, buildCameraRaw); } catch (e) { fix = null; }
- state.repairedSpecs.set(key, fix ? fix.spec : null);
- if (fix) state.cameraRepairs.push({ name: fix.name, moved_back_m: fix.moved_back_m, moved_up_m: fix.moved_up_m,
- moved_side_m: fix.moved_side_m || 0, nearest_before: fix.nearest_before,
- inside_before: fix.inside_before, under_before: fix.under_before || '',
- blocked_before: !!fix.blocked_before, cut_before: fix.cut_before || '',
- nearest_after: fix.nearest_after });
+ try { fix = repairCameraSpec(state.scene, base, THREE, buildCameraRaw); } catch (e) { fix = null; }
+ state.repairedSpecs.set(key, fix ? fix.spec : (aimed ? base : null));
+ if (fix || aimed) state.cameraRepairs.push({ name: spec.name, moved_back_m: fix ? fix.moved_back_m : 0, moved_up_m: fix ? fix.moved_up_m : 0,
+ moved_side_m: fix ? fix.moved_side_m || 0 : 0, nearest_before: fix ? fix.nearest_before : null,
+ inside_before: fix ? fix.inside_before : [], under_before: fix ? fix.under_before || '' : '',
+ blocked_before: !!(fix && fix.blocked_before), cut_before: fix ? fix.cut_before || '' : '',
+ aimed_at: aimed, nearest_after: fix ? fix.nearest_after : null });
}
const fixed = state.repairedSpecs.get(key);
if (fixed) return buildCameraRaw(fixed);
diff --git a/harness/tests/scene_gates/test_live_hero_in_frame.py b/harness/tests/scene_gates/test_live_hero_in_frame.py
index 15690575..118fe7e2 100644
--- a/harness/tests/scene_gates/test_live_hero_in_frame.py
+++ b/harness/tests/scene_gates/test_live_hero_in_frame.py
@@ -36,7 +36,11 @@ ROOM = """
"""
-def _with_hero(ws: Workspace, *, hidden: bool, roofed: bool = False) -> None:
+# a camera NAMED for the hero, aimed 90 degrees away from it (loop 25's LanternDetail at the tower wall)
+AWAY_CAMERA = " { name: 'HeroCubeDetail', position: [10, 8, 30], lookAt: [40, 6, 30], fov: 45 },\n"
+
+
+def _with_hero(ws: Workspace, *, hidden: bool, roofed: bool = False, away_camera: bool = False) -> 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()
@@ -46,6 +50,10 @@ def _with_hero(ws: Workspace, *, hidden: bool, roofed: bool = False) -> None:
" 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 "") + (ROOM if roofed else ""), 1)
+ if away_camera:
+ anchor = " { name: 'windmill', position: [9, heightAt(9, 9) + 1.7, 9], lookAt: [12, 4.5, -2], fov: 50 },\n"
+ assert anchor in text
+ text = text.replace(anchor, anchor + AWAY_CAMERA, 1)
if roofed:
text = text.replace("import { buildEnv, heightAt, SUN_AZIMUTH_DEG } from './env.js';",
"import { buildEnv, heightAt, SUN_AZIMUTH_DEG } from './env.js';\nimport { roomShell } from './lib/environment.js';", 1)
@@ -104,3 +112,23 @@ def test_the_overview_rig_lifts_the_room_shells_lid_but_an_authored_camera_keeps
assert chk["overview"]["glb_frac"].get(URL, 0.0) < 0.002, chk["overview"]["glb_frac"]
names = [g["name"] for g in m["census"]["groups"]]
assert "RoomShell" in names # the census counts the shell as built
+
+
+def test_a_camera_named_for_the_hero_is_re_aimed_when_the_hero_is_out_of_its_frame(starter_ws: Workspace):
+ """Loop 25's lighthouse (2026-09-09): `LanternDetail` shot the tower wall for three rounds
+ while `hero_unseen` read 0.0 % each time — cameras belong to the plan and no session moved
+ it. The host re-aims a hero-named camera at the hero's centre when that centre is outside
+ the frustum, and the repair log says so."""
+ _with_hero(starter_ws, hidden=False, away_camera=True)
+ 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)
+ chk = {c["name"]: c for c in m["camera_checks"]}
+ assert chk["HeroCubeDetail"]["glb_frac"].get(URL, 0.0) > 0.01, chk["HeroCubeDetail"]["glb_frac"]
+ aimed = [r for r in m["census"]["camera_repair"] if r.get("aimed_at")]
+ assert aimed and aimed[0]["name"] == "HeroCubeDetail" and aimed[0]["aimed_at"] == URL, m["census"]["camera_repair"]
+ # the other authored cameras are not named for it and keep their shots
+ assert not [r for r in m["census"]["camera_repair"] if r.get("aimed_at") and r["name"] != "HeroCubeDetail"]
+ gate = frame_gate_from_renders(rs)
+ assert not [f for f in gate.findings if f.data["kind"] == "hero_unseen"], [f.message for f in gate.findings]