Image-3D のWeb UIの使い方をまとめたドキュメントです。開発・セットアップ手順は README.md、機能仕様の詳細は SPEC.md を参照してください。
./run.shブラウザで http://127.0.0.1:8000 を開きます(ポートはIMAGE3D_PORT環境変数で変更可)。
デフォルトでは IMAGE3D_GENERATOR が未設定だと mock ジェネレータ(入力画像に依らず
固定のテスト用メッシュを返す開発用モード)で起動します。実際にアップロードした画像から
3Dモデルを生成したい場合は、起動前に環境変数を指定してください。
IMAGE3D_GENERATOR=hunyuan3d ./run.sh画面左上に読み込まれるのは常に同じ花びら状の柱型メッシュ、体積が入力画像と無関係に 一定、といった場合は mock で起動してしまっている可能性が高いです。
左右2ペイン構成です。
- 左ペイン: 画像アップロード → 生成パラメータ → 進捗 → ジョブ履歴、と 上から順に操作します。
- 右ペイン: 3Dビューア(全画面)。上部にモデル情報バーと表示モード切替、 下部にエクスポートボタンがあります。
「1. 画像アップロード」のドロップゾーンに画像をドラッグ&ドロップするか、クリックして ファイルを選択します。
- 対応形式: PNG / JPEG / WebP
- 最大ファイルサイズ: 20MB
- 背景つきの写真でもOK(後述の「背景除去」で自動的に除去できます)
正面画像の下に「背面」「左側面」「右側面」の3つの追加スロットがあります。ここに画像を 追加すると、Hunyuan3D-2mv(マルチビュー対応モデル)を使ってより正確な形状を生成します。 追加ビューを1枚もアップロードしない場合は、正面画像1枚のみを使う通常のモデルで生成 されます。
各スロットは「×クリア」ボタンでリセットできます。
よく使う設定をまとめて適用できます。適用後も個別項目を変更でき、変更すると自動的に 「カスタム」表示に戻ります。
| プリセット | 高さ | 解像度 | 最大面数 | カラー |
|---|---|---|---|---|
| フィギュア | 100mm | 384 | 20万面 | ON |
| 小型フィギュア | 60mm | 256 | 10万面 | ON |
| ペンダント | 40mm | 256 | 8万面 | OFF |
| 高精細 | 150mm | 512 | 40万面 | ON |
| 項目 | 説明 |
|---|---|
| ステップ数 (steps) | 拡散モデルの推論ステップ数。大きいほど高品質だが遅い(既定30)。 |
| ガイダンススケール (guidance_scale) | 入力画像への忠実度(既定5.5)。 |
| メッシュ解像度 (octree_resolution) | 256/384/512。大きいほど高精細・低速。 |
| シード (seed) | 空欄でランダム。同じ値+同じ入力なら結果を再現可能。 |
| 背景除去 (remove_bg) | rembgで背景を自動除去してから生成(既定ON)。 |
| 目標高さ (target_height_mm) | 出力メッシュを何mmの高さにスケーリングするか。 |
| 最大面数 (max_faces) | ポリゴン簡略化の上限面数。 |
| カラーモード | ONにすると4色プリンタ向けに頂点カラーを量子化し、色ごとに分割したモデルを生成(色数は2〜4から選択)。 |
| テクスチャ生成(実験的) | ONにすると texgen(Hunyuan3D-2 paint pipeline)で全周テクスチャを焼き込む。/api/health の texgen_available が false の環境ではチェックボックスが無効化され「この環境では利用できません」と表示される。 |
テクスチャ生成の既知の制限(目など細部のズレが出ることがある理由)については README.md の「既知の制限(texgen固有)」 を参照してください。
「3Dモデルを生成」ボタンで生成ジョブを開始します。
生成は非同期ジョブとして実行され、1秒間隔でポーリングして進捗を表示します。
待機中(キュー) → 画像前処理中 → 3D生成中 → メッシュ後処理中 → 完了 の順に進みます。
失敗した場合は赤字でエラーメッセージが表示されます。
複数ビューを使っている場合は「Nビュー(front/back/...)で生成」という注記が表示されます。
過去に生成したジョブがサムネイル・状態・作成日時つきで一覧表示されます。完了した
ジョブをクリックすると、右ペインのビューアに再読み込みしてすぐ確認・エクスポートし
直せます(サーバ再起動をまたいでも data/jobs/ に永続化されています)。
- 回転: 左ドラッグ
- ズーム: マウスホイール
- パン(平行移動): 右ドラッグ
右ペイン上部の情報バーには頂点数・面数・寸法(mm)・watertight判定・体積(cm³)が 表示されます。カラーモード使用時はパレット(使用色と面積比)も表示されます。
表示モードは3種類から切り替えられます。
| モード | 内容 |
|---|---|
| シェーディング | 通常の陰影表示(既定) |
| ワイヤーフレーム | メッシュの辺のみ表示 |
| オーバーハング | 造形方向(Z軸)に対する面の傾斜角からサポート材が必要になりやすい箇所を赤系グラデーションで強調表示。表示中は閾値スライダー(既定45°、30〜70°で調整可)が出現する。 |
右ペイン下部のエクスポートバーから、生成済みモデルを4形式でダウンロードできます。
| 形式 | 内容 |
|---|---|
| STL | 形状のみ(色情報なし) |
| 3MF | 通常時は単一オブジェクト。カラーモード時は色ごとに分割された最大4オブジェクトとして出力されるので、スライサー(Cura等)側でオブジェクトごとにフィラメントを割り当てる。 |
| GLB | テクスチャ生成(paint)使用時はテクスチャ付き、それ以外は頂点カラー付き。ビューアで使っているのと同じデータ。 |
| OBJ | 形状のみ。 |
- 何を入れても同じ形が出る / 画像と無関係な結果になる:
mockジェネレータで 起動している可能性が高いです。「1. 起動してアクセスする」を参照しIMAGE3D_GENERATOR=hunyuan3dで起動し直してください。 - テクスチャ生成のチェックボックスが押せない: この環境に texgen (custom_rasterizer CUDA拡張)が未導入です。形状生成自体は通常通り可能です。 導入手順は README.md の Phase 3c セットアップ節を参照してください。
- テクスチャ生成した3Dモデルの目や細部がズレる: マルチビュー拡散モデルが 生成した複数ビューをベイクする方式のため、完全な一致は保証されません。既知の 限界です(README.md 参照)。正面の色精度を優先したい場合は「テクスチャ生成」を OFFにしてください。