Skip to content

Latest commit

 

History

History
142 lines (101 loc) · 7.5 KB

USAGE.md

File metadata and controls

142 lines (101 loc) · 7.5 KB

操作方法(利用者向けマニュアル)

Image-3D のWeb UIの使い方をまとめたドキュメントです。開発・セットアップ手順は README.md、機能仕様の詳細は SPEC.md を参照してください。

1. 起動してアクセスする

./run.sh

ブラウザで http://127.0.0.1:8000 を開きます(ポートはIMAGE3D_PORT環境変数で変更可)。

デフォルトでは IMAGE3D_GENERATOR が未設定だと mock ジェネレータ(入力画像に依らず 固定のテスト用メッシュを返す開発用モード)で起動します。実際にアップロードした画像から 3Dモデルを生成したい場合は、起動前に環境変数を指定してください。

IMAGE3D_GENERATOR=hunyuan3d ./run.sh

画面左上に読み込まれるのは常に同じ花びら状の柱型メッシュ、体積が入力画像と無関係に 一定、といった場合は mock で起動してしまっている可能性が高いです。

2. 画面構成

左右2ペイン構成です。

  • 左ペイン: 画像アップロード → 生成パラメータ → 進捗 → ジョブ履歴、と 上から順に操作します。
  • 右ペイン: 3Dビューア(全画面)。上部にモデル情報バーと表示モード切替、 下部にエクスポートボタンがあります。

3. 画像アップロード

3.1 正面画像(必須)

「1. 画像アップロード」のドロップゾーンに画像をドラッグ&ドロップするか、クリックして ファイルを選択します。

  • 対応形式: PNG / JPEG / WebP
  • 最大ファイルサイズ: 20MB
  • 背景つきの写真でもOK(後述の「背景除去」で自動的に除去できます)

3.2 追加ビュー(任意、マルチビュー生成)

正面画像の下に「背面」「左側面」「右側面」の3つの追加スロットがあります。ここに画像を 追加すると、Hunyuan3D-2mv(マルチビュー対応モデル)を使ってより正確な形状を生成します。 追加ビューを1枚もアップロードしない場合は、正面画像1枚のみを使う通常のモデルで生成 されます。

各スロットは「×クリア」ボタンでリセットできます。

4. 生成パラメータ

プリセット

よく使う設定をまとめて適用できます。適用後も個別項目を変更でき、変更すると自動的に 「カスタム」表示に戻ります。

プリセット 高さ 解像度 最大面数 カラー
フィギュア 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モデルを生成」ボタンで生成ジョブを開始します。

5. 進捗確認

生成は非同期ジョブとして実行され、1秒間隔でポーリングして進捗を表示します。

待機中(キュー) → 画像前処理中 → 3D生成中 → メッシュ後処理中 → 完了 の順に進みます。 失敗した場合は赤字でエラーメッセージが表示されます。

複数ビューを使っている場合は「Nビュー(front/back/...)で生成」という注記が表示されます。

6. ジョブ履歴

過去に生成したジョブがサムネイル・状態・作成日時つきで一覧表示されます。完了した ジョブをクリックすると、右ペインのビューアに再読み込みしてすぐ確認・エクスポートし 直せます(サーバ再起動をまたいでも data/jobs/ に永続化されています)。

7. 3Dビューアの操作

  • 回転: 左ドラッグ
  • ズーム: マウスホイール
  • パン(平行移動): 右ドラッグ

右ペイン上部の情報バーには頂点数・面数・寸法(mm)・watertight判定・体積(cm³)が 表示されます。カラーモード使用時はパレット(使用色と面積比)も表示されます。

表示モードは3種類から切り替えられます。

モード 内容
シェーディング 通常の陰影表示(既定)
ワイヤーフレーム メッシュの辺のみ表示
オーバーハング 造形方向(Z軸)に対する面の傾斜角からサポート材が必要になりやすい箇所を赤系グラデーションで強調表示。表示中は閾値スライダー(既定45°、30〜70°で調整可)が出現する。

8. エクスポート

右ペイン下部のエクスポートバーから、生成済みモデルを4形式でダウンロードできます。

形式 内容
STL 形状のみ(色情報なし)
3MF 通常時は単一オブジェクト。カラーモード時は色ごとに分割された最大4オブジェクトとして出力されるので、スライサー(Cura等)側でオブジェクトごとにフィラメントを割り当てる。
GLB テクスチャ生成(paint)使用時はテクスチャ付き、それ以外は頂点カラー付き。ビューアで使っているのと同じデータ。
OBJ 形状のみ。

9. よくあるつまずき

  • 何を入れても同じ形が出る / 画像と無関係な結果になる: mock ジェネレータで 起動している可能性が高いです。「1. 起動してアクセスする」を参照し IMAGE3D_GENERATOR=hunyuan3d で起動し直してください。
  • テクスチャ生成のチェックボックスが押せない: この環境に texgen (custom_rasterizer CUDA拡張)が未導入です。形状生成自体は通常通り可能です。 導入手順は README.md の Phase 3c セットアップ節を参照してください。
  • テクスチャ生成した3Dモデルの目や細部がズレる: マルチビュー拡散モデルが 生成した複数ビューをベイクする方式のため、完全な一致は保証されません。既知の 限界です(README.md 参照)。正面の色精度を優先したい場合は「テクスチャ生成」を OFFにしてください。