Community图像github.com

vector-avator

Turn a single character illustration into a moving 2D vector avatar for this repository (vector-avator): restyle it and make two character sheets with Codex imagegen, have Fable 5.2 draw fill-only SVG parts with hidden regions completed, check them, and play gestures, head turns, blinking and lip-sync in the viewer. Use when the user wants to add a new character, redo a character's parts, or asks how the sample character was made. 一枚絵から、身振り手振りで動くベクターキャラを作る手順。

vector-avator 是什么?

vector-avator is a Claude Code agent skill that turn a single character illustration into a moving 2D vector avatar for this repository (vector-avator): restyle it and make two character sheets with Codex imagegen, have Fable 5.2 draw fill-only SVG parts with hidden regions completed, check them, and play gestures, head turns, blinking and lip-sync in the viewer. Use when the user wants to add a new character, redo a character's parts, or asks how the sample character was made. 一枚絵から、身振り手振りで動くベクターキャラを作る手順。.

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/grmchn/vector-avator/tree/HEAD/.claude/skills/vector-avator

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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.

ToolUsageStageHow to Verify
Claude Code + Fable 5.2Required5. Part separation (sub-agent)The sub-agent model can be set to Fable 5.2
Codex CLI (imagegen)Required2. Style conversion, 4. Sheetscodex --version, codex login done (works with ChatGPT plan, no API key needed)
Node 22, npmRequired7. Viewer, 8. Videonpm install done
Python 3.10+Required2–6python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
resvgRequired6. Inspection reference imagesresvg --version (e.g., cargo install resvg)
Playwright Chromium, ffmpegRequired7–8. Screenshots & videonpx playwright install chromium, ffmpeg -version
MiniMax H3 (ComfyUI)Optional3. Angle referencesComfyUI API (default http://127.0.0.1:8188). Skip stage 3 if unavailable
TTSOptional8. Lip-sync audioWithout 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.

StageAssigned ToTimeAttempts
1. Character notesClaude (main)~10 min—
2. Front-facing stanceCodex imagegen~4.7 min2 generations, 1 adopted
3. Angle references (optional)MiniMax H3~7 min1
4. Two sheetsCodex imagegen~5 min1 each
5. Part separationFable 5.2~16 min + ~2.5 min fixes1 + 1 fix
6–7. Inspection, check, adjustClaude (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

StageContentToolsOutput
1Write character notes (features to preserve)Manualtools/vector/sheets/characters/<id>.md & .json
2Convert original art to common style, create front-facing A-pose stancemake.py gen <id> restyleref/front.png
3Extract frames from 360° rotation video (optional)turntable.sh <id>ref/turntable.mp4, ref/angle_*.png
4Two sheets (turnaround + hand shapes, face variations)make.py gen <id> sheet_turnaround & sheet_faceref/sheet_turnaround.png, ref/sheet_face.png
5Draw fill-only parts, completing hidden regionsFable 5.2 + references/fable-brief.mdvector.json
6Structural inspection and visual reference checkcheck_parts.py <id>0 errors
7Animate and check in viewernpm run dev, viewer_shots.mjsAdjusted vector.json
8Export video and lip-syncrecord.mjs, lipsync.pyMP4

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.md prompt 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's roles field 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 via codex exec. Trials remain in var/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.
  • adopt saves the chosen image to ref/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) using h3/usagi.txt as template. Only replace the character description part.
  • Output files angle_045.png, angle_090.png, angle_180.png are 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)

  1. Fill in the template references/fable-brief.md with: character ID, character name, character-specific notes, and the viewer URL (default http://127.0.0.1:5280/). Save to var/vector/<id>/fable/brief.md. Writing style and sample (sample bunny) in references/character-notes.md.
  2. Start a sub-agent with Fable 5.2 selected and pass the full brief.md. Fable follows references/parts-spec.md, creates public/characters/<id>/vector/vector.json with drawing scripts, self-inspects, and reports.
  3. 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.
  • _L and _R are the character's own left and right (in front view, _L is 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

  1. Ensure data/characters/<id>.json (created in Stage 1) exists.

  2. Start the dev server with npm run dev and open http://localhost:5280/?char=<id> (if two or more characters exist, a selection menu appears).

  3. 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"
    
  4. 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?

  5. Adjust values in vector.json. Try values via URL parameters first, then write them. See references/tuning.md for adjustable values and references/troubleshooting.md for 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 --seconds for 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)

相关技能