Skip to content

Official Codebase of 3DCodeVerse

Python

frames gate: a blocked lens, a cut line of sight and a lens under the terrain are measured; the camera repair lifts the buried one

gaoypeng3f8125c10e84
diff --git a/harness/codeverse/spatial/frame_metrics.py b/harness/codeverse/spatial/frame_metrics.py
index 8af7ded4..a51590db 100644
--- a/harness/codeverse/spatial/frame_metrics.py
+++ b/harness/codeverse/spatial/frame_metrics.py
@@ -45,6 +45,8 @@ CONTENT_MIN_ESTABLISHING = 0.20
CONTENT_MIN_AUTHORED = 0.10
CONTENT_MIN_OVERVIEW = 0.05
EYE_MIN_ABOVE_GROUND_M = 0.3
+TARGET_BLOCKED_FRAC = 0.5 # the line of sight to lookAt is cut before this fraction of the distance
+BLOCKED_RAYS_MIN = 6 # of the 3 x 3 sight rays, within near_limit_m (host BLOCKED_M)
EYE_MAX_ABOVE_GROUND_M = 80.0
#: for a frame that is dark AND flat -- nothing is lit, so adding light is right
@@ -148,9 +150,47 @@ def _geometry_findings(chk: dict[str, Any], *, authored: bool, ground_y: float |
where = f"inside {inside[:3]}" if inside else f"nearest surface {near:.2f} m ({chk.get('nearest_hit_name', '')})"
out.append(_f(sev, name, rig + f"camera inside / touching geometry: {where}", _NEAR_HINT,
kind="camera_in_geometry", view=name, nearest_hit_m=near, inside=inside[:5]))
+ else:
+ # The shot is a surface: most of the 3 x 3 sight rays end within arm's reach. cmp6's
+ # crypt (2026-09-09): a squat stone pillar 0.8 m in front of AthanorDetail filled the
+ # frame, the hero behind it was never seen, and the judge called the HERO "a massive
+ # untextured grey box" for two rounds — nothing measured said the lens was blocked.
+ near_rays, rays_total = _num(chk, "near_rays"), _num(chk, "rays_total")
+ if authored and near_rays is not None and rays_total and near_rays >= BLOCKED_RAYS_MIN:
+ limit = _num(chk, "near_limit_m") or 1.5
+ out.append(_f(Severity.ERROR, name,
+ f"camera blocked: {near_rays:.0f} of {rays_total:.0f} sight rays end within {limit:g} m "
+ f"(nearest {chk.get('nearest_hit_name', '')} at {near:.2f} m) — the frame is that surface, not the shot",
+ "move the camera back or aside until its subject is clear, or move the blocking object out of the "
+ "sightline; render this view and look before re-judging",
+ kind="camera_blocked", view=name, near_rays=near_rays, nearest_hit_m=near,
+ nearest_hit_name=chk.get("nearest_hit_name", "")))
+ # …or the line of sight to the plan's lookAt is cut well before it (a pillar between the
+ # lens and its subject; a close-up meets its own subject near the full distance).
+ t_dist, t_hit = _num(chk, "target_distance_m"), _num(chk, "target_hit_m")
+ if authored and t_dist and t_hit is not None and t_hit < TARGET_BLOCKED_FRAC * t_dist:
+ cutter = str(chk.get("target_hit_name") or "geometry")
+ out.append(_f(Severity.WARN, name,
+ f"line of sight from {name} to its lookAt is cut by {cutter} at {t_hit:.2f} m of {t_dist:.1f} m "
+ f"({100 * t_hit / t_dist:.0f}% of the way) — the subject may be hidden behind it",
+ f"look at this view: if {cutter} hides the subject, move the camera aside or the object out of the sightline",
+ kind="camera_target_blocked", view=name, target_hit_m=t_hit, target_distance_m=t_dist, cutter=cutter))
eye = _num(chk, "eye_height_m")
below = _num(chk, "ground_below_m")
- if authored and below is not None:
+ above_g = _num(chk, "ground_above_m")
+ if authored and above_g is not None:
+ # A ground surface straight above the lens: a camera under the terrain looks up at back
+ # faces, so its frame renders "fine" (structures floating over a void) — cmp6's
+ # lighthouse shot its slipway from under the headland for three rounds. The camera
+ # repair lifts it when it runs; this is the verdict when it did not.
+ under = str(chk.get("ground_above_name") or "a ground surface")
+ buried = _frame_looks_buried(chk)
+ out.append(_f(Severity.ERROR if buried else Severity.WARN, name,
+ f"camera is {above_g:.1f} m under {under} — the frame is its underside",
+ "set position[1] = heightAt(x, z) + 1.6 (eye level) — never below the terrain",
+ kind="camera_underground" if buried else "camera_under_ground_mesh",
+ view=name, eye_height_m=eye, ground_above_m=above_g))
+ elif authored and below is not None:
# The ray straight down from the eye (``nearGeometry``): the surface this lens
# actually stands over. Scene-wide ``ground_y`` is the top of the HIGHEST ground
# mesh, and on relief terrain it called a camera at eye level on a low patch an
diff --git a/harness/codeverse/spatial/scene_placement.py b/harness/codeverse/spatial/scene_placement.py
index 9b618377..64c87554 100644
--- a/harness/codeverse/spatial/scene_placement.py
+++ b/harness/codeverse/spatial/scene_placement.py
@@ -433,8 +433,9 @@ def contract_findings(census: dict[str, Any] | None, plan: Any,
out.append(_f(Severity.WARN, short + " — past it the land is the background colour while the unfogged sky "
"stays sharp: a world edge and backdrops floating in the sky",
target="env", kind="fog_short", fog=fog, plan_span_m=round(span, 1),
- hint=f"fog far >= {FOG_FAR_MIN_SPANS:g} x the plan span (the starter's shell fog is scaled to it: "
- "keep `scene.fog = shell.fog`, or lengthen yours) and let the horizon ridge / outskirts close the world"))
+ hint=f"fog far >= {FOG_FAR_MIN_SPANS * span:.0f} m ({FOG_FAR_MIN_SPANS:g} x the plan span; the starter's "
+ "shell fog is scaled to it: keep `scene.fog = shell.fog`, or lengthen yours) and let the horizon "
+ "ridge / outskirts close the world"))
# -- backdrop ring: outdoor worlds must have geometry past the play area
bounds = _plan_bounds(plan)
groups = census.get("groups")
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 39cdf1e0..76aebabe 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -266,6 +266,9 @@ frame_gate_from_renders(renders) -> GateReport # gate "scene_frames"; da
# camera_in_geometry | camera_underground | camera_low | camera_high | content_small; authored cameras → ERROR, orbit rig → WARN
# Δ camera_low / camera_high measure camera_checks.ground_below_m (the ray straight down from the eye, nearGeometry);
# the scene-wide census ground_y is the fallback when nothing lies beneath the lens
+ # Δ 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)
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_metrics.mjs b/harness/runtime_js/lib/host_metrics.mjs
index 5b27d835..27cfccf5 100644
--- a/harness/runtime_js/lib/host_metrics.mjs
+++ b/harness/runtime_js/lib/host_metrics.mjs
@@ -3,7 +3,7 @@
* readback of the render canvas and near-geometry tests for a camera.
*/
-import { nonSolid } from './backdrop.mjs';
+import { classifyBackdrop, nonSolid } from './backdrop.mjs';
export const SAMPLE_W = 96;
export const SAMPLE_H = 54;
@@ -85,12 +85,34 @@ export function eyeInsideMesh(o, eye, THREE) {
return odd >= 4;
}
+/** A sight ray that ends this close is a surface in the lens, not the shot. */
+export const BLOCKED_M = 1.5;
+
+/** A ground-classified mesh at least this wide is terrain, not a floor a shot may sit under. */
+export const TERRAIN_SPAN_M = 40;
+
+/**
+ * The lowest terrain-scale ground surface straight above `eye`, or null. Cast DOWN from
+ * 500 m up and take the last hit above the eye: a FrontSide terrain is back faces to a ray
+ * from beneath, and the Raycaster honours material.side.
+ */
+export function groundAbove(eye, groundMeshes, THREE) {
+ if (!groundMeshes.length) return null;
+ try {
+ const top = eye.clone(); top.y += 500;
+ const down = new THREE.Raycaster(top, new THREE.Vector3(0, -1, 0), 0, 500 - 1e-3);
+ const hits = down.intersectObjects(groundMeshes, false);
+ const h = hits.length ? hits[hits.length - 1] : null;
+ return h ? { distance: +(h.point.y - eye.y).toFixed(3), y: h.point.y, name: h.object.name || h.object.parent?.name || h.object.type } : null;
+ } catch (e) { return null; }
+}
+
/**
* Near-geometry test: centre + 3x3 grid rays from the camera; nearest hit
* distance, plus meshes whose own volume contains the eye (closed rooms,
* back-face culled interiors — `eyeInsideMesh`).
*/
-export function nearGeometry(scene, camera, THREE, limitM = 0.3) {
+export function nearGeometry(scene, camera, THREE, limitM = 0.3, lookAt = null) {
const rc = new THREE.Raycaster();
rc.far = 50;
let nearest = Infinity;
@@ -105,24 +127,28 @@ export function nearGeometry(scene, camera, THREE, limitM = 0.3) {
const pts = [];
for (let gy = -1; gy <= 1; gy++) for (let gx = -1; gx <= 1; gx++) pts.push([gx * 0.6, gy * 0.6]);
let hits = 0;
+ let nearRays = 0;
for (const [x, y] of pts) {
rc.setFromCamera(new THREE.Vector2(x, y), camera);
let hit = null;
try { hit = rc.intersectObjects(targets, false)[0]; } catch (e) { hit = null; }
if (hit) {
hits += 1;
+ if (hit.distance < BLOCKED_M) nearRays += 1;
if (hit.distance < nearest) { nearest = hit.distance; nearestName = hit.object.name || hit.object.parent?.name || hit.object.type; }
}
}
const inside = [];
const eye = camera.position;
const box = new THREE.Box3();
+ const groundMeshes = [];
for (const o of targets) {
if (o.isInstancedMesh) continue;
if (!o.geometry) continue;
if (!o.geometry.boundingBox) o.geometry.computeBoundingBox();
box.copy(o.geometry.boundingBox).applyMatrix4(o.matrixWorld);
const s = box.getSize(new THREE.Vector3());
+ if (Math.max(s.x, s.z) >= TERRAIN_SPAN_M && classifyBackdrop(o, box) === 'ground') groundMeshes.push(o);
if (Math.max(s.x, s.y, s.z) > 60 || Math.min(s.x, s.y, s.z) < 0.05) continue; // ground/sky/flat decals
// The bbox is the cheap pre-filter; the verdict is the mesh's own volume. A windmill's
// 22 m lattice sails own a 22 x 22 m bbox that is nearly all air: measured 2026-09-07
@@ -143,6 +169,27 @@ export function nearGeometry(scene, camera, THREE, limitM = 0.3) {
const h = down.intersectObjects(targets, false)[0];
if (h) { groundBelow = +h.distance.toFixed(3); groundBelowName = h.object.name || h.object.parent?.name || h.object.type; }
} catch (e) { groundBelow = null; }
+ // …and a ground surface ABOVE the lens: a camera under the terrain looks up at back faces,
+ // so the frame renders "fine" (the structures float over a void) and nothing said buried —
+ // cmp6's lighthouse (2026-09-09) shot its slipway from under the headland for three rounds
+ // while the judge called it major each time. Ground-classified meshes only (backdrop.mjs):
+ // a roof or a bridge deck overhead is a shot, a terrain overhead is a bug.
+ const above = groundAbove(eye, groundMeshes, THREE);
+ // The line of sight to the plan's lookAt: what cuts it, and how far along. cmp6's crypt
+ // (2026-09-09): AthanorDetail's ray to the hero met VaultPillarMasonry at 0.9 m of 2.8 m,
+ // the hero was never in frame, and the judge called IT "a massive untextured grey box".
+ let targetDist = null, targetHit = null, targetHitName = '';
+ if (Array.isArray(lookAt) && lookAt.length === 3) {
+ const to = new THREE.Vector3(lookAt[0], lookAt[1], lookAt[2]).sub(eye);
+ targetDist = +to.length().toFixed(3);
+ if (targetDist > 1e-6) {
+ try {
+ const los = new THREE.Raycaster(eye.clone(), to.clone().normalize(), 0, targetDist);
+ const h = los.intersectObjects(targets, false)[0];
+ if (h) { targetHit = +h.distance.toFixed(3); targetHitName = h.object.name || h.object.parent?.name || h.object.type; }
+ } catch (e) { targetHit = null; }
+ }
+ }
const center = new THREE.Vector3();
camera.getWorldDirection(center);
return {
@@ -155,6 +202,13 @@ export function nearGeometry(scene, camera, THREE, limitM = 0.3) {
eye_height_m: +eye.y.toFixed(3),
ground_below_m: groundBelow,
ground_below_name: groundBelowName,
+ ground_above_m: above ? above.distance : null,
+ ground_above_name: above ? above.name : '',
+ near_rays: nearRays,
+ near_limit_m: BLOCKED_M,
+ target_distance_m: targetDist,
+ target_hit_m: targetHit,
+ target_hit_name: targetHitName,
look_dir: [center.x, center.y, center.z].map((v) => +v.toFixed(3)),
};
}
@@ -179,6 +233,7 @@ 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;
+const EYE_ABOVE_GROUND_M = 1.6;
export function repairCameraSpec(scene, spec, THREE, makeCam) {
const dir = new THREE.Vector3(
@@ -186,17 +241,25 @@ export function repairCameraSpec(scene, spec, THREE, makeCam) {
if (dir.lengthSq() < 1e-9) dir.set(0, 0, 1);
dir.normalize();
let before = null;
+ // A lens under a ground surface (terrain overhead) is lifted to eye level above it first —
+ // no backward retreat clears that, and the plan's camera is nobody else's to move.
+ let lift = 0;
+ let underBefore = '';
+ {
+ const n0 = nearGeometry(scene, makeCam(spec), THREE);
+ before = n0;
+ if (n0.ground_above_m !== null) { lift = n0.ground_above_m + EYE_ABOVE_GROUND_M; underBefore = n0.ground_above_name; }
+ }
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 pos = [spec.position[0] + dir.x * back, spec.position[1] + dir.y * back + up + lift, spec.position[2] + dir.z * back];
const candidate = { ...spec, position: pos };
- const n = nearGeometry(scene, makeCam(candidate), THREE);
- if (before === null) before = n;
+ const n = lift === 0 && back === 0 && up === 0 ? before : nearGeometry(scene, makeCam(candidate), THREE);
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,
+ if (back === 0 && up === 0 && lift === 0) return null; // the authored camera is fine: no repair
+ return { spec: candidate, name: spec.name || '', moved_back_m: back, moved_up_m: +(up + lift).toFixed(3),
nearest_before: before.nearest_hit_m, inside_before: before.inside_mesh_bbox,
- nearest_after: n.nearest_hit_m };
+ under_before: underBefore, 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/scene_host.mjs b/harness/runtime_js/lib/scene_host.mjs
index 631c6b59..74b6e273 100644
--- a/harness/runtime_js/lib/scene_host.mjs
+++ b/harness/runtime_js/lib/scene_host.mjs
@@ -379,7 +379,7 @@ function buildCamera(spec) {
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 });
+ under_before: fix.under_before || '', nearest_after: fix.nearest_after });
}
const fixed = state.repairedSpecs.get(key);
if (fixed) return buildCameraRaw(fixed);
@@ -472,7 +472,7 @@ function cameraRepairs() {
function cameraChecks(spec) {
const cam = buildCamera(spec);
state.scene.updateMatrixWorld(true);
- const near = nearGeometry(state.scene, cam, THREE);
+ const near = nearGeometry(state.scene, cam, THREE, undefined, Array.isArray(spec.lookAt) ? spec.lookAt : null);
renderOnce(cam);
const stats = frameStats(state.canvas);
let coverage = {};
diff --git a/harness/tests/scene_gates/test_frame_metrics.py b/harness/tests/scene_gates/test_frame_metrics.py
index baa17978..f579e170 100644
--- a/harness/tests/scene_gates/test_frame_metrics.py
+++ b/harness/tests/scene_gates/test_frame_metrics.py
@@ -74,6 +74,37 @@ def test_camera_in_geometry_and_near_hit():
assert "Tower" in rep.findings[0].message and "0.5 m" in rep.findings[0].fix_hint
+def test_a_lens_whose_sight_rays_end_within_reach_is_blocked():
+ """cmp6's crypt (2026-09-09): a squat pillar 0.8 m before AthanorDetail filled the frame and
+ the judge called the hidden hero "a massive untextured grey box" for two rounds."""
+ rep = frame_findings(_metrics(_chk("AthanorDetail", nearest_hit_m=0.8, nearest_hit_name="StonePillar_3", near_rays=7, rays_total=9,
+ near_limit_m=1.5),
+ _chk("WorkTable", nearest_hit_m=0.9, nearest_hit_name="Bench", near_rays=2, rays_total=9),
+ _chk("overview_top", kind="overview", nearest_hit_m=0.8, near_rays=9, rays_total=9)))
+ assert [(k, s, t) for k, s, t in _kinds(rep)] == [("camera_blocked", Severity.ERROR, "AthanorDetail")]
+ assert "StonePillar_3" in rep.findings[0].message and not rep.passed
+ # the measured crypt shape: only 3 of 9 rays end within reach, but the line of sight to the
+ # hero is cut at 0.9 m of 2.8 m — a WARN that names the pillar; a close-up meets its own
+ # subject near the full distance and stays quiet
+ cut = frame_findings(_metrics(_chk("AthanorDetail", nearest_hit_m=0.897, near_rays=3, rays_total=9, target_distance_m=2.8,
+ target_hit_m=0.9, target_hit_name="VaultPillarMasonry"),
+ _chk("HeroCloseUp", nearest_hit_m=1.1, near_rays=4, rays_total=9, target_distance_m=1.6,
+ target_hit_m=1.15, target_hit_name="Athanor")))
+ assert [(k, s, t) for k, s, t in _kinds(cut)] == [("camera_target_blocked", Severity.WARN, "AthanorDetail")]
+ assert "VaultPillarMasonry" in cut.findings[0].message and cut.passed
+
+
+def test_a_lens_under_a_ground_surface_is_named_even_when_its_frame_looks_fine():
+ """cmp6's lighthouse: SlipwaySurge under the headland for three rounds, the frame 'fine'."""
+ rep = frame_findings(_metrics(_chk("SlipwaySurge", eye_height_m=2.0, ground_below_m=2.0, ground_below_name="Sea",
+ ground_above_m=1.4, ground_above_name="HeadlandTerrain"), ground_y=4.8))
+ assert [(k, s) for k, s, _ in _kinds(rep)] == [("camera_under_ground_mesh", Severity.WARN)]
+ assert "HeadlandTerrain" in rep.findings[0].message
+ buried = frame_findings(_metrics(_chk("SlipwaySurge", ground_above_m=1.4, ground_above_name="HeadlandTerrain",
+ mean_lum=0.03, dark_frac=0.9), ground_y=4.8))
+ assert "camera_underground" in [k for k, _, _ in _kinds(buried)] and not buried.passed
+
+
def test_eye_height_is_measured_under_the_lens_when_the_census_has_it():
"""Relief terrain: a camera at eye level over a low patch is not an ant. Loop 21's ski
station (2026-09-09): eye 3.20 m, the highest snow 3.14 m → "0.06 m above ground —
diff --git a/harness/tests/scene_runtime/test_camera_inside_volume.py b/harness/tests/scene_runtime/test_camera_inside_volume.py
index 608be62d..e005156b 100644
--- a/harness/tests/scene_runtime/test_camera_inside_volume.py
+++ b/harness/tests/scene_runtime/test_camera_inside_volume.py
@@ -31,7 +31,7 @@ const cam = new THREE.PerspectiveCamera(50, 16 / 9, 0.1, 500);
cam.position.set(EYE);
cam.lookAt(0, 8, 0);
cam.updateMatrixWorld(true);
-console.log(JSON.stringify(nearGeometry(scene, cam, THREE)));
+console.log(JSON.stringify(nearGeometry(scene, cam, THREE, undefined, LOOKAT)));
"""
# four 11 m lattice arms on a hub 12 m up, the sail plane turned 45 deg so the world bbox is a
@@ -57,9 +57,21 @@ const mound = new THREE.Mesh(new THREE.BoxGeometry(10, 3, 10), solid);
mound.name = 'SnowMound'; mound.position.set(30, 1.5, 30); scene.add(mound);
"""
+# a squat 1.2 m stone pillar 0.8 m in front of the lens (cmp6's crypt AthanorDetail)
+PILLAR = """
+const pillar = new THREE.Mesh(new THREE.BoxGeometry(1.2, 3.2, 1.2), solid);
+pillar.name = 'StonePillar_3'; pillar.position.set(0, 1.6, -1.4); scene.add(pillar);
+"""
+
+# a 60 m headland terrain 1.4 m ABOVE the lens (cmp6's lighthouse SlipwaySurge)
+HEADLAND = """
+const head = new THREE.Mesh(new THREE.PlaneGeometry(60, 60, 2, 2), solid);
+head.name = 'HeadlandTerrain'; head.rotation.x = -Math.PI / 2; head.position.y = 3.0; scene.add(head);
+"""
-def _run(body: str, eye: str) -> dict:
- return run_node_json(JS.replace("BODY", body).replace("EYE", eye).replace("'./lib/", f"'{RUNTIME_JS}/lib/"))
+
+def _run(body: str, eye: str, look_at: str = "null") -> dict:
+ return run_node_json(JS.replace("BODY", body).replace("EYE", eye).replace("LOOKAT", look_at).replace("'./lib/", f"'{RUNTIME_JS}/lib/"))
def test_a_lens_near_lattice_sails_is_not_inside_them():
@@ -89,3 +101,25 @@ def test_the_ground_under_the_lens_is_the_ray_straight_down_not_the_highest_grou
assert abs(got["ground_below_m"] - 1.6) < 1e-3 and got["ground_below_name"] == "Ground", got
void = _run(MOUND, "60, 1.6, 60") # off the 80 x 80 m ground: nothing beneath the lens
assert void["ground_below_m"] is None, void
+
+
+def test_a_surface_filling_the_lens_counts_its_near_sight_rays():
+ JS_PILLAR = JS.replace("cam.lookAt(0, 8, 0);", "cam.lookAt(0, 1.6, -10);")
+ got = run_node_json(JS_PILLAR.replace("BODY", PILLAR).replace("EYE", "0, 1.6, 0").replace("LOOKAT", "[0, 1.6, -4]")
+ .replace("'./lib/", f"'{RUNTIME_JS}/lib/"))
+ assert got["near_rays"] >= 6 and got["near_limit_m"] == 1.5 and got["nearest_hit_name"] == "StonePillar_3", got
+ assert got["camera_in_geometry"] is False, got # 0.8 m away is not "inside": a different verdict
+ # the line of sight to a subject 4 m away is cut by the pillar at 0.8 m
+ assert abs(got["target_distance_m"] - 4.0) < 1e-3 and abs(got["target_hit_m"] - 0.8) < 1e-3, got
+ assert got["target_hit_name"] == "StonePillar_3", got
+ clear = run_node_json(JS_PILLAR.replace("BODY", "").replace("EYE", "0, 1.6, 0").replace("LOOKAT", "[0, 1.6, -4]")
+ .replace("'./lib/", f"'{RUNTIME_JS}/lib/"))
+ assert clear["near_rays"] == 0 and clear["target_hit_m"] is None, clear
+
+
+def test_a_ground_surface_above_the_lens_is_reported():
+ got = _run(HEADLAND, "0, 1.6, 0")
+ assert abs(got["ground_above_m"] - 1.4) < 1e-3 and got["ground_above_name"] == "HeadlandTerrain", got
+ assert abs(got["ground_below_m"] - 1.6) < 1e-3, got
+ open_air = _run(MOUND, "0, 1.6, 0")
+ assert open_air["ground_above_m"] is None, open_air
diff --git a/harness/tests/scene_runtime/test_camera_repair.py b/harness/tests/scene_runtime/test_camera_repair.py
index 585ccc8a..65bfd390 100644
--- a/harness/tests/scene_runtime/test_camera_repair.py
+++ b/harness/tests/scene_runtime/test_camera_repair.py
@@ -35,7 +35,14 @@ 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 }));
+// a lens under a 60 m terrain raised to y = 3 (cmp6's lighthouse SlipwaySurge): lifted to eye level above it
+const head = new THREE.Mesh(new THREE.PlaneGeometry(60, 60, 2, 2), mat);
+head.name = 'HeadlandTerrain'; head.rotation.x = -Math.PI / 2; head.position.set(0, 3.0, -40); scene.add(head);
+scene.updateMatrixWorld(true);
+const buried = { name: 'SlipwaySurge', position: [5, 1.6, -40], lookAt: [0, 4.0, -30], fov: 45 };
+const lifted = repairCameraSpec(scene, buried, THREE, makeCam);
+const liftedAfter = lifted ? nearGeometry(scene, makeCam(lifted.spec), THREE) : null;
+console.log(JSON.stringify({ fix, after, noFix, lifted, liftedAfter }));
"""
@@ -56,3 +63,11 @@ def test_a_lens_inside_geometry_retreats_until_clear(result):
def test_a_clear_camera_is_left_exactly_as_authored(result):
assert result["noFix"] is None
+
+
+def test_a_lens_under_a_ground_surface_is_lifted_to_eye_level_above_it(result):
+ lifted = result["lifted"]
+ assert lifted is not None and lifted["under_before"] == "HeadlandTerrain", lifted
+ assert abs(lifted["spec"]["position"][1] - (3.0 + 1.6)) < 1e-6, lifted # terrain at 3 m + 1.6 m eye
+ after = result["liftedAfter"]
+ assert after["ground_above_m"] is None and abs(after["ground_below_m"] - 1.6) < 1e-3, after