img2threejs/img2threejs

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

解決的問題

img2threejs 可以將單個物體或角色的參考圖像轉換為程序化的 Three.js 模型。與攝影測量或網格提取不同，它使用純程式碼幾何、基元和程序化著色器重新構建物體，確保結果可直接用於動畫，並且對 AI 代理具有極高的 Token 效率。

工作原理

該專案使用了一個將 AI 代理（如 Claude Code）與確定性 Python 腳本相結合的分階段雕刻流水線。過程遵循嚴格的構建階段序列：

  1. Analysis: 系統對主體（物體、角色或混合體）進行分類，並建立定義身份特徵（倒角、螺絲、光澤等）的 detailInventory。
  2. Specification: 編寫 ObjectSculptSpec JSON，用於定義組件樹和材質。
  3. Iterative Sculpting: 模型透過多個階段構建（輪廓 $ ightarrow$ 結構 $ ightarrow$ 形狀精修 $ ightarrow$ 材質 $ ightarrow$ 表面 $ ightarrow$ 光照 $ ightarrow$ 互動 $ ightarrow$ 優化）。
  4. Review Loop: 在每個階段之後，Python 腳本會生成一份並排對比表（參考圖 vs 渲染圖）。AI 代理會根據視覺評分審查渲染結果，並決定是 continue、refine-spec 還是 refine-code。
  5. Output: 最終結果是一個 TypeScript 工廠函數，回傳一個帶有執行階段層級結構（樞軸、插槽和碰撞體）的 THREE.Group，用於動畫製作。

適用對象

希望無需依賴沉重的網格檔案或手動建模，直接從圖像生成 3D 資產的開發人員和技術美術師，特別是那些使用 AI 代理來自動化 3D 創建工作流的人員。

亮點

  • Code-only Reconstruction: 生成 TypeScript 程式碼而非二進位網格檔案，使資產具備可對比性（diffable）和版本控制能力。
  • Agent-Agnostic: 適用於任何具有視覺和瀏覽器工具的代理（例如 Claude Code, Codex）。
  • Token-Efficient: 將機械性任務（驗證、PBR 提取、對比打包）卸載到 Python 腳本中，以節省模型 Token。
  • Animation-Ready: 包含帶有樞軸和插槽的執行階段層級結構，而不是生成靜態網格。
  • Strict Quality Gates: 在規範足夠詳細以匹配物體複雜程度之前，防止進行程式碼生成。