img2threejs

hoainho/img2threejs — 参照画像をコードのみの手続き的 Three.js モデルへ再構築する Agent Skill（v1.2.0）

1 — 概要

何か

img2threejs は、オブジェクト（またはキャラクター）の参照画像 1 枚から、THREE.Group を返す TypeScript 工場関数を段階生成するスキル。フォトグラメトリ・メッシュ抽出・外部アセットパックは使わない。プリミティブ、手続きシェーダ、生成ジオメトリで再構築する。

Claude Code / Codex / OpenCode で動く。エージェント非依存で、「エージェント vision」「ブラウザツール」と書いてある箇所はホストが提供する手段（ネイティブ画像読み取り、ブラウザ MCP、プレビュー、ユーザー提供スクショ）を使う。

v1.2.0

Skill version

Python 3.10+

stdlib only

Three.js

Runtime target

MIT

License

対象と精度

object / character / hybrid に分類。オブジェクトは hard-surface、キャラクターは解剖トラック（頭単位比率・顔ランドマーク・ポーズ）へ分岐する。
コード生成前に detailInventory で同一性を決める細部（gloss、bevel、ネジ、線画、ステイン等）を列挙し、厳格品質ゲートが完了を要求する。
特定人物・キャラの最大類似度は opt-in の投影パス（ランドマーク適合 → de-light → カメラマッチ → 投影）。1 枚では 100% 保証はせず、領域別 confidence を出す。

img2threejs/
├── SKILL.md          # スキル入口・手順・ゲート
├── README.md         # 概要・デモ・クイックスタート
├── forge/             # 決定論スクリプト（stage1–4）
│   ├── stage1_intake/  # probe / PBR / landmarks / detail
│   ├── stage2_spec/    # assessment / ObjectSculptSpec
│   ├── stage3_build/   # pass 制御 / factory 生成
│   └── stage4_review/  # 比較シート / review 記録
└── grimoire/          # ルーブリック・レシピ・語彙

2 — パイプライン

役割分担

スクリプトが強制し、エージェント vision が判定する。 Python は検証・ゲート・仕様作成・比較シート打包・状態管理を担う。見た目スコアは付けない。モデルのトークンは「参照とレンダの横並び 1 枚を見て continue / refine を決める」ことに使う。

flowchart TD
  A["参照画像"] --> B["Probe / 適性ゲート"]
  B --> C["Pre-Spec Assessment\nclass / complexity / quality contract"]
  C --> D["ObjectSculptSpec 作成\ncomponents / materials / sockets"]
  D --> E{"Validate +\nstrict-quality"}
  E -- "浅い" --> D
  E -- "ok" --> F["ロック済みビルドパス"]
  F --> G["Three.js factory 生成\n現在パスのみ"]
  G --> H["ブラウザ描画 + スクショ"]
  H --> I["比較シート 1 枚"]
  I --> J{"Agent vision レビュー"}
  J -- "閾値未満" --> K["Self-correct\nrefine-spec / refine-code"]
  K --> F
  J -- "pass" --> L{"次のパスあり?"}
  L -- "yes" --> F
  L -- "no" --> M["アニメーション準備済み\nThree.js モデル"]

Self-correction: 各パス後に取る行動はちょうど 1 つ — continue / refine-spec / refine-code / request-input / stop。refine-spec は浅い・誤った仕様を直して再検証し、refine-code は健全な仕様に合わないジオメトリ／マテリアル／ライティングを直す。

3 — ビルドパス

固定順

モデルは固定順序でスカルプトする。前パスがレビュー受け入れされるまで次はアンロックされない。ジェネレータは現在アンロックされたパスだけを出力する。

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

continue には実レンダ、比較シート、エージェント vision の全体スコアが閾値以上、かつ同一性を決める各 feature が個別閾値以上、が必要。

4 — ゲート

