Create a Moving Vector Character from a Single Illustration
This is the procedure for adding a new character to this repository (vector-avator). From a single character illustration, create a front-facing standing figure and character sheets in a consistent art style, have Fable 5.2 draw the vector parts, inspect them, and animate them in the viewer.
The sample is a temporary bunny (character ID usagi. Original art in inputs/kariusagi/). Final outputs for each stage are in public/characters/usagi/vector/ and tools/vector/sheets/characters/usagi.* — compare them if you get stuck.
0. Prerequisites
Working directory: the root of this repository. All commands below use relative paths from root.
| Tool | Usage | Stage | How to Verify |
|---|---|---|---|
| Claude Code + Fable 5.2 | Required | 5. Part separation (sub-agent) | The sub-agent model can be set to Fable 5.2 |
| Codex CLI (imagegen) | Required | 2. Style conversion, 4. Sheets | codex --version, codex login done (works with ChatGPT plan, no API key needed) |
| Node 22, npm | Required | 7. Viewer, 8. Video | npm install done |
| Python 3.10+ | Required | 2–6 | python3 -m venv .venv && .venv/bin/pip install -r requirements.txt |
| resvg | Required | 6. Inspection reference images | resvg --version (e.g., cargo install resvg) |
| Playwright Chromium, ffmpeg | Required | 7–8. Screenshots & video | npx playwright install chromium, ffmpeg -version |
| MiniMax H3 (ComfyUI) | Optional | 3. Angle references | ComfyUI API (default http://127.0.0.1:8188). Skip stage 3 if unavailable |
| TTS | Optional | 8. Lip-sync audio | Without it, animate lip-sync from text |
If Fable 5.2 or Codex imagegen is unavailable, stop and tell the user. Substituting other models for part separation is known to yield insufficient quality.
Dev server port: Default is 5280 (npm run dev). If busy, start with npx vite --port <port> --strictPort and prefix all screenshot/video export commands (viewer_shots.mjs, record.mjs) with VIEWER_URL=http://127.0.0.1:<port>/. Also include the URL in the brief passed to Fable.
Estimated Cost & Time (Measured)
Measured when creating the sample bunny (47 parts). For second and subsequent characters, including waiting time, 1–1.5 hours per character. Human work is limited to writing character notes and reviewing.
| Stage | Assigned To | Time | Attempts |
|---|---|---|---|
| 1. Character notes | Claude (main) | ~10 min | — |
| 2. Front-facing stance | Codex imagegen | ~4.7 min | 2 generations, 1 adopted |
| 3. Angle references (optional) | MiniMax H3 | ~7 min | 1 |
| 4. Two sheets | Codex imagegen | ~5 min | 1 each |
| 5. Part separation | Fable 5.2 | ~16 min + ~2.5 min fixes | 1 + 1 fix |
| 6–7. Inspection, check, adjust | Claude (main) | ~20 min | — |
- Codex imagegen takes about 2–2.5 min per image. Hitting the ChatGPT plan usage limit may cause delays of several hours. One character needs 1–2 front views and 2 sheets.
- Fable 5.2 part separation took ~22 min (49 parts) and ~24 min (61 parts) for two other characters.
- When an agent unfamiliar with the project built one character (63 parts) using only this Skill, skipping angle references, the total was ~43 min (4 imagegen calls, 1 Fable call ~24 min/~280k tokens, 0 redo attempts).
- Token counts and costs were not measured.
Overall Flow
| Stage | Content | Tools | Output |
|---|---|---|---|
| 1 | Write character notes (features to preserve) | Manual | tools/vector/sheets/characters/<id>.md & .json |
| 2 | Convert original art to common style, create front-facing A-pose stance | make.py gen <id> restyle | ref/front.png |
| 3 | Extract frames from 360° rotation video (optional) | turntable.sh <id> | ref/turntable.mp4, ref/angle_*.png |
| 4 | Two sheets (turnaround + hand shapes, face variations) | make.py gen <id> sheet_turnaround & sheet_face | ref/sheet_turnaround.png, ref/sheet_face.png |
| 5 | Draw fill-only parts, completing hidden regions | Fable 5.2 + references/fable-brief.md | vector.json |
| 6 | Structural inspection and visual reference check | check_parts.py <id> | 0 errors |
| 7 | Animate and check in viewer | npm run dev, viewer_shots.mjs | Adjusted vector.json |
| 8 | Export video and lip-sync | record.mjs, lipsync.py | MP4 |
ref/ is public/characters/<id>/vector/ref/. Character IDs are lowercase alphanumeric (e.g., usagi). Trial images and Fable working files go to var/vector/<id>/ (not committed).
1. Write Character Notes
In tools/vector/sheets/characters/<id>.md, list features that must be preserved even when the style changes as bullet points. In <id>.json, write the original art path and its role. Place original art in inputs/<id>/ or similar.
- Writing style and sample in
references/character-notes.md. Sample bunny:tools/vector/sheets/characters/usagi.md&usagi.json. - Write colors as approximate values (
#RRGGBB). - The common style (
tools/vector/sheets/style_base.md) renders characters as "animals/creatures." For aspects where this makes the character look wrong (e.g., a hairless character getting tufts of fur, a non-human character redrawn as an animal), negate it explicitly in the notes with statements like "do not draw X" or "do not apply Y." Do not modify the common style file. - Even if the original art has a dynamic pose (body twist, bent arm), the
layouts/restyle.mdprompt instructs redrawing into a front-facing A-pose. You don't need to write this in the notes, but adding "pose is not a reference" in<id>.json'srolesfield helps stability.
Also register the character in the viewer, which Fable needs to check in Stage 5. data/characters/<id>.json:
{ "id": "<id>", "label": "<character name>", "vector": { "url": "characters/<id>/vector/vector.json" } }
2. Front-Facing Stance (Codex imagegen)
.venv/bin/python tools/vector/sheets/make.py gen <id> restyle --count 2
.venv/bin/python tools/vector/sheets/make.py log <id>
.venv/bin/python tools/vector/sheets/make.py adopt <id> restyle <number>
- The prompt is built from "common style + character notes + what to draw (
layouts/restyle.md)", passed to imagegen viacodex exec. Trials remain invar/vector/<id>/gen/with prompts and duration. - Always visually inspect the generated image, comparing it with the original art. Check: is it recognizable as the character? Is it 2–2.5 heads tall? Is it a true front-facing A-pose with gaps under the armpits? No eye highlights? No cross-eyes?
- If it doesn't match, fix with
--note "additional instructions"or rewrite the character notes. (Example: the sample bunny looked like a different character due to the common style's "fur volume," so it was negated in the notes.) Record the fix in the notes. adoptsaves the chosen image toref/front.png(1024×1536).
3. Angle References (Optional: MiniMax H3)
bash tools/vector/sheets/turntable.sh <id> # Set COMFY_SERVER to change ComfyUI URL
- First write
tools/vector/sheets/h3/<id>.txt(rotation video prompt) usingh3/usagi.txtas template. Only replace the character description part. - Output files
angle_045.png,angle_090.png,angle_180.pngare automatically added as reference images for generating sheet 4. H3 rotation is not constant speed, so angles are approximate. - Skip this stage if ComfyUI and H3 are unavailable. Part separation can work with sheets alone.
4. Two Character Sheets (Codex imagegen)
.venv/bin/python tools/vector/sheets/make.py gen <id> sheet_turnaround
.venv/bin/python tools/vector/sheets/make.py adopt <id> sheet_turnaround 1
.venv/bin/python tools/vector/sheets/make.py gen <id> sheet_face
.venv/bin/python tools/vector/sheets/make.py adopt <id> sheet_face 1
- Sheet 1: 4 views (front, 3/4, side, back) + 4 hand shapes (open, point, fist, palm). Sheet 2: face variations (eyes: open, half, closed; mouth: closed, ah, i, u, e, o; expressions: neutral, smile, surprised, troubled).
- The 3/4 and side views must face the character's left (same direction as H3 rotation).
- Inspect visually: is it the same character as the front stance? Are the variations consistent (e.g., half-closed eyes don't crush the iris)? If not, re-generate with
--note.
5. Part Separation (Fable 5.2 Sub-Agent)
- Fill in the template
references/fable-brief.mdwith: character ID, character name, character-specific notes, and the viewer URL (defaulthttp://127.0.0.1:5280/). Save tovar/vector/<id>/fable/brief.md. Writing style and sample (sample bunny) inreferences/character-notes.md. - Start a sub-agent with Fable 5.2 selected and pass the full
brief.md. Fable followsreferences/parts-spec.md, createspublic/characters/<id>/vector/vector.jsonwith drawing scripts, self-inspects, and reports. - Read the report, then perform inspection (Stage 6) and viewer check (Stage 7). If fixes are needed, request them from the same sub-agent (starting a new one loses context).
Mandatory rules (written in the template):
- Draw each part from scratch as a meaningful unit. Do not use pixel extraction or auto-trace for shapes.
- Draw fill only. Outlines are generated automatically at render time.
- Complete hidden regions (hair-hidden forehead, ear-base-hidden scalp, arm-removed torso, neck, tail base, etc.).
- Do not draw arms (they are generated at render time). Instead, measure and write skeleton landmarks, arm thickness, and arm color.
_Land_Rare the character's own left and right (in front view,_Lis on the right side of the screen).
6. Inspection
.venv/bin/python tools/vector/check_parts.py <id>
- Must pass with 0 errors. For warnings, judge based on content.
- Visually inspect the reference images (
var/vector/<id>/check/). Checklist:references/visual-qa.md. Crucially, check for holes or cut edges when foreground parts are hidden (qa_*.png), that variations (variants.png,expressions.png) match the sheets, and that the skeleton (skeleton.png) joints align with the art. - Reference images do not include auto-outlines or generated arms. Final appearance is verified in Stage 7.
7. Animate in the Viewer
-
Ensure
data/characters/<id>.json(created in Stage 1) exists. -
Start the dev server with
npm run devand openhttp://localhost:5280/?char=<id>(if two or more characters exist, a selection menu appears). -
Take screenshots to verify (with dev server running):
DSF=2 node tools/capture/viewer_shots.mjs var/vector/<id>/check/viewer \ neutral="char=<id>" face30="char=<id>&framing=face&yaw=30&blink=0" faceM30="char=<id>&framing=face&yaw=-30&blink=0" \ explain="char=<id>&motion=explain&t=1.0" spread="char=<id>&motion=spread&t=1.2" \ half="char=<id>&framing=face&eye=half&blink=0" point="char=<id>&motion=point&t=1.5" -
Check: Are there unwanted lines at the boundaries of parts on a white character? Do eyes stay within the face outline when turning head ±30°? Do ears/hair roots stay attached to the head? Are arm and hand thickness/color correct? How do dangling items sway?
-
Adjust values in
vector.json. Try values via URL parameters first, then write them. Seereferences/tuning.mdfor adjustable values andreferences/troubleshooting.mdfor common issues and fixes.
8. Export Video and Lip-Sync
# Video (with dev server running)
node tools/vector/record.mjs --out out/<id>_explain --motion explain --query "char=<id>"
# Lip-sync: from .wav and reading (Japanese in hiragana). TTS type is flexible
.venv/bin/python tools/lipsync/lipsync.py line.wav --text "こんにちは、よろしくおねがいします。" -o line.json
node tools/vector/record.mjs --out out/<id>_hello --motion talk_demo --lipsync line.json --audio line.wav --query "char=<id>"
- Without TTS, create video with text-driven lip-sync:
node tools/vector/record.mjs --out out/<id>_hello --motion talk_demo --seconds 6 --query "char=<id>&say=Hello, nice to meet you.". The speech repeats to match duration; video length is determined by motion length (or--secondsfor non-looping motions). For speech-length-based timing, use--seconds(rough guide: 0.15 sec per mora, 0.3 sec per punctuation). - For English speech:
--lang en. For volume-only (no text):--method rms. With Whisper word timestamps:--whisper whisper.json. - Background color:
--query "bg=ffd3e0". Hand-drawn lines:vHand=0–4(none, light, medium, heavy, hand-drawn+. Default heavy). - In the viewer, lip-sync JSON and audio files can also be loaded and played.
When Done
Report to the user:
- Created files (
ref/images,vector.json,data/characters/<id>.json) and locations of inspection images/videos - Time per stage and number of generations/redos
- Inspection results and remaining issues (parts you're unsure about, visual artifacts that couldn't be fixed)