单图生成 3D 模型

这是一个用于课程演示的 Gradio 项目：输入一张物体图片，使用 TripoSR 或 Stable Fast 3D 生成带纹理、材质和 UV 的 GLB 文件，并在浏览器中交互预览。

1. 环境要求

• Linux
• Python 3.13（当前，可以兼容性）
• NVIDIA GPU，建议显存 11GB 以上
• NVIDIA 驱动可用，nvidia-smi 能看到 GPU
• CUDA Toolkit 12.x 编译器，默认路径是 /usr/local/cuda-12.1
• 可访问 Hugging Face

已验证组合：Python 3.13、PyTorch 2.10.0+cu128、CUDA GPU、CUDA 12.1 nvcc。

2. 安装

解压后进入项目目录：

cd Gen3D
python --version

项目使用当前 Python 环境，不要求额外创建 Conda 环境。先确保 PyTorch 是 CUDA 版本；如果尚未安装，可以执行：

python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

然后安装项目依赖和 GPU 扩展：

./install_gpu_dependencies.sh

脚本会安装 Python 依赖，并编译 GPU 版 torchmcubes、Stable Fast 3D 的 texture_baker 和 uv_unwrapper。

如果 CUDA 12.1 在其他位置：

CUDA_HOME=/你的/cuda-12.x ./install_gpu_dependencies.sh

检查 GPU：

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

必须输出 True 和显卡名称。不要安装 CPU 版 PyTorch。

3. 下载模型权重

模型源码已包含在 vendor/，权重通过 Hugging Face 下载，不放进压缩包：

python download_models.py --model all

如果 Stable Fast 3D 提示 gated：

1. 登录 Hugging Face；
2. 打开 stabilityai/stable-fast-3d 页面并接受许可；
3. 执行：

hf auth login
python download_models.py --model all

权重默认保存在当前用户的 Hugging Face 缓存目录。换机器时重新执行下载命令即可。

4. 双模型测试

用同一张示例图依次运行两个模型，并验证输出 GLB 包含几何体：

export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:${LD_LIBRARY_PATH:-}"
export PYOPENGL_PLATFORM=egl
python test_models.py

使用自己的图片：

python test_models.py /path/to/object.png --resolution 256

成功后会生成：

outputs/triposr_textured.glb
outputs/stable_fast_3d_textured.glb

256 适合首次验证；显存足够时可以改为 512。

5. 启动网页

./run_demo.sh

本机浏览器打开 http://127.0.0.1:7860。页面支持上传图片、读取服务器示例图片、读取服务器绝对路径图片、选择模型、下载 GLB 和交互预览。

两个模型不会同时占用显存，切换模型时程序会释放上一个模型。

6. 远程服务器

服务器上启动：

./run_demo.sh

自己电脑上建立 SSH 转发：

ssh -N -L 7860:127.0.0.1:7860 用户名@服务器地址

然后在自己电脑浏览器打开 http://127.0.0.1:7860。网页文件选择器选择的是自己电脑上的图片，图片会上传到服务器处理。

项目使用自身的 .gradio_tmp/，不会访问其他用户拥有的 /tmp/gradio。不要删除共享的 /tmp/gradio。无图形桌面服务器使用 EGL 完成 TripoSR 纹理烘焙。

7. 常见问题

CUDA 不可用

python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"

如果第二项是 False，检查 NVIDIA 驱动和 CUDA 版 PyTorch。

找不到 CUDA 编译器

CUDA_HOME=/usr/local/cuda-12.1 ./install_gpu_dependencies.sh

PermissionError: /tmp/gradio/...

使用 ./run_demo.sh 并重启旧服务。项目会使用 .gradio_tmp/，不需要修改其他用户的目录。

显存不足

使用 --resolution 256，或把网页纹理分辨率设为 512。两个模型不要同时加载。

8. 文件说明

app.py                         Gradio 界面
backends.py                    两个模型的统一推理接口
test_models.py                 双模型端到端测试
download_models.py             Hugging Face 权重下载
download_demo_data.py          下载公开示例图片
install_gpu_dependencies.sh    GPU 依赖安装
run_demo.sh                    一键启动
vendor/                        两个模型源码
demo_data/                     示例图片
outputs/                       生成的 GLB

本项目只导出 GLB。单张图片无法真实恢复不可见面，因此结果适合课程展示，不等同于多视角扫描。

9. 许可

TripoSR、Stable Fast 3D、模型权重和示例图片分别受其上游许可证约束。公开展示、再分发或商业使用前，请阅读对应 GitHub 和 Hugging Face 页面中的许可条款。