toy-loops 是做什麼的?
小型紙藝世界(一座島嶼、一個露營地、一個片場),Claude 飾演主角,配上溫暖柔和的光線與如微縮模型般的淺景深。每個物體都由程式碼構建,每個影格都根據其編號計算得出,因此循環能完美閉合。此視覺風格是根據 Pimbo 在 anymation/3d_ref/style2 中的參考資料,並使用 reference-video-analysis 技能(第一輪分析:3d_ref/style2/analysis/FIRST_PASS.md)研究而來。這些參考資料是私人學習材料:請複製其工藝,切勿複製其場景。
狀態:v1,2026-11-18。 使用此技能製作並已審核的作品:
claude_isla:獲得 Pimbo 認可(「esta épica」)。claude_fogata:第二個循環動畫。director_hero:一張 2400x1200 的網頁主視覺圖片,有兩種配色。claude_pose:具有即時網頁眼睛的剪影。claude.glb:3D 模型。
所有檔案的位置
程式碼位於 Pimbo 電腦的資料夾:C:\Users\Pimbo\work\anymation\toy3d\skill。除非另有說明,以下所有路徑都是相對於其 kit/ 資料夾。
| 路徑 | 說明 |
|---|---|
lib/toy.py | 視覺風格:白色斜角邊緣的紙張材質、形狀、燈光、攝影機、渲染設定 |
lib/anim.py | 動畫師工具:緩動函數、Track(姿勢到姿勢)、彈簧、squash、arc、looped |
lib/chars.py | Claude:骨架及其六組眼睛;每影格呼叫一次 .pose(...) |
lib/runner.py | 逐影格渲染場景;每個場景都以 runner.run(...) 結尾 |
loops/<name>/scene.py | 一個循環動畫 |
stills/<name>/scene.py | 一張圖片(T = 1) |
tools/make_loop.py | 渲染、編碼為 GIF 1080/720 和 MP4 x1/x3、品質檢測、連絡表,一個指令搞定 |
tools/qa_loop.py | 循環接縫、影格數量、死幀停頓、與參考資料相比的動作量 |
tools/duotone.py | 圖片的藍色單色版本(網頁主視覺風格) |
tools/web_eyes.py | 一個網頁,Claude 的眼睛會跟隨游標,基於無眼睛的渲染結果 |
tools/claude_glb.py | 將 Claude 模型輸出為 .glb 格式(平面色彩,保留白色邊緣),在 Blender 內部執行 |
out/<name>/ | 輸出:frames/ 資料夾、最終檔案、sheet.jpg、qa.json |
完成的作品會複製到 anymation/toy3d/videos/<name>/;網頁作品則放在 anymation/toy3d/web/。
需求:
- Blender 5.2:Pimbo 的可攜帶版本位於
anymation/tools/blender;在其他環境請設定$BLENDER環境變數或將blender加入 PATH。 - ffmpeg 需在 PATH 中。
- 需安裝 Python 及 numpy 與 Pillow 函式庫,以執行工具。
Pimbo 不執行腳本:由你執行腳本並向他展示圖片結果。
不可打破的規則
- 建設之前先展示。 在開始一個新世界或角色前,先渲染 2-3 張靜態預覽(
--frames ... --scale 0.5),讓 Pimbo 選擇。在展示之前,你自己必須先仔細檢查每一張圖片。 pose(f)是影格的純函數。 影格之間不攜帶狀態,不使用無固定種子的亂數,所有週期性運動在每個循環中必須是完整的循環次數。跨越循環結尾的效果請使用looped()。- 像動畫師一樣製作動畫(詳見
references/ANIMATION.md)。首先撰寫律動表(dope sheet),然後使用帶有緩動函數的關鍵姿勢。每個動作前都要有預備動作(anticipation),撞擊時擠壓(squash),快速時拉伸(stretch),手臂有重疊動作(overlap),以及單影格的眼睛切換。絕對不要線性地移動身體。 - 只有當品質檢測通過(
make_loop.py會顯示 PASS/FAIL),並且你已逐影格檢視過每個動作的連續畫面(請見下方「連續截圖」),才算循環完成。 - 明確說明哪些是測量得出的 [M]、肉眼觀察得出的 [V] 以及假設的 [S]。
工作流程
| 步驟 | 內容 | 指令(在 kit/ 目錄下執行) |
|---|---|---|
| 1 | 構思:一個地點,一個有開頭且能循環回來的小故事;長度 6-9 秒 | 與 Pimbo 討論 |
| 2 | 複製最接近的場景:loops/claude_isla(白天,戶外)或 loops/claude_fogata(夜晚,道具,特效) | |
| 3 | 建立場景、放置 Claude、設定燈光與攝影機;檢視靜態預覽 | python tools/make_loop.py <name> --frames 0 --scale 0.5 |
| 4 | 撰寫律動表註解,然後建立各個 Track;渲染關鍵姿勢 | python tools/make_loop.py <name> --frames 44,62,66,71,77,81 |
| 5 | 快速預覽整個循環 | python tools/make_loop.py <name> --preview(每隔 8 幀顯示一張) |
| 6 | 完整渲染 + 輸出 GIF + MP4 + 品質檢測 | python tools/make_loop.py <name> |
| 7 | 為每個動作製作連續截圖檢查,修正問題後重新渲染 | 請見下方「連續截圖」 |
| 8 | 將完成的檔案複製到 anymation/toy3d/videos/<name>/,然後傳送給 Pimbo |
在 Pimbo 電腦上的耗時(RX 6800 XT)[M]:
- EEVEE: 每個 1080x1080 影格約需 0.7 秒,因此 200 影格的循環大約需要 2.5 分鐘。
- Cycles: 每個影格約需 10 秒,但視覺效果幾乎相同。僅在靜態圖片時使用:
--engine cycles --samples 256在 2400x1200 解析度下約需 20 秒。
連續截圖。 若要逐影格檢視某個動作:
ffmpeg -framerate 25 -start_number 56 -i out/<n>/frames/%04d.png -frames:v 30 -vf "crop=...,scale=260:-1,tile=6x5" -frames:v 1 strip.jpg
視覺風格簡介(詳細數據請見 references/LOOK.md)
- 玩具比例。 1 單位 = 1 公尺,Claude 約 9 公分寬。真實攝影機的景深(70 mm,f/4.5-7)即可自然產生微縮模型的模糊效果。
- 紙張材質。 每個立體物件都使用
paper(...):霧面色彩、纖維凹凸、柔和斑點。具有斜角的物件會自動應用白色邊緣材質(box、prism、disc)。 - 色彩。 色彩空間轉換使用 AgX 搭配 Punchy 風格。白天場景曝光值 -1,夜晚場景約 -0.35。
- 受光面:Claude 受光面的色彩接近參考資料(我們的是 #DA8D6C,參考資料為 #EC815B)。
- 亮度:白天影格的平均亮度為 120-140(參考資料範圍 91-181)。
- 燈光。 一盞暖色主光,高位且位於前方,使頂面比正面更亮。加上微弱的冷色補光和一盞暖色邊緣光。發光物體(火焰、星星、煙霧)使用
flame_mat和no_shadow。 - 攝影機。 在循環動畫中保持靜止(參考資料只在需要剪輯或推近鏡頭時移動攝影機)。
- GIF 使用正方形 1080 解析度。
- 英雄圖片是寬幅的,使用
shift_x將主體推到畫面三分之一處。
Claude 角色簡介(詳見 references/CHARACTERS.md)
claude = Claude('claude', loc)
然後每影格呼叫:
claude.pose(s, hop, pitch, roll, yaw, arm_l, arm_r, eyes, eye_big, eye_look, loc)
- 眼睛:
sq、happy(^ ^)、line(- -)、squeeze(> <)、dot(. .)、sad。 - 道具: 手持的道具會父子級聯到
claude.hand(side)。 - 揮手: 揮動的手臂必須是面向攝影機的那一隻。
網頁作品:即時眼睛與 3D 模型
- 即時眼睛。
- 使用
--eyes-off(和用於剪影的--transparent)進行渲染:python tools/make_loop.py claude_pose --transparent --eyes-off --tag _noeyes。渲染器會隱藏眼睛,並寫入eyes.json:包含每隻眼睛的像素中心點,以及以每毫米像素數為單位的人臉軸線。 - 執行
python tools/web_eyes.py <noeyes.png> <eyes.json> <out_dir> --ink-from <render with eyes>。它會產生index.html以及一個單檔<dir>_un_archivo.html。 - 該頁面的功能:
- 眼睛是在臉部平面上繪製的 SVG 形狀,因此在傾斜的臉部上也能保持正確的透視。
- 眼睛會以欠阻尼彈簧運動跟隨滑鼠游標,並每隔 2.5-5.5 秒眨眼一次。
- 游標靠近時顯示
^ ^,按壓時顯示> <。 - 點擊時會有擠壓拉伸彈跳效果(但使用
--hero時不會有此效果,--hero會保持完整圖片靜止)。
- 已在 Chrome 瀏覽器中透過 playwright 進行測試(滑鼠左移、右移、上移、下移、靠近、按壓、放開):未發現控制台錯誤。
- 使用
- 3D 模型。 執行
blender -b --factory-startup --python tools/claude_glb.py -- <out.glb> [--eyes sq]。它會輸出一個約 27 KB 的 GLB 檔案,寬度約 9 公分,已重新匯入並檢查過。 - 場景與
--eyes-off。 在建立時設定 Claude 姿勢的場景,必須在pose(f)中再次設定姿勢;--eyes-off只在該函數內生效(請參考stills/director_hero範例)。
品質檢測門檻(tools/qa_loop.py)
失敗(FAIL):
- 影格數量錯誤。
- 存在接縫:從最後一個影格到第一個影格的變化量大於正常步數的第 90 百分位數。
警告(WARN):
- 存在連續相同的影格(死幀停頓)。
- 運動量低於平均亮度的 0.8%。測量值 [M]:參考資料 r2/r3/r4 為 1.65/1.97/1.07%,
claude_isla為 0.89%,claude_fogata為 1.66%。
品質檢測無法評斷品味、表演或構圖。這些需要透過肉眼在靜態預覽和連續截圖上檢查。
已知錯誤(references/KNOWN_ERRORS.md)
那些會導致需要重新渲染的錯誤:
- 手臂舉起超過約 70° 時會隱藏在身體側面。
- 明亮的發光體在 AgX 色彩空間下會變成白色:請使用
flame_mat。 - 側面主光會使得正面變暗。
- 使用絕對灰階數值測量的夜晚場景會顯得「太安靜」。
- 弧形的背景板如果弧度太窄,會露出其邊緣。