img2threejs 手記：參考圖到程序化 Three.js 模型的介紹與用法

這是 aogl.cn 上的一篇個人原創使用手記，本地歸檔在 original/img2threejs/（2026-08-03）。主題是開源項目 img2threejs（Apache-2.0，本稿對照 v1.4.3）：把一張參考圖重建成純代碼寫出的程序化 Three.js 模型——不是 photogrammetry、不是扒 mesh、也不是下載素材包。產出是可 diff 的 TypeScript THREE.Group 工廠，帶 pivots / sockets / colliders，方便動畫與交互。本文寫清它是什麼、和常見 image-to-3D 差在哪、怎麼安裝與調用、如何加嚴門禁、何時該停，並附 showcase 截圖，方便檢索「image to Three.js」「procedural Three.js from photo」「Claude Code skill 3D」等長尾詞。

logo.svg — 項目標識（歸檔自上游 assets）。

它解決什麼問題

瀏覽器裡做道具、硬表面物體、甚至部分角色時，常見兩條路：一是把 mesh / GLB 扔進場景；二是讓大模型「一句話生成一段 Three.js」。前者難版本管理、難審查；後者容易一次出一坨不可維護的幾何，還燒大量 token。img2threejs 的承諾更窄、更硬：

Reconstruction-by-code — 用 primitives、程序化 shader 與生成幾何「雕」出物體。
Quality-gated — 分 pass 構建，每步要有渲染 vs 參考的對照，未過門禁不前進。
Token-efficient — 校驗、門禁、對比圖打包交給 Python 腳本；模型 token 主要花在視覺判斷與寫代碼。
Animation-ready — 不是死網格，而是帶運行時層級的工廠函數。

官方 Live Gallery 在 img2threejs-showcase：每個 demo 都是生成代碼在瀏覽器裡跑，可繞轉、看參考、讀源碼。我歸檔的 bmx-endurance.png 就是其中「BMX Endurance Bike」頁的界面截圖——橙車架、五輻輪、側牆字樣與零件列表（frame / welds / handlebar…），並有 Explode parts、View generated source 等按鈕。

img2threejs showcase BMX Endurance Bike — 程序化 Three.js 重建與零件列表 — `bmx-endurance.png` — Showcase 實機截圖：參考重建結果 + 側欄元數據。

和「一鍵出 3D」有什麼不同

SEO 上很多人搜 image-to-3D，期待的是深度估計或高斯濺射。img2threejs 刻意不做那條路。它先寫 ObjectSculptSpec（部件、材質、燈光、pivots），再按固定順序雕：

blockout → structural → form → material → surface → lighting → interaction → optimization

每個 pass 解鎖前，要有真實渲染、對照表、agent vision 分數，以及身份關鍵細節各自過線。腳本負責「能不能生成」；模型負責「像不像」。這讓輸出可審查、可回退到 refine-spec / refine-code，而不是黑盒 mesh。

怎麼安裝（Claude Code / 同類 agent）

Skill 設計為 agent-agnostic，文檔常以 Claude Code 為例，也可在 Codex、OpenCode 等環境下使用——「agent vision」用宿主提供的讀圖、瀏覽器 MCP 或你提供的截圖即可。

把倉庫克隆到 skills 目錄（路徑按你的工具約定調整）：

git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

確認本機有 Python 3.10+。forge 腳本聲稱純標準庫，無需 pip 安裝依賴。
準備一張清晰的物體參考圖（正面或 3/4 角、主體完整、光照不要糊成一團）。

本地筆記 original/img2threejs/rd.txt 也摘錄了同一克隆命令與示例 prompt，方便離線對照。

怎麼用：最短調用

在 Claude Code 裡附上或指向圖片後運行：

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

中文意圖等價寫法可以是：「用 img2threejs 把這張圖重建成程序化 Three.js 模型，保持比例、角度與顏色。」Skill 會自行做主體分類（object / character / hybrid）、細節清單（detail inventory），並按門禁推進各 pass。你需要做的是：看每一步的對照圖，確認身份特徵是否真的對齊，而不是隻看全局分數。

怎麼用：加嚴提示（把判斷寫進門禁）

一句話會把判斷交給 skill。若你已經知道「什麼叫對」，把要求寫進 prompt——這些句子會映射到真實的 gate / artifact，而不只是形容詞：

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
Fidelity   Hold proportions and silhouette to the reference. Enumerate identity-defining
           details first — bevels, seams, fasteners, engraved/painted linework, gloss vs matte,
           wear — and drop details you cannot place on a real component.
Materials  Derive finish class and gradient stops from reference pixels, not memory.
Runtime    Expose pivots/sockets for moving parts, plus userData.tick for idle loops.
Gates      Run --strict-quality; do not advance until side-by-side review passes.
           Report per-region confidence for hidden faces.

按主體追加一句往往很有用：

特定人物 / 角色 — 要求 maximize likeness：參數模板對齊 landmark、de-light、相機匹配、再投影；並寫明哪些區域是推斷。
動物 / 生物 — 聲明非人形，走 quadruped（或對應）體型與 body-unit 比例。
陽極氧化 / candy 塗層 — 點名 candy-coat，別讓環境光偷色。
省 token — 要求 low effort，跳過 presentation composer，只要評估渲染。

怎麼用：不用 agent、只跑 forge 腳本

在 skill 根目錄可逐步手工跑（適合理解流水線或 CI）：

python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

完整腳本表與 token 設計見上游 docs/ARCHITECTURE.md。日常建議先跑 python3 forge/next.py <spec>：它會告訴你當前解鎖的 pass、下一條命令與未滿足的驗收條件——這是 SKILL.md 強調的「先問 next」習慣。

流水線裡我會盯的關卡

Suitability — 這張圖適不適合當 3D 目標。
Pre-spec + strict-quality — 規格太淺就禁止 codegen，避免白燒渲染。
Detail inventory — 螺絲、倒角、線稿、磨損等必須落到真實 component / material，不能只寫散文。
Screenshot feedback — continue 需要對照表 + 過線分數；身份特徵錯了，全局分再高也算失敗。
Action-ready — userData.sculptRuntime 一類運行時層級要在。

CS2 刀皮 / Glock 等路線還有家族級部件合同與投影優先的 finish 策略：圖案皮膚優先用去光照後的參考投影，而不是瞎編程序化 Doppler——否則對照圖一眼假。細節在上游 docs/cs2/review-gates.md 與 grimoire/build/cs2_finishes.md。

誠實邊界（寫進文章也是 SEO 誠實信號）

單張圖看不見背面，不能保證精確幾何。Skill 應明確標註 approximate / stylized / low-poly，並用鏡像等策略推斷不可見面，而不是假裝自信。硬表面物體通常更強；角色是風格化重建，不是照片級 likeness。輸出「這張圖達不到你要的保真度」是合法、預期的結果——這也是我願意把它收進本站書籤手記的原因：流程可調試，而不是營銷口號。

在本站的歸檔方式

original/img2threejs/bmx-endurance.png — Showcase BMX 頁截圖（封面源）。
original/img2threejs/logo.svg — 項目 logo。
original/img2threejs/rd.txt — 倉庫鏈接、gallery 鏈接與 quick-start 摘錄。

上游完整源碼請以 GitHub 為準；本站手記負責可索引的中英文用法說明 + 本地截圖證據，並與交互地球等 WebGL 原創並列，方便「Three.js 程序化 / AI agent 出模型」類檢索落到真實頁面。