docs/reviews/motion-axis-bias.md

# Review: Motion Axis Bias Toward [0, 1, 0]

Date: 2026-06-15
Scope: Does the current prompt (and surrounding pipeline) bias part motion
toward the world Y axis `[0, 1, 0]`?

## Short answer

Yes. The system prompt nudges the model toward `[0, 1, 0]`, and two
non-prompt layers (the renderer default and the coercion fallback) push the
*rendered* result toward Y even harder. The net effect is that uncertain or
under-specified parts tend to spin/oscillate/slide about world Y regardless of
their actual geometry orientation.

## Where the bias comes from

### 1. Prompt anchoring (`snap2sim/prompts.py`, `VISION_SYSTEM_PROMPT`)

`[0, 1, 0]` is the *only* concrete axis literal the model ever sees, and it
appears twice with no counterexample:

- Line 29: `Motions, with axis as a numeric vector like [0, 1, 0]:`
- Line 40: `Every motion axis must be a numeric vector such as [0, 1, 0], never a string like x, y, or z.`

The compact example payload (lines 52–68) uses a `pulse` motion, which has no
`axis` field, so it adds no balancing example. With a single repeated exemplar
and no contrast cases, an LLM under uncertainty defaults to the most available
pattern — here, `[0, 1, 0]`. This is textbook few-shot anchoring.

Note: `EXAMPLE_ANALYSIS` in `snap2sim/schema.py` is *not* injected into the
prompt (the prompt is self-contained), so it does not directly steer the model.
But it reflects the same lean: of its three parts that carry an axis, two are
`[0, 1, 0]` (`ratchet_gear` rotate, `pawl` oscillate) and one is `[1, 0, 0]`
(`selector_pin` translate). It is also the local sample-mode render, so the
Y-lean is visible there too.

### 2. Renderer hard default (`index.html`)

`applyMotion`, line 1418:

```js
const axis = new THREE.Vector3(...(motion.axis || [0, 1, 0])).normalize();
```

If the model omits `axis` entirely (valid — `axis` is optional in the schema
and coercion never injects one), the renderer animates about Y. So "model is
biased to emit `[0, 1, 0]`" and "model omits axis" produce the *same* on-screen
result: Y-axis motion. This makes the bias look even stronger than the model's
raw output.

### 3. Coercion fallback (`snap2sim/model_io.py`)

- `_axis_vector` (lines 297–309) returns `None` when no usable axis is present;
  `_coerce_part` only adds `axis` if truthy (lines 173–175). So omitted axes
  stay omitted → renderer default (Y) applies.
- `_generic_analysis` (line 232) hard-codes `"axis": [0, 1, 0]` for its rotor
  part. Any fully-degraded response that falls back to the generic payload is
  pure Y.

## Why this is a real visual problem, not just cosmetics

Geometry orientation and motion axis are decided **independently**, and they can
disagree:

- Geometry: `axisProfile` + `orientYAxisGeometry` / `orientZAxisGeometry`
  (`index.html` lines 1319–1367) bake the primitive's long axis into the
  geometry buffer using the **odd-one-out `size` dimension**. A cylinder with
  `size [3, 0.5, 3]`... e.g. `size [2.0, 0.4, 0.4]` lays the shaft along world X.
- Motion: `applyMotion` calls `mesh.rotateOnAxis(axis, …)` with the raw motion
  axis (object space, and with no `baseRotation` that equals world space).

So a shaft whose geometry was oriented along **X** but whose motion axis is the
biased **`[0, 1, 0]`** will spin about Y — i.e. it sweeps end-over-end instead
of rotating about its own length. The size-driven geometry inference added in
`docs/reviews/scene-geometry-review.md` made geometry orientation smart, but
motion axis was left to the model/default, so the two can visibly contradict.

## Conclusion

The prompt is a genuine contributor to the `[0, 1, 0]` lean, but fixing only the
prompt will not fully resolve the on-screen behavior because the renderer
default and generic fallback also resolve to Y. Address the prompt *and* make
motion axis follow the geometry's inferred primitive axis when the model is
silent or low-signal.

## Implementation plan (completed)

