Skip to content

Official Codebase of 3DCodeVerse

Python

scene: deterministic camera repair — opt-in retreat for a lens stuck in geometry

gaoypeng0a13047758db
diff --git a/harness/codeverse/spatial/probes.py b/harness/codeverse/spatial/probes.py
index b2a8e188..740565ed 100644
--- a/harness/codeverse/spatial/probes.py
+++ b/harness/codeverse/spatial/probes.py
@@ -72,6 +72,8 @@ def probe_scene(ws: Workspace, *, timeout_s: float = 60.0, write_census: bool =
args = ["--ws", str(ws.root), "--out", str(out_json), "--timeout-ms", str(int(timeout_s * 1000))]
if os.environ.get("CV3D_SETTLE") == "0": # A/B switch for the boot-time auto-seat
args.append("--no-settle")
+ if os.environ.get("CV3D_CAMERA_REPAIR") == "1": # opt-in: repair plan cameras stuck in geometry
+ args.append("--camera-repair")
res = run_scene_script("probe_scene.mjs", args, timeout_s=timeout_s + 20)
except SceneRenderError as e:
findings.append(_f(gate, Severity.ERROR, f"scene probe could not run: {e}", target="src/scene.js",
diff --git a/harness/codeverse/spatial/render_scene.py b/harness/codeverse/spatial/render_scene.py
index d28eb8c0..d5a79e71 100644
--- a/harness/codeverse/spatial/render_scene.py
+++ b/harness/codeverse/spatial/render_scene.py
@@ -142,6 +142,8 @@ def render_scene(
args += ["--timeout-ms", str(int(tmo * 1000))]
if os.environ.get("CV3D_SETTLE") == "0": # A/B switch for the boot-time auto-seat
args.append("--no-settle")
+ if os.environ.get("CV3D_CAMERA_REPAIR") == "1": # opt-in: repair plan cameras stuck in geometry
+ args.append("--camera-repair")
driver_error = ""
try:
res = run_scene_script("render_scene.mjs", args, timeout_s=tmo + 30)
diff --git a/harness/runtime_js/lib/host_metrics.mjs b/harness/runtime_js/lib/host_metrics.mjs
index 849a918e..7d23e882 100644
--- a/harness/runtime_js/lib/host_metrics.mjs
+++ b/harness/runtime_js/lib/host_metrics.mjs
@@ -101,3 +101,45 @@ export function nearGeometry(scene, camera, THREE, limitM = 0.3) {
look_dir: [center.x, center.y, center.z].map((v) => +v.toFixed(3)),
};
}
+
+/**
+ * Deterministic camera repair, added 2026-08-30 and OFF by default
+ * (drivers pass --camera-repair; python gates it behind CV3D_CAMERA_REPAIR=1).
+ *
+ * Why: cameras belong to the PLAN — no refine agent owns a file that could fix
+ * one, so camera_in_geometry stood in final rounds across whole batteries
+ * (camera_unusable in 23/48 scored runs; fv_izakaya_night lost 0.26 to it three
+ * rounds straight). The measurement (nearGeometry) is deterministic, so the fix
+ * can be: try the smallest retreat (backward along the view axis, then upward)
+ * that clears the lens, keeping lookAt — composition survives, the shot stops
+ * being inside the furniture.
+ *
+ * Pure: no renderer, raycasts only. `makeCam(spec)` is supplied by the host so
+ * near/far/aspect match the real render exactly.
+ */
+const REPAIR_OFFSETS = [
+ [0, 0], [0, 0.5], [0.5, 0], [0.5, 0.5], [1, 0.5], [1, 1], [2, 1], [2, 2], [3, 2], [4, 2],
+];
+const REPAIR_CLEAR_M = 0.5;
+
+export function repairCameraSpec(scene, spec, THREE, makeCam) {
+ const dir = new THREE.Vector3(
+ spec.position[0] - spec.lookAt[0], spec.position[1] - spec.lookAt[1], spec.position[2] - spec.lookAt[2]);
+ if (dir.lengthSq() < 1e-9) dir.set(0, 0, 1);
+ dir.normalize();
+ let before = null;
+ for (const [back, up] of REPAIR_OFFSETS) {
+ const pos = [spec.position[0] + dir.x * back, spec.position[1] + dir.y * back + up, spec.position[2] + dir.z * back];
+ const candidate = { ...spec, position: pos };
+ const n = nearGeometry(scene, makeCam(candidate), THREE);
+ if (before === null) before = n;
+ const clear = !n.camera_in_geometry && (n.nearest_hit_m === null || n.nearest_hit_m >= REPAIR_CLEAR_M);
+ if (clear) {
+ if (back === 0 && up === 0) return null; // the authored camera is fine: no repair
+ return { spec: candidate, name: spec.name || '', moved_back_m: back, moved_up_m: up,
+ nearest_before: before.nearest_hit_m, inside_before: before.inside_mesh_bbox,
+ nearest_after: n.nearest_hit_m };
+ }
+ }
+ return null; // nothing within the retreat budget clears it: keep the authored shot
+}
diff --git a/harness/runtime_js/lib/host_page.mjs b/harness/runtime_js/lib/host_page.mjs
index 8cf5e4ea..51ab16cb 100644
--- a/harness/runtime_js/lib/host_page.mjs
+++ b/harness/runtime_js/lib/host_page.mjs
@@ -55,7 +55,7 @@ export function requestFailureLine(url, base, hasResponse, errorText) {
* Open the host for workspace `wsRoot`.
* @returns {Promise<{page, browser, base, gpu, renderer, errors, boot, close}>}
*/
-export async function openHost(wsRoot, { width = 1024, height = 576, gpu = 'auto', logDepth = false, sceneRel = 'src/scene.js', createSceneTimeoutMs = 0, settle = true } = {}) {
+export async function openHost(wsRoot, { width = 1024, height = 576, gpu = 'auto', logDepth = false, sceneRel = 'src/scene.js', createSceneTimeoutMs = 0, settle = true, cameraRepair = false } = {}) {
wsRoot = path.resolve(wsRoot);
if (!fs.existsSync(path.join(wsRoot, sceneRel))) {
throw new Error(`missing ${sceneRel} in workspace ${wsRoot}`);
@@ -101,7 +101,7 @@ export async function openHost(wsRoot, { width = 1024, height = 576, gpu = 'auto
await page.waitForFunction('window.__c3v_ready === true', { timeout: 60000 });
const boot = await page.evaluate(
(o) => window.__c3v.boot(o),
- { sceneUrl: `/${sceneRel}`, width, height, logDepth, createSceneTimeoutMs, settle },
+ { sceneUrl: `/${sceneRel}`, width, height, logDepth, createSceneTimeoutMs, settle, cameraRepair },
);
const close = async () => {
// page first, then release: a SHARED browser (connect-first reuse) must get
diff --git a/harness/runtime_js/lib/scene_host.mjs b/harness/runtime_js/lib/scene_host.mjs
index 3190034e..b575fe11 100644
--- a/harness/runtime_js/lib/scene_host.mjs
+++ b/harness/runtime_js/lib/scene_host.mjs
@@ -16,7 +16,7 @@ import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { sceneCensus } from './host_census.mjs';
import { placementTable, settleScene } from './host_placement.mjs';
-import { frameStats, nearGeometry } from './host_metrics.mjs';
+import { frameStats, nearGeometry, repairCameraSpec } from './host_metrics.mjs';
import { frameCoverage } from './host_coverage.mjs';
import { installShaderErrorHook } from './host_shader_errors.mjs';
import { attributeErrors, captured, captureMaterialSources, materialAudit } from './host_compile.mjs';
@@ -47,6 +47,9 @@ const state = {
contentBox: null,
fullBox: null,
settleInfo: null,
+ cameraRepair: false,
+ cameraRepairs: [],
+ repairedSpecs: new Map(),
};
/**
@@ -169,6 +172,9 @@ async function boot(opts) {
state.bootInfo = info;
try {
loadedGlbs = [];
+ state.cameraRepair = !!opts.cameraRepair;
+ state.cameraRepairs = [];
+ state.repairedSpecs = new Map();
state.width = opts.width || 1024;
state.height = opts.height || 576;
window.requestAnimationFrame = () => { state.rafCalls += 1; return 0; };
@@ -294,6 +300,27 @@ function raceCreateScene(mod, ctx, timeoutMs) {
}
function buildCamera(spec) {
+ // camera repair (opt-in, --camera-repair): cameras belong to the plan and no refine
+ // agent can fix one, so a lens inside geometry is repaired here — the smallest
+ // backward/upward retreat that clears it, cached per camera name so every render of
+ // that camera uses the same repaired spec, recorded in census.camera_repair.
+ 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)) {
+ 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,
+ nearest_before: fix.nearest_before, inside_before: fix.inside_before,
+ nearest_after: fix.nearest_after });
+ }
+ const fixed = state.repairedSpecs.get(key);
+ if (fixed) return buildCameraRaw(fixed);
+ }
+ return buildCameraRaw(spec);
+}
+
+function buildCameraRaw(spec) {
const aspect = state.width / state.height;
if (!state.fullBox) { const c = sceneCensus(state.scene, THREE); state.fullBox = c.bbox; state.contentBox = c.content_bbox; }
const fb = state.fullBox;
@@ -422,6 +449,7 @@ function census() {
const c = sceneCensus(state.scene, THREE);
c.glb_assets = glbUsage(state.scene);
if (state.settleInfo) c.settle = state.settleInfo;
+ if (state.cameraRepairs.length) c.camera_repair = state.cameraRepairs.slice();
state.contentBox = c.content_bbox;
state.fullBox = c.bbox;
c.cameras = state.cameras.length;
diff --git a/harness/runtime_js/probe_scene.mjs b/harness/runtime_js/probe_scene.mjs
index c335a385..036fef52 100644
--- a/harness/runtime_js/probe_scene.mjs
+++ b/harness/runtime_js/probe_scene.mjs
@@ -57,6 +57,7 @@ async function main() {
width: 320, height: 180, gpu: args.gpu, sceneRel: args.scene.replace(/^\.?\//, ''),
createSceneTimeoutMs: createTimeoutMs(args['create-timeout-ms'], timeoutMs),
settle: !args['no-settle'],
+ cameraRepair: !!args['camera-repair'],
});
} catch (e) {
return fail(`host failed: ${e.message}`);
diff --git a/harness/runtime_js/render_scene.mjs b/harness/runtime_js/render_scene.mjs
index 00c752e0..4511ca13 100644
--- a/harness/runtime_js/render_scene.mjs
+++ b/harness/runtime_js/render_scene.mjs
@@ -54,6 +54,7 @@ async function main() {
width, height, gpu: args.gpu, logDepth: args['log-depth'],
createSceneTimeoutMs: createTimeoutMs(args['create-timeout-ms'], timeoutMs),
settle: !args['no-settle'],
+ cameraRepair: !!args['camera-repair'],
});
} catch (e) {
return fail(`host failed: ${e.message}`);
diff --git a/harness/tests/scene_runtime/test_camera_repair.py b/harness/tests/scene_runtime/test_camera_repair.py
new file mode 100644
index 00000000..585ccc8a
--- /dev/null
+++ b/harness/tests/scene_runtime/test_camera_repair.py
@@ -0,0 +1,58 @@
+"""Deterministic camera repair: the smallest retreat that clears the lens."""
+
+from __future__ import annotations
+
+import pytest
+
+from codeverse.config import get_settings
+from tests.scene_runtime.conftest import needs_node, run_node_json
+
+pytestmark = [pytest.mark.node, needs_node]
+
+RUNTIME_JS = get_settings().runtime_js_dir()
+
+JS = """
+import * as THREE from 'three';
+import { nearGeometry, repairCameraSpec } from './lib/host_metrics.mjs';
+const mat = new THREE.MeshStandardMaterial();
+const scene = new THREE.Scene();
+const ground = new THREE.Mesh(new THREE.PlaneGeometry(60, 60, 2, 2), mat);
+ground.name = 'Ground'; ground.rotation.x = -Math.PI / 2; scene.add(ground);
+const counter = new THREE.Mesh(new THREE.BoxGeometry(3, 1.1, 1.2), mat);
+counter.name = 'BarCounter'; counter.position.set(0, 0.55, 0); scene.add(counter);
+scene.updateMatrixWorld(true);
+const makeCam = (spec) => {
+ const cam = new THREE.PerspectiveCamera(spec.fov || 50, 16 / 9, 0.1, 500);
+ cam.position.set(...spec.position);
+ cam.lookAt(...spec.lookAt);
+ cam.updateMatrixWorld(true);
+ return cam;
+};
+// the fv_izakaya failure shape: an eye INSIDE the counter, looking along it
+const stuck = { name: 'PotDetail', position: [0.2, 0.6, 0.1], lookAt: [-1.5, 0.8, -0.5], fov: 45 };
+const fix = repairCameraSpec(scene, stuck, THREE, makeCam);
+const after = fix ? nearGeometry(scene, makeCam(fix.spec), THREE) : null;
+// a camera with open air in front needs no repair
+const fine = { name: 'Establishing', position: [10, 4, 10], lookAt: [0, 1, 0], fov: 45 };
+const noFix = repairCameraSpec(scene, fine, THREE, makeCam);
+console.log(JSON.stringify({ fix, after, noFix }));
+"""
+
+
[email protected](scope="module")
+def result() -> dict:
+ return run_node_json(JS.replace("'./lib/", f"'{RUNTIME_JS}/lib/"))
+
+
+def test_a_lens_inside_geometry_retreats_until_clear(result):
+ fix = result["fix"]
+ assert fix is not None, "the stuck camera must be repaired"
+ assert fix["inside_before"] == ["BarCounter"]
+ assert fix["moved_back_m"] + fix["moved_up_m"] > 0
+ after = result["after"]
+ assert not after["camera_in_geometry"]
+ assert after["nearest_hit_m"] is None or after["nearest_hit_m"] >= 0.5
+
+
+def test_a_clear_camera_is_left_exactly_as_authored(result):
+ assert result["noFix"] is None