img2threejsとは｜画像1枚からThree.jsコードを生成するAIスキルの仕組み・使い方・品質ゲート

画像から3Dモデルを作るOSSはこの1年でいくつも出たが、そのほとんどはメッシュや 3D Gaussian といった「バイナリのアセット」を推論して吐く。img2threejs はそこから外れる。参照画像を1枚渡すと、返ってくるのは .glb ではなく Three.js の TypeScript コード——THREE.Group を組み立てるファクトリ関数だ。公開は2026年7月15日、そこから約6週間で GitHub スター 13,420（2026-08-25 時点）を集めている。Claude Code のスキルとして動かす前提の設計なので、Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きで扱ったスキル運用の延長線上に置くと位置づけが掴みやすい。

本記事では公式リポジトリ・SKILL.md・CHANGELOG・公式ライブデモを一次ソースに、img2threejs が何を作るのか／どう使うのか／宣伝文句のどこまでが実測で裏付くのかを確かめる。README を訳すだけでは分からない部分——品質ゲートが実際にどこで止まるか、生成物の実行時階層に何が入っているか——は手元で実行し、公式ギャラリーのランタイムを直接読んで測った。

img2threejsとは——メッシュを作らず「Three.jsのコード」を書く画像→3D

img2threejs の自己紹介は「reconstruction-by-code（コードによる再構築）であって、フォトグラメトリでもメッシュ抽出でも既製アセットのダウンロードでもない」という否定形から始まる。この否定形が設計のすべてを説明している。形状はプリミティブ（箱・球・円柱などの基本形状）と手続き的なシェーダの組み合わせで組み上げられる——いわゆるプロシージャル生成を、人間ではなくAIエージェントに書かせる、というのが正体だ。

何ができるのか——出てくる3つの成果物

公式が挙げる成果物は3つある。

・ObjectSculptSpec という JSON：コンポーネントツリー、マテリアル、繰り返し構造（リベットやボルトのような反復要素）、ソケット、そして各パスのレビュー履歴までを含む設計図。これが記事でいう「原稿」にあたる
・TypeScript のファクトリ関数：createObjectNameModel(spec, options) という形で THREE.Group を返す。ルートの userData.sculptRuntime にノード・ソケット・コライダー・破壊グループが露出する
・レンダリング結果と比較シート：各ビルドパスの忠実度を、参照画像と描画結果を並べた1枚の画像として記録したもの

3つ目が地味だが重要だ。img2threejs は「作って終わり」ではなく、参照画像とレンダリング結果を並べてAIの視覚で採点し、閾値を超えるまで自己修正するループを内蔵している。後述するトークン設計はこのループを前提に組まれている。

何を解決するのか——「編集できない3D」からの離脱

拡散モデル型の image-to-3D で出てくる .glb は、開けば数MBのバイナリだ。色を少し変えたい、ネジの位置を1cm動かしたい、という要求に対して、できることは「3Dソフトで開いて手で直す」か「プロンプトを変えて作り直す」かの二択になる。バージョン管理も難しい。前回との差分がバイナリ差分にしかならないからだ。

img2threejs の成果物はテキストなので、この二択から抜けられる。公式が「diffable TypeScript plus a JSON spec」と表現している通り、レビューできてバージョン管理できる3D資産というのが狙いだ。数十MBのメッシュではなく数百行のコードなので、コードレビューの俎上に載せられる。

何を代替できるのか——そして代替できないもの

得意分野は公式自身が線を引いている。ハードサーフェス（機械的で面が硬い人工物）には強く、キャラクターは「様式化された再構成であって写実的な似姿ではない」と先に断っている。公式ギャラリーの被写体構成もそれを裏付けていて、宝箱・装甲トラック・BMX・イヤホンケース・ナイフといった人工物が中心だ。

つまり、ゲームの小道具・UIの3Dアクセント・製品の模式的な立体表現あたりが現実的な射程になる。人物のフォトリアルなアバターを作りたい、実在の建物をスキャンしたい、といった用途は守備範囲外だ。「この画像からは要求された忠実度に到達できない」という結論を正常な結果として返す設計になっている点は、むしろ誠実な部類に入る。

