Fit deterministic scene geometry

Co-authored-by: OpenAI Codex <codex@openai.com>

AGENTS.md

@@ -334,6 +334,19 @@ technical cutaway animation.
   returned a real Modal analysis for `cutaway mechanism` at `0.7` confidence
   with 3 parts, and `/generate_scene` returned `renderer: three`,
   `render_mode: three`, and no HTML field.
+- Implemented the `REVIEW3.md` deterministic renderer pass on June 15, 2026:
+  axial and disk-like primitives now infer their axis from `geometry.size`,
+  radius comes from the cross-section pair, explicit `geometry.rotation`
+  remains additive, the Three.js assembly recenters before reveal animation,
+  camera/OrbitControls fit is derived from the bounding sphere and viewport
+  aspect, the grid moves to the recentered assembly bottom, and label
+  projection uses world positions. Prompt wording now tells the model that the
+  renderer infers primitive orientation from the odd-one-out size dimension.
+- Local verification after the `REVIEW3.md` pass: prompt/schema imports,
+  schema validation, parser/coercion validation, FastAPI `TestClient` checks
+  in `INFERENCE_BACKEND=local`, browser verification for `MODEL_OUTPUT.json`
+  and `EXAMPLE_ANALYSIS`, desktop/mobile nonblank screenshots, mobile
+  no-overflow measurement, orbit drag, and Reset view all passed.
 
 ## Next Work
 

index.html

@@ -922,8 +922,9 @@
       scene.fog = new THREE.Fog(0x0f1318, 8, 20);
 
       const camera = new THREE.PerspectiveCamera(42, 1, 0.1, 100);
+      const defaultViewDirection = new THREE.Vector3(5.4, 3.9, 6.2).normalize();
       const defaultCameraPosition = new THREE.Vector3(5.4, 3.9, 6.2);
-      const defaultTarget = new THREE.Vector3(0, 0.1, 0);
+      const defaultTarget = new THREE.Vector3(0, 0, 0);
       camera.position.copy(defaultCameraPosition);
 
       const controls = window.THREE.OrbitControls
