Skip to content

Official Codebase of 3DCodeVerse

Python

conventions: the GLB → authoring-frame mapping is stated once — prompting and the contract gate carried a copy each (Law 2)

gaoypeng72b1a1e97f2f
diff --git a/harness/codeverse3d/conventions.py b/harness/codeverse3d/conventions.py
index 75f18ffa..cdd94646 100644
--- a/harness/codeverse3d/conventions.py
+++ b/harness/codeverse3d/conventions.py
@@ -21,6 +21,7 @@ Frames
from __future__ import annotations
import re
+from collections.abc import Sequence
from dataclasses import dataclass
from enum import StrEnum
@@ -53,6 +54,22 @@ LANGUAGE_FRAME: dict[str, Frame] = {
GLB_FRAME = Frame.Y_UP_POS_Z_FRONT
+def authoring_frame(language: str) -> Frame:
+ """``language``'s authoring frame; an unknown / empty id is the GLB frame itself."""
+ return LANGUAGE_FRAME.get(str(language), GLB_FRAME)
+
+
+def to_authoring_frame(v: Sequence[float], language: str, *, extents: bool = False) -> tuple[float, float, float]:
+ """A GLB-frame vector (Y-up, +Z front) in ``language``'s authoring frame: the inverse of the
+ glTF export mapping ``(x, y, z) → (x, z, -y)``, so a Z-up language reads ``(x, -z, y)``.
+ ``extents`` (sizes, size deltas) are permuted, never sign-flipped — and that permutation is
+ its own inverse: it also takes a Z-up plan's (W, D, H) into the GLB frame's (W, H, D)."""
+ x, y, z = (float(c) for c in v)
+ if authoring_frame(language) is Frame.Z_UP_NEG_Y_FRONT:
+ return (x, z if extents else -z, y)
+ return (x, y, z)
+
+
def frame_doc(frame: Frame) -> str:
"""Return the one-paragraph prompt text describing ``frame``."""
if frame is Frame.Z_UP_NEG_Y_FRONT:
diff --git a/harness/codeverse3d/spatial/contract.py b/harness/codeverse3d/spatial/contract.py
index 295b1ba9..41590838 100644
--- a/harness/codeverse3d/spatial/contract.py
+++ b/harness/codeverse3d/spatial/contract.py
@@ -41,10 +41,13 @@ from codeverse3d.conventions import (
BBOX_TOLERANCE_M,
CONTACT_GAP_M,
FRAME_AXES,
- LANGUAGE_FRAME,
Frame,
+ to_authoring_frame,
to_snake,
)
+from codeverse3d.conventions import (
+ authoring_frame as language_frame, # the name connectivity.py imports from here
+)
from codeverse3d.spatial.measure import fmt_extent_cm, fmt_vec
GATE = "contract"
@@ -80,11 +83,6 @@ ORIENT_OVER = 1.4
# --------------------------------------------------------------------------- frames
-def language_frame(language: str) -> Frame:
- """Authoring frame of ``language`` (unknown / empty → the GLB frame itself)."""
- return LANGUAGE_FRAME.get(str(language), Frame.Y_UP_POS_Z_FRONT)
-
-
def frame_label(language: str) -> str:
"""Short frame tag for fix hints, e.g. ``"blender frame: Z-up, -Y front"``."""
if language_frame(language) is Frame.Z_UP_NEG_Y_FRONT:
@@ -102,13 +100,9 @@ def plan_bbox_to_glb(bbox: BBox, language: str) -> BBox:
def glb_vec_to_plan(v, language: str, *, extents: bool = False) -> np.ndarray:
- """Inverse of the glTF mapping for a GLB-frame vector: Z-up languages get
- ``(x, y, z) → (x, -z, y)``; ``extents`` (per-axis sizes / size deltas) are only
- permuted, never sign-flipped. Hints must be written in the frame the agent codes in."""
- v = np.asarray(v, dtype=float)
- if language_frame(language) is Frame.Y_UP_POS_Z_FRONT:
- return v
- return np.array([v[0], v[2] if extents else -v[2], v[1]])
+ """``conventions.to_authoring_frame`` as an array: hints must be written in the frame the
+ agent codes in."""
+ return np.asarray(to_authoring_frame(v, language, extents=extents), dtype=float)
# --------------------------------------------------------------------------- matching
diff --git a/harness/codeverse3d/tracks/prompting.py b/harness/codeverse3d/tracks/prompting.py
index 4ba3fe3f..ff31e5c6 100644
--- a/harness/codeverse3d/tracks/prompting.py
+++ b/harness/codeverse3d/tracks/prompting.py
@@ -18,7 +18,7 @@ from codeverse3d.contracts.chat import ImagePart
from codeverse3d.contracts.common import HARNESS_OWNED_SRC, Language, Track, is_harness_owned
from codeverse3d.contracts.plan import Plan, StaticPlan
from codeverse3d.contracts.run import RoundRecord
-from codeverse3d.conventions import LANGUAGE_FRAME, Frame, frame_doc, to_snake
+from codeverse3d.conventions import LANGUAGE_FRAME, frame_doc, to_authoring_frame, to_snake
from codeverse3d.prompts import render
from codeverse3d.prompts.catalog import prompt_dir_for
from codeverse3d.tracks.common import RunContext
@@ -117,17 +117,6 @@ def bbox_line(bbox: Any) -> str:
return f"centre ({c}) m, extents ({e}) m"
-def glb_to_plan_frame(
- v: Sequence[float], language: Language, *, extents: bool = False
-) -> tuple[float, float, float]:
- """Map a GLB-frame (Y-up, +Z front) vector into the language's authoring frame.
- Blender/CadQuery/URDF plans are Z-up with -Y front: glb (x, y, z) → (x, -z, y)."""
- x, y, z = float(v[0]), float(v[1]), float(v[2])
- if LANGUAGE_FRAME[language.value] is Frame.Z_UP_NEG_Y_FRONT:
- return (x, abs(z) if extents else -z, y)
- return (x, y, z)
-
-
def constraints_text(spec: Any) -> str:
c = spec.constraints
lines = []
@@ -574,7 +563,7 @@ def measurement_vs_plan(
if m is None or plan is None or not hasattr(plan, "overall_bbox"):
return ""
pe = plan.overall_bbox.extents
- me = glb_to_plan_frame(m.extents, language, extents=True)
+ me = to_authoring_frame(m.extents, language, extents=True)
lines = [
f"Measured overall extents {me[0]:.3f}×{me[1]:.3f}×{me[2]:.3f} m vs plan "
f"{pe[0]:.3f}×{pe[1]:.3f}×{pe[2]:.3f} m; ground gap {m.ground_gap_m:+.3f} m; footprint offset {m.footprint_offset_m:.3f} m; "
@@ -585,12 +574,8 @@ def measurement_vs_plan(
p = planned.get(to_snake(pm.name))
if p is None:
continue
- ext = glb_to_plan_frame(
- [b - a for a, b in zip(pm.bbox_min, pm.bbox_max, strict=True)], language, extents=True
- )
- cen = glb_to_plan_frame(
- [(a + b) / 2 for a, b in zip(pm.bbox_min, pm.bbox_max, strict=True)], language
- )
+ ext = to_authoring_frame([b - a for a, b in zip(pm.bbox_min, pm.bbox_max, strict=True)], language, extents=True)
+ cen = to_authoring_frame([(a + b) / 2 for a, b in zip(pm.bbox_min, pm.bbox_max, strict=True)], language)
lines.append(
f"- {p.name}: measured centre ({cen[0]:.3f}, {cen[1]:.3f}, {cen[2]:.3f}) extents ({ext[0]:.3f}, {ext[1]:.3f}, {ext[2]:.3f})"
f" | plan centre ({p.bbox.center[0]:.3f}, {p.bbox.center[1]:.3f}, {p.bbox.center[2]:.3f}) extents "
diff --git a/harness/codeverse3d/tracks/static_object.py b/harness/codeverse3d/tracks/static_object.py
index df278627..bf13ef86 100644
--- a/harness/codeverse3d/tracks/static_object.py
+++ b/harness/codeverse3d/tracks/static_object.py
@@ -27,6 +27,7 @@ from codeverse3d.conventions import (
BBOX_TOLERANCE_M,
OBJECT_CLAY_VIEWS,
OBJECT_VIEWS,
+ to_authoring_frame,
)
from codeverse3d.orchestrator import RefineTask, TaskGroup, compact_instructions
from codeverse3d.prompts import render
@@ -45,7 +46,6 @@ from codeverse3d.tracks.prompting import (
budget_for,
expected_files,
file_for_target_factory,
- glb_to_plan_frame,
judge_digest,
judged_sheet,
language_system_prompt,
@@ -139,7 +139,7 @@ class ObjectPipeline:
# reorder into the measurement table's frame (W×H×D, Y-up): the (x,|z|,y) swap is
# self-inverse for extents, so Z-up plans (W,D,H) → (W,H,D), threejs is identity —
# otherwise the judge compares the digest position-wise against swapped numbers.
- e = glb_to_plan_frame(plan.overall_bbox.extents, ctx.language, extents=True)
+ e = to_authoring_frame(plan.overall_bbox.extents, ctx.language, extents=True)
return f"{plan.object_name}: {plan.summary} Overall {e[0]:.2f}×{e[1]:.2f}×{e[2]:.2f} m (W×H×D). Parts: {parts}."
def judge_context(