img2threejs/img2threejs

img2threejs – 単一の参照画像をプロシージャルなThree.jsコードに変換

概要

• Python駆動のスキルで、大規模言語モデルエージェント（Claude Code、Codex、OpenCode、Hermesなど）が単一の写真からオブジェクトやキャラクターを、TypeScriptで書かれた**THREE.Groupファクトリ**として再構築できます。生成されたコードはプリミティブ、プロシージャルシェーダー、生成ジオメトリのみを使用し、メッシュファイルやダウンロードしたアセットは含まれません。

重要性

• アニメーション対応、トークン効率の良い3Dモデルを生成し、Three.jsシーンに直接組み込むことができます。出力はコードであるため、軽量でバージョン管理が容易で、調整が簡単です。
• 品質ゲート付きパイプラインを備えており、視覚的な詳細をすべて列挙し、マテリアルレジストリに対して検証し、視覚的判断が必要な部分にのみLLMトークンを費やします。

主な機能

• エージェント非依存のスキル – スキルを実行できる任意のLLM（Claude Code、Codex、OpenCode、Hermes）で動作します。スキルはエージェントのスキルストアにインストールされ、簡単なプロンプトで呼び出されます。
• ドメインプラグイン – 特定のユースケース向けのオプション拡張（キャラクターリギング、Counter-Strike 2武器スキン、プライベート環境プラグインなど）。プラグインは追加の入力契約、リグチェック、レビューゲートを追加します。
• 決定論的パイプライン – 多段階の彫刻フロー（blockout → structural → form → material → surface → lighting → interaction → optimization）で、Pythonスクリプトがゲートを強制し、保存された状態から作業を再開します。
• ライブデモギャラリー – 公開サイト（https://img2threejs.io）で数十の再構築を紹介し、各サンプルには生成されたTypeScriptソースへのリンクが含まれています。
• オープンソースツール – コアスキルはこのリポジトリに、ショーケースは関連リポジトリにあり、プラグインはimg2ハーネスを介して追加できる別々のパッケージです。

インストール

# 検出されたすべてのエージェントにスキルをインストール
npx --yes img2threejs@latest install
# エージェントごとにインストールを確認
npx --yes img2threejs@latest doctor

• Node ≥ 18、Git、Python ≥ 3.10が必要です。
• Hermesユーザーは、READMEに記載されているように、スキルをアクティブプロファイルにリンクしてください。

オプションのプラグインハーネス

# プラグインを管理するハーネスをインストール
npx --yes @img2threejs/img2@latest install --yes
# 利用可能なプラグインを一覧表示
img2 plugins
# プラグインを追加（例：キャラクターリギング）
img2 add character --yes

プラグインはデフォルトではインストールされません。必要なものだけを選択してください。

再構築の実行

1. インストール後、エージェントを再起動します。
2. エージェントチャットで、画像を添付（またはパスを指定）し、次のようなプロンプトを発行します。

   /img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
   Keep its proportions, silhouette and colours. Follow the quality gates.
   

3. エージェントは次のことを行います。
   • 画像を検証。
   • 詳細インベントリと仕様ドキュメントを構築。
   • TypeScriptファクトリをパスごとに生成。
   • 結果を非表示のThree.jsビューでレンダリングし、参照と比較。
   • 生成されたソースファイル、レンダーレビューの証拠、および信頼スコアを返します。

出力

• src/model.ts（または同様の名前）ファイルで、THREE.Groupファクトリをエクスポートします。
• 階層、マテリアル、信頼メトリクスを記述するJSON仕様。
• ビジュアルレビューステップに使用されるレンダリングされたスクリーンショット。

ドキュメントとリソース

• アーキテクチャとゲート設計：docs/ARCHITECTURE.md
• インストールガイド：docs/INSTALL.md
• プラグインシステム：docs/PLUGINS.md
• 独自プラグインの作成：WRITING_A_PLUGIN.md
• ライブデモギャラリー：https://img2threejs.io

ライセンス

• Apache 2.0（LICENSEを参照）。

対象ユーザー

• 重いメッシュファイルを配布せずに軽量でアニメーション可能なアセットを必要とするゲーム開発者。
• コードファーストの3Dモデルを好むインタラクティブなウェブ体験の作成者。
• LLM駆動の3D生成パイプラインを研究する研究者。
• 写真をThree.jsコードに変換する、決定的で品質管理された方法を求めるすべての人。