img2threejs/img2threejs

img2threejs – 將單張參考圖轉換為程序化 Three‑js 模型

是什麼

• 一種技能型函式庫，讓大型語言模型 (Claude, Codex, 等) 可以透過單張物體或角色圖片，輸出 TypeScript code，僅使用 primitives、procedural shaders 和生成的 geometry 來構建相同的內容。輸出結果是一個準備好進行動畫製作的 THREE.Group 工廠，無需 mesh files，無需下載。

運作方式

1. Intake – 將圖片輸入給 LLM (或任何 “agent‑vision” 工具)。模型會對主題 (object, character, …) 進行分類，並建立一個定義身份特徵的 detail inventory (例如：倒角、螺絲、磨損、顏色等)。
2. Spec generation – 一個確定性的 Python 腳本 (forge/state.py) 會記錄證據清單，並建立一個描述 geometry、materials 和 hierarchy 的 JSON spec。
3. Code synthesis – LLM 會生成一個 TypeScript factory，利用 Three.js primitives、custom shaders 和（可選的）voxel‑carved silhouettes 來重建重建 spec。
4. Vision‑review loop – 在每一輪 (blockout → structural → material → surface …) 之後，渲染結果會與參考圖進行比較；任何缺失的細節區塊都會持續進行，直到滿足門檻 (gate) 為止。
5. Runtime output – 最終的 code 可以在瀏覽器中執行，並暴露 pivots、sockets 和 userData，以便模型可以立即進行動畫製作。

關鍵特性

• Token‑efficient: 僅視覺判斷與 code generation 消耗 LLM tokens；繁重的任務由確定性的 Python validation 處理。
• Domain plugins: 插件系統 (plugin‑cs2, plugin‑character, plugin‑img2glb, …) 為特定的資產家族添加了專門的清單與重建規則。
• Quality gates: 每個細節都必須對應到一個真實的組件；管線 (pipeline) 會拒絕“用來“發明”隱藏的 geometry。
• Multi‑view silhouette carving (可選) 在提供多個視角時，可進行基於 voxel 的 hull 構建。
• Live demo gallery: 一個公開網站展示了數十個生成的模型，並附帶 source code links。

典型使用場景

• 需要從概念圖中獲得輕量化、可進行動畫製作的 Three.js 模型之遊戲資產管線 (game‑asset pipelines)。
• 在不導出重型 mesh files 的情況下，快速原型設計 3D UI 元件或產品視覺化。
• 關於程序化 geometry 如何逼近真實世界物體的教學演示。
• 擴展 AI agents (Claude Code, Codex, OpenCode) 的 “rebuild this object” 能力。

入門指南

# Clone the skill into your Claude/Codex skills directory
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

# (Optional) Install the plugin harness and domain plugins
npx github:img2threejs/img2 install          # creates ~/.img2 and the `img2` launcher
img2 add img2threejs/plugin-cs2               # CS2 weapon‑skin rules
img2 add img2threejs/plugin-character         # animated‑character pipeline

執行技能 (在 Claude Code 或任何可以呼叫技能的 LLM 之中):

/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.

該技能會:

1. 分析附帶的圖片,
2. 產出一個逐步的 spec,
3. 生成 TypeScript factory,
4. 並與原始參考圖進行並列的 live preview。

進階控制 – 你可以在 prompt 中嵌入明確的限制條件來引導門檻 (gates)，例如:

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
Fidelity   Hold proportions and silhouette, enumerate bevels, seams, fasteners, wear.
Materials  Derive finish and gradient stops from the pixels, flag colours that won’t tone‑map.
Runtime    Expose pivots andsks much more than one view is supplied.

每一行都對應到管線 (pipeline) 中的一個真實 validation gate。

在哪裡可以看見它

• Live demo gallery: https://img2threejs.io/ (每個 demo 都在連結至生成的 source code).
• Showcase repo: https://github.com/img2threejs/img2threejs-showcase.
• Architecture details: docs/ARCHITECTURE.md 在 repository 中.

License & community

• Apache 2.0.
• 歡迎貢獻 (參見 CONTRIBUTING.md).
• 由 Atlas Cloud, Tripo, Hyper3D, 以及 Ko‑fi 頁面贊助。

---

*簡而言之，img2threejs 是一個 AI 增強型管線 (pipeline)，將單張圖片轉換為乾淨、可進行動畫製作的 Three.js code，並高度關注於確定性的 validation 及其可擴展的 domain plugins。