インストールと使い方——スキルを置いて /img2threejs と打つまで

img2threejs は npm パッケージでも CLI でもなく、AIコーディングエージェントのスキルディレクトリに置くリポジトリとして配布されている。この形式はClaude Skillsとは｜「スキル=フォルダ」の仕組みと作り方・使い方を徹底解説で整理した「スキル＝フォルダ」の考え方そのままだ。

導入は clone 一発

公式の手順は、スキルディレクトリへリポジトリを置くだけで完結する。

# Claude Code のスキルディレクトリへ配置する（公式手順）
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

# 複数のホストで使う場合は、チェックアウトを1つに保ってシンボリックリンクで参照する
#   ~/.claude/skills/img2threejs -> <your checkout>
#   ~/.codex/skills/img2threejs  -> <your checkout>

複数ホストを使う場合にチェックアウトを1つに保ってシンボリックリンクで参照せよ、と公式が明記しているのは、スキル本体がバージョン管理された状態機械だからだ。ホストごとに別々の実体を置くと、パイプラインの状態やレビュー履歴が食い違う。

配置したあとは、画像を添付してスラッシュコマンドを打つ。

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

これだけで、スキルが被写体を分類し、ディテール棚卸しを作り、各パスをゲートしながら進む——というのが公式の説明だ。ここでいう「エージェントの視覚」「エージェントのブラウザツール」は、ホストが提供するものなら何でもよい（ネイティブの画像読み取り、ブラウザMCP、プロジェクトのプレビュー、あるいはユーザーが撮ったスクリーンショット）とされており、特定のツールに縛られない。

中身のスクリプトは単体でも動く

スキル経由でなくても、forge/ 配下の Python スクリプトは単体で実行できる。当サイトで実際に動かしたのが次の流れだ。

# 検証環境: macOS (Darwin 23.5.0) / Python 3.14.4 / 2026-08-21
# 1. 画像の技術的な下見（メタデータと明らかな不備の検出）
python3 forge/stage1_intake/probe_image.py <image>

# 2. 被写体の分類と複雑度スコアの雛形を作る
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json

# 3. assessment から ObjectSculptSpec を起こす
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json

# 4. spec の検証（--strict-quality で浅い spec をブロック）
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality

# 5. 現在アンロックされているビルドパスのファクトリを生成する
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

512×512 の合成PNGを渡して probe_image.py を叩いたところ、pip install を一切せずに {"type":"png","width":512,"height":512,"technicalSuitability":"pass"} という JSON が返ってきた。同時に "This is only technical image probing. Semantic object suitability still requires visual inspection."（これは技術的なプローブに過ぎず、被写体としての適性判断には視覚的な検査が必要）という注記も付く。スクリプトは形式を見るだけで、絵の意味は見ないという役割分担が、ここで既に表明されている。

続く new_pre_spec_assessment.py の出力を開くと、その分担がさらにはっきりする。primaryType は "unassessed"、複雑度スコアは全項目 0、そして "Fill from direct visual inspection before writing the final spec."（最終 spec を書く前に、直接の視覚的検査から埋めること）という指示文が入っていた。Python が作るのは記入用のフォームであって、中身を埋めるのはモデルの仕事だ。

品質ゲートの実測——「PASS」が出ても通っていない

README は「ファクトリ生成器は strict-quality ゲートを再実行し、fail-closed である」と書いている。この主張を、公式の雛形コマンドが出すそのままの spec（被写体を1つも記入していない状態）で確かめた。結果は README と矛盾しないが、読者が踏みやすい落とし穴が1つある。以下は v1.5.1（2026-08-25 実測）の値で、初出時の v1.4.4 系から警告件数だけが変わり、終了コードの設計は同じだった。

同じ spec に4通りのコマンドを当てた結果

1行目の PASS を「通った」と読むと事故る。 既定の validate_sculpt_spec.py は、preSpecAssessment.objectClass.primaryType is unassessed（被写体の分類が未評価）、only one component found; this is likely still blockout quality（部品が1つしかなく、まだ大まかな塊の段階だろう）といった12件の指摘を出しながら、終了コード0で PASS と表示する。これらが error に昇格するのは --strict-quality を付けたときだけだ。

