Stable-Dreamfusion

一个基于 PyTorch 的文本到 3D 模型 Dreamfusion 的实现，由 Stable Diffusion 文本到 2D 模型驱动。

广告：请查看 threestudio，它在 3D 内容生成方面有最新的改进和更好的实现！

新闻 (2023.6.12)：

• 支持 Perp-Neg 来缓解文本到 3D 中的多头问题。
• 同时支持 Stable Diffusion 和 DeepFloyd-IF 的 Perp-Neg。

https://user-images.githubusercontent.com/25863658/236712982-9f93bd32-83bf-423a-bb7c-f73df7ece2e3.mp4

https://user-images.githubusercontent.com/25863658/232403162-51b69000-a242-4b8c-9cd9-4242b09863fa.mp4

更新日志

Colab 笔记本：

• Instant-NGP 骨干（-O）：

• 范式 NeRF 骨干（-O2）：

重要提示

该项目目前仍处于 开发中，与论文相比存在许多差异。当前的生成质量还无法达到原论文的结果，许多提示仍然会严重失败！

与论文的主要区别

• 由于 Imagen 模型未公开，我们使用 Stable Diffusion 替代它（实现来自 diffusers）。与 Imagen 不同，Stable-Diffusion 是一种潜在扩散模型，它是在潜在空间而非原始图像空间中进行扩散的。因此，我们需要将损失也反向传播到 VAE 的编码器部分，这会增加训练时间成本。
• 我们使用 多分辨率网格编码器 来实现 NeRF 骨干（实现来自 torch-ngp），这使得渲染速度大幅提升（800x800 分辨率下约 10 FPS）。
• 我们默认使用 Adan 优化器。

安装

git clone https://github.com/ashawkey/stable-dreamfusion.git
cd stable-dreamfusion

可选：创建 Python 虚拟环境

为避免 Python 包冲突，建议使用虚拟环境，例如使用 conda 或 venv：

python -m venv venv_stable-dreamfusion
source venv_stable-dreamfusion/bin/activate # 每次打开新终端都需要重复此步骤

使用 pip 安装

pip install -r requirements.txt

下载预训练模型

要使用图像条件下的 3D 生成，需要手动下载一些预训练检查点：

• Zero-1-to-3 作为扩散后端。 默认使用 zero123-xl.ckpt，并在 guidance/zero123_utils.py 中硬编码。

  cd pretrained/zero123
  wget https://zero123.cs.columbia.edu/assets/zero123-xl.ckpt
  

• Omnidata 用于深度和法线预测。 这些检查点在 preprocess_image.py 中硬编码。

  mkdir pretrained/omnidata
  cd pretrained/omnidata
  # 假设已安装 gdown
  gdown '1Jrh-bRnJEjyMCS7f-WsaFlccfPjJPPHI&confirm=t' # omnidata_dpt_depth_v2.ckpt
  gdown '1wNxVO4vVbDEMEpnAi_jwQObf2MFodcBR&confirm=t' # omnidata_dpt_normal_v2.ckpt
  

要使用 DeepFloyd-IF，需要接受来自 hugging face 的使用条款，并通过命令行使用 huggingface-cli login 登录。

对于 DMTet，我们将预先生成的 32/64/128 分辨率四面体网格移植到 tets 目录下。256 分辨率的网格可以在 这里 找到。

构建扩展（可选）

默认情况下，我们使用 load 在运行时构建扩展。 我们也提供了 setup.py 来构建每个扩展：

cd stable-dreamfusion

# 安装所有扩展模块
bash scripts/install_ext.sh

# 如果你想手动安装，这里有一个例子：
pip install ./raymarching # 安装到 Python 路径（你仍然需要 raymarching/ 文件夹，因为这只是安装了编译好的扩展。)

Taichi 后端（可选）

使用 Taichi 后端来替代 Instant-NGP。它可以在无需 CUDA 的情况下实现与 CUDA 实现相当的性能。使用 pip 安装 Taichi：

pip install -i https://pypi.taichi.graphics/simple/ taichi-nightly

故障排除：

