---
name: 2D Image To Motion
slug: 2d-image-to-motion
category: AI Engineering
description: 2D Image To Motion turns one static character, creature, vehicle, weapon, or prop image into a style-consistent transparent game-animation sequence. Use it for key poses, in-between frames, spritesheets, and other action loops like idle, walk, attack, or death.
github: "https://github.com/WU-HAOTIAN34/2dimg2motion"
language: Python
stars: 186
forks: 5
install: "npx degit https://github.com/WU-HAOTIAN34/2dimg2motion ~/.claude/skills/2dimg2motion"
installs_to: ~/.claude/skills/2dimg2motion
source_path: SKILL.md
collection_size: 3
category_size: 3278
collection_url: "https://dirskills.com/collections/WU-HAOTIAN34/2dimg2motion"
added: 2026-09-06T05:20:25.688Z
last_synced: 2026-09-06T05:20:25.688Z
canonical_url: "https://dirskills.com/skills/2d-image-to-motion"
---

# 2D Image To Motion

2D Image To Motion turns one static character, creature, vehicle, weapon, or prop image into a style-consistent transparent game-animation sequence. Use it for key poses, in-between frames, spritesheets, and other action loops like idle, walk, attack, or death.

**Install:**

```bash
npx degit https://github.com/WU-HAOTIAN34/2dimg2motion ~/.claude/skills/2dimg2motion
```

## README

# 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 images, alpha sources, failed drafts, temporary splits, and debug images belong in a temporary directory and must be deleted after delivery. Do not leave `*-imagegen-*` intermediates in the final output unless the user explicitly requests process drafts.
- **Validation passes but visuals fail:** deterministic validation is only a structural gate. After `OK`, inspect `contact-sheet.png` and `preview.gif`. If there is hand swapping, slicing, missing colors, fragments, scale popping, or unreadable motion, do not claim completion.

## Limb-Side and Topology Lock

Before designing poses, establish limb identity:

- Do not infer anatomical left/right from an unqualified "left" or "right" when the source faces front, back, or is mirrored. Unless context is explicit, ask whether the user means screen space or character anatomy.
- Normalize all sides to `screen-left` or `screen-right`. If anatomy matters, record both forms, such as `character-left (screen-right)`.
- Record the `activeLimb`, its `activeShoulder`, the opposite `anchorLimb`, and any distinctive markings or spikes that identify both sides.
- For weapon actions, record `activeWeapon`, `weaponHand`, `emptyHand`, and screen-space side. Do not write only "right hand swings sword" or "left hand swings sword"; write locks such as `screen-right sword hand remains the sword hand in every frame; screen-left hand remains empty/counterbalance`.
- In every key pose and in-between, even when the active limb crosses the body centerline, it must remain connected to the same shoulder.
- The anchor limb must remain visible and attached to its original shoulder as a continuity reference. Do not let it lift, disappear, or become the attacking limb.
- Use normalized side names in image-generation prompts and contact-sheet review. Before generation, explicitly state the topology lock, for example `active=screen-left; anchor=screen-right`.
- Persist `coordinateSpace`, `activeLimb`, `activeShoulder`, and `anchorLimb` in `manifest.json`. Do not mix anatomical and screen-space naming inside one animation.

### Weapon, Prop, Accessory, and Creature Locks

Before prompt writing, classify non-body elements and non-human motion drivers:

- Record `activeWeapon`, `carriedProp`, `passiveAccessory`, and `detachedProp` separately. A held torch, shield, embedded arrow, helmet crest, and thrown weapon need different rules.
- Every weapon or carried prop must have one owner: `weaponHand`, `propHand`, mouth, tail, harness, or body socket. It must not switch sides, duplicate, float, or detach unless a release beat explicitly says so.
- Passive accessories follow their attachment surface. Embedded swords/arrows, shell spikes, antlers, crystals, capes, and belt items may lag or tilt, but they must not become active limbs or attacking weapons by accident.
- For non-humanoid creatures, record `activeFeature` and `anchorSurface` instead of forcing `activeLimb`: horn, jaw, tail, branch, shell, belly mass, root feet, bottom puddle, or whole-body charge.
- Long weapons, tails, antlers, branches, banners, and wings require larger gutters or a larger final canvas. Do not shrink the character to fit a wide pose.

## Default 14-Frame Plan

Use six immutable anchors in this order: `00 -> 02 -> 05 -> 08 -> 11 -> 13`.