一方、コード生成器はフラグを何も付けなくても既定で strict-quality を再実行して止まる。返ってくる JSON には status・phase・gate・artifact・metric（failureCount: 11）・cause（未達項目の列挙）・warnings が入っており、終了コードは 2、.ts ファイルは1バイトも書かれなかった。つまり「fail-closed である」という README の主張は codegen 側について正しく、validate 側は既定では fail-open だ。CI に組み込むなら、validate_sculpt_spec.py には必ず --strict-quality を付けるべきだということになる。

なお上の3行は、numpy も Pillow も入っていない仮想環境（python3 -m venv --without-pip で作り、import numpy と import PIL がどちらも ModuleNotFoundError になることを対照群として先に確認した）で実行しても、終了コード・PASS/BLOCKED の別・警告12件がすべて一致した。品質ゲートは第三者パッケージに一切依存していないということで、次節の依存関係の話と符合する。

抜け道は用意されているが、警告つき

--allow-nonstrict を付けると、中身が空同然の spec からでも 759行・9つの export を持つ TypeScript が生成された。createTestBoxModel のほか、ルックデヴ用ライト、環境、カメラのフレーミング、プレゼンテーション用コンポーザ、レンダラ設定、インスペクト用コントロールまで一式が出てくる。ただし標準出力の1行目に WARNING: generating a non-production test-fixture factory が出るし、README も「明示的なレガシーのテストフィクスチャ専用であり、本番の出力には決して使わない」と書いている。逃げ道はあるが、静かではない。

img2threejs は本当に依存ゼロか——204ファイルの import を全部数えた

README で最も検証したくなる主張がこれだ。「すべてのスクリプトは純粋な Python 3.10+ 標準ライブラリ。pip も PIL も numpy も Playwright も無い。PNG の読み書きは struct と zlib でやっている」。

この主張は v1.5.1 で試される場面を迎えた。このリリースは numpy と Pillow を必要とする GLB 参照パイプラインを新規に追加しており、CHANGELOG は「forge のコアが標準ライブラリのみのままでいられるよう、独自の pyproject.toml と uv.lock を持たせた。forge/ の中身は何一つそれを import していない」と自己申告している。自己申告は実行して確かめる——というわけで、初出時と同じAST解析を v1.5.1 に対して丸ごとやり直した。

結論：依存を足したリリースを跨いでも、コアの0件は保たれた

リポジトリ全体（.py 204ファイル）を対象に、正規表現ではなく AST でパースして import 文を列挙し、標準ライブラリ（sys.stdlib_module_names）でもリポジトリ内のモジュール名でもないものだけを第三者パッケージとして数えた。結果はサブツリーごとにきれいに分かれる。

初出時（v1.4.4 系）の forge/ は162ファイル・45,711行だったので、本体は約1万行ぶん太りながら第三者 import 0件を維持している。「zero dependencies」は現状維持で守られたのではなく、依存を持ち込む新機能を入れた上で守られた——ここが今回いちばん確かめる価値のあった点だ。

第三者パッケージが登場するのは6ファイルで、うち3ファイルは v1.5.1 で新しく入った GLB 参照パイプラインだ。

この「遅延か即時か」の差が、隔離のやり方が変わったことを示している。 従来の3ファイルはすべて関数の内側で import しており、パッケージが無くてもモジュールの読み込み自体は落ちない設計だった。v1.5.1 で入った3ファイルはトップレベルで numpy を import しているため、この方式は使えない。代わりに専用サブツリーへ隔離され、自前の pyproject.toml（numpy>=1.26,<3 と pillow>=11,<13 の2つだけ、requires-python = ">=3.11,<3.13"）と uv.lock を持たされている。

CHANGELOG の「forge/ の中身は何一つそれを import していない」という自己申告も、forge/ 配下から integrations / glb_character_pipeline への import 文を検索して 0件であることを確認した。前節のとおり、numpy も Pillow も存在しない仮想環境で品質ゲートが完走することも実測済みだ。主張と実装は一致している。

「依存ゼロ」は3つの層のうち1つだけを指している

ここを誤読すると評価を間違える。v1.5.1 時点の img2threejs は、依存関係の性格が違う3つの層でできている。

