2dimg2motion

# 2dimg2motion

## Overview

Convert one baseline character, creature, vehicle, weapon, or prop image into a style-consistent transparent game-animation sequence. Motion artwork must be generated by the model: by default, use built-in `image_gen` to directly generate whole-character key poses and in-between frames.

**Core principle:** first analyze the baseline frame's subject, body parts, weapons, and art style; establish an identity lock; write detailed prompts for keyframes 02/05/08/11; then use `image_gen` to generate shared key poses and in-betweens. Do not use scripts, Pillow, canvas, SVG, or affine transforms to draw or synthesize motion artwork.

Before generating animation assets, read [references/keypose-redraw.md](references/keypose-redraw.md). When designing action timing or prompt wording, also consult [references/motion-prompt-patterns.md](references/motion-prompt-patterns.md), which distills reusable patterns from the local `motion/` reference library.

If project knowledge exists in `img2mo-knowledge/`, read `img2mo-knowledge/index.md` before prompt writing. Then read only the relevant knowledge files for the requested action or style: `action-patterns.md`, `style-patterns.md`, `prompt-patterns.md`, `failures.md`, or matching records in `learnings.jsonl`. Project knowledge is guidance, not ground truth: never let it override the current baseline identity, current user request, or hard failure constraints.

## Input Contract

Collect or infer:

- baseline image and character facing direction;
- whether the baseline image has already been standardized for animation: foreground subject longest side 300-400 px, transparent action margins on all sides, no tight crop, and no huge source canvas;
- motion type, ordered beats, and loop behavior;
- preferred frame count or timing;
- canvas size, stable foot/bottom baseline, and naming prefix;
- required deliverables: keyframe prompts, sequence frames, spritesheet, contact sheet, and playback preview.

Ask only for information that materially changes the result. Default to 14 transparent RGBA frames per action with a seamless return to the source pose.

## Generation Boundaries

- The default image generation capability is built-in `image_gen`. Unless the user explicitly requests a CLI/API path, do not switch to script-based image generation or custom SDK calls.
- Character poses in keyframes, in-betweens, and sprite strips must be directly generated by `image_gen` from prompts and visual references.
- Local scripts are allowed only for non-creative post-processing: copying generated images, removing chroma-key backgrounds, splitting cells, normalizing canvases, packing spritesheets, generating previews, writing manifests, and running validation.
- Do not use scripts to produce motion artwork. Do not use Pillow, OpenCV, canvas, SVG, bone slicing, rotation/scale/affine transforms, limb copy-paste, procedural interpolation, or hand-written drawing to create keyframes or in-betweens.
- If `image_gen` output has the wrong cell count, wrong background, or identity inconsistency, rewrite the prompt and call `image_gen` again. Do not "fix" it into a new pose with scripts; scripts may only clean backgrounds and organize generated images.
- In any delivery note, distinguish "model-generated content" from "local post-processing." If only a key-pose sheet is complete and the full 14 frames are not, say so explicitly.

## Hard Failure Constraints

If any of the following appears, treat the batch as failed. Re-prompt and call `image_gen` again; do not hide the problem with post-processing:

- **Weapon hand or active-limb side swap:** if a sword, club, spear, staff, or similar weapon moves from the `screen-left` hand to the `screen-right` hand, or the reverse, reject the batch. Prompts must explicitly state: "the weapon always remains in the same screen-space hand; the other hand remains empty/anchoring/counterbalancing and must not hold the weapon."
- **Character colors removed by chroma key:** before choosing a chroma key, list the character's main colors, weapon colors, and highlight colors. The key color must not be close to subject colors. For green/blue subjects, prefer `#ff00ff`; for pink/purple/magenta subjects, avoid `#ff00ff` and prefer `#00ffff` or another pure color absent from the subject. If matting removes body, weapon, eyes, armor, horns, or outlines, change the key color and regenerate the source image.
- **Insufficient gutters causing split-frame cuts:** sprite-strip prompts must require large chroma-key gutters, centered cells, and complete weapons inside each cell. If equal-cell splitting cuts into a neighboring body, weapon, ear, horn, foot, or introduces neighboring fragments, do not deliver it. Prefer shorter batches such as `01-06` and `07-12`, or regenerate with larger spacing.
- **Canvas too small:** normalized canvases must leave a safety margin. If a weapon tip, horn, ear, foot, tail, or body part touches the edge or is cropped in the contact sheet, enlarge the final canvas or regenerate.
- **Unstandardized baseline frame:** if the source image is very large, tightly cropped around the character, has no transparent action margin, or cannot contain the likely attack/walk stretch without overlap, standardize it before generation with `scripts/standardize_baseline.py`. Do not start image generation from a huge or edge-hugging source; it causes crowded source sheets, clipped cells, forced local resizing, scale popping, and long runtimes.
- **Scale popping or drifting centers:** if the model draws some cells as visibly smaller/larger variants, or local processing needs per-frame scale/center fitting to make frames align, reject the source batch. Regenerate with stronger same-size prompts or use shorter batches. If a pose needs more room, enlarge the final canvas instead of shrinking that pose or the whole sequence.
- **Output directory pollution:** the final output directory may contain only contract files. Model source i