Files
umamo-reference-layer/README.md
T
litruv 4eb583b5f3 Design doc and reference implementation sketch for the reference layer
Design for a poseable mannequin plus glTF/GLB import overlay in Umamo:
world axes, orbit camera, draw path, UMA persistence, UI, risks.

docs/seams.md lists the RenderDevice additions the feature needs:
PrimitiveTopology, DepthState, depthAttachment, WorldToClip,
ReferenceMeshSpec.

sketch/ mirrors the algorithms in Kotlin. verify/verify.py proves them:
30 checks, all passing. Two findings: accessor byteOffset must be a
multiple of the component size, and the screen-right basis collapses to a
zero vector at pitch +/-90 degrees, so pitch is clamped to an open
interval.
2026-11-03 18:14:07 +11:00

36 lines
1.5 KiB
Markdown

# 3D model reference layer
Design work for Umamo's `Pose Reference` wish (`umamo/TODO.md` § Future Feature Wishes):
a poseable 3D mannequin that sits in the viewport as an overlay, plus import of the user's
own glTF model as the reference object.
Umamo is a 2D puppet editor. This does not make it a 3D modeler. The reference layer is a
drawing aid: proportions, anatomy, foreshortening, and scale, checked against the drawing.
## Contents
| Path | What it is |
| --- | --- |
| `docs/spec.md` | The design: data model, camera, draw path, persistence, UI, non-goals |
| `docs/seams.md` | The `RenderDevice` seam changes the feature forces, and why |
| `docs/pr-stack.md` | The stack of mergeable PRs, in order |
| `sketch/` | Kotlin reference implementation of the pure parts, shaped like the umamo modules |
| `verify/verify.py` | Proof harness for the three pure algorithms |
## Verified facts
`python3 verify/verify.py` runs 25 checks against the algorithms the sketch implements:
GLB container rules, accessor alignment, forward kinematics invariants, and the orbit camera
basis. All pass. The numbers those checks assert are the numbers the sketch's tests pin.
Two of them are findings, not assertions:
- An accessor whose resolved `byteOffset` is not a multiple of its component size must be
rejected, not read.
- At `pitch == ±90°` the camera looks along the world up axis and the screen-right axis
collapses to a zero vector. The camera must clamp pitch to the open interval.
## License
GPLv3, matching Umamo.