video2threejs — 影片 → 程序化 Three.js 場景
從參考影片(Seedance / Sora / Veo 輸出,或實拍片段)重建為純程式碼、零資產的 Three.js 場景。目標是 1:1:相機、每個物體的位置和比例、色調、光線、角色外觀,以及角色遵循的動作時間軸。
以程式碼重建 — 非 NeRF、非影片轉網格、非下載資產包。是 img2threejs(從一張影像重建一個物體或角色)的姊妹技能;此技能涵蓋整個房間、人物和時間。
此檔案是始終載入的路由器。它包含操作順序、硬性規則及其理由、完成定義以及反模式。每個階段的完整合約位於 grimoire/ 檔案中,規則名稱即為檔案名 — 請在到達該階段時才閱讀,不要提前。
何時使用
- 使用者分享一個影片或包含影片的推文,並要求重建/複製/「用 three.js 做出這個」。
- 使用者詢問如何以程序化方式建模特定的軟質或有機物體(羽絨被、枕頭、毛絨玩具、動漫頭髮、貓)。
- 需要從影片片段中 1:1 重建一個房間或內部空間,用於遊戲、立體模型、互動致敬。
不適用於:單張影像的單一英雄物體(請使用 img2threejs),或可接受下載 GLB 資產的專案。
必要輸入
- 影片(mp4 URL / 推文 URL / 檔案)。如果是推文,請擷取媒體變體並下載 720p mp4。
- 使用者的容忍度:「1:1」(此技能的預設值)或「風格類似」。
- 一個可以運行開發伺服器的地方,讓使用者可以在瀏覽器中開啟。
硬性規則
以下每條規則都是在「藍色房間」案例研究中經過返工驗證的。它們不是風格偏好。
1. 雕刻時即時預覽
在建模任何東西之前,啟動開發伺服器並為使用者 open 頁面。以支援熱重載的階段撰寫場景(牆壁 → 家具 → 光線 → 角色 → 動作 → 開場相機)。在頁面角落放置一個階段標籤;將 window.onerror 路由到該標籤,以便運行時錯誤在頁面上可見。
原因: 錯誤的牆壁出現時的即時回饋成本最低,而不是在整個房間佈置好之後。
→ grimoire/build/live_preview.md
2. 首先從多個角度分析影片
從整個剪輯中提取至少 8 幀。對於空間事實(哪面牆、哪個角落、什麼東西在什麼上面),逐格讀取一個格線化幀;在第二幀中確認每個事實;如果透視仍然無法解析,請使用者在截圖上畫出角落和地板線。在撰寫程式碼之前,產生空間事實表、物體清單、色調、角色卡和動作場景表。
明確決定每個鏡頭什麼在移動 — 主體還是相機。搞反這個代價高昂:一個被動畫化為緩慢推近的鏡頭,結果是靜態相機觀看一隻手臂抬起來,而手臂沒有骨架。
原因: 三個有信心的重建都把窗戶放錯了位置;一次紅筆草稿就修正了。
→ grimoire/intake/multi_view_analysis.md,grimoire/intake/frame_extraction.md
3. 空間先於物體;求解相機
決定可見的牆壁和角落,設定座標系(左牆 x = LW,右牆 z = RW),然後使用 forge/solve_camera.py 求解相機的標誌點分數。只有這樣才能放置家具。
使用 forge/solve_camera.mjs 從測量值 — 標誌點螢幕位置和視覺大小 — 進行求解,並限制仰角,使求解器無法選擇錯誤的分支。在追求某個構圖之前,先檢查它是否可能:兩個複合參考鏡頭通常無法在一個尺度下共存(三角不等式測試,詳見 grimoire)。如此說明,選擇最接近的連貫構圖,然後繼續。
原因: 憑感覺放置的相機會使得之後的每次比較都失真;一個不可能的相機會使它們永遠失真。
→ grimoire/space/perspective_solving.md
4. 維護一個書面佈局合約
每行一個物體:牆壁、位置、大小、關係、參考幀。每次使用者修正都先編輯合約,然後再編輯程式碼。合約是家具、姿勢和相機求解器使用的位置的單一事實來源。
→ grimoire/space/layout_contract.md
5. 顏色來自像素
在格線化幀上對每個物體的受光和陰影區域進行取樣;在它們之間選擇基色,傾向明亮。永遠不要憑記憶輸入顏色。
→ grimoire/intake/frame_extraction.md
6. 真實光線,經過診斷,絕非繪製
堅實的牆壁帶有真實的窗戶開口;一個恰好覆蓋房間內部的屋頂;一個底部階梯為零的卡通色階;一個陰影相機覆蓋整個房間的暖色太陽。絕不要使用繪製的地板補丁、體積平面或浮動粒子來偽造光線。使用純太陽渲染進行診斷(?diag=sun):牆壁和天花板必須是黑色的,補丁必須落在幾何學預測的位置。
→ grimoire/build/lighting.md
7. 逐個物體雕刻到 8/10 分
在建造一個物體之前,列出其參考特徵(形狀、位置、顏色、配件)。建造後,從近距離相機截圖並為其評分。低於 8 分別繼續。幾何優先於紋理:羽絨被是垂墜的床單,書架是開放的並有真實的書,枕頭是厚的且傾斜的。
→ grimoire/build/procedural_recipes.md
8. 一個網格,雕刻而成 — 絕不拼裝
有機形態(頭、耳朵、軀幹、肢體、手、長袍)是一個封閉的表面,透過移動其自身的頂點來塑形:將其凸出、凹陷、從其一個面擠出一個肢體、用平滑場位移。不要用一個球體加一個圓錐再加一個膠囊拼湊在一起。拼裝的有機體每次都會產生:隨著光線移動的明亮接縫、圍繞埋藏部分的輪廓環、關節旋轉時脫落的部分、Z 軸閃爍、一個纏繞錯誤的子網格導致的「透明」外觀,以及任何材質調整都無法移除的陰影中斷。
何時適用: 參考中共享皮膚的任何東西在構建中都必須共享一個網格 — 鼻子就是向前推的臉,耳朵就是抬起的頭骨。真正分離的物體(燈、書、桿、窗框)保持為分離的基本體;位於表面上且永不變形的小型剛性固體(髮捲、鉚釘、花朵)是雕刻皮膚上的實例化珠寶;長而細的形狀是一個掃掠管,而不是一串膠囊。
兩種基板: 密集細分基本體上的位移場(頭部,近球形形態),或是盒狀建模骨架 + Catmull-Clark,然後是細節的位移(身體、肢體、手、服裝)。兩者都產生一個皮膚,骨架將綁定到這個皮膚上。
原因: 這個專案歷史上的每個拼裝有機體最終都被重建為一個網格,在接縫消耗了每次審查回合之後。
→ grimoire/build/one_mesh_sculpting.md,grimoire/build/box_modelling.md
9. 先推理,然後逐步雕刻,每一步都要完成
在觸碰幾何之前,先寫下形狀:基礎體積、哪些特徵是凸起的、哪些是凹陷的、哪些是斜率的變化,以及它們必須應用的順序 — 每一步都建立在上一步留下的表面上。然後將工作拆分為每個都留下一個有效、可檢查的表面的步驟(空白基礎 → 大平面 → 主要特徵 → 次要 → 精細細節),並在開始下一步之前完成每一步:為其截圖,傾印其數值輪廓,展示它,讓它被接受。第二步留下的搖擺在第五步是無法修復的,因為現在有五個場疊加在它之上。永遠不要有一個其結果只能在之後的步驟完成後才能判斷的步驟。
原因: 被 blob 逐個雕刻的頭部被丟棄了兩次;而同一個頭部按照 空白臉 → 凹陷 → 眼睛 → 嘴巴 → 鼻子 雕刻,每個箭頭一次簽核,結果被接受了。
→ grimoire/build/one_mesh_sculpting.md
10. 用數字驗證表面,而不是用眼睛
傾印一個跨越表面的輪廓 — 臉的中線、手掌的紋路、關節周圍的環 — 並檢查它在應該單調的地方是單調的。兩個凸起之間的一個平台,在眼睛看來像一個凹陷,而一個高光反射會隱藏兩者。在任何骨架操作之後,也要計算由 ≠ 2 個面使用的邊的數量:非零表示一個 T 型接合點,並且細分會將其渲染為一條硬摺痕。
→ grimoire/build/box_modelling.md,grimoire/build/one_mesh_sculpting.md
11. 封閉實體,正確的纏繞方向,盡可能一個表面
手動構建的掃掠管有兩個可能的三角形順序,只有一個朝外;錯誤的那個會使 FrontSide 剔除外殼,所以你看到的是物體的內部 — 人物看起來透明且「縫合得很差」,你會歸咎於材質。LatheGeometry 是一個開放管。關節球必須大於它們要封蓋的管端。偏好一個連續的輪廓(脖子和軀幹在同一個掃掠中)勝過兩個拼湊在一起的基本體:「距離足夠遠以至於不會顯示」這句話,一旦它們的橫截面不同或關節旋轉,就不再成立。使用 ?diag=flat(不透明材質 — 仍然透明表示幾何問題)、?diag=norm,然後 ?off=<part> 進行診斷。
原因: 幾個審查回合花在了為一個單行索引順序錯誤進行材質調整上。
→ grimoire/build/solid_geometry.md
12. 著色器會無聲地失敗 — 先連接錯誤鉤子
在撰寫任何自訂材質之前,先將 renderer.debug.onShaderError 連接到頁面上。一個編譯失敗的 ShaderMaterial 不渲染任何東西,並且只會在控制台中記錄。然後了解那些無聲的錯誤:modelMatrix 僅存在於頂點階段;pow(negative, 2.0) 和 smoothstep(hi, lo, x) 在 GLSL 中是未定義的,會產生 NaN;一個整數雜湊在執行位元運算之前溢位為 double,會產生偏差並使場景中的每個紋理變平;當相機掠過肢體時,菲涅耳效應無法產生大氣效果。
→ grimoire/build/shader_traps.md
13. 不確定時進行研究
如果某個構造未知(布料、頭髮、燈弧),搜尋 three.js 範例、論壇和姊妹技能,列出最多三種方法,選擇最可控的,引用來源,並將發現記錄在 grimoire/research/when_unsure.md 中。使用 node 驗證數學(尤拉角順序、幾何 φ 原點),而不是推理它。
→ grimoire/research/when_unsure.md
14. 動作必須看起來像人類
根骨骼尤拉角順序 YZX;大腿負值 = 向前,小腿正值 = 向後摺疊;在背部 rx=-π/2,俯臥增加 rz=π,側臥增加 rz=±π/2。頭的 rotation.x 與直覺相反 — Rx(+t) 看起來是向下。將戲劇性的手勢指定為 手掌在這裡,朝向那裡,手指那樣,並使用 forge/solve_ik_arm.mjs 求解它們,使用一個連續性項按序列對它們進行關鍵幀設定,使姿勢保持在一個分支上並插值為一個單一動作。路徑點(via)引導角色繞過家具。坐姿和臥姿的高度是從羽絨被頂部測量的。記錄任何「消失」角色的關節和邊界框。為每個場景截圖。
使用剛性分段和短鉸鏈(一個肢體直徑的混合,關節處的半旋轉骨骼,在關節上扇形的骨架循環)來綁定皮膚,並推導每個關節軸而不是假設它 — 手腕的屈曲軸是 前臂 × 手掌法線,而在肘部的鉸鏈軸上構建它會使關鍵幀完全不起作用。角色產生的效果屬於剪輯的時鐘,而不是鏡頭的時鐘。
→ grimoire/build/characters.md,grimoire/build/motion_timeline.md,grimoire/build/skinning_rig.md
15. 截取一切,然後自我審查
使用 GPU 路徑的 Headless Chrome(秒級),視口設定為影片的寬高比,與參考幀進行 hstack 水平堆疊。在交付之前,撰寫一個帶有差距列表的評分自我審查表,讓使用者選擇下一批次。「改進」不等於「完成」。
→ grimoire/review/verification.md,grimoire/review/self_review.md
16. 使用者的「否」清單是永久性的
使用者拒絕的所有內容都放入 grimoire/feedback/user_signals.md,絕不重新引入(浮動粒子、繪製的光線、樂高床單、絲狀頭髮、狗一樣的腿、牆上的光線……)。
→ grimoire/feedback/user_signals.md
17. 從專案根目錄部署
僅從專案目錄執行 vercel --prod(或任何部署)。撰寫專案 CLAUDE.md,包含座標系、相機、色調、光線、物體事實、除錯參數和使用者的清單。
→ grimoire/review/handoff.md
管線
| 階段 | 執行內容 | 輸出 | 閱讀文件 |
|---|---|---|---|
| 0 | 擷取影片,提取幀和格線圖像 | frame_*.jpg,grid_01.jpg | intake/frame_extraction.md |
| 1 | 多角度分析 | 事實表、清單、色調、角色卡、場景表 | intake/multi_view_analysis.md |
| 2 | 空間:牆壁 → 框架 → 相機求解 → 佈局合約 | landmarks.json,CAM/LOOK/fov,合約 | space/* |
| 3 | 使用即時預覽搭建框架;從模板建立階段性骨架 | 使用者觀看的運行中頁面 | build/live_preview.md |
| 4 | 光線 | 窗戶孔、屋頂、色階、太陽;?diag=sun 測試乾淨 | build/lighting.md |
| 5 | 逐個物體;有機形態作為一個雕刻網格,逐步進行 | 每個物體的特寫 ≥8/10 分,輪廓傾印 | build/one_mesh_sculpting.md,build/box_modelling.md,build/procedural_recipes.md,build/solid_geometry.md,build/shader_traps.md |
| 6 | 角色:雕刻 → 骨架 → 權重 → 姿勢關鍵幀 → 動作時間軸 | 每個場景的截圖,權重圖,IK 日誌 | build/characters.md,build/skinning_rig.md,build/motion_timeline.md |
| 6b | 體積效果(火、風暴、爆炸),與剪輯同步 | 軌道截圖 + 鏡頭內截圖 | build/volumetrics.md |
| 7 | 相機 UX:軌道、複製/持久化、開場 | C/R 鍵,開場鏡頭驗證 | build/camera_ux.md |
| 8 | 驗證和自我審查;與使用者循環 | 並排比較,評分表 | review/* |
| 9 | 部署和交付 | URL,專案 CLAUDE.md | review/handoff.md |
完成定義
- 與參考幀並排比較:牆壁、顏色、光線和物體位置在 1 個物體直徑的容忍度內匹配。
- 所有物體都依據其參考特徵進行了雕刻和評分,分數 ≥8/10。
- 角色已建模、綁定皮膚、設定了關鍵幀,並且其動作在視覺上令人信服。
- 鏡頭構圖與參考影片中的相機運動或靜態鏡頭相符。
- 場景從專案根目錄成功部署,無錯誤。
- 所有使用者回饋都已記錄在
grimoire/feedback/user_signals.md中,並且「否」清單中的項目已被移除。