從一張插圖,打造會動的向量角色
此儲存庫(vector-avator)新增角色的步驟。從角色的一張插圖開始,統一畫風做出正面站立姿態與角色表,交由 Fable 5.2 用向量繪製零件,經檢查後在檢視器中運作。
範例為假兔子(角色 ID usagi,原始圖片在 inputs/kariusagi/)。各階段的完成品放在 public/characters/usagi/vector/ 與 tools/vector/sheets/characters/usagi.*,有疑慮時可相互對照。
0. 前置條件
工作目錄為此儲存庫的根目錄。 以下所有指令皆以根目錄為相對路徑。
| 工具 | 用途 | 使用階段 | 確認方式 |
|---|---|---|---|
| Claude Code + Fable 5.2 | 必備 | 5. 零件分解(子代理程式) | 子代理程式的模型需能指定為 Fable 5.2 |
| Codex CLI(imagegen) | 必備 | 2. 風格轉換、4. 角色表 | codex --version、codex login 已完成(透過 ChatGPT 方案運作,不需 API 金鑰) |
| Node 22、npm | 必備 | 7. 檢視器、8. 影片 | npm install 已完成 |
| Python 3.10 以上 | 必備 | 2~6 | python3 -m venv .venv && .venv/bin/pip install -r requirements.txt |
| resvg | 必備 | 6. 檢查用確認圖片 | resvg --version(例如 cargo install resvg) |
| Playwright 的 Chromium、ffmpeg | 必備 | 7~8. 拍攝與影片 | npx playwright install chromium、ffmpeg -version |
| MiniMax H3(ComfyUI) | 選用 | 3. 角度範例 | ComfyUI 的 API(預設 http://127.0.0.1:8188)。若無則跳過步驟 3 |
| TTS | 選用 | 8. 嘴型同步語音 | 若無則使用文字嘴型同步 |
若無法使用 Fable 5.2 或 Codex imagegen,請告知使用者並停止。使用其他模型替代零件分解,已知品質不足。
開發伺服器連接埠: 預設為 5280(npm run dev)。若已佔用,請使用 npx vite --port <埠> --strictPort 啟動,並在拍攝與影片匯出指令(viewer_shots.mjs、record.mjs)後加上 VIEWER_URL=http://127.0.0.1:<埠>/。提供給 Fable 的提示中也需包含該 URL。
費用與時間估算(實測值)
以下為製作假兔子(47 個零件)的實測數據。從第二個角色起,含等待時間 每個角色約 1~1.5 小時。人力工作僅限於角色特徵條列與審查。
| 階段 | 負責 | 時間 | 次數 |
|---|---|---|---|
| 1. 角色補充說明 | Claude(主) | 約 10 分鐘 | — |
| 2. 正面站立姿態 | Codex imagegen | 約 4.7 分鐘 | 生成 2 次,採用 1 張 |
| 3. 角度範例(選用) | MiniMax H3 | 約 7 分鐘 | 1 次 |
| 4. 兩張角色表 | Codex imagegen | 約 5 分鐘 | 各 1 次 |
| 5. 零件分解 | Fable 5.2 | 約 16 分鐘 + 修正約 2.5 分鐘 | 1 次 + 修正 1 次 |
| 6~7. 檢查、確認、調整 | Claude(主) | 約 20 分鐘 | — |
- Codex imagegen 每張約需 2
2.5 分鐘。若 ChatGPT 方案用量達到上限,可能需要等待數小時。每個角色需要正面立繪 12 次與角色表 2 次。 - Fable 5.2 的零件分解,在其他兩個角色上分別約需 22 分鐘(49 個零件)與 24 分鐘(61 個零件)。
- 若由不熟悉流程的代理程式僅憑此技能製作一個角色(63 個零件),跳過角度範例後總計約 43 分鐘(imagegen 4 次、Fable 1 次約 24 分鐘、約 28 萬個 token,無需重做)。
- Token 數與費用未經量測。
整體流程
| 階段 | 內容 | 工具 | 輸出 |
|---|---|---|---|
| 1 | 撰寫角色補充說明(應保留的特徵) | 手寫 | tools/vector/sheets/characters/<id>.md、.json |
| 2 | 將原始圖片轉換為統一風格,製作正面 A 字站立姿態 | make.py gen <id> restyle | ref/front.png |
| 3 | 從 360 度旋轉影片裁切圖片(選用) | turntable.sh <id> | ref/turntable.mp4、ref/angle_*.png |
| 4 | 兩張角色表(四面圖 + 手部姿勢、臉部表情差異) | make.py gen <id> sheet_turnaround、sheet_face | ref/sheet_turnaround.png、ref/sheet_face.png |
| 5 | 繪製僅填充的零件,並補齊隱藏部分 | Fable 5.2 + references/fable-brief.md | vector.json |
| 6 | 結構檢查與確認圖片目視 | check_parts.py <id> | 錯誤 0 件 |
| 7 | 在檢視器中操作並確認、調整 | npm run dev、viewer_shots.mjs | 調整後的 vector.json |
| 8 | 影片匯出與嘴型同步 | record.mjs、lipsync.py | MP4 |
ref/ 即 public/characters/<id>/vector/ref/。角色 ID 使用小寫英數字(例如:usagi)。嘗試用的圖片與 Fable 的工作檔案存放在 var/vector/<id>/(不納入版本控制)。
1. 撰寫角色補充說明
在 tools/vector/sheets/characters/<id>.md 中以條列方式寫下即使改變畫風也應保留的特徵。<id>.json 則記錄原始圖片路徑及其用途。原始圖片放在 inputs/<id>/ 等目錄。
- 撰寫方式與範例請參考
references/character-notes.md。假兔子的範例:tools/vector/sheets/characters/usagi.md、usagi.json。 - 顏色以近似值(
#RRGGBB)書寫。 - 統一畫風(
tools/vector/sheets/style_base.md)會將角色描繪為「動物、生物」。若因此導致角色特徵改變(例如無毛角色長出毛簇、非人物角色被重繪為動物),請在補充說明中明確記載「不要畫~」「不套用~」以取消該效果。請勿修改統一畫風的檔案。 - 即使原始圖片為動態姿勢(身體扭轉、手臂彎曲),重新繪製正面 A 字姿勢的指示由
layouts/restyle.md負責,無需寫入補充說明。在<id>.json的roles中加入「姿勢僅供參考」可提高穩定性。
同時在檢視器中註冊角色。步驟 5 中 Fable 在檢視器中確認時需要此項。data/characters/<id>.json:
{ "id": "<id>", "label": "<角色名稱>", "vector": { "url": "characters/<id>/vector/vector.json" } }
2. 正面站立姿態(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 <編號>
- 提示會組合「統一畫風 + 角色補充說明 + 繪製內容(
layouts/restyle.md)」,透過codex exec傳遞給 imagegen。嘗試記錄存放在var/vector/<id>/gen/,包含提示與耗時。 - 生成後的圖片務必親眼檢視,與原始圖片並排比對。檢查重點:能否辨識出該角色、是否約 2~2.5 頭身、是否為正面 A 字姿勢且腋下有間隙、眼睛是否無高光、是否未對眼。
- 若不符合,使用
--note "補充指示"修正,或重新撰寫角色補充說明(例如假兔子因統一的「毛髮量感」導致看起來像不同角色,因此在補充說明中取消此效果)。修正內容應保留在補充說明中。 adopt會將採用的圖片統一調整為ref/front.png(1024×1536)。
3. 角度範例(選用:MiniMax H3)
bash tools/vector/sheets/turntable.sh <id> # 可透過 COMFY_SERVER 變更 ComfyUI 的 URL
- 先以
tools/vector/sheets/h3/usagi.txt為範本,撰寫tools/vector/sheets/h3/<id>.txt(旋轉影片的提示)。僅需替換角色描述部分。 - 輸出的
angle_045.png、angle_090.png、angle_180.png會自動加入步驟 4 角色表生成的參考圖片中。由於 H3 的旋轉並非等速,角度僅供參考。 - 若無 ComfyUI 與 H3,則跳過此階段。即使僅有角色表,零件分解仍可進行。
4. 兩張角色表(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
- 第一張為四面圖(正面、斜側、側面、背面)與四種手勢(張開、指向、握拳、手掌);第二張為臉部表情差異(眼睛:睜、半閉、閉;嘴巴:閉、啊、伊、嗚、欸、哦;表情:正常、微笑、驚訝、困擾)。
- 斜側與側面需繪製為臉部朝向畫面左方(與 H3 旋轉方向一致)。
- 親眼確認是否與正面站立姿態為同一角色、表情差異是否一致(例如半閉眼時虹膜是否未壓扁)。若不符合,使用
--note修正後重新生成。
5. 零件分解(Fable 5.2 子代理程式)
- 將
references/fable-brief.md範本中的角色 ID、角色名稱、角色注意事項、檢視器 URL(預設http://127.0.0.1:5280/)填入,儲存為var/vector/<id>/fable/brief.md。角色注意事項的撰寫方式與範例(假兔子)請參考references/character-notes.md。 - 啟動指定為 Fable 5.2 的子代理程式,傳入完整的
brief.md內容。Fable 將依照references/parts-spec.md,透過繪圖腳本建立public/characters/<id>/vector/vector.json,自行檢查後回報結果。 - 閱讀回報,進行步驟 6 的檢查與步驟 7 的確認。如需修正,請在同一個子代理程式中繼續提出要求(重新啟動會遺失對話歷程)。
需確保的事項(已寫入範本):
- 零件應以意義為單位從零開始繪製。不得使用像素裁切或自動描邊來決定形狀。
- 僅使用填色繪製。線條將在繪製時自動產生。
- 需補齊隱藏部分(瀏海下的額頭、耳朵根部下方的頭部、手臂以外的身體、頸部、尾巴根部等)。
- 不繪製手臂圖形(將於繪製時生成),而是測量並記錄骨骼標記與手臂粗細、顏色。
_L、_R代表角色自身的左右(正面圖中_L位於畫面右側)。
6. 檢查
.venv/bin/python tools/vector/check_parts.py <id>
- 錯誤 0 件為合格。警告則依內容判斷。
- 親眼檢視確認圖片(
var/vector/<id>/check/)。檢查重點詳見references/visual-qa.md。特別注意:隱藏前方零件後的狀態(qa_*.png)中是否有洞或切口、差異圖(variants.png、expressions.png)是否與角色表一致、骨架(skeleton.png)的關節是否與繪圖一致。 - 確認圖片中不含自動輪廓線與生成的手臂。最終外觀請在步驟 7 中確認。
7. 在檢視器中操作
-
確認
data/characters/<id>.json(已在步驟 1 建立)已存在。 -
執行
npm run dev啟動開發伺服器,開啟http://localhost:5280/?char=<id>(若有多個角色,畫面會顯示選擇欄位)。 -
拍攝截圖進行確認(開發伺服器運作中):
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" -
檢查重點:白色角色零件邊界是否出現多餘線條、轉頭 ±30° 時眼睛是否未超出臉部輪廓、耳朵與頭髮根部是否未脫離頭部、手臂與手掌的粗細與顏色是否吻合、擺動物的搖晃方式是否自然。
-
調整透過
vector.json的數值進行。可先透過 URL 參數測試數值再寫入。可調整的數值列表請參考references/tuning.md,常見問題與對策請參考references/troubleshooting.md。
8. 影片匯出與嘴型同步
# 影片(開發伺服器運作中)
node tools/vector/record.mjs --out out/<id>_explain --motion explain --query "char=<id>"
# 嘴型同步:從 wav 與朗讀內容(日語用假名)產生。TTS 種類不限。
.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>"
- 若無 TTS,亦可使用文字嘴型同步製作影片:
node tools/vector/record.mjs --out out/<id>_hello --motion talk_demo --seconds 6 --query "char=<id>&say=こんにちは、よろしくね。"。台詞會配合時鐘重複播放,影片長度由動作長度決定(非循環動作則使用--seconds)。若希望於台詞結束時停止,請指定--seconds(估算:每個音節 0.15 秒,標點符號 0.3 秒)。 - 英文台詞請使用
--lang en,僅需音量而無文字時使用--method rms,若有 Whisper 產生的單字時間戳則使用--whisper whisper.json。 - 背景色可透過
--query "bg=ffd3e0"設定,手繪風格線條強度透過vHand=0~4調整(無、弱、中、強、手繪+。預設為強)。 - 在檢視器中也可載入嘴型同步 JSON 與音訊檔案進行播放。
完成後
向使用者回報以下內容:
- 產生的檔案(
ref/中的圖片、vector.json、data/characters/<id>.json)以及確認圖片與影片的位置 - 各階段耗時與生成、重新生成的次數
- 檢查結果與剩餘問題(信心不足的零件、無法完全修正的外觀問題)