• 我们假设所有依赖项都使用最新版本，如果遇到特定依赖项的问题，请先尝试升级它（例如 pip install -U diffusers）。如果问题仍然存在，请提交 bug 报告，我们将不胜感激！
• [F glutil.cpp:338] eglInitialize() failed Aborted (core dumped)：这通常表示 OpenGL 安装存在问题。尝试重新安装 Nvidia 驱动程序，或者如 https://github.com/ashawkey/stable-dreamfusion/issues/131 所示，如果您使用的是无头服务器，可以尝试使用 nvidia-docker。
• TypeError: xxx_forward(): incompatible function arguments：当您更新 CUDA 源代码并之前使用 setup.py 安装过扩展时，可能会出现这种情况。尝试重新安装相应的扩展（例如 pip install ./gridencoder）。

测试环境

• Ubuntu 22，配备 torch 1.12 和 CUDA 11.6 的 V100 显卡。

使用方法

首次运行时，编译 CUDA 扩展可能需要一些时间。

#### stable-dreamfusion 设置

### Instant-NGP NeRF 骨干
# + 渲染速度更快
# + GPU 内存占用更少（约 16G）
# - 需要编译 CUDA 扩展（也有无需 CUDA 的 Taichi 后端）

## 使用文本提示训练（使用默认设置）
# `-O` 等价于 `--cuda_ray --fp16`
# `--cuda_ray` 启用类似 Instant-NGP 的占用网格加速。
python main.py --text "a hamburger" --workspace trial -O

# 使用 `--vram_O` 减少 Stable-Diffusion 的内存使用
# 启用各种显存节省功能（https://huggingface.co/docs/diffusers/optimization/fp16）。
python main.py --text "a hamburger" --workspace trial -O --vram_O

# 你可以将参数收集到一个文件中。通过在 `--file` 后指定参数，可以覆盖文件中的参数。请注意，带引号的字符串无法从 .args 文件中加载……
python main.py --file scripts/res64.args --workspace trial_awesome_hamburger --text "a photo of an awesome hamburger"

# 使用无 CUDA 的 Taichi 后端，只需添加 `--backbone grid_taichi`
python3 main.py --text "a hamburger" --workspace trial -O --backbone grid_taichi

# 选择 Stable Diffusion 版本（支持 1.5、2.0 和 2.1，默认为 2.1）
python main.py --text "a hamburger" --workspace trial -O --sd_version 1.5

# 使用来自 Hugging Face 的自定义 Stable Diffusion 检查点：
python main.py --text "a hamburger" --workspace trial -O --hf_key andite/anything-v4.0

# 使用 DeepFloyd-IF 进行引导（实验性）：
python main.py --text "a hamburger" --workspace trial -O --IF
python main.py --text "a hamburger" --workspace trial -O --IF --vram_O # 需要约 24G 显存

# 我们现在也支持负面文本提示：
python main.py --text "a rose" --negative "red" --workspace trial -O

## 训练完成后：
# 测试（导出 360 度视频）
python main.py --workspace trial -O --test
# 同时保存网格模型（包含 obj、mtl 和 png 纹理）
python main.py --workspace trial -O --test --save_mesh
# 使用 GUI 进行测试（可自由控制视角！）
python main.py --workspace trial -O --test --gui

### Vanilla NeRF 后台
# + 纯 PyTorch 实现，无需编译扩展！
# - 渲染速度较慢
# - 需要更多显存

## 训练
# `-O2` 等同于 `--backbone vanilla`
python main.py --text "a hotdog" --workspace trial2 -O2

# 如果 CUDA 内存不足，可以尝试减少 NeRF 采样步骤（`--num_steps` 和 `--upsample_steps`）
python main.py --text "a hotdog" --workspace trial2 -O2 --num_steps 64 --upsample_steps 0

## 测试
python main.py --workspace trial2 -O2 --test
python main.py --workspace trial2 -O2 --test --save_mesh
python main.py --workspace trial2 -O2 --test --gui # 不推荐，帧率会很低。

### DMTet 微调

## 使用 `--dmtet` 和 `--init_with <nerf checkpoint>` 来以更高分辨率微调网格
python main.py -O --text "a hamburger" --workspace trial_dmtet --dmtet --iters 5000 --init_with trial/checkpoints/df.pth

## 使用网格初始化 DMTet 以生成纹理
# 需要安装 cubvh：pip install git+https://github.com/ashawkey/cubvh
# 移除 `--lock_geo` 可以同时微调几何形状，但性能可能较差。
python main.py -O --text "a white bunny with red eyes" --workspace trial_dmtet_mesh --dmtet --iters 5000 --init_with ./data/bunny.obj --lock_geo

