Official Codebase of 3DCodeVerse
Python
scene: plan-aware contract checks — atmosphere, dressing, scale, bounds
gaoypengbca2b84e831f
diff --git a/harness/codeverse/spatial/scene_placement.py b/harness/codeverse/spatial/scene_placement.pyindex c3ff76ba..22209aae 100644--- a/harness/codeverse/spatial/scene_placement.py+++ b/harness/codeverse/spatial/scene_placement.py@@ -192,7 +192,15 @@ def _asset_findings(rows: list[AssetRow], *, floating_m: float, ground_y: floatdef _pair_findings(pairs: list[Interpenetration]) -> list[GateFinding]:out: list[GateFinding] = []+ # one finding per PAIR OF NAMES, keeping the worst overlap: a zone that stamps four+ # TerracottaPlanters against one arbour used to yield four identical ERRORs+ # (measured on t36_santorini) and flood the refine prompt with one fact+ best: dict[tuple[str, str], Interpenetration] = {}for p in pairs:+ key = tuple(sorted((f"{p.zone_a}/{p.a}", f"{p.zone_b}/{p.b}")))+ if key not in best or p.aabb_overlap > best[key].aabb_overlap:+ best[key] = p+ for p in best.values():qa = f"{p.zone_a}/{p.a}" if p.zone_a else p.aqb = f"{p.zone_b}/{p.b}" if p.zone_b else p.bsev = Severity.ERROR if p.aabb_overlap > OVERLAP_ERROR else Severity.WARN@@ -243,6 +251,136 @@ def placement_findings(table: dict[str, Any] | PlacementTable, *, indoor: bool =return GateReport(gate=GATE, passed=passed, findings=findings, duration_ms=duration_ms)+# --------------------------------------------------------------------------- plan-aware checks+#: measured 2026-08-30 across the 48 scored runs of the four scene batteries: the top+#: standing defects are exactly the ones nothing measured — thin_atmosphere 32/48 and+#: undressed_scene 31/48 while the census already records ``fog`` / ``background`` and+#: every placed asset's name, zone and bbox. These checks are pure functions of the+#: census + the plan; their ERRORs route into refine with the zone as the target.+SCALE_WARN, SCALE_ERROR = 2.5, 4.0+BOUNDS_MARGIN_MIN_M = 2.0+++def _plan_zones(plan: Any) -> list[tuple[str, list[str]]]:+ zones = (plan.get("zones") if isinstance(plan, dict) else getattr(plan, "zones", None)) or []+ out = []+ for z in zones:+ name = z.get("name") if isinstance(z, dict) else getattr(z, "name", "")+ contents = (z.get("contents") if isinstance(z, dict) else getattr(z, "contents", None)) or []+ if name:+ out.append((str(name), [str(c) for c in contents]))+ return out+++def _plan_asset_sizes(plan: Any) -> dict[str, float]:+ assets = (plan.get("assets") if isinstance(plan, dict) else getattr(plan, "assets", None)) or []+ out: dict[str, float] = {}+ for a in assets:+ name = a.get("name") if isinstance(a, dict) else getattr(a, "name", "")+ size = (a.get("approx_size_m") if isinstance(a, dict) else getattr(a, "approx_size_m", None)) or ()+ try:+ m = max(float(v) for v in size)+ except (TypeError, ValueError):+ continue+ if name and m > 0.05:+ out[to_snake(name)] = m+ return out+++def _plan_bounds(plan: Any) -> tuple[tuple[float, ...], tuple[float, ...]] | None:+ b = plan.get("bounds") if isinstance(plan, dict) else getattr(plan, "bounds", None)+ if b is None:+ return None+ try:+ if isinstance(b, dict):+ c, e = b.get("center"), b.get("extents")+ lo = tuple(float(c[i]) - float(e[i]) / 2 for i in range(3))+ hi = tuple(float(c[i]) + float(e[i]) / 2 for i in range(3))+ return lo, hi+ return tuple(map(float, b.min)), tuple(map(float, b.max))+ except (TypeError, ValueError, IndexError, AttributeError):+ return None+++def contract_findings(census: dict[str, Any] | None, plan: Any) -> list[GateFinding]:+ """Deterministic plan-vs-census checks: env atmosphere present, every zone dressed+ with its planned contents, plausible scale, content inside the world bounds."""+ if not isinstance(census, dict) or plan is None:+ return []+ out: list[GateFinding] = []+ # -- atmosphere: the two env facts the census measures on every boot+ if "fog" in census and census.get("fog") is None:+ out.append(_f(Severity.ERROR, "scene.fog is not set — frames read as thin_atmosphere (32/48 measured runs)",+ target="env", kind="no_fog",+ hint="in buildEnv set scene.fog = new THREE.Fog(<sky horizon hex>, near, far) with the plan's numbers"))+ if "background" in census and census.get("background") is None:+ out.append(_f(Severity.ERROR, "scene.background is not set (renders on the raw clear colour)",+ target="env", kind="no_background",+ hint="in buildEnv set scene.background to the sky colour or sky texture the plan names"))+ table = census.get("placement") if isinstance(census.get("placement"), dict) else None+ rows = [AssetRow.model_validate(r) for r in (table.get("assets") or [])] if table else []+ if not rows:+ return out+ # -- every zone dressed with what the plan put there (names matched loosely on words)+ by_zone: dict[str, list[AssetRow]] = {}+ for r in rows:+ by_zone.setdefault(to_snake(r.zone), []).append(r)+ all_names = " ".join(to_snake(r.name) for r in rows)+ for zone_name, contents in _plan_zones(plan):+ zk = to_snake(zone_name)+ placed = by_zone.get(zk, [])+ if not placed and contents:+ out.append(_f(Severity.ERROR, f"zone {zone_name} placed nothing (plan lists: {', '.join(contents[:6])})",+ target=zone_name, kind="zone_empty",+ hint=f"build the zone group named '{zone_name}' and place its planned contents"))+ continue+ zone_names = " ".join(to_snake(r.name) for r in placed)+ missing = [c for c in contents if to_snake(c) not in zone_names and to_snake(c) not in all_names]+ if missing:+ out.append(_f(Severity.ERROR,+ f"zone {zone_name} is missing planned contents: {', '.join(missing[:5])}"+ + (f" (+{len(missing) - 5} more)" if len(missing) > 5 else ""),+ target=zone_name, kind="missing_content", missing=missing[:8],+ hint="place each listed asset (import its builder / clone its GLB) inside this zone's bbox"))+ # -- plausible scale vs the plan's approx_size_m+ sizes = _plan_asset_sizes(plan)+ for r in rows:+ if r.exempt or not r.bbox or not r.bbox.get("size"):+ continue+ rk = to_snake(r.name)+ key = next((k for k in sizes if k in rk), "")+ if not key:+ continue+ measured = max(float(v) for v in r.bbox["size"])+ f = measured / sizes[key]+ if f > SCALE_ERROR or f < 1 / SCALE_ERROR:+ sev = Severity.ERROR+ elif f > SCALE_WARN or f < 1 / SCALE_WARN:+ sev = Severity.WARN+ else:+ continue+ out.append(_f(sev, f"{r.qualified} measures {measured:.2f} m but the plan sized {key} at ~{sizes[key]:.2f} m ({f:.1f}x)",+ target=r.qualified, kind="scale", factor=round(f, 2), zone=r.zone,+ hint=f"scale {r.name} so its largest dimension is ~{sizes[key]:.2f} m as planned"))+ # -- content inside the world bounds+ bounds = _plan_bounds(plan)+ if bounds:+ lo, hi = bounds+ margin = max(BOUNDS_MARGIN_MIN_M, 0.05 * max(hi[0] - lo[0], hi[2] - lo[2]))+ for r in rows:+ if r.exempt or not r.bbox or not r.bbox.get("min"):+ continue+ bmin, bmax = r.bbox["min"], r.bbox["max"]+ fully_out = (bmin[0] > hi[0] + margin or bmax[0] < lo[0] - margin+ or bmin[2] > hi[2] + margin or bmax[2] < lo[2] - margin)+ if fully_out:+ out.append(_f(Severity.ERROR, f"{r.qualified} sits entirely outside the plan bounds "+ f"(x {bmin[0]:.0f}..{bmax[0]:.0f}, z {bmin[2]:.0f}..{bmax[2]:.0f})",+ target=r.qualified, kind="out_of_bounds", zone=r.zone,+ hint="move it inside the plan bounds or into its zone bbox"))+ return out++def placement_census(ws: Workspace, *, force_probe: bool = False, timeout_s: float = 60.0) -> dict[str, Any]:"""The census dict carrying ``placement``: the last build's ``artifacts/census.json``,or a fresh ``probe_scene`` when it is missing / predates the table / ``force_probe``."""@@ -285,7 +423,13 @@ def placement_gate_safe(census: dict[str, Any] | None, *, plan: Any = None) -> Gtable = (census or {}).get("placement")if not isinstance(table, dict):return None- return placement_findings(table, indoor=infer_indoor(setting_text(plan)))+ report = placement_findings(table, indoor=infer_indoor(setting_text(plan)))+ extra = _cap_per_kind(contract_findings(census, plan))+ if extra:+ findings = report.findings + extra+ passed = not any(f.severity == Severity.ERROR for f in findings)+ report = GateReport(gate=GATE, passed=passed, findings=findings, duration_ms=report.duration_ms)+ return reportexcept Exception as e: # noqa: BLE001 — advisory instrumentation must not fail the roundlog.warning("scene placement gate failed: %s", e)return GateReport(gate=GATE, passed=True, findings=[diff --git a/harness/tests/scene_gates/test_placement.py b/harness/tests/scene_gates/test_placement.pyindex 967f74d9..62929f47 100644--- a/harness/tests/scene_gates/test_placement.py+++ b/harness/tests/scene_gates/test_placement.py@@ -11,7 +11,7 @@ from types import SimpleNamespacefrom codeverse.contracts.artifacts import BuildResult, Severityfrom codeverse.contracts.common import Language-from codeverse.contracts.plan import BBox, CameraPlan, ScenePlan, ZonePlan+from codeverse.contracts.plan import AssetPlan, BBox, CameraPlan, ScenePlan, ZonePlanfrom codeverse.judges.rubrics import apply_caps, load_rubricfrom codeverse.orchestrator import build_refine_instructionsfrom codeverse.spatial.scene_placement import (@@ -175,3 +175,54 @@ def test_check_placement_reads_the_last_census_and_the_table_text(tmp_path):assert not r.passed and "indoor tolerance 2 cm" in r.findings[0].messagetext = placement_table_text(table)assert "Yard/Lantern | +0.300 | Ground | 0.000 | - | - | -" in text and "Yard/Rock | +0.000 | Ground | 0.300 | Terrain" in text+++# --------------------------------------------------------------------- plan-aware contract checks+def _contract_plan() -> ScenePlan:+ bb = BBox(center=(0, 0, 0), extents=(40, 8, 40))+ zb = BBox(center=(0, 0, 0), extents=(20, 8, 20))+ return ScenePlan(+ title="t", summary="s", setting="meadow", mood="calm", bounds=bb, environment="sunny",+ zones=[ZonePlan(name="Yard", description="d", bbox=zb, contents=["Lantern", "Bench"]),+ ZonePlan(name="House", description="d", bbox=zb, contents=["Bench"])],+ assets=[AssetPlan(name="Lantern", kind="threejs", description="d", approx_size_m=(0.4, 0.6, 0.4)),+ AssetPlan(name="Bench", kind="threejs", description="d", approx_size_m=(1.6, 0.9, 0.6))],+ cameras=[CameraPlan(name="overview", position=(1, 1, 1), look_at=(0, 0, 0), fov=50, purpose="p")])+++def test_contract_checks_fire_on_atmosphere_contents_scale_and_bounds():+ """One census, five distinct deterministic failures the VLM used to carry alone."""+ far = _row("FarCrate")+ far["bbox"] = {"min": [100, 0, 100], "max": [101, 1, 101], "size": [1, 1, 1]}+ census = {"fog": None, "background": None,+ "placement": _table(_row("Lantern", h=3.0), far)} # lantern 5x the planned 0.6 m+ rep = placement_gate_safe(census, plan=_contract_plan())+ kinds = {f.data.get("kind") for f in rep.findings}+ assert {"no_fog", "no_background", "missing_content", "zone_empty", "scale", "out_of_bounds"} <= kinds+ assert not rep.passed+ missing = next(f for f in rep.findings if f.data.get("kind") == "missing_content")+ assert missing.target == "Yard" and "Bench" in missing.message+ empty = next(f for f in rep.findings if f.data.get("kind") == "zone_empty")+ assert empty.target == "House"+ scale = next(f for f in rep.findings if f.data.get("kind") == "scale")+ assert scale.severity == Severity.ERROR and "5.0x" in scale.message+++def test_contract_checks_stay_quiet_on_a_dressed_in_bounds_scene():+ census = {"fog": {"type": "Fog", "near": 10, "far": 60}, "background": "#aabbcc",+ "placement": _table(_row("Lantern_3", h=0.6), _row("Bench", h=0.9),+ _row("BenchB", zone="House", h=0.9))}+ rep = placement_gate_safe(census, plan=_contract_plan())+ contract_kinds = {"no_fog", "no_background", "missing_content", "zone_empty", "scale", "out_of_bounds"}+ assert not [f for f in rep.findings if f.data.get("kind") in contract_kinds], [(f.data.get("kind"), f.message) for f in rep.findings]+ assert rep.passed+++def test_interpenetration_pairs_report_once_at_worst_overlap():+ pair = {"a": "Planter", "b": "Arbor", "zone_a": "Yard", "zone_b": "Yard"}+ r = placement_findings(_table(_row("Planter"), _row("Arbor"),+ pairs=[{**pair, "aabb_overlap": 0.3, "inside_frac": 0.2},+ {**pair, "aabb_overlap": 0.7, "inside_frac": 0.6},+ {**pair, "aabb_overlap": 0.5, "inside_frac": 0.4}]))+ inter = _by_kind(r, "interpenetration")+ assert len(inter) == 1 and "70%" in inter[0].message and inter[0].severity == Severity.ERROR