Skip to content

Official Codebase of 3DCodeVerse

Python

placement gate: a ring of same-size copies stamped evenly round the world is measured (census stamps → stamped_ring WARN)

gaoypeng2bbaa05b6c2c
diff --git a/harness/codeverse/spatial/scene_placement.py b/harness/codeverse/spatial/scene_placement.py
index 64c87554..fc4dca57 100644
--- a/harness/codeverse/spatial/scene_placement.py
+++ b/harness/codeverse/spatial/scene_placement.py
@@ -305,6 +305,13 @@ DENSITY_MIN_BUDGET = 20
#: arm while the plan's env contract demands a silhouette ring at ~0.6 x fog-far
#: (well beyond bounds); 1.25x the half-extent is a deliberately lenient floor.
BACKDROP_REACH_FACTOR = 1.25
+#: stamped ring (host_census `stamps`): copies, where the ring sits relative to the plan's
+#: half-extent, and how even / alike it must be before it is called stamped
+RING_MIN_COPIES = 8
+RING_BACKDROP_FRAC = 0.6
+RING_RADIUS_CV_MAX = 0.08
+RING_GAP_CV_MAX = 0.25
+RING_SIZE_CV_MAX = 0.05
BACKDROP_MIN_HEIGHT_M = 2.0
@@ -436,8 +443,33 @@ def contract_findings(census: dict[str, Any] | None, plan: Any,
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
+ # -- a stamped ring: >= 8 same-size copies evenly on a circle round the world's edge.
+ # Five of six exteriors on 2026-09-09 drew their horizon as "a ring of identical cones
+ # stamped round the perimeter" / "rocks in a perfect circle" and the judge called each a
+ # toy backdrop, twice. The census measures the ring (host_census `stamps`); a rotunda's
+ # columns or chairs round a table sit INSIDE the content and are not it.
bounds = _plan_bounds(plan)
+ if bounds and isinstance(census.get("groups"), list):
+ lo, hi = bounds
+ half = max(hi[0] - lo[0], hi[2] - lo[2]) / 2
+ for g in census["groups"]:
+ for st in (g.get("stamps") if isinstance(g, dict) else None) or []:
+ if not isinstance(st, dict):
+ continue
+ n, r = int(st.get("n") or 0), float(st.get("radius_m") or 0)
+ rcv, gcv, scv = (float(st.get(k) or 0) for k in ("radius_cv", "gap_cv", "size_cv"))
+ if (n >= RING_MIN_COPIES and half > 0 and r >= RING_BACKDROP_FRAC * half
+ and rcv <= RING_RADIUS_CV_MAX and gcv <= RING_GAP_CV_MAX and scv <= RING_SIZE_CV_MAX):
+ where = f"{g.get('name', '?')}/{st.get('name', '?')}"
+ out.append(_f(Severity.WARN,
+ f"{where}: {n} same-size copies stamped evenly on a {r:.0f} m ring round the world "
+ f"(radius spread {rcv:.0%}, spacing spread {gcv:.0%}, size spread {scv:.0%}) — a toy backdrop",
+ target=str(g.get("name", "overall")), kind="stamped_ring", n=n, radius_m=r,
+ radius_cv=rcv, gap_cv=gcv, size_cv=scv,
+ hint="vary them — at least 3 silhouettes, scale 0.6-1.6x, radius +-25 %, random yaw, "
+ "clusters rather than a ring — or drop the ring and let the starter's worldShell "
+ "ridge and makeOutskirts hills close the horizon"))
+ # -- backdrop ring: outdoor worlds must have geometry past the play area
groups = census.get("groups")
if bounds and isinstance(groups, list) and not is_interior(plan):
lo, hi = bounds
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 9114defe..73456fa8 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -271,6 +271,8 @@ frame_gate_from_renders(renders) -> GateReport # gate "scene_frames"; da
# when the frame agrees: a terrain-scale ground surface straight above the eye, ground_above_m; the camera repair lifts it)
# Δ hero_unseen (ERROR: a loaded GLB in the scene fills < 0.5 % of every authored frame — camera_checks[].glb_frac, one mask
# 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)
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_census.mjs b/harness/runtime_js/lib/host_census.mjs
index 4358c199..cc4b8e0f 100644
--- a/harness/runtime_js/lib/host_census.mjs
+++ b/harness/runtime_js/lib/host_census.mjs
@@ -26,6 +26,34 @@ function boxToJson(box) {
};
}
+const STAMP_MIN = 8; // copies before a family's ring / size statistics are worth reporting
+const STAMPS_PER_GROUP = 6;
+
+/**
+ * How a family of placed copies sits: evenly on a circle round their centroid, and all one
+ * size? `points` are world [x, y, z] per copy, `sizes` their largest extents. Null below
+ * STAMP_MIN. The day's tally (2026-09-09, five of six exteriors): "a ring of identical cones
+ * stamped round the perimeter", "rocks in a perfect circle" — a backdrop the judge calls a toy,
+ * and one the census can see: radius spread, angular spread, size spread.
+ */
+export function stampStats(points, sizes) {
+ const n = points.length;
+ if (n < STAMP_MIN) return null;
+ let cx = 0, cz = 0;
+ for (const [x, , z] of points) { cx += x; cz += z; }
+ cx /= n; cz /= n;
+ const cv = (v) => {
+ const m = v.reduce((s, x) => s + x, 0) / v.length;
+ if (m <= 1e-9) return 0;
+ return Math.sqrt(v.reduce((s, x) => s + (x - m) ** 2, 0) / v.length) / m;
+ };
+ const radii = points.map(([x, , z]) => Math.hypot(x - cx, z - cz));
+ const angles = points.map(([x, , z]) => Math.atan2(z - cz, x - cx)).sort((a, b) => a - b);
+ const gaps = angles.map((a, i) => (i ? a - angles[i - 1] : a + 2 * Math.PI - angles[n - 1]));
+ const r = radii.reduce((s, x) => s + x, 0) / n;
+ return { n, radius_m: +r.toFixed(2), radius_cv: +cv(radii).toFixed(3), gap_cv: +cv(gaps).toFixed(3), size_cv: +cv(sizes).toFixed(3) };
+}
+
function walkGroup(root, THREE) {
let meshes = 0, instances = 0, tris = 0, lights = 0, custom = 0;
const kinds = { sky: 0, ground: 0, content: 0 };
@@ -33,6 +61,14 @@ function walkGroup(root, THREE) {
const boxAll = new THREE.Box3(); // everything drawable
const groundBox = new THREE.Box3();
const tmp = new THREE.Box3();
+ const families = new Map(); // family name -> { points, sizes } of its placed copies
+ const copy = (family, b) => {
+ if (!families.has(family)) families.set(family, { points: [], sizes: [] });
+ const f = families.get(family);
+ const size = b.getSize(new THREE.Vector3());
+ f.points.push([(b.min.x + b.max.x) / 2, (b.min.y + b.max.y) / 2, (b.min.z + b.max.z) / 2]);
+ f.sizes.push(Math.max(size.x, size.y, size.z));
+ };
root.updateMatrixWorld(true);
root.traverse((o) => {
if (!o.visible) return;
@@ -55,9 +91,11 @@ function walkGroup(root, THREE) {
o.getMatrixAt(i, m);
tmp.copy(gb).applyMatrix4(m).applyMatrix4(o.matrixWorld);
mb.union(tmp);
+ copy(o.name || 'instances', tmp);
}
} else {
mb.copy(gb).applyMatrix4(o.matrixWorld);
+ copy((o.name || '').replace(/[_.]\d+$/, '') || 'meshes', mb);
}
if (mb.isEmpty()) return;
const kind = classifyBackdrop(o, mb); // shared rules (lib/backdrop.mjs); no content bbox yet here
@@ -67,7 +105,13 @@ function walkGroup(root, THREE) {
if (kind === 'ground') groundBox.union(mb);
});
const kind = kinds.content ? 'content' : kinds.ground ? 'ground' : kinds.sky ? 'sky' : (lights && !meshes ? 'light' : 'empty');
- return { meshes, instances, tris, lights, custom, box, boxAll, groundBox, kind, kinds };
+ const stamps = [];
+ for (const [name, f] of families) {
+ const st = stampStats(f.points, f.sizes);
+ if (st) stamps.push({ name, ...st });
+ }
+ stamps.sort((a, b) => b.n - a.n);
+ return { meshes, instances, tris, lights, custom, box, boxAll, groundBox, kind, kinds, stamps: stamps.slice(0, STAMPS_PER_GROUP) };
}
function overlapStats(groups) {
@@ -123,7 +167,7 @@ export function sceneCensus(scene, THREE, opts = {}) {
groups.push({
name, named: !!child.name, type: child.type, kind: g.kind, meshes: g.meshes, instances: g.instances,
triangles: g.tris, lights: g.lights, custom_shader_meshes: g.custom, mesh_kinds: g.kinds,
- bbox: boxToJson(g.kind === 'content' ? g.box : g.boxAll),
+ bbox: boxToJson(g.kind === 'content' ? g.box : g.boxAll), stamps: g.stamps,
});
totals.meshes += g.meshes; totals.instances += g.instances; totals.triangles += g.tris; totals.lights += g.lights; totals.custom_shader_meshes += g.custom;
if (!g.boxAll.isEmpty()) unionAll.union(g.boxAll);
diff --git a/harness/tests/scene_gates/test_placement.py b/harness/tests/scene_gates/test_placement.py
index 996cdaec..694e38de 100644
--- a/harness/tests/scene_gates/test_placement.py
+++ b/harness/tests/scene_gates/test_placement.py
@@ -323,3 +323,21 @@ def test_no_backdrop_fires_outdoors_and_stays_quiet_with_a_ring_or_indoors():
rep = placement_gate_safe(near_only, plan=indoor, layouts=None)
assert not [f for f in rep.findings if f.data.get("kind") == "no_backdrop"]
+
+
+def test_a_ring_of_identical_copies_round_the_world_is_warned_but_not_a_rotunda():
+ """2026-09-09, five of six exteriors: "a ring of identical cones stamped round the perimeter"
+ — the census measures the ring (host_census `stamps`); columns round a rotunda sit inside
+ the content and are architecture."""
+ plan = _contract_plan() # 40 m half-extent
+ ring = {"name": "FarPeaks", "n": 16, "radius_m": 36.0, "radius_cv": 0.01, "gap_cv": 0.02, "size_cv": 0.0}
+ census = {"fog": {"type": "Fog", "near": 10, "far": 120}, "background": "#aabbcc",
+ "placement": _table(_row("Lantern", h=0.6), _row("Bench", h=0.9), _row("BenchB", zone="House", h=0.9)),
+ "groups": [{"name": "FarShore", "kind": "content", "stamps": [ring]}]}
+ hits = [f for f in placement_gate_safe(census, plan=plan).findings if f.data.get("kind") == "stamped_ring"]
+ assert len(hits) == 1 and hits[0].severity == Severity.WARN and "FarShore/FarPeaks: 16 same-size copies" in hits[0].message
+ assert "36 m ring" in hits[0].message and "silhouettes" in hits[0].fix_hint
+ census["groups"][0]["stamps"] = [dict(ring, size_cv=0.3, radius_cv=0.2)] # varied: a real skyline
+ assert not [f for f in placement_gate_safe(census, plan=plan).findings if f.data.get("kind") == "stamped_ring"]
+ census["groups"][0]["stamps"] = [dict(ring, name="Column", n=12, radius_m=4.0)] # a rotunda: inside the content
+ assert not [f for f in placement_gate_safe(census, plan=plan).findings if f.data.get("kind") == "stamped_ring"]
diff --git a/harness/tests/scene_runtime/test_census_stamps.py b/harness/tests/scene_runtime/test_census_stamps.py
new file mode 100644
index 00000000..424b4b48
--- /dev/null
+++ b/harness/tests/scene_runtime/test_census_stamps.py
@@ -0,0 +1,58 @@
+"""The census measures a stamped ring: >= 8 copies of a family, how evenly they sit on a circle
+round their centroid and how alike their sizes are (`groups[].stamps`, 2026-09-09)."""
+
+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 { sceneCensus } from './lib/host_census.mjs';
+const scene = new THREE.Scene();
+const zone = new THREE.Group(); zone.name = 'FarShore'; scene.add(zone);
+const mat = new THREE.MeshStandardMaterial();
+// 16 cones on a ring: an InstancedMesh (JITTER = 0 → a perfect stamp)
+const peaks = new THREE.InstancedMesh(new THREE.ConeGeometry(4, 12, 6), mat, 16); peaks.name = 'Peaks';
+const d = new THREE.Object3D();
+for (let i = 0; i < 16; i++) {
+ const a = (i / 16) * Math.PI * 2 + JITTER * Math.sin(i * 7.3);
+ const r = 120 * (1 + JITTER * Math.cos(i * 3.1));
+ d.position.set(Math.cos(a) * r, 6, Math.sin(a) * r); d.scale.setScalar(1 + JITTER * 2 * Math.sin(i * 5.7)); d.updateMatrix();
+ peaks.setMatrixAt(i, d.matrix);
+}
+zone.add(peaks);
+// 10 numbered plain meshes on a small circle (a rotunda's columns): a family by name
+for (let i = 0; i < 10; i++) {
+ const c = new THREE.Mesh(new THREE.CylinderGeometry(0.3, 0.3, 4, 8), mat); c.name = 'Column_' + i;
+ const a = (i / 10) * Math.PI * 2; c.position.set(Math.cos(a) * 5, 2, Math.sin(a) * 5); zone.add(c);
+}
+scene.updateMatrixWorld(true);
+const g = sceneCensus(scene, THREE).groups.find((x) => x.name === 'FarShore');
+console.log(JSON.stringify(g.stamps));
+"""
+
+
+def _stamps(jitter: float) -> dict[str, dict]:
+ rows = run_node_json(JS.replace("JITTER", repr(jitter)).replace("'./lib/", f"'{RUNTIME_JS}/lib/"))
+ return {r["name"]: r for r in rows}
+
+
+def test_a_perfect_ring_of_instances_reads_as_stamped():
+ st = _stamps(0.0)
+ peaks = st["Peaks"]
+ assert peaks["n"] == 16 and abs(peaks["radius_m"] - 120) < 1.0, peaks
+ assert peaks["radius_cv"] < 0.01 and peaks["gap_cv"] < 0.01 and peaks["size_cv"] < 0.01, peaks
+ cols = st["Column"] # numbered plain meshes are one family
+ assert cols["n"] == 10 and abs(cols["radius_m"] - 5) < 0.2, cols
+
+
+def test_a_jittered_ring_is_not():
+ peaks = _stamps(0.25)["Peaks"]
+ assert peaks["radius_cv"] > 0.1 and peaks["size_cv"] > 0.1, peaks