## 测试与导出网格
python main.py -O --text "a hamburger" --workspace trial_dmtet --dmtet --iters 5000 --test --save_mesh

## 可视化 DMTet 的 GUI
python main.py -O --text "a hamburger" --workspace trial_dmtet --dmtet --iters 5000 --test --gui

### 基于图像的 3D 生成

## 预处理输入图像
# 注意：图像转 3D 的效果取决于 zero-1-to-3 的能力。为了获得最佳效果，输入图像应包含单一正面物体，长宽比为正方形，分辨率为 1024 像素以下。请查看 ./data 下的示例。
# 这将输出 `<image>_rgba.png`、`<image>_depth.png` 和 `<image>_normal.png` 到输入图像所在的目录。
python preprocess_image.py <image>.png
python preprocess_image.py <image>.png --border_ratio 0.4 # 如果中心物体显得过大且结果不理想，可增加边框比例。

## zero123 训练
# 通过 `--image` 传入处理后的 `<image>_rgba.png`，不要传入 `--text`，以启用 zero-1-to-3 后端。
python main.py -O --image <image>_rgba.png --workspace trial_image --iters 5000

# 如果图像并非完全正面（仰角 ≠ 0），需调整 default_polar（我们用 0 到 180 表示 90 到 -90 的仰角）
python main.py -O --image <image>_rgba.png --workspace trial_image --iters 5000 --default_polar 80

# 默认情况下，我们会利用单目深度估计来辅助图像转 3D，但如果发现深度估计不准确并影响结果，可以通过以下方式关闭：
python main.py -O --image <image>_rgba.png --workspace trial_image --iters 5000 --lambda_depth 0

python main.py -O --image <image>_rgba.png --workspace trial_image_dmtet --dmtet --init_with trial_image/checkpoints/df.pth

## 多张图像的 zero123
python main.py -O --image_config config/<config>.csv --workspace trial_image --iters 5000

## 每批渲染 <num> 张图像（默认 1 张）
python main.py -O --image_config config/<config>.csv --workspace trial_image --iters 5000 --batch_size 4

# 同时提供 `--text` 和 `--image` 将启用 Stable Diffusion 后端（类似于 make-it-3d）
python main.py -O --image hamburger_rgba.png --text "一张美味汉堡的 DSLR 照片" --workspace trial_image_text --iters 5000

python main.py -O --image hamburger_rgba.png --text "一张美味汉堡的 DSLR 照片" --workspace trial_image_text_dmtet --dmtet --init_with trial_image_text/checkpoints/df.pth

## 测试 / 可视化
python main.py -O --image <image>_rgba.png --workspace trial_image_dmtet --dmtet --test --save_mesh
python main.py -O --image <image>_rgba.png --workspace trial_image_dmtet --dmtet --test --gui

### 调试

# 可以保存引导图像用于调试目的。这些图像会保存在 trial_hamburger/guidance 目录下。
# 注意：这会显著减慢训练速度，并占用大量磁盘空间！
python main.py --text "a hamburger" --workspace trial_hamburger -O --vram_O --save_guidance --save_guidance_interval 5 # 每 5 步保存一次

有关示例命令，请查看 scripts。

有关高级技巧和其他开发内容，请查看 Advanced Tips。

评估

重现论文中的 CLIP R 精度评估

在使用说明中的测试部分完成后，会生成包含不同角度投影的验证集。测试提示词与图像之间的 R 精度。（R=1）

python r_precision.py --text "a snake is flying in the sky" --workspace snake_HQ --latest ep0100 --mode depth --clip clip-ViT-B-16

致谢

本工作基于日益增长的一系列卓越的研究成果和开源项目，衷心感谢所有作者的分享！

• DreamFusion：使用2D扩散模型实现文本到3D生成

  @article{poole2022dreamfusion,
      author = {Poole, Ben and Jain, Ajay and Barron, Jonathan T. and Mildenhall, Ben},
      title = {DreamFusion: Text-to-3D using 2D Diffusion},
      journal = {arXiv},
      year = {2022},
  }
  

