Communitygithub.com

video2threejs

從參考影片(AI生成或實拍)重建一個房間/場景,轉化為純程式碼的 Three.js 立體模型,在佈局、顏色、光線、物體、角色及其動作時間軸上達到1:1還原。

video2threejs 是什麼?

這項技能專為需要從影片(例如 Seedance、Sora、Veo 等 AI 生成或實拍的影片)重建三維空間的開發者設計。它不同於 NeRF 或影片轉網格的方法,完全依賴程式碼生成一個零資產的 Three.js 場景,目標是達到1:1的精確還原,包含相機視角、每個物體的位置和比例、色調、光線、角色外觀以及角色的動作時間軸。技能內建了即時預覽、多幀分析、透視求解、細節雕刻、不確定時的研究機制以及截圖驗證的迭代流程,確保重建的準確性。此技能特別適合處理包含多個物體和角色的室內場景,與專門處理單一物體或角色的 img2threejs 技能互補。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/pacb9148/Video2ThreeJS/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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.jpgintake/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.mdreview/handoff.md

完成定義

  • 與參考幀並排比較:牆壁、顏色、光線和物體位置在 1 個物體直徑的容忍度內匹配。
  • 所有物體都依據其參考特徵進行了雕刻和評分,分數 ≥8/10。
  • 角色已建模、綁定皮膚、設定了關鍵幀,並且其動作在視覺上令人信服。
  • 鏡頭構圖與參考影片中的相機運動或靜態鏡頭相符。
  • 場景從專案根目錄成功部署,無錯誤。
  • 所有使用者回饋都已記錄在 grimoire/feedback/user_signals.md 中,並且「否」清單中的項目已被移除。

相關技能