@@ -931,8 +932,6 @@
         : null;
       if (controls) {
         controls.enableDamping = true;
-        controls.minDistance = 2.4;
-        controls.maxDistance = 12;
         controls.maxPolarAngle = Math.PI * 0.48;
         controls.target.copy(defaultTarget);
         if (window.THREE.TOUCH) {
@@ -955,6 +954,8 @@
       grid.material.opacity = 0.75;
       scene.add(grid);
 
+      const partGroup = new THREE.Group();
+      scene.add(partGroup);
       const meshes = (analysis.parts || []).slice(0, 6).map((part, index) => {
         const mesh = buildPartMesh(part, index);
         const position = part.geometry && part.geometry.position || [0, 0, 0];
@@ -969,10 +970,13 @@
           ? part.motion.pivot
           : [0, 0, 0];
         mesh.userData.pivot = new THREE.Vector3(pivot[0], pivot[1], pivot[2]);
-        mesh.scale.setScalar(0.001);
-        scene.add(mesh);
+        partGroup.add(mesh);
         return mesh;
       });
+      const fitBounds = fitAssembly(partGroup, grid);
+      for (const mesh of meshes) {
+        mesh.scale.setScalar(0.001);
+      }
 
       const clock = new THREE.Clock();
       let frameId = 0;
@@ -983,6 +987,8 @@
           camera.position.copy(defaultCameraPosition);
           if (controls) {
             controls.target.copy(defaultTarget);
+            controls.minDistance = Math.max(0.05, fitBounds.radius * 0.6);
+            controls.maxDistance = Math.max(controls.minDistance * 2, fitBounds.radius * 6);
             controls.update();
           }
         },
@@ -996,8 +1002,8 @@
       function resize() {
         const rect = viewport.getBoundingClientRect();
         camera.aspect = Math.max(1, rect.width) / Math.max(1, rect.height);
-        camera.updateProjectionMatrix();
         renderer.setSize(Math.max(1, rect.width), Math.max(1, rect.height));
+        fitCameraToBounds(camera, controls, fitBounds, defaultViewDirection, defaultCameraPosition, defaultTarget);
       }
 
       function animate() {
@@ -1211,6 +1217,50 @@
       sourceCard.hidden = false;
     }
 
+    function fitAssembly(partGroup, grid) {
+      partGroup.updateMatrixWorld(true);
+      const box = new THREE.Box3().setFromObject(partGroup);
+      if (box.isEmpty()) {
+        return { radius: 1, target: new THREE.Vector3(0, 0, 0) };
+      }
+      const center = box.getCenter(new THREE.Vector3());
+      partGroup.position.sub(center);
+      partGroup.updateMatrixWorld(true);
+
+      const recenteredBox = new THREE.Box3().setFromObject(partGroup);
+      const sphere = recenteredBox.getBoundingSphere(new THREE.Sphere());
+      const radius = Math.max(0.35, sphere.radius);
+      if (Number.isFinite(recenteredBox.min.y)) {
+        grid.position.y = recenteredBox.min.y;
+      }
+      return { radius, target: new THREE.Vector3(0, 0, 0) };
+    }
+
+    function fitCameraToBounds(camera, controls, bounds, viewDirection, defaultCameraPosition, defaultTarget) {
+      const target = bounds.target || new THREE.Vector3(0, 0, 0);
+      const radius = Math.max(0.35, bounds.radius || 1);
+      const verticalFov = THREE.MathUtils.degToRad(camera.fov);
+      const horizontalFov = 2 * Math.atan(Math.tan(verticalFov / 2) * Math.max(0.1, camera.aspect));
+      const verticalDistance = radius / Math.sin(verticalFov / 2);
+      const horizontalDistance = radius / Math.sin(horizontalFov / 2);
+      const distance = Math.max(verticalDistance, horizontalDistance) * 1.35;
+
+      defaultTarget.copy(target);
+      defaultCameraPosition.copy(target).add(viewDirection.clone().multiplyScalar(distance));
+      camera.position.copy(defaultCameraPosition);
+      camera.near = Math.max(0.01, distance / 100);
+      camera.far = Math.max(100, distance * 100);
+      camera.updateProjectionMatrix();
+
+      if (controls) {
+        controls.target.copy(defaultTarget);
+        controls.minDistance = Math.max(0.05, radius * 0.6);
+        controls.maxDistance = Math.max(controls.minDistance * 2, radius * 6);
+        controls.update();
+        controls.saveState();
+      }
+    }
+
     function buildPartMesh(part, index) {
       const geometryData = part.geometry || {};
       const size = Array.isArray(geometryData.size) ? geometryData.size : [1, 1, 1];
@@ -1219,27 +1269,38 @@
       const z = Math.max(0.05, Number(size[2]) || 1);
       let geometry;
       if (geometryData.shape === "cylinder") {
-        const radius = Math.max(x, z) / 2;
-        geometry = new THREE.CylinderGeometry(radius, radius, y, 48);
+        const profile = axisProfile([x, y, z], "max");
+        geometry = new THREE.CylinderGeometry(profile.radius, profile.radius, profile.length, 48);
+        orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "cone") {
-        geometry = new THREE.ConeGeometry(Math.max(x, z) / 2, y, 48);
+        const profile = axisProfile([x, y, z], "max");
+        geometry = new THREE.ConeGeometry(profile.radius, profile.length, 48);
+        orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "sphere") {
         geometry = new THREE.SphereGeometry(Math.max(x, y, z) / 2, 36, 18);
       } else if (geometryData.shape === "capsule") {
-        const radius = Math.min(Math.max(x, z) / 2, y / 2);
-        geometry = new THREE.CapsuleGeometry(radius, Math.max(0.05, y - radius * 2), 8, 24);
+        const profile = axisProfile([x, y, z], "max");
+        const radius = Math.min(profile.radius, profile.length / 2);
+        geometry = new THREE.CapsuleGeometry(radius, Math.max(0.05, profile.length - radius * 2), 8, 24);
+        orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "rod") {
-        geometry = new THREE.CylinderGeometry(Math.max(x, y) / 2, Math.max(x, y) / 2, z, 24);
-        geometry.rotateX(Math.PI / 2);
+        const profile = axisProfile([x, y, z], "max");
+        geometry = new THREE.CylinderGeometry(profile.radius, profile.radius, profile.length, 24);
+        orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "gear") {
-        geometry = gearGeometry(Math.max(x, z) / 2, y, geometryData.teeth || 18);
+        const profile = axisProfile([x, y, z], "min");
+        geometry = gearGeometry(profile.radius, profile.length, geometryData.teeth || 18);
+        orientZAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "torus") {
-        const outerRadius = Math.max(x, z) / 2;
-        const tube = Math.min(y / 2, outerRadius * 0.36);
+        const profile = axisProfile([x, y, z], "min");
+        const outerRadius = profile.radius;
+        const tube = Math.min(profile.length / 2, outerRadius * 0.36);
         geometry = new THREE.TorusGeometry(Math.max(0.05, outerRadius - tube), Math.max(0.025, tube), 16, 64);
-        geometry.rotateX(Math.PI / 2);
+        orientZAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "spring") {
-        geometry = springGeometry(Math.max(x, z) / 2, y, geometryData.coils || 5, geometryData.wire);
+        const profile = axisProfile([x, y, z], "max");
+        geometry = springGeometry(profile.radius, profile.length, geometryData.coils || 5, geometryData.wire);
+        orientYAxisGeometry(geometry, profile.axis);
       } else {
         geometry = new THREE.BoxGeometry(x, y, z);
       }
@@ -1255,6 +1316,57 @@
       return new THREE.Mesh(geometry, material);
     }
 
+    function axisProfile(extents, fallback) {
+      const values = extents.map((value) => Math.max(0.05, Number(value) || 1));
+      const maxValue = Math.max(...values);
+      const minValue = Math.min(...values);
+      let axis = 1;
+      if (!dimensionsAreClose(maxValue, minValue)) {
+        const pairs = [
+          { axis: 2, diff: relativeDifference(values[0], values[1]) },
+          { axis: 1, diff: relativeDifference(values[0], values[2]) },
+          { axis: 0, diff: relativeDifference(values[1], values[2]) }
+        ].sort((left, right) => left.diff - right.diff);
+        if (pairs[0].diff <= 0.2) {
+          axis = pairs[0].axis;
+        } else if (fallback === "min") {
+          axis = values.indexOf(minValue);
+        } else if (fallback === "max") {
+          axis = values.indexOf(maxValue);
+        }
+      }
+      const crossSection = values.filter((_, index) => index !== axis);
+      return {
+        axis,
+        length: values[axis],
+        radius: Math.max(0.025, (crossSection[0] + crossSection[1]) / 4)
+      };
+    }
+
+    function dimensionsAreClose(left, right) {
+      return relativeDifference(left, right) <= 0.2;
+    }
+
+    function relativeDifference(left, right) {
+      return Math.abs(left - right) / Math.max(0.05, Math.max(Math.abs(left), Math.abs(right)));
+    }
+
+    function orientYAxisGeometry(geometry, axis) {
+      if (axis === 0) {
+        geometry.rotateZ(-Math.PI / 2);
+      } else if (axis === 2) {
+        geometry.rotateX(Math.PI / 2);
+      }
+    }
+
+    function orientZAxisGeometry(geometry, axis) {
+      if (axis === 0) {
+        geometry.rotateY(Math.PI / 2);
+      } else if (axis === 1) {
+        geometry.rotateX(-Math.PI / 2);
+      }
+    }
+
     function gearGeometry(radius, depth, teeth) {
       const shape = new THREE.Shape();
       const steps = teeth * 2;
@@ -1271,7 +1383,6 @@
       shape.holes.push(hole);
       const geometry = new THREE.ExtrudeGeometry(shape, { depth, bevelEnabled: false });
       geometry.center();
-      geometry.rotateX(Math.PI / 2);
       return geometry;
     }
 
@@ -1338,7 +1449,7 @@
       const rect = viewport.getBoundingClientRect();
       labelLayer.replaceChildren();
       for (const mesh of meshes) {
-        const projected = mesh.position.clone().project(camera);
+        const projected = mesh.getWorldPosition(new THREE.Vector3()).project(camera);
         if (projected.z < -1 || projected.z > 1) continue;
         const label = document.createElement("div");
         label.className = "scene-label";

snap2sim/prompts.py

@@ -38,6 +38,10 @@ Motions, with axis as a numeric vector like [0, 1, 0]:
 Every geometry must use size: [x, y, z] and position: [x, y, z]. Do not use
 radius, height, length, width, or depth fields. Every motion axis must be a
 numeric vector such as [0, 1, 0], never a string like x, y, or z.
+For axial or disk-like shapes, express the main axis or disk normal through the
+size vector: one dimension should differ from the other two. The renderer uses
+that odd-one-out dimension for the primitive axis and treats rotation as a
+fine-tuning offset only.
 
 Use 2 to 6 parts; prefer the fewest that explain the mechanism. Keep names and
 descriptions short. When possible, include annotation.point in normalized image