• Magic3D：高分辨率文本到3D内容生成

  @inproceedings{lin2023magic3d,
     title={Magic3D: High-Resolution Text-to-3D Content Creation},
     author={Lin, Chen-Hsuan and Gao, Jun and Tang, Luming and Takikawa, Towaki and Zeng, Xiaohui and Huang, Xun and Kreis, Karsten and Fidler, Sanja and Liu, Ming-Yu and Lin, Tsung-Yi},
     booktitle={IEEE Conference on Computer Vision and Pattern Recognition ({CVPR})},
     year={2023}
   }
  

• Zero-1-to-3：零样本单张图像到3D物体生成

  @misc{liu2023zero1to3,
      title={Zero-1-to-3: Zero-shot One Image to 3D Object},
      author={Ruoshi Liu and Rundi Wu and Basile Van Hoorick and Pavel Tokmakov and Sergey Zakharov and Carl Vondrick},
      year={2023},
      eprint={2303.11328},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
  }
  

• Perp-Neg：重新构想负向提示算法——将2D扩散转化为3D，缓解Janus问题并进一步拓展

  @article{armandpour2023re,
    title={Re-imagine the Negative Prompt Algorithm: Transform 2D Diffusion into 3D, alleviate Janus problem and Beyond},
    author={Armandpour, Mohammadreza and Zheng, Huangjie and Sadeghian, Ali and Sadeghian, Amir and Zhou, Mingyuan},
    journal={arXiv preprint arXiv:2304.04968},
    year={2023}
  }
  

