为什么值得关注

它提供了从图像到 3D 打印数据和绑定角色模型的完整本地化流水线，无需云端依赖，并具备多视图输入、角色图自动分割和 AI 纹理生成等高级功能。

适合谁使用

3D 打印爱好者和创客
VRM/3D 角色创作者
需要快速生成 3D 模型的游戏开发者
对本地图像转 3D 流水线感兴趣的开发者

典型使用场景

将手办照片转换为可 3D 打印的水密 STL 文件
为多色打印机（如拓竹 AMS）生成带颜色分割的 3MF 文件
从 T pose 角色图像创建带有骨骼的 GLB 和 VRM 1.0 模型
实验 AI 驱动的纹理合成与多视角重建

项目优势

端到端流水线：上传图像、生成、预览并下载多种格式
本地执行（无云端依赖），支持可配置的 GPU 或 CPU 模拟模式
模块化开发阶段便于逐步采用高级功能
支持多视图输入、角色图自动分割以及带调色板量化的四色打印

使用前须知

完整 GPU 功能（Hunyuan3D-2）需要较大显存（形状生成 16GB+，纹理生成 32GB+）和 CUDA 环境配置
模拟生成器不反映实际图像内容，仅产生确定性的参数化网格
Hunyuan3D-2 及其依赖具有限制性许可证（如 pymeshlab 的 GPL、Tencent 社区许可证），需要手动克隆和构建

README 快速开始

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)に基づく目安。

使用機能	実測ピーク	最小要件	備考
mockジェネレータのみ	—	GPU不要	開発・UI確認用
形状生成(単一ビュー/マルチビュー)	約12GB	16GB	単一ビュー・mvの両パイプライン常駐+生成中ピークを含む
+テクスチャ生成 (`texture_mode=paint`)	約25GB	32GB	shape+paint(delight・multiview diffusion)常駐+生成中ピーク

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

项目描述

image to 3d for 3D-printer

image-3d