Sprite Pose Editor

Sprite Pose Editor and the reconstruction loop

Before the equipment tools, SpriteMotion started as a reconstruction project: make a 3D character whose animations, rendered through the game's camera, land on the original sprites. That workflow is still available for research and annotation, and the bundled procedural sample character lets you run every step without any game data.

Sources: tools/sprite-pose-editor/README.md, docs/reconstruction-workflow.md, docs/getting-started.md.

The editor

A Godot 4.7 editor for reviewing and correcting 2D joint annotations on sprite frames. Canvas, directions, mirror pairs, sequences, skeleton and colors all come from the dataset manifest; nothing is hard-coded for one game.

launchers\editor\sprite-pose-editor.bat [dataset]
launchers\editor\sample-character.bat

Action	Input
Move a joint	Drag it
Nudge	Arrow keys 1 px, Shift+Arrow 0.1 px
Zoom / pan / fit	Wheel, middle-drag, F
Frames	A/D or Page Up/Down
Preview playback	Space
Undo / redo	Ctrl+Z / Ctrl+Y or Ctrl+Shift+Z
Save	Ctrl+S (autosave 0.8 s after the last edit)

Pose approved is cleared whenever you move a joint; tick it only after checking every joint. Link mirrored view also updates the mirror partner. A red banner warns when a pose was drawn on different pixels (fingerprint mismatch).

Annotations have two layers: read-only estimates and your corrections. Only poses you actually changed, reviewed or annotated are saved. Rig projections are always labelled not independent evidence.

The sample character

Canvas	160x192, ground anchor (80, 170)
Directions	south, east, north, west (all stored)
Skeleton	stick-13 (13 joints)
Rig	rig/sample-rig.json, 12 bones
Sequences	wave (right hand) and walk, 6 frames each

It is generated from code (MIT), so its true 3D poses are known and every step can be scored against ground truth. wave has exact, approved corrections for the south and east views.

The 7-step loop

 extract ──► annotate ──► fit ──► key in Blender ──► render views ──► compare
   ▲             ▲                                                    │
   │             └──────────── correct the worst frames ◄─────────────┘

Run the whole loop on the sample with one launcher:

launchers\dev\sample-loop.bat

#	Step	Command / launcher	On the sample
1	Extract frames into a dataset	python -m spritemotion extract ... / pipeline\1-extract-uo.bat	The sample is already a dataset; no game data needed
2	Annotate: correct and approve poses	editor\sprite-pose-editor.bat	wave south and east are approved
3	Export the rig and write a rig mapping	blender ... tools/blender/export_rig.py	rig/sample-rig.json, rig/sample-mapping.json
4	Fit rig poses to the annotations	python -m spritemotion fit ... / pipeline\3-fit.bat	Uses 2 approved views per frame
5	Key in Blender	tools/blender/apply_solution.py / pipeline\4-key-in-blender.bat	Keys a new action; old ones kept as .v001
6	Render every view	tools/blender/render_views.py / pipeline\5-render-views.bat	Flat silhouettes, stored views only
7	Compare and correct the worst frames	python -m spritemotion compare + sheet / pipeline\6-compare.bat	Sheet below

Expected results on the sample: fit error below 0.02 units against the truth, Blender matching the solver to about 1e-7, keyed reprojection error below 1 px, and silhouette IoU around 0.9 (the capsule model only approximates the drawn outline).

For each frame: sprite with joints, render, difference.

IoU is shape overlap, not completion. A high score can hide swapped limbs or wrong depth. Use the sheet to find the worst frames, correct their annotations, and fit again.

Things worth knowing

• Approve two directions of the same frame to make depth solvable; one view constrains the pose but not depth.
• Mirrored views are not extra cameras. UO draws three facings by flipping stored ones. A pose annotated on a mirrored view is flipped back and used for its partner; treating it as another camera angle would pull asymmetric actions toward half-mirrored poses.
• Scene versions: every --save keeps what it replaces in model.versions/; python -m spritemotion versions list|restore model.blend.
• Rig mappings for Rigify (FK) and Mixamo ship in games/ultima-online/skeletons/rig-mappings/.

With real UO data

Requires SPRITEMOTION_UO_SOURCE (see Installation).

launchers\pipeline\1-extract-uo.bat
launchers\editor\sprite-pose-editor.bat

Expected for body 400: 1680 frames, 1680 annotated, 6 approved, 0 fingerprint mismatches. Only action 22 (death_forward, SE) has approved poses so far; every other action has rig-projection estimates. Correcting and approving more poses is one of the most useful contributions (see Contributing). Frames stay in workspace/ and must never be committed.