Wonder3D

环境要求

• Linux 系统（Windows 用户需切换到 main-windows 分支查看安装细节）
• 已安装 Conda，可创建 Python 虚拟环境
• 具备可用的 CUDA/GPU 环境（需安装 tiny-cuda-nn 的 CUDA 扩展）
• 需要下载项目代码与预训练模型（README 未给出权重下载命令，需自行参考官方说明）

安装与启动步骤

1. 1创建 Conda 环境

   新建名为 wonder3d 的独立环境并激活，避免与系统 Python 依赖冲突。

   conda create -n wonder3d
   conda activate wonder3d

   复制

2. 2安装项目依赖

   在项目根目录下根据 requirements.txt 安装 Python 依赖，需先进入已克隆的仓库目录。

   pip install -r requirements.txt

   复制

3. 3安装 tiny-cuda-nn

   安装 NVlabs 的 tiny-cuda-nn 的 PyTorch 绑定，这是官方 Linux 安装流程的必需步骤。

   pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch

   复制

4. 4运行多视角生成

   用 accelerate 启动 test_mvdiffusion_seq.py，输入单张图片生成 6 视角一致的法线图与彩色图，结果输出到 ./outputs，单张约 2~3 分钟。

   accelerate launch --config_file 1gpu.yaml test_mvdiffusion_seq.py --config configs/mvdiffusion-joint-ortho-6views.yaml validation_dataset.root_dir=./example_images validation_dataset.filepaths=['owl.png'] save_dir=./outputs

   复制

5. 5安装去背景工具

   README 使用 rembg 去除生成结果的背景，可先安装该包再在代码中调用 rembg.remove。

   pip install rembg

   复制

6. 6启动法线生成 Demo

   运行本地 Gradio 演示，仅生成多视角法线与彩色图，不做网格重建，需先运行 gradio_app_mv.py。

   python gradio_app_mv.py

   复制

7. 7启动重建 Demo

   运行另一个 Gradio 演示，先生成法线与彩色图再完成重建，无需提前运行 gradio_app_mv.py。

   python gradio_app_recon.py

   复制

关键配置

如何确认成功

命令执行完成后，在 save_dir 指定的 ./outputs 文件夹中可看到生成的多视角法线图与彩色图；Gradio Demo 启动后可在浏览器打开的本地页面中操作。

常见问题

注意事项

• Windows 用户请切换到 main-windows 分支查看专用安装步骤，不要直接套用主分支的 Linux 命令。
• README 未提供预训练权重下载命令，请以官方仓库/项目页的最新说明为准。
• 掩码分割质量会显著影响最终重建网格的质量，建议必要时手动优化掩码。
• 项目已扩展出更进阶的 Wonder3D++，位于同一仓库的 Wonder3D_Plus 分支。