②について具体的に言うと、--allow-nonstrict で生成した TypeScript の冒頭7行は、three 本体に加えて three/examples/jsm/environments/RoomEnvironment.js、postprocessing/EffectComposer.js、BokehPass.js、UnrealBloomPass.js、controls/OrbitControls.js を import している。生成されたコードを動かすには Three.js とその examples が要る。

つまり「zero dependencies」は画像を読んで spec を作りコードを吐くまでのツールチェーンが標準ライブラリだけで完結するという意味であって、出力した3Dモデルがどこでも裸で動くという意味でも、リポジトリ全体が numpy と無縁という意味でもない。トークン節約の文脈で語られている主張なので、①に限定した読み方が正しい。

この線引きは公式のコード中にも書かれている。参照メッシュ生成スクリプトが GLB と OBJ の両方を書き出す理由として、コメントは「forge/ のゲートはハウスルールにより純粋な標準ライブラリであり、OBJ は約30行の標準ライブラリのパーサで読める v/vn/f のASCIIだ。GLB のアクセサを純粋な Python でデコードするのは200〜400行の面倒な作業になり、Draco 圧縮されていれば端的に不可能だ」と説明している。「①を標準ライブラリのみに保つ」という制約が、データ形式の選択そのものを決めているわけで、看板倒れの原則ではないことが分かる。

生成されるコードと実行時階層——8パーツの宝箱で確かめる

「アニメーション対応（animation-ready）」「ピボット・ソケット・コライダーを持つランタイム階層」という言葉は魅力的だが、実際にどこまで埋まるのか。公式ライブデモは window.__IMG2THREEJS_RUNTIME__ としてランタイム情報をページに露出しているので、3体分を直接読んで数えた。

器は常にあるが、中身は被写体次第

宝箱（crown-chest）は lidHinge・handleMount・crownEmitter という3つの意味のあるソケット名を持ち、破壊グループは6つ。装甲トラック（warhauler）はソケットが exhaustOutlet の1つで破壊グループ5、BMX（bmx-endurance）はソケット0で破壊グループ5だった。一方 userData.tick（アイドルアニメーション用のループ）は宝箱には無く、トラックと BMX には有る。

そして3体とも pivotNames は空配列、colliderCount は 0 だった。生成されるコードの型定義には sockets・colliders・destructionGroups の枠が常に用意される（--allow-nonstrict の出力でも ProceduralModelRuntime 型にすべて存在した）が、枠があることと中身が自動で埋まることは別だ。「アニメーション対応」は「リグ済みで物理まで入っている」という意味ではなく、「動かすために必要な取っ手を置ける構造になっている」という意味に読むのが正確だろう。

部品として分解できることの意味

公式デモには「Explode parts」ボタンがあり、押すと生成モデルが部品ごとに分解される。宝箱は body・lid・corner-brackets・front-latch・side-handle・crown-frame・crown-panel・crown-glyph の8パーツ、三角形数はそれぞれ 2.0k / 2.0k / 21.0k / 1.2k / 1.4k / 972 / 972 / 80（デモ画面の表示値）で、合計はおよそ 29.6k だった。

三角形数の内訳を見ると、角金具（corner-brackets）だけで全体の7割を占めている。面取りされた金具が8個あるためで、「どの部品にポリゴンを使うか」の判断が spec の段階で残っていることが分かる。メッシュ抽出型の出力では、この配分は後から読み取りにくい。

8段のビルドパスで少しずつ作る

生成が一発勝負でないのは、パイプラインが8段のビルドパスに区切られているからだ。コード生成器は現在アンロックされているパスの分しか出力しないため、モデルは毎回モデル全体を読み直したり作り直したりしなくて済む。

blockout（大まかな塊）→ structural（構造）→ form（形）→ material（素材）→ surface（表面）→ lighting（照明）→ interaction（インタラクション）→ optimization（最適化）の順で、各パスごとに参照画像と描画結果を並べた1枚の比較シートを作り、それをAIの視覚で採点して閾値に届くまで自己修正する。orchestrate_passes.py には status / check / sync の3サブコマンドがあり、check は「ビルドパスがアンロックされていなければ失敗する」ゲートとして機能する。