ゲート	内容	主な参照
Suitability	画像が 3D 再構築の対象として成立するか（pass / conditional / reject）。	`grimoire/intake/validation_rubric.md`
Pre-spec / strict-quality	複雑さに見合う深さになるまでコード生成をブロック（複合オブジェクトの単一ルート仕様は不可）。	`grimoire/intake/quality_contract.md`
Detail inventory	`moderate` 以上では `targetMinDetails` 到達と、各 detail → component/material への実マッピングが必須。	`grimoire/intake/detail_inventory.md`
Screenshot feedback	レンダ + 比較シート + 全体スコア（既定 ≥ 0.7）+ critical feature 個別閾値。	`grimoire/feedback/render_capture.md`
Action-ready	ピボット・ソケット・コライダ・破壊グループを持つ実行時階層。`root.userData.sculptRuntime`。	`grimoire/readiness/action_rigging.md`
Attachment	持ち手・四肢・チューブ等は親ソケットと接触パラメータを宣言。空中浮遊パーツ禁止。	`grimoire/readiness/joint_attachment.md`
Material / lighting	独立した PBR チャネルと実ライト。albedo を roughness へエイリアスしない。	`grimoire/feedback/shading_realism.md`

5 — トークン効率

設計意図

典型的な image-to-3D ループは、毎回モデル全体を読み直し、ピクセル採点や JSON 手検証にトークンを燃やす。img2threejs はその機械仕事を決定論スクリプトへ押し出し、モデルは判断が要るところだけ使う。

Scripts enforce

検証・ゲート・仕様・PBR 証拠・比較シート・パス状態。見た目スコアは付けない。

Zero install

Python 3.10+ 標準ライブラリのみ。pip / PIL / numpy / Playwright なし。PNG は struct + zlib。

Pass-gated codegen

現在パスだけ生成。毎イテレーションでモデル全体を再生成・再読しない。

Fail before codegen

strict-quality が浅い仕様を先に落とす。仕様不足のままレンダしてトークンを捨てない。

成果は差分可能な TypeScript + JSON 仕様。多 MB のメッシュバイナリではない。段階別の内訳は docs/TOKEN_COST.md。

6 — クイックスタート

インストールと呼び出し

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

# Claude Code などで画像を添付し:
# /img2threejs Rebuild this object as a Three.js model,
# keep the proportions, angles, and colours.

主要スクリプト（スキルルートから）

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

スクリプト	役割
`stage1_intake/probe_image.py`	画像メタデータと明らかな技術問題（見た目判定ではない）
`stage2_spec/new_pre_spec_assessment.py`	クラス分類・複雑さ・quality contract
`stage2_spec/new_sculpt_spec.py`	ObjectSculptSpec の作成
`stage2_spec/validate_sculpt_spec.py`	検証。`--strict-quality` で浅い仕様をブロック
`stage3_build/orchestrate_passes.py`	パス状態: status / check / sync
`stage3_build/generate_threejs_factory.py`	現在パスの Three.js Group 工場関数を出力
`stage4_review/make_comparison_sheet.py`	参照 vs レンダの比較シート 1 枚
`stage4_review/append_review.py`	パスごとのスコア・決定・証拠を記録

7 — 成果物と限界

得られるもの

ObjectSculptSpec（JSON）— コンポーネントツリー、マテリアル、反復系、ソケット、パスごとの review 履歴
createObjectNameModel(spec, options) — THREE.Group を返し、root.userData.sculptRuntime に nodes / sockets / colliders / destruction groups
各パスのレンダと比較シート

限界: 1 枚では隠れた面や厳密幾何は保証できない。見え方は近似・スタイライズ・ローポリと明示し、見えない面は可視側のミラー推論に留める。hard-surface 向きで、キャラクターはスタイライズ再構築（フォトリアル顔コピーではない）。「この画像では要求 fidelity に届かない」は正しい結果。

ロードマップ（要約）

v1.0–1.2 shipped — オブジェクト段階スカルプト、detail-first、ヒューマノイド・キャラクター生成
v1.3 planned — likeness maximization（投影ファースト、領域別 confidence）
v1.4 planned — SkinnedMesh / morph / glTF 出力

8 — 参考リンク

公式・デモ

GitHub: hoainho/img2threejs — スキル本体
Live Demo Gallery — 生成コードのブラウザ実行デモ
hoainho/img2threejs-showcase — ギャラリーソース
SKILL.md — 手順・ゲート・実装ルール
docs/TOKEN_COST.md — 段階別トークン内訳
ROADMAP.md — マイルストーン

出典: hoainho/img2threejs の README.md / SKILL.md（公開リポジトリ）