| Index | Role | Rule |
|---|---|---|
| 00 | baseline start | Place the exact source image on the final canvas; do not redraw or rescale it. |
| 01 | in-between | Interpolate 00 -> 02. |
| 02 | keyframe 1 | First generated defining pose. |
| 03-04 | in-betweens | Interpolate 02 -> 05 in chronological order. |
| 05 | keyframe 2 | Second generated defining pose. |
| 06-07 | in-betweens | Interpolate 05 -> 08 in chronological order. |
| 08 | keyframe 3 | Third generated defining pose. |
| 09-10 | in-betweens | Interpolate 08 -> 11 in chronological order. |
| 11 | keyframe 4 | Fourth generated defining pose. |
| 12 | in-between | Interpolate 11 -> 13. |
| 13 | baseline end | Exact copy of frame 00. |

Generate exactly four keyframes at indices 02, 05, 08, and 11. Save exact copies of those images into both `keyframe/` and the matching positions in `fullframe/`. Never redraw keyframes during the in-between stage. Insert 1 frame near each baseline endpoint and 2 frames between each pair of generated keyframes.

Persist `frameCount: 14`, `keyframeIndices: [2, 5, 8, 11]`, `anchorIndices: [0, 2, 5, 8, 11, 13]`, and `segmentInsertions: [1, 2, 2, 2, 1]` in `manifest.json`.
Persist `previewBackground: "#FFFFFF"` in `manifest.json`.

## Motion Library Patterns

The local `motion/` library shows these practical timing patterns:

- **Attacks:** usually `guard -> anticipation -> acceleration -> contact -> contact hold/follow-through -> recovery`. The contact pose should be the clearest silhouette. Attacks commonly widen to about `1.5x-1.6x` the neutral width while keeping character scale stable.
- **Idle:** small settle/rise/settle breathing loop, usually around `5%` width/height variation.
- **Move/walk:** contact/down/passing/up/opposite-contact, with clear feet alternation, small body bob, and stable mass.
- **Block:** compact guard raise/hold/return, fixed feet, little scale change.
- **Hit/suffer:** impact/recoil/squash/recovery; face and accessories can exaggerate, but identity stays locked.
- **Death:** imbalance/fall/impact/rest; do not force the final frame to loop to neutral.
- **Born/spawn:** small seed/egg/portal/curled silhouette unfolds into full identity; large size change is valid only for spawn-like actions.
- **Skill/cast:** anticipation/charge/peak cast/hold/recovery; detached effects should be separate overlays unless explicitly requested in the character sheet.

In every pose-sheet prompt, include the stable canvas rules:

```text
Same apparent character size in every cell.
Same foot/bottom baseline in every cell.
Body center stays near the same cell center except for intentional lunges.
Complete character, weapons, horns, ears, tails, claws, and effects remain inside the cell.
Allow the silhouette to widen for attacks, but do not scale the character smaller or larger.
```

For local post-processing, use one shared scale and one fixed foot/bottom baseline. Never auto-fit each frame independently. If a generated pose needs more horizontal or vertical room, enlarge the output canvas instead of shrinking the character.

### Action Prompt Templates

Use these beat templates when the user gives only a broad action request:

| Action | Key pose 02 | Key pose 05 | Key pose 08 | Key pose 11 |
|---|---|---|---|---|
| Compact melee slash | crouch/wind up; weapon draws up/back on locked side | fastest slash/chop; clear contact silhouette | low/front follow-through; body overcommitted | weapon returns to ready guard |
| Horn/body bash | body compresses; head/horn pulls back; side limbs brace | forward/down lunge; horn/shell/face leads | lowest compressed impact hold | body rises and re-centers |
| Claw swipe | active claw pulls back; anchor claw visible | active claw maximum extension | torso twist and follow-through | active claw returns to guard |
| Ground smash | body rises or fists/weapon lift overhead | hard drop to ground line | lowest squash; widest impact silhouette | heavy rebound upward |
| Idle | settle | rise | settle | neutral loop return |
| Move/walk | contact | down | passing/up | opposite contact |
| Block | begin guard raise | guard silhouette readable | hold guard | return to neutral |
| Hit/suffer | impact | recoil | squash/stretch | recovery |
| Death | imbalance | fall | impact | rest |
| Born/spawn | seed/egg/portal/curled shape | unfolding | nearly full form | neutral identity |
| Skill/cast | anticipation | charge | peak cast/hold | recovery |

## Workflow

### 0. Audit and Standardize the Baseline Frame

For the `/img2mo-std` baseline standardization sub-skill and command reference, read [skills/img2mo-std/SKILL.md](skills/img2mo-std/SKILL.md).

When the user invokes `/img2mo-std 图片名/位置`, resolve the image path, run the standardization step, and use the standardized output as the baseline for later animation generation.

Before baseline analysis or any `image_gen` call, check whether the input frame is a usable animation baseline:

- foreground subject longest side should be about `300-400 px`;
- transparent or removable background should surround the subject;
- every side should have enough action margin for walk bob, weapon arcs, hair, horns, cloak, tail, wings, or props;
- long weapons, capes, tails, antlers, banners, and large attack silhouettes need extra horizontal/vertical margin;
- source images much larger than this range should be standardized to reduce generation time and reduce model scale drift.