1. **De-anchor the prompt** (`snap2sim/prompts.py`):
   - In the motions section, show axis examples across all three world axes,
     e.g. spin about a shaft's long axis `[1, 0, 0]` / `[0, 0, 1]` as well as
     `[0, 1, 0]`, so no single axis is the lone exemplar.
   - Add one sentence: the motion axis should match the part's real axis of
     rotation/translation (usually the geometry's long/odd-one-out dimension),
     not default to vertical.
   - Optionally add a second `parts` exemplar in the compact shape that carries
     an explicit non-`[0,1,0]` axis, to balance the `pulse` example.

2. **Make the renderer default geometry-aware** (`index.html`):
   - When `motion.axis` is absent, derive the default from the same
     `axisProfile` result used to orient the geometry (map the inferred
     `profile.axis` 0/1/2 to `[1,0,0]`/`[0,1,0]`/`[0,0,1]`) instead of the hard
     `[0, 1, 0]`. This aligns spin with the part's long axis for free.
   - Keep `[0, 1, 0]` only as the final fallback when no geometry/profile is
     available.

3. **Align the coercion fallback** (`snap2sim/model_io.py`):
   - Consider deriving `_generic_analysis` rotor axis from its own geometry, or
     at minimum document that the generic part is intentionally Y.
   - Decide whether `_coerce_part` should inject a geometry-derived axis when the
     model omits one (vs. leaving it to the renderer). Prefer leaving it to the
     renderer so there is a single source of truth (option 2).

4. **Verification after changes:**
   - `EXAMPLE_ANALYSIS` and `docs/fixtures/mini-fan-analysis.json` render with
     each part rotating about a sensible axis (shafts about their length).
   - Schema/parser/coercion checks still pass; FastAPI `TestClient` smoke for
     `/`, `/analyze_image`, `/generate_scene`.
   - Re-run a representative Modal analysis and inspect the distribution of
     emitted motion axes — confirm it is no longer almost entirely `[0, 1, 0]`.

## Implementation status

Completed locally on 2026-06-15:

- Prompt examples now show X, Y, and Z axes and explicitly tell the model to
  match motion axes to the real rotation or translation axis.
- The deterministic renderer stores the geometry-inferred axis on each mesh
  and uses it when `motion.axis` is omitted, keeping `[0, 1, 0]` only as the
  final no-profile fallback.
- `_generic_analysis` no longer hard-codes the rotor motion axis; its disk-like
  geometry lets the renderer derive the Y axis from size.
- Local schema/parser/coercion checks, FastAPI smoke checks, and Playwright
  renderer probes passed.
- Modal dev `run_analysis_endpoint_check` returned a rotating `dial` part with
  `axis: [1, 0, 0]`, confirming the prompt no longer collapses the synthetic
  check to `[0, 1, 0]`.
- Stable Modal deployment completed after the prompt/renderer update, and an
  unauthenticated deployed `runtime_probe` request returned `401 Unauthorized`.
- GitHub-to-Hugging Face sync run `27544185461` deployed commit `e7369eb` to the
  then-private Space after shortening the README `short_description` metadata to meet
  Hugging Face's 60-character limit.
- Authenticated Space verification passed: the root served the trusted
  shell, a synthetic target image returned `rotating shaft assembly` at `0.65`
  confidence with an emitted `[1.0, 0.0, 0.0]` motion axis, `/generate_scene`
  returned `renderer: three` and `render_mode: three`, and no HTML field was
  present.
- Final submission note, 2026-06-15: this pass shipped before the public
  `build-small-hackathon/Snap2Sim` submission.

## Files referenced

- `snap2sim/prompts.py` — `VISION_SYSTEM_PROMPT` (lines 29, 40), example payload.
- `index.html` — `applyMotion` (line 1418), `axisProfile` (1319–1344),
  `orientYAxisGeometry` / `orientZAxisGeometry` (1354–1367), `buildPartMesh`.
- `snap2sim/model_io.py` — `_axis_vector` (297–309), `_coerce_part` (145–204),
  `_generic_analysis` (~232).
- `snap2sim/schema.py` — `EXAMPLE_ANALYSIS` axes, motion schema.