Reference layer: poseable mannequin and glTF overlay #1

Open
opened 2026-11-03 18:16:40 +11:00 by litruv · 0 comments
Owner

Tracks the wish in umamo/TODO.md line 187: "Pose Reference - A poseable and adjustable 3D mannequin model for overlay reference."

This repo holds the design and a reference implementation sketch for that feature.

What it is
A drawing aid, not a 3D modeler. It gives proportion, anatomy, foreshortening, and scale reference, and can draw as a line-art underlay behind the puppet.

Non-goals
glTF export, materials, lighting, animation, physics, bendy bones.

Design decisions

  • Reuses Umamo world axes (X right, Y depth, Z up). At yaw 0 and pitch 0 the reference camera agrees exactly with ViewportCamera.worldToNdc.
  • Orthographic camera by default, perspective optional. Pitch is clamped to the open interval +/-89.9 degrees because the screen-right basis collapses to a zero vector at +/-90.
  • Draw order Above by default. Depth-sorted occlusion against the puppet is deferred: the puppet path has no depth today.
  • CPU skinning first as the oracle; the GPU path comes later.
  • The mannequin is procedural, not a bundled asset. That avoids licensing and keeps output deterministic and testable.
  • Pose storage reuses the planned Cubism 5.4 "Model state set" pose library shape.
  • UMA persistence adds one new additive, ignorable entry, reference. It stores an asset key and hash, never geometry.
  • Six PRs, each independently mergeable. See docs/pr-stack.md.

Verified findings
verify/verify.py runs 30 checks against the same algorithms the sketch implements, and all pass. Two findings:

  1. An accessor byteOffset must be rejected when it is not a multiple of the component size.
  2. At pitch +/-90 degrees the screen-right basis is a zero vector, so pitch must be clamped to an open interval.

The sketch is not compiled here: no kotlinc or gradle on this machine. Correctness is proven by the Python harness mirroring the same algorithms.

Tracks the wish in `umamo/TODO.md` line 187: "Pose Reference - A poseable and adjustable 3D mannequin model for overlay reference." This repo holds the design and a reference implementation sketch for that feature. **What it is** A drawing aid, not a 3D modeler. It gives proportion, anatomy, foreshortening, and scale reference, and can draw as a line-art underlay behind the puppet. **Non-goals** glTF export, materials, lighting, animation, physics, bendy bones. **Design decisions** - Reuses Umamo world axes (X right, Y depth, Z up). At yaw 0 and pitch 0 the reference camera agrees exactly with `ViewportCamera.worldToNdc`. - Orthographic camera by default, perspective optional. Pitch is clamped to the open interval +/-89.9 degrees because the screen-right basis collapses to a zero vector at +/-90. - Draw order `Above` by default. Depth-sorted occlusion against the puppet is deferred: the puppet path has no depth today. - CPU skinning first as the oracle; the GPU path comes later. - The mannequin is procedural, not a bundled asset. That avoids licensing and keeps output deterministic and testable. - Pose storage reuses the planned Cubism 5.4 "Model state set" pose library shape. - UMA persistence adds one new additive, ignorable entry, `reference`. It stores an asset key and hash, never geometry. - Six PRs, each independently mergeable. See `docs/pr-stack.md`. **Verified findings** `verify/verify.py` runs 30 checks against the same algorithms the sketch implements, and all pass. Two findings: 1. An accessor `byteOffset` must be rejected when it is not a multiple of the component size. 2. At pitch +/-90 degrees the screen-right basis is a zero vector, so pitch must be clamped to an open interval. The sketch is not compiled here: no `kotlinc` or `gradle` on this machine. Correctness is proven by the Python harness mirroring the same algorithms.
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: litruv/umamo-reference-layer#1