Use the bundled script when the image is too large, too tight, or has a white background:

```powershell
python scripts\standardize_baseline.py sample\s7.png
```

Default output is `sample/<name>-standard.png`. Use that standardized file as the animation baseline unless the user explicitly wants to keep the original. The script trims transparent/near-white background, resizes the visible subject so its longest side is 360 px by default, preserves aspect ratio, and adds transparent margins on all sides.

Useful options:

```powershell
python scripts\standardize_baseline.py sample\s7.png --subject-max 380 --margin-ratio 0.8
python scripts\standardize_baseline.py sample\s7.png --output sample\s7-standard.png
python scripts\standardize_baseline.py sample\s7.png --check-only
```

Treat the standardized baseline as the `00`/`13` source for validation. Keep the original file unchanged unless the user explicitly asks to overwrite it.

### 0.5. Load Project Knowledge

Before baseline analysis and prompt writing, check whether `img2mo-knowledge/index.md` exists.

If it exists:

- read `img2mo-knowledge/index.md`;
- for the requested action type, read `img2mo-knowledge/action-patterns.md` if present;
- for style-sensitive requests, read `img2mo-knowledge/style-patterns.md` if present;
- before writing prompts, read `img2mo-knowledge/prompt-patterns.md` if present;
- before validation/rejection decisions, read `img2mo-knowledge/failures.md` if present;
- search `img2mo-knowledge/learnings.jsonl` only for matching action types, character styles, or source tags when detailed examples are useful.

Use learned knowledge to improve beat choices, prompt clauses, canvas margins, style wording, and rejection checks. Do not copy old prompts blindly and do not reuse old generated output unless the user explicitly asks.

### 1. Analyze the Baseline Frame and Establish the Identity Lock

Inspect the source image at original resolution. Before generating images, write a reusable baseline-frame analysis that records every invariant that must survive redraw:

- subject type: what the character, creature, vehicle, weapon, or prop is, and how its overall silhouette reads;
- body structure: count, position, proportion, and facing of head, torso, limbs, wings, tail, claws, horns, shell, exoskeleton, etc.;
- face, expression, silhouette, proportions, and facing;
- palette, outline weight, shading style, material treatment, pixel/hand-drawn/cartoon/realistic style;
- limb count, hand order, clothing, armor, markings, and accessories;
- shoulder-to-limb topology, active-side mapping, anchor limb, and side-specific markings;
- weapon shape, grip, length, emblem, and distinctive small details.

Record uncertain or occluded regions explicitly. Use this analysis as the fixed identity block for all later keyframe prompts. Keep the source image visible during every generation and correction pass.

### 2. Design Motion Beats and Key Poses

Before generating images, choose readable motion beats:

- idle: settle -> rise -> settle;
- walk: contact -> down -> passing/step-through -> up -> opposite contact;
- attack: guard -> anticipation -> acceleration -> contact -> contact hold -> recovery;
- hit: contact -> recoil -> settle;
- death: imbalance -> collapse -> impact -> rest.

Choose exactly four generated key poses for indices 02, 05, 08, and 11. For attacks, use anticipation, acceleration/contact, contact hold/follow-through, and recovery. Frames 00 and 13 provide the neutral guard or baseline pose. The contact pose should have the clearest silhouette.

For one-limb actions, describe both sides in every beat: how the active limb remains connected to the locked shoulder, and how the anchor limb stays fixed. Track the full shoulder-to-hand trajectory, not only the hand tip.

### 3. Write the Four Keyframe Prompts

Before calling built-in `image_gen`, write detailed prompt briefs for keyframes 02, 05, 08, and 11. Each prompt must derive from the same baseline-frame analysis and must not reinterpret the character identity on the fly.

**Prompts are not the only input.** The four keyframe prompts are pose specifications, not the identity source. Do not let the model redraw keyframes independently from text alone; generation must also reference the baseline image as the visual identity anchor. If the current UI or tool cannot pass the baseline image as a reference input to `image_gen`, the prompt must request a `reference identity cell` in the output pose sheet: the first cell reproduces the baseline appearance for identity comparison only, and the next four cells are 02/05/08/11. Discard the reference cell during splitting; it is not an animation frame.

Each keyframe prompt must include:

- fixed identity block: subject, body parts, weapons, proportions, silhouette, palette, outline, material, art style, and details that must not change;
- current pose block: the action beat for that index, center of mass, body lean, head direction, active and anchor limb positions, weapon trajectory, contact point, and clear silhouette;
- continuity block: motion direction from the previous anchor to the next anchor, foot/bottom baseline, and relationship to the 00/13 loop;
- canvas and background block: complete character, equal cells, stable scale, ge