トークンコストと限界——公式が自分で「実測ではない」と書いている

リポジトリの説明文には「Token-efficient image-to-3D」とある。この主張の根拠を docs/TOKEN_COST.md で確かめると、冒頭で公式自身が「これらはエンジニアリング上の見積もりであってベンチマークの実測ではない」と断っている。

見積もりの内訳

公式が示す1オブジェクトあたりの内訳は次の通りだ（いずれも見積もり値）。

キャラクター再構築はさらに重く、約150k〜350k とされる。最大のレバーはレビューサイクル数であり、「前もって整った spec を書くことは、下流のどんな細かい最適化よりも価値がある」というのが公式の結論だ。品質ゲートを厳しくして早期に止めるのは、生成コストを抑えるための設計でもある。

なお docs/TOKEN_COST.md は「実測に基づくベンチマークは v1.5 で予定」とも書いている。その v1.5 は2026-08-12に、v1.5.1 は2026-08-23に出荷されたが、2026-08-25 時点の docs/TOKEN_COST.md は依然として同じ一文を将来形のまま載せている。つまり約束された実測ベンチマークはまだ現れていない。数値は引き続き設計上の見積もりとして扱い、自分のワークロードで測り直すのが妥当だ。

一方で、スキル本体の常駐コストは明確に軽くなった。初出時に 48,766バイト・613行あった SKILL.md は、v1.5.1 では 30,633バイト・415行まで縮んでいる（2026-08-25 実測）。CHANGELOG はこれを「重複したステージブロックと宙に浮いたループ末尾を削り、どのホストもゲートの連なりを1本の連続した流れとして読み込めるようにした」と説明している。機能を増やしたリリースでスキル本文が約37%軽くなったわけで、常駐コストを気にする用途では素直に良い変化だ。トークン削減を掲げるスキルの比較という文脈では、graphify完全ガイド｜Claude Code トークン削減を71.5倍にする知識グラフスキルのように「何を削って何を残すか」を明示するタイプと並べて見ると設計思想の違いが見えてくる。

限界について公式が言っていること

README の「Honesty about limits」節は、この種のプロジェクトとしては珍しく率直だ。要点は3つある。

・1枚の画像では隠れた面や正確な形状は保証できない。見えない面は見えている面のミラーで推測し、自信があるふりはしない
・近似・様式化・ローポリになる場合はそう明言する設計になっている
・ハードサーフェスには強いが、キャラクターは様式化された再構成であって写実的な似姿ではない

加えて、複数視点のシルエット彫り込み（visualHull）はオプトインで、2枚以上の直交シルエットを交差させて境界のあるボクセルメッシュを作り、見えなかった領域は「隠れたディテールを捏造する代わりに低信頼度として記録する」という挙動になっている。「分からないところを分からないと記録する」実装が入っている点は、生成AI系のツールとしては評価してよい。

類似ツールとの比較——拡散モデル型・エージェント型と何が違うか

「画像から3D」というカテゴリには性格の異なるものが混ざっている。同じ入力を受けても出るものが違うので、比較軸を「成果物」に置くと整理しやすい。

Microsoft Research の TRELLIS のような拡散モデル型と img2threejs は、競合というより用途が分かれる。写実的なアセットを大量に作るなら前者、Web に埋める編集可能な3Dを作るなら後者、という住み分けだ。

v1.5.1：拡散モデル型を「定規」として取り込む GLB 参照ルート

ところが v1.5.1 で、この住み分けにもう一段の関係が加わった。2026-08-23 のリリースはテーマ自体が「the GLB-reference route」で、リリースノートは狙いをこう書いている——GLB を非公式の補助から「測定器」に格上げし、パイプラインと、1:1 で合わせられるパラメータ／合わせられないパラメータの明示を伴わせる。

そして参照GLBを自前で用意する手段も、別のオプトイン統合として同梱されている。integrations/mesh3d/generate_reference_mesh.py は、ホストされた TRELLIS の Space を呼んで参照メッシュを生成する（既定は trellis-community/TRELLIS）。上の表で「別の陣営」として並べた拡散モデル型を、img2threejs 自身が採寸用の道具として使える構図になっているわけだ。

ただしこの2つは別々の統合で、自動で繋がってはいない。GLB 参照パイプライン側のドキュメントは参照GLBの入手元として CHARACTER_GLB のパスや添付された .glb を挙げるだけで、mesh3d にも TRELLIS にも言及していない（当サイトで両ドキュメントを検索して確認）。参照GLBをどこから持ってくるかは利用者の裁量で、TRELLIS 経由はその選択肢の1つという位置づけだ。

スクリプトのコメントはその判断理由まで書いている。ローカルで動かさずホスト版を使うのは、TRELLIS 側が「コードは Linux でのみテストされている」「16GB以上のVRAMを積んだNVIDIA GPUが必要」と明言し、その submodule 群（spconv・nvdiffrast・diff-gaussian-rasterization・flash-attn）が CUDA 専用で MPS 経路が存在しないためだ。Apple Silicon のマシンでも、TRELLIS をローカルで一切動かさずに TRELLIS の出力が得られる——という書き方をしている。

出力を GLB と OBJ の両方にするのも意図的で、GLB は Three.js が GLTFLoader でそのまま読めるので候補モデルと同じカメラ・同じシェーダで描画して比べられる（写真とPBRレンダリングを比べると ssim が0に張り付く、という具体的な失敗が理由として挙げられている）。OBJ は前述のとおり標準ライブラリだけで採点するための形式だ。しかも両方を1回の生成・1回の変換から書き出す設計で、理由は「ここでいちばん危険な失敗は静かな失敗だから」——GLB と OBJ が軸の取り方で食い違うと、Three.js の描画と Python の採点が別々の物体を見たまま、どちらも警告を出さない。--assert-axes がバウンディングボックスを比較して不一致なら中断する。

また、エージェント向けスキルという形式に注目すると、img2threejs は「エージェントに新しい感覚器と手を与える」タイプのパッケージに分類できる。ブラウザ操作を足すBrowserbaseとは｜Claude Codeに17スキルを足すブラウザ自動化パッケージ解説と同じ棚に置くと、「エージェントが自分で結果を見て直す」ループをどう作るかという共通の設計課題が見えてくる。img2threejs の場合、その「見る」対象が比較シート1枚に絞られている点が特徴的だ。

ロードマップは「アセット→世界→制作基盤」

公式 ROADMAP は v1.6（環境・建物・地形）→ v1.7（Unity / Unreal エクスポータ、Blender ブリッジ、LOD）→ v1.8（自動リギング）→ v1.9（Web UI・バッチ処理）→ v2.0（マルチビュー再構築・手続き的都市生成）という順に並ぶ。初出時に「進行中」だった v1.5（The Character Update）は2026-08-12に出荷済みとなり、コンポーネント木から導いたスケルトンを SkinnedMesh にバインドする仕組み、測地的スキニング、髪を5段階のサブシステムとして扱う実装などが入った。

ただしROADMAP自身が v1.5 で「出荷しなかったもの」を明記している点は見落とさない方がいい——hairProfile コンパイラ、IK、ポーズスイープのゲーティング、そして服飾は未実装として列挙されている。この手のロードマップは前倒しにならないのが常なので、現時点で堅いのは「ハードサーフェスの物体を Three.js コードとして起こす」ところまでと見るのが安全だ。Unity / Unreal への書き出しや自動リギングを当てにして導入計画を立てるのはまだ早い。

参照ソース

• img2threejs/img2threejs — GitHub 公式リポジトリ（README・SKILL.md・CHANGELOG.md・ROADMAP.md・docs/TOKEN_COST.md・integrations/ 配下を参照。★13,420 / fork 1,082 / Apache-2.0、最新リリース v1.5.1、2026-08-25 時点。本記事のAST解析・品質ゲートの実測はタグ v1.5.1 のチェックアウトに対して実施）
• img2threejs 公式ライブデモギャラリー（本記事のスクリーンショット・動画は当サイトが実機で撮影。ランタイム階層の実測値も同ギャラリーから取得）
• img2threejs/img2threejs-showcase — ギャラリーのソースリポジトリ（各デモの生成コードが公開されている）
• microsoft/TRELLIS — 比較対象として参照した拡散モデル型の画像→3D生成