• RealFusion：从单张图像重建任意物体的360°视图

  @inproceedings{melaskyriazi2023realfusion,
      author = {Melas-Kyriazi, Luke and Rupprecht, Christian and Laina, Iro and Vedaldi, Andrea},
      title = {RealFusion: 360 Reconstruction of Any Object from a Single Image},
      booktitle={CVPR}
      year = {2023},
      url = {https://arxiv.org/abs/2302.10663},
  }
  

• Fantasia3D：解耦几何与外观以实现高质量文本到3D内容生成

  @article{chen2023fantasia3d,
      title={Fantasia3D: Disentangling Geometry and Appearance for High-quality Text-to-3D Content Creation},
      author={Rui Chen and Yongwei Chen and Ningxin Jiao and Kui Jia},
      journal={arXiv preprint arXiv:2303.13873},
      year={2023}
  }
  

• Make-It-3D：基于扩散先验的单张图像高保真3D生成

  @article{tang2023make,
      title={Make-It-3D: High-Fidelity 3D Creation from A Single Image with Diffusion Prior},
      author={Tang, Junshu and Wang, Tengfei and Zhang, Bo and Zhang, Ting and Yi, Ran and Ma, Lizhuang and Chen, Dong},
      journal={arXiv preprint arXiv:2303.14184},
      year={2023}
  }
  

• Stable Diffusion 和 diffusers 库。

  @misc{rombach2021highresolution,
      title={High-Resolution Image Synthesis with Latent Diffusion Models},
      author={Robin Rombach and Andreas Blattmann and Dominik Lorenz and Patrick Esser and Björn Ommer},
      year={2021},
      eprint={2112.10752},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
  }
  
  @misc{von-platen-etal-2022-diffusers,
      author = {Patrick von Platen and Suraj Patil and Anton Lozhkov and Pedro Cuenca and Nathan Lambert and Kashif Rasul and Mishig Davaadorj and Thomas Wolf},
      title = {Diffusers: State-of-the-art diffusion models},
      year = {2022},
      publisher = {GitHub},
      journal = {GitHub repository},
      howpublished = {\url{https://github.com/huggingface/diffusers}}
  }
  

• GUI界面采用 DearPyGui 开发。

• 小狗图片来自：https://www.pexels.com/photo/high-angle-photo-of-a-corgi-looking-upwards-2664417/

• 安雅图片来自：https://www.goodsmile.info/en/product/13301/POP+UP+PARADE+Anya+Forger.html

引用

如果您觉得本工作有所帮助，请通过以下方式引用：

@misc{stable-dreamfusion,
    Author = {Jiaxiang Tang},
    Year = {2022},
    Note = {https://github.com/ashawkey/stable-dreamfusion},
    Title = {Stable-dreamfusion: Text-to-3D with Stable-diffusion}
}

Stable-Dreamfusion 快速上手指南

Stable-Dreamfusion 是一个基于 PyTorch 的文本生成 3D 模型实现，利用 Stable Diffusion 作为先验知识。本指南将帮助你快速在本地部署并运行该工具。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: 推荐 Ubuntu 22.04 (其他 Linux 发行版或 Windows WSL2 也可尝试)。
• GPU: 支持 CUDA 的 NVIDIA 显卡 (推荐显存 16GB 以上，使用 --vram_O 参数可适当降低要求)。
• CUDA: 推荐 CUDA 11.6 或更高版本。
• Python: Python 3.8+。
• 依赖: 需要安装 git, wget, gdown (用于下载部分预训练模型)。

注意: 该项目处于开发阶段，生成质量可能与原论文有差异，且部分提示词可能效果不佳。

安装步骤

1. 克隆项目

git clone https://github.com/ashawkey/stable-dreamfusion.git
cd stable-dreamfusion

2. 创建虚拟环境 (推荐)

为了避免依赖冲突，建议使用 conda 或 venv 创建独立环境。

python -m venv venv_stable-dreamfusion
source venv_stable-dreamfusion/bin/activate

3. 安装 Python 依赖

pip install -r requirements.txt

国内用户若下载缓慢，可添加清华源加速：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 下载预训练模型 (可选但推荐)

若需使用图像生成 3D功能，需手动下载以下模型：

Zero-1-to-3 (扩散后端):

mkdir -p pretrained/zero123
cd pretrained/zero123
wget https://zero123.cs.columbia.edu/assets/zero123-xl.ckpt
cd ../..

Omnidata (深度与法线预测): 需先安装 gdown: pip install gdown

mkdir -p pretrained/omnidata
cd pretrained/omnidata
gdown '1Jrh-bRnJEjyMCS7f-WsaFlccfPjJPPHI&confirm=t' # omnidata_dpt_depth_v2.ckpt
gdown '1wNxVO4vVbDEMEpnAi_jwQObf2MFodcBR&confirm=t' # omnidata_dpt_normal_v2.ckpt
cd ../..

注：若使用 DeepFloyd-IF 模型，需先在 Hugging Face 接受协议并执行 huggingface-cli login 登录。

5. 构建扩展模块 (可选)

默认情况下，程序会在运行时自动编译 CUDA 扩展。若需预先安装以提升稳定性：

bash scripts/install_ext.sh

若无 CUDA 环境，可使用 Taichi 后端（性能相当但无需编译 CUDA）：

pip install -i https://pypi.taichi.graphics/simple/ taichi-nightly

基本使用

首次运行时，系统会自动编译 CUDA 扩展，可能需要几分钟时间。

场景一：文本生成 3D (Text-to-3D)

使用默认的 Instant-NGP 骨干网络进行训练（速度快，显存占用较低）：

# 基础用法：生成一个汉堡包
python main.py --text "a hamburger" --workspace trial -O

# 显存优化模式：如果显存不足，添加 --vram_O 参数
python main.py --text "a hamburger" --workspace trial -O --vram_O

# 使用负向提示词
python main.py --text "a rose" --negative "red" --workspace trial -O

参数说明：

• -O: 启用 Instant-NGP 加速 (--cuda_ray --fp16)。
• --workspace: 指定输出目录。
• --sd_version: 指定 Stable Diffusion 版本 (1.5, 2.0, 2.1)，默认为 2.1。

场景二：测试与导出

训练完成后，使用以下命令进行测试、视频导出或网格保存：

# 导出 360 度旋转视频
python main.py --workspace trial -O --test

# 保存 3D 网格文件 (.obj, .mtl, 纹理图)
python main.py --workspace trial -O --test --save_mesh

# 启动 GUI 交互式查看器 (支持自由视角控制)
python main.py --workspace trial -O --test --gui

场景三：图像生成 3D (Image-to-3D)

若需基于单张图像生成 3D 模型，首先预处理图像：

# 预处理：生成带透明通道、深度图和法线图的图像
python preprocess_image.py <input_image>.png

然后使用处理后的图像进行训练（不要传入 --text 参数以启用 Zero-1-to-3 后端）：

python main.py -O --image <input_image>_rgba.png --workspace trial_image --iters 5000

训练结束后同样使用 --test --save_mesh 导出结果。