Skip to content

Official Codebase of 3DCodeVerse

Python

frames gate: eye height is measured under the lens (a ray straight down), not against the scene's highest ground

gaoypengbfb2f55de840
diff --git a/harness/codeverse/spatial/frame_metrics.py b/harness/codeverse/spatial/frame_metrics.py
index eb4dc085..8af7ded4 100644
--- a/harness/codeverse/spatial/frame_metrics.py
+++ b/harness/codeverse/spatial/frame_metrics.py
@@ -149,7 +149,25 @@ def _geometry_findings(chk: dict[str, Any], *, authored: bool, ground_y: float |
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]))
eye = _num(chk, "eye_height_m")
- if authored and eye is not None and ground_y is not None:
+ below = _num(chk, "ground_below_m")
+ if 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
+ # "ant's-eye view" (loop 21 ski station: eye 3.20 m, snow mound 3.14 m) — a false
+ # WARN the judge then repeated as a major issue.
+ under = str(chk.get("ground_below_name") or "the surface beneath it")
+ if below < EYE_MIN_ABOVE_GROUND_M:
+ out.append(_f(Severity.WARN, name, f"camera eye only {below:.2f} m above {under} — ant's-eye view",
+ "human shots: position[1] = heightAt(x, z) + 1.6; establishing: 6–20 m above ground looking down 15–30°",
+ kind="camera_low", view=name, eye_height_m=eye, ground_below_m=below))
+ elif below > EYE_MAX_ABOVE_GROUND_M:
+ out.append(_f(Severity.WARN, name, f"camera {below:.0f} m above {under} — satellite view, not a shot",
+ "bring the camera down: establishing 6–20 m above ground at ~1.2 × the content span",
+ kind="camera_high", view=name, eye_height_m=eye, ground_below_m=below))
+ elif authored and eye is not None and ground_y is not None:
+ # Nothing beneath the lens (under the terrain, off the ground's edge) or an older
+ # census: compare with the scene's highest ground surface.
above = eye - ground_y
if above < -0.2:
# ``ground_y`` is the TOP of every ground-classified mesh in the scene (census),
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 52eab04a..39cdf1e0 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -264,6 +264,8 @@ select_judge_views(rs, max_n=10) -> RenderSet # priority: authored@t0,
from codeverse.spatial.frame_metrics import frame_gate_from_renders, frame_findings, frame_summary_text, FRAME_GATE
frame_gate_from_renders(renders) -> GateReport # gate "scene_frames"; data.kind ∈ dark_frame | blown_frame | flat_frame |
# 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
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 5f7ced2d..5b27d835 100644
--- a/harness/runtime_js/lib/host_metrics.mjs
+++ b/harness/runtime_js/lib/host_metrics.mjs
@@ -130,6 +130,19 @@ export function nearGeometry(scene, camera, THREE, limitM = 0.3) {
// three rounds, the repair moved it twice for nothing and the judge marked it critical.
if (box.containsPoint(eye) && eyeInsideMesh(o, eye, THREE)) inside.push(o.name || o.parent?.name || o.type);
}
+ // The surface under the lens: one ray straight down to the nearest solid mesh. The
+ // census ground_y is the TOP of every ground mesh scene-wide, so on relief terrain a
+ // camera at eye level over a low patch read "0.06 m above ground — ant's-eye view"
+ // against a 3.1 m snow mound elsewhere (loop 21 ski station, 2026-09-09) and the judge
+ // repeated the false warning as a major issue. Null when nothing lies beneath (a lens
+ // under the terrain, or off the edge of the ground) — the gate then falls back to ground_y.
+ let groundBelow = null;
+ let groundBelowName = '';
+ try {
+ const down = new THREE.Raycaster(eye.clone(), new THREE.Vector3(0, -1, 0), 0, 500);
+ 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; }
const center = new THREE.Vector3();
camera.getWorldDirection(center);
return {
@@ -140,6 +153,8 @@ export function nearGeometry(scene, camera, THREE, limitM = 0.3) {
inside_mesh_bbox: inside.slice(0, 5),
camera_in_geometry: (Number.isFinite(nearest) && nearest < limitM) || inside.length > 0,
eye_height_m: +eye.y.toFixed(3),
+ ground_below_m: groundBelow,
+ ground_below_name: groundBelowName,
look_dir: [center.x, center.y, center.z].map((v) => +v.toFixed(3)),
};
}
diff --git a/harness/tests/scene_gates/test_frame_metrics.py b/harness/tests/scene_gates/test_frame_metrics.py
index 44bc467a..baa17978 100644
--- a/harness/tests/scene_gates/test_frame_metrics.py
+++ b/harness/tests/scene_gates/test_frame_metrics.py
@@ -74,6 +74,21 @@ 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_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 —
+ ant's-eye view", repeated by the judge as a major issue on a frame shot from 1.6 m."""
+ rep = frame_findings(_metrics(_chk("Hill", eye_height_m=3.2, ground_below_m=1.62, ground_below_name="SnowTerrain"),
+ _chk("Ant", eye_height_m=3.2, ground_below_m=0.06, ground_below_name="SnowTerrain"),
+ _chk("Drone", eye_height_m=98.0, ground_below_m=95.0, ground_below_name="Ground"),
+ ground_y=3.137))
+ assert [(k, s) for k, s, _ in _kinds(rep)] == [("camera_low", Severity.WARN), ("camera_high", Severity.WARN)]
+ assert "SnowTerrain" in rep.findings[0].message and rep.findings[0].data["view"] == "Ant"
+ # nothing beneath the lens (under the terrain / off the ground's edge) → the scene-wide rule
+ under = frame_findings(_metrics(_chk("Under", eye_height_m=-0.5, ground_below_m=None), ground_y=0.0))
+ assert [k for k, _, _ in _kinds(under)] == ["camera_below_high_ground"]
+
+
def test_eye_height_sanity_against_ground():
# a camera below the scene's highest ground surface whose frame renders fine is NOT
# buried — census ground_y is the TOP of every ground mesh, so a hill or a raised bed
diff --git a/harness/tests/scene_runtime/test_camera_inside_volume.py b/harness/tests/scene_runtime/test_camera_inside_volume.py
index bd3b9bd5..608be62d 100644
--- a/harness/tests/scene_runtime/test_camera_inside_volume.py
+++ b/harness/tests/scene_runtime/test_camera_inside_volume.py
@@ -51,6 +51,12 @@ const room = new THREE.Mesh(new THREE.BoxGeometry(6, 3, 6), solid);
room.name = 'CottageShell'; room.position.set(0, 1.5, 0); scene.add(room);
"""
+# a 3 m snow mound 40 m from the lens: the census's highest ground surface, not the ground under the eye
+MOUND = """
+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);
+"""
+
def _run(body: str, eye: str) -> dict:
return run_node_json(JS.replace("BODY", body).replace("EYE", eye).replace("'./lib/", f"'{RUNTIME_JS}/lib/"))
@@ -74,3 +80,12 @@ def test_a_lens_inside_a_solid_arm_is_inside():
got = _run(SAILS, "0, 12, 0") # the hub itself, inside both arms
assert "Sails_1" in got["inside_mesh_bbox"], got
assert got["camera_in_geometry"] is True, got
+
+
+def test_the_ground_under_the_lens_is_the_ray_straight_down_not_the_highest_ground():
+ """Loop 21's ski station (2026-09-09): eye 3.2 m on relief terrain, the highest snow 3.14 m,
+ the gate said "0.06 m above ground — ant's-eye view" and the judge repeated it."""
+ got = _run(MOUND, "0, 1.6, 0")
+ 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