Image-3D

画像から3Dプリントデータ(STL / 3MF / GLB / OBJ)を生成するローカルWebアプリ。

Web UIの使い方は docs/USAGE.md、詳細仕様は docs/SPEC.md、開発方針は docs/DEVELOPMENT_POLICY.md、実装計画は docs/IMPLEMENTATION_PLAN.md を参照。 自動リグ+VRM化サービス rig-service は別リポジトリ(../rig-service/)。 設計・実装計画はそちらの docs/RIG_SERVICE_PLAN.md を参照。

現在の状態(Phase 1〜3b)

• Image-to-3D 生成は mockジェネレータ(決定的なパラメトリックメッシュ)を使用。
• GPU / Hunyuan3D-2 は未導入でも、アップロード → 生成 → メッシュ後処理 → 3Dビューア表示 → STL/3MF/GLB/OBJ ダウンロードの全パイプラインがE2Eで動作する。
• Phase 2 で IMAGE3D_GENERATOR=hunyuan3d により実モデルに切り替え可能(下記参照)。
• Phase 2.5 で4色カラープリンタ向け出力(color_mode=color4)に対応 (下記「Phase 2.5: 4色カラープリント対応」参照)。
• Phase 3a でマルチビュー入力(正面+背面/左/右)とキャラクターシート自動分割に対応 (下記「Phase 3a: マルチビュー入力+キャラクターシート自動分割」参照)。
• Phase 3b でパラメータプリセット(FR-11)とビューアのオーバーハングヒートマップ (FR-12)に対応(下記「Phase 3b: プリセット+オーバーハングヒートマップ」参照、 フロントエンドのみの変更でサーバAPIは不変)。
• Phase 3c でテクスチャ生成(texture_mode=paint、FR-10)に対応(下記 「Phase 3c: テクスチャ生成 (texgen)」参照)。custom_rasterizer CUDA拡張の ビルドが必要で、未導入環境では /api/health の texgen_available=false に 応じてUI上で無効表示し、正面/背面投影方式(FR-8)にフォールバックする。
• Phase R4 で 自動リグ+VRM化サービス(rig-service、別リポジトリ) との連携に対応(下記「Phase R4: リグ/VRM化サービス連携」参照)。 IMAGE3D_RIGSVC_URL を設定すると完了ジョブに「リグ/VRM化」ボタンが出る。 Tポーズの立ち絵から生成したモデルを送ると、21ボーンのリグ済みGLBと VRM 1.0 が得られる。

セットアップ

前提

• Python 3.12
• (Phase 2用) NVIDIA GPU + CUDA 12.8 対応ドライバ

VRAM最小要件(実測ベース)

RTX PRO 6000 Blackwell 96GB での実測ピーク(既定パラメータ: octree_resolution=384, max_faces=200000, テクスチャ2048×2048)に基づく目安。

• octree_resolution=512 や max_faces 増(高精細プリセット)ではピークが上記より 増加する。VRAMが最小要件付近のGPUでは octree_resolution=256 への引き下げを推奨。
• 生成ジョブは直列実行(NFR-2)のため、同時実行によるVRAM加算は発生しない。 各ジョブ後に torch.cuda.empty_cache() で解放される(NFR-3で重みは常駐)。
• 他プロセスとGPUを共有する場合は、上記に加えてそのプロセスの使用量を確保すること。

venv作成 + 依存インストール

Linux / macOS / WSL2:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt

Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\p