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

画像から3Dモデルを作るOSSはこの1年でいくつも出たが、そのほとんどはメッシュや 3D Gaussian といった「バイナリのアセット」を推論して吐く。img2threejs はそこから外れる。参照画像を1枚渡すと、返ってくるのは .glb ではなく Three.js の TypeScript コード——THREE.Group を組み立てるファクトリ関数だ。公開は2026年7月15日、そこから約5週間で GitHub スター 12,379（2026-08-21 時点）を集めている。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 を作って確かめた。結果は README と矛盾しないが、読者が踏みやすい落とし穴が1つある。

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

1行目の PASS を「通った」と読むと事故る。 既定の validate_sculpt_spec.py は、preSpecAssessment.objectClass.primaryType is unassessed（被写体の分類が未評価）、detailInventory has 0 details but targetMinDetails is 6（ディテール棚卸しが0件だが最低6件必要）といった15件の指摘を出しながら、終了コード0で PASS と表示する。これらが error に昇格するのは --strict-quality を付けたときだけだ。

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

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

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

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

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

結論：本体は主張どおり、ただし線引きがある

リポジトリ全体（.py 167ファイル・約47,000行）を対象に、正規表現ではなく AST でパースして import 文を列挙した。forge/ 配下 162ファイル・45,711行から抽出された import は99モジュールで、そのうち標準ライブラリでもリポジトリ内モジュールでもないものは 0件だった。materials・scripts・stage4_review・stage5_rig という4つが一見「外部」に見えるが、これらはすべてリポジトリ内の兄弟ディレクトリで、PyPI のパッケージではない。

第三者パッケージが登場するのは3ファイルだけだ。

しかもこれらはすべて関数の内側に書かれた遅延 import で、モジュールを読み込むだけならパッケージが無くても落ちない。README も「オプションの参照忠実度ツール」という別セクションを立てて、これらが分離された証拠レイヤーであり「パスを承認したり黙って形状を提供したりはしない」と明記している。つまり主張と実装は一致している。実際、pip install を一度も実行していない環境で probe_image.py が JSON を返したことがそれを裏付けた。

「依存ゼロ」が指しているのはツール側だけ

ただし成果物の側は依存ゼロではない。--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モデルがどこでも裸で動くという意味ではない。トークン節約の文脈で語られている主張なので、この読み方が正しい。

生成されるコードと実行時階層——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 で予定」とも書いている。現時点では数値は設計上の見積もりとして扱い、自分のワークロードで測り直すのが妥当だ。スキル本体の常駐コストという観点では、SKILL.md が 48,766バイト・613行あることも頭に入れておきたい。トークン削減を掲げるスキルの比較という文脈では、graphify完全ガイド｜Claude Code トークン削減を71.5倍にする知識グラフスキルのように「何を削って何を残すか」を明示するタイプと並べて見ると設計思想の違いが見えてくる。

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

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

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

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

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

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

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

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

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

公式 ROADMAP は v1.5（キャラクター）→ v1.6（環境・建物・地形）→ v1.7（Unity / Unreal エクスポータ、Blender ブリッジ、LOD）→ v1.8（自動リギング）→ v1.9（Web UI・バッチ処理）→ v2.0（マルチビュー再構築・手続き的都市生成）という順に並ぶ。出荷済みは v1.0（オブジェクトパイプライン）から v1.4.1（CS2 の武器再構築の堅牢化）までと、4つの体型プラン（四足・鳥類・有翼竜・蛇形）を持つクリーチャー生成器だ。

ただしこの手のロードマップは前倒しにならないのが常なので、現時点で使えるのは「ハードサーフェスの物体を Three.js コードとして起こす」ところまでと見るのが安全だ。Unity / Unreal への書き出しや自動リギングを当てにして導入計画を立てるのはまだ早い。

参照ソース

• img2threejs/img2threejs — GitHub 公式リポジトリ（README・SKILL.md・CHANGELOG.md・ROADMAP.md・docs/TOKEN_COST.md を参照。★12,379 / fork 988 / Apache-2.0、2026-08-21 時点）
• img2threejs 公式ライブデモギャラリー（本記事のスクリーンショット・動画は当サイトが実機で撮影。ランタイム階層の実測値も同ギャラリーから取得）
• img2threejs/img2threejs-showcase — ギャラリーのソースリポジトリ（各デモの生成コードが公開されている）
• microsoft/TRELLIS — 比較対象として参照した拡散モデル型の画像→3D生成