threestudio:基于深度学习的3D内容生成与编辑项目

threestudio 是一个统一的框架，用于从文本提示、单张图像和少量样本图像生成三维内容，通过提升二维文本到图像生成模型。

👆 threestudio 实现的方法获得的结果 👆
| ProlificDreamer | DreamFusion | Magic3D | SJC | Latent-NeRF | Fantasia3D | TextMesh |
| Zero-1-to-3 | Magic123 | HiFA | SDI |
| InstructNeRF2NeRF | Control4D |

没有找到你想要的内容？查看 threestudio 扩展 或提交一个功能请求 这里!

| Animate-124 | 4D-fy | GeoDream | DreamCraft3D | Dreamwaltz | 3DFuse | Progressive3D | GaussianDreamer | Gaussian Splatting | MVDream | Mesh-Fitting |

新闻

• 2024年11月08日：感谢Artem Lukoianov实现了通过重参数化DDIM的分数蒸馏！Threestudio新增了文本到3D模块以及一个包含2D分数蒸馏实验的笔记本。

• 2024年10月21日：感谢Amir Barda实现了MagicClay！请按照网站上的说明尝试使用。

• 2024年03月12日：感谢Matthew Kwak和Inès Hyeonsu Kim实现了3DFuse！请按照网站上的说明尝试使用。

• 2024年03月08日：感谢Xinhua Cheng实现了GaussianDreamer！请按照网站上的说明尝试使用。

• 2024年03月01日：感谢Xinhua Cheng实现了Progressive3D！请按照网站上的说明尝试使用。

• 2024年01月09日：感谢Zehuan Huang实现了3D人类角色生成的Dreamwaltz！请按照网站上的说明尝试使用。

• 2024年01月06日：感谢Baorui Ma实现了GeoGream扩展！请按照网站上的说明尝试使用。

• 2024年01月05日：实现了HiFA。请按照这里的说明尝试所有三个变体。

• 2023年12月23日：感谢Yuyang Zhao实现了图像到4D生成扩展Animate-124！请按照扩展网站的说明尝试使用。

• 2023年12月18日：实现了用于4D生成的4D-fy和用于高质量图像到3D生成的DreamCraft3D作为自定义扩展！请按照扩展网站的说明尝试使用。

• 2023年12月13日：实现了支持从单张图像生成3D内容的Stable Zero123！请按照这里的说明尝试使用。

• 2023年11月30日：实现了MVDream、Gaussian Splatting作为自定义扩展。您还可以使用神经表示通过Mesh-Fitting拟合网格。

• 2023年11月30日：实现了自定义扩展系统，您可以在这个项目中添加您的扩展。

• 2023年06月25日：实现了Magic123！请按照这里的说明尝试使用。

• 2023年07月06日：加入我们的Discord服务器参与热烈的讨论！

• 2023年07月03日：在HuggingFace Spaces或使用我们的自托管服务（由腾讯提供GPU支持）在线尝试文本到3D。要本地托管Web界面，请查看这里。

• 2023年06月20日：实现了高保真3D编辑的Instruct-NeRF2NeRF和Control4D！请按照Control4D和Instruct-NeRF2NeRF的说明尝试使用。

• 2023年06月14日：实现了TextMesh！请按照这里的说明尝试使用。

• 2023年06月14日：实现了prompt debiasing和Perp-Neg！请按照这里的说明尝试使用。

• 2023年05月29日：实验性实现了使用Zero-1-to-3从单张图像生成3D内容！请按照这里的说明尝试使用。

• 2023年05月26日：实现了ProlificDreamer！请按照这里的说明尝试使用。

• 2023年05月14日：您可以使用我们的2dplayground在2D图像上尝试SDS损失。

• 2023年05月13日：现在您可以在Google Colab上尝试threestudio！

• 2023年05月11日：我们现在支持导出纹理化的网格！请查看这里获取说明。

安装

请查看installation.md获取附加信息，包括通过Docker安装。

以下步骤已在Ubuntu20.04上测试。

• 您必须拥有一块至少6GB VRAM的NVIDIA显卡并安装了CUDA。
• 安装Python >= 3.8。
• （可选，推荐）创建一个虚拟环境：

python3 -m virtualenv venv
. venv/bin/activate

# Newer pip versions, e.g. pip-23.x, can be much faster than old versions, e.g. pip-20.x.
# For instance, it caches the wheels of git packages to avoid unnecessarily rebuilding them later.
python3 -m pip install --upgrade pip

• 安装 PyTorch >= 1.12。我们已在 torch1.12.1+cu113 和 torch2.0.0+cu118 上进行了测试，但其他版本也应能正常运行。

# torch1.12.1+cu113
pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 --extra-index-url https://download.pytorch.org/whl/cu113
# or torch2.0.0+cu118
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

• （可选，建议）安装 ninja 以加快 CUDA 扩展的编译速度：

pip install ninja

• 安装依赖项：

pip install -r requirements.txt

• （可选）安装 tiny-cuda-nn 可能需要将 pip 降级至 23.0.1 版本。

• （可选，推荐）threestudio 中表现最佳的模型使用了新发布的 T2I 模型 DeepFloyd IF，目前使用该模型需要签署一份许可协议。如果您希望使用这些模型，需要先在 DeepFloyd IF 的模型卡片上接受许可，并在终端中使用 huggingface-cli login 登录 Hugging Face hub。

• 对于贡献者，请参考 此处。

快速入门

这里我们将展示 threestudio 的一些基本用法。首先，让我们训练一个 DreamFusion 模型来创建一个经典的煎饼兔子。

如果您在连接 Hugging Face 时遇到不稳定的连接问题，我们建议您：(1) 在运行命令之前，先设置环境变量 TRANSFORMERS_OFFLINE=1 DIFFUSERS_OFFLINE=1 HF_HUB_OFFLINE=1，以确保在首次获取所有所需文件后，每次运行时避免连接到 Hugging Face；或者 (2) 按照以下指南 这里 和 这里 下载您使用的指导模型至本地文件夹，并将指导模型和提示处理器的 pretrained_model_name_or_path 设置为本地路径。

# if you have agreed the license of DeepFloyd IF and have >20GB VRAM
# please try this configuration for higher quality
python launch.py --config configs/dreamfusion-if.yaml --train --gpu 0 system.prompt_processor.prompt="a zoomed out DSLR photo of a baby bunny sitting on top of a stack of pancakes"
# otherwise you could try with the Stable Diffusion model, which fits in 6GB VRAM
python launch.py --config configs/dreamfusion-sd.yaml --train --gpu 0 system.prompt_processor.prompt="a zoomed out DSLR photo of a baby bunny sitting on top of a stack of pancakes"

threestudio 采用 OmegaConf 进行灵活配置。您可以通过指定不带 -- 的参数，轻松地在 YAML 文件中更改任何配置，例如上述案例中的指定提示。有关所有支持的配置，请参阅我们的文档。

训练持续 10,000 次迭代。您可以在试验目录中查看当前状态的可视化结果，默认目录为 [exp_root_dir]/[name]/[tag]@[timestamp]，其中 exp_root_dir（默认为 outputs/）、name 和 tag 可以在配置文件中设置。训练完成后将生成一段 360 度视频。在训练过程中，首次按下 ctrl+c 将停止训练并直接进入生成视频的测试阶段。再次按下 ctrl+c 将完全退出程序。

多 GPU 训练

多 GPU 训练是被支持的，但可能仍然存在错误。请注意 data.batch_size 是每个排名（设备）的批大小。同时请确保：

• 将 data.n_val_views 设置为 GPU 数量的倍数。
• 设置一个唯一的 tag，因为在多 GPU 训练中禁用了时间戳，且不会在 tag 后追加。如果与之前试验使用相同的 tag，则保存的配置文件、代码和可视化结果将被覆盖。

# this results in an effective batch size of 4 (number of GPUs) * 2 (data.batch_size) = 8
python launch.py --config configs/dreamfusion-if.yaml --train --gpu 0,1,2,3 system.prompt_processor.prompt="a zoomed out DSLR photo of a baby bunny sitting on top of a stack of pancakes" data.batch_size=2 data.n_val_views=4

在调用 launch.py 之前，如果您定义了 CUDA_VISIBLE_DEVICES 环境变量，那么就无需指定 --gpu 参数——这将自动使用 CUDA_VISIBLE_DEVICES 中指定的所有可用 GPU。例如，以下命令将自动使用 GPU 3 和 4：

CUDA_VISIBLE_DEVICES=3,4 python launch.py --config configs/dreamfusion-if.yaml --train system.prompt_processor.prompt="一张缩放后的婴儿兔子坐在煎饼堆上的 DSLR 照片"

这尤其在您在集群中运行 launch.py 并通过一条命令自动选择 GPU 并通过 CUDA_VISIBLE_DEVICES 导出其 ID 时特别有用，例如通过 SLURM。

cd git/threestudio
. venv/bin/activate
srun --account mod3d --partition=g40 --gpus=1 --job-name=3s_bunny python launch.py --config configs/dreamfusion-if.yaml --train system.prompt_processor.prompt="a zoomed out DSLR photo of a baby bunny sitting on top of a stack of pancakes"

从检查点恢复

如果您希望从检查点继续执行，请进行如下操作：

# resume training from the last checkpoint, you may replace last.ckpt with any other checkpoints
python launch.py --config path/to/trial/dir/configs/parsed.yaml --train --gpu 0 resume=path/to/trial/dir/ckpts/last.ckpt
# if the training has completed, you can still continue training for a longer time by setting trainer.max_steps
python launch.py --config path/to/trial/dir/configs/parsed.yaml --train --gpu 0 resume=path/to/trial/dir/ckpts/last.ckpt trainer.max_steps=20000
# you can also perform testing using resumed checkpoints
python launch.py --config path/to/trial/dir/configs/parsed.yaml --test --gpu 0 resume=path/to/trial/dir/ckpts/last.ckpt
# note that the above commands use parsed configuration files from previous trials
# which will continue using the same trial directory
# if you want to save to a new trial directory, replace parsed.yaml with raw.yaml in the command

# only load weights from saved checkpoint but dont resume training (i.e. dont load optimizer state):
python launch.py --config path/to/trial/dir/configs/parsed.yaml --train --gpu 0 system.weights=path/to/trial/dir/ckpts/last.ckpt

导出网格

若需将场景导出为纹理网格，请使用 --export 选项。目前我们支持导出为 obj+mtl 格式，或者带有顶点颜色的 obj 格式。

# this uses default mesh-exporter configurations which exports obj+mtl
python launch.py --config path/to/trial/dir/configs/parsed.yaml --export --gpu 0 resume=path/to/trial/dir/ckpts/last.ckpt system.exporter_type=mesh-exporter
# specify system.exporter.fmt=obj to get obj with vertex colors
# you may also add system.exporter.save_uv=false to accelerate the process, suitable for a quick peek of the result
python launch.py --config path/to/trial/dir/configs/parsed.yaml --export --gpu 0 resume=path/to/trial/dir/ckpts/last.ckpt system.exporter_type=mesh-exporter system.exporter.fmt=obj
# for NeRF-based methods (DreamFusion, Magic3D coarse, Latent-NeRF, SJC)
# you may need to adjust the isosurface threshold (25 by default) to get satisfying outputs
# decrease the threshold if the extracted model is incomplete, increase if it is extruded
python launch.py --config path/to/trial/dir/configs/parsed.yaml --export --gpu 0 resume=path/to/trial/dir/ckpts/last.ckpt system.exporter_type=mesh-exporter system.geometry.isosurface_threshold=10.
# use marching cubes of higher resolutions to get more detailed models
python launch.py --config path/to/trial/dir/configs/parsed.yaml --export --gpu 0 resume=path/to/trial/dir/ckpts/last.ckpt system.exporter_type=mesh-exporter system.geometry.isosurface_method=mc-cpu system.geometry.isosurface_resolution=256

关于导出时可以指定的所有选项，请参阅文档。

有关我们支持的所有模型的示例运行命令，请参见此处。如需获取更高质量的结果，请参阅这里的建议，以及此处关于减少VRAM使用的技巧。

Gradio Web 界面

通过

python gradio_app.py launch

参数：

• --listen：启动 Gradio 应用时，通过设置 server_name="0.0.0.0" 监听所有地址。
• --self-deploy：允许直接从网页更改任意配置。
• --save：启用检查点保存。

对于功能请求、错误报告或技术问题的讨论，请提交一个 issue。如果您想讨论生成质量或展示您的生成结果，请随时参与讨论面板。

支持的模型

通过重参数化的 DDIM 进行分数蒸馏（SDI）

SDI 建议重新考虑在 Dreamfusion 中对噪声项的采样方法。该论文表明，分数蒸馏过程可以视为 2D 图像采样算法的重参数化。在这种情况下，分数蒸馏每一步添加的噪声应该具有非常特定的形式。然而，Dreamfusion（SDS）中的噪声是随机采样的，这会导致过度模糊。SDI 通过逆转 DDIM 过程来近似正确的噪声项。

与论文中的显著差异：无。

优点：

• 质量很高的纹理
• 锋利的几何细节

缺点：

• 由于额外的逆转，比 SDS（1.5 倍）慢。但仍比 steps 数较少的 prolific dreamer 快。
• 由于高分辨率渲染，比 SDS 需要更多的 VRAM。降低分辨率以适应较小的 GPU。

在 threestudio（稳定扩散，512x512）获得的结果

示例运行命令

python launch.py --config configs/sdi.yaml --train --gpu 0 system.prompt_processor.prompt="pumpkin head zombie, skinny, highly detailed, photorealistic"

python launch.py --config configs/sdi.yaml --train --gpu 1 system.prompt_processor.prompt="a photograph of a ninja"

python launch.py --config configs/sdi.yaml --train --gpu 2 system.prompt_processor.prompt="a zoomed out DSLR photo of a hamburger"

python launch.py --config configs/sdi.yaml --train --gpu 3 system.prompt_processor.prompt="bagel filled with cream cheese and lox"

丰富梦想者

请注意，这是一个非官方的实验性实现！请访问 https://github.com/thu-ml/prolificdreamer 获取官方代码发布。

由 threestudio 获取的结果（稳定扩散，256x256 阶段1）

https://github.com/threestudio-project/threestudio/assets/19284678/27b42d8f-4aa4-4b47-8ea0-0f77db90fd1e

https://github.com/threestudio-project/threestudio/assets/19284678/ffcbbb01-3817-4663-a2bf-5e21a076bc3d

由 threestudio 获取的结果（稳定扩散，256x256 阶段1，512x512 阶段2+3）

https://github.com/threestudio-project/threestudio/assets/19284678/cfab881e-18dc-45fc-8384-7476f835b36e

与论文中值得注意的差异：

• 丰富梦想者采用两阶段采样策略，包含 64 个粗糙样本和 32 个精细样本，而我们仅使用 512 个粗糙样本。
• 在第一阶段，我们仅在最初 5000 次迭代中渲染 64x64 图像。此后，由于空白空间已被有效修剪，渲染 512x512 图像不会消耗过多的 VRAM。
• 我们目前不支持多粒子功能。

# --------- Stage 1 (NeRF) --------- #
# object generation with 512x512 NeRF rendering, ~30GB VRAM
python launch.py --config configs/prolificdreamer.yaml --train --gpu 0 system.prompt_processor.prompt="a pineapple"
# if you don't have enough VRAM, try training with 64x64 NeRF rendering, ~15GB VRAM
python launch.py --config configs/prolificdreamer.yaml --train --gpu 0 system.prompt_processor.prompt="a pineapple" data.width=64 data.height=64 data.batch_size=1
# using the same model for pretrained and LoRA enables 64x64 training with <10GB VRAM
# but the quality is worse due to the use of an epsilon prediction model for LoRA training
python launch.py --config configs/prolificdreamer.yaml --train --gpu 0 system.prompt_processor.prompt="a pineapple" data.width=64 data.height=64 data.batch_size=1 system.guidance.pretrained_model_name_or_path_lora="stabilityai/stable-diffusion-2-1-base"
# Using patch-based renderer to reduce memory consume, 512x512 resolution, ~20GB VRAM
python launch.py --config configs/prolificdreamer-patch.yaml --train --gpu 0 system.prompt_processor.prompt="a pineapple"
# scene generation with 512x512 NeRF rendering, ~30GB VRAM
python launch.py --config configs/prolificdreamer-scene.yaml --train --gpu 0 system.prompt_processor.prompt="Inside of a smart home, realistic detailed photo, 4k"

# --------- Stage 2 (Geometry Refinement) --------- #
# refine geometry with 512x512 rasterization, Stable Diffusion SDS guidance
python launch.py --config configs/prolificdreamer-geometry.yaml --train --gpu 0 system.prompt_processor.prompt="a pineapple" system.geometry_convert_from=path/to/stage1/trial/dir/ckpts/last.ckpt

# --------- Stage 3 (Texturing) --------- #
# texturing with 512x512 rasterization, Stable Difusion VSD guidance
python launch.py --config configs/prolificdreamer-texture.yaml --train --gpu 0 system.prompt_processor.prompt="a pineapple" system.geometry_convert_from=path/to/stage2/trial/dir/ckpts/last.ckpt

HiFA

这是一个重实现版本，缺少了原论文中的一些改进（粗到细NeRF采样，核平滑）。若需原始结果，请参考 https://github.com/JunzheJosephZhu/HiFA

HiFA更像是一系列改进的组合，包括图像空间SDS、z-方差损失和噪声强度退火。它与大多数基于优化的方法兼容。因此，我们基于DreamFusion、ProlificDreamer和Magic123提供了三种变体。我们提供了一个统一的指导配置以及适用于DreamFusion和ProlificDreamer变体的SDS/VSD指导配置，两种配置都应达到相同的结果。此外，我们还使HiFA兼容ProlificDreamer场景。

由threestudio获得的Dreamfusion-HiFA结果（512x512）

https://github.com/threestudio-project/threestudio/assets/24391451/c0030c66-0691-4ec2-8b79-d933101864a0

由threestudio获得的ProlificDreamer-HiFA结果（512x512）

https://github.com/threestudio-project/threestudio/assets/24391451/ff5dc4d0-d7d7-4a73-964e-84b8c48e2907

由threestudio获得的Magic123-HiFA结果（512x512）

https://github.com/threestudio-project/threestudio/assets/24391451/eb6f2f74-9143-4e26-8429-e300ad2d2b80

示例运行命令

# ------ DreamFusion-HiFA ------- # (similar to original paper)
python launch.py --config configs/hifa.yaml --train --gpu 0 system.prompt_processor.prompt="a plate of delicious tacos"
python launch.py --config configs/experimental/unified-guidance/hifa.yaml --train --gpu 0 system.prompt_processor.prompt="a plate of delicious tacos"
# ------ ProlificDreamer-HiFA ------- #
python launch.py --config configs/prolificdreamer-hifa.yaml --train --gpu 0 system.prompt_processor.prompt="a plate of delicious tacos"
python launch.py --config configs/experimental/unified-guidance/prolificdreamer-hifa.yaml --train --gpu 0 system.prompt_processor.prompt="a plate of delicious tacos"
# ------ ProlificDreamer-scene-HiFA ------- #
python launch.py --config configs/prolificdreamer-scene-hifa.yaml --train --gpu 0 system.prompt_processor.prompt="A DSLR photo of a hamburger inside a restaurant"
# ------ Magic123-HiFA ------ #
python launch.py --config configs/magic123-hifa-coarse-sd.yaml --train --gpu 0 data.image_path=load/images/firekeeper_rgba.png system.prompt_processor.prompt="a toy figure of firekeeper from dark souls"
# We included a config for magic123's refine stage, but didn't really run it, since the coarse stage result already looks pretty decent.

技巧

• 如果生成的物体颜色过于饱和，请减小 lambda_sds_img（如果使用统一指导，则为 lambda_sd_img）。
• 如果生成的物体看起来有雾，请增加 lamda_z_variance。如果形状被破坏，请减小 lambda_z_variance。
• 如果生成的物体整体亮度较高，请增加 min_step_percent。
• 确保设置 sqrt_anneal 和 use_img_loss 都为 True。
• 查看 原始仓库! 结果更佳。
• 如果您使用 sqrt_anneal，请确保 system.guidance.trainer_max_steps 与 trainer.max_steps 相等，以使噪声强度退火正常工作

DreamFusion

由 threestudio（DeepFloyd IF，批量大小 8）获得的结果

https://user-images.githubusercontent.com/19284678/236694848-38ae4ea4-554b-4c9d-b4c7-fba5bee3acb3.mp4

与论文中的显著差异

• 我们使用开源的 T2I 模型（StableDiffusion、DeepFloyd IF），而论文中使用 Imagen。
• 我们为 DeepFloyd IF 使用 20 的指导尺度，而论文中对 Imagen 使用 100。
• 我们没有使用 sigmoid 来归一化反照率颜色，而是简单地将颜色从 [-1,1] 缩放到 [0,1]，我们发现这有助于收敛。
• 我们使用 HashGrid 编码并沿光线均匀采样点，而论文使用 Integrated Positional Encoding 和 MipNeRF360 的采样策略。
• 我们采用了 Magic3D 的相机设置和密度初始化策略，这与 DreamFusion 论文略有不同。
• 一些超参数有所不同，例如损失项的权重。

示例运行命令

# uses DeepFloyd IF, requires ~15GB VRAM to extract text embeddings and ~10GB VRAM in training
# here we adopt random background augmentation to improve geometry quality
python launch.py --config configs/dreamfusion-if.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger" system.background.random_aug=true
# uses StableDiffusion, requires ~6GB VRAM in training
python launch.py --config configs/dreamfusion-sd.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger"

技巧

• DeepFloyd IF的表现远超StableDiffusion。
• 验证显示，system.material.ambient_only_steps之前的固有颜色和之后的着色颜色。
• 如果您的场景充满了悬浮物/变得空旷，请尝试增加/减少system.loss.lambda_sparsity。
• 如果您的物体有雾/过度平滑，请尝试增加/减少system.loss.lambda_orient。
• 如果您发现模型错误地将背景视为对象的一部分，请通过设置system.background.random_aug=true以50%的概率将背景替换为随机颜色。
• DeepFloyd IF使用T5-XXL作为其文本编码器，即使在8位量化下也消耗约15GB VRAM。这目前是使用较少VRAM进行训练的瓶颈。如果有人知道如何使用较少的VRAM运行文本编码器，请提交一个issue。我们也在尝试将文本编码器推向Replicate以通过API提取文本嵌入，但遇到了一些网络连接问题。如果您愿意提供帮助，请联系bennyguo。

Magic3D

由threestudio（DeepFloyd IF，批量大小8；第一行：粗略，第二行：细化）获得的结果

https://user-images.githubusercontent.com/19284678/236694858-0ed6939e-cd7a-408f-a94b-406709ae90c0.mp4

与论文中的显著差异

• 我们在粗略阶段使用了开源的T2I模型（StableDiffusion，DeepFloyd IF），而论文中使用的是eDiff-I。
• 在粗略阶段，我们对DeepFloyd IF使用了20的指导尺度，而论文中对eDiff-I使用的是100。
• 在粗略阶段，我们使用了分析法线，而论文中使用的是预测法线。
• 在粗略阶段，我们使用了与DreamFusion相同的方向损失，而论文中没有。
• 论文中省略了许多内容，例如损失项的权重和DMTet网格分辨率，这些都可能有所不同。

示例运行命令

首先训练粗略阶段的NeRF：

# uses DeepFloyd IF, requires ~15GB VRAM to extract text embeddings and ~10GB VRAM in training
python launch.py --config configs/magic3d-coarse-if.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger"
# uses StableDiffusion, requires ~6GB VRAM in training
python launch.py --config configs/magic3d-coarse-sd.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger"

然后，将粗阶段（coarse stage）的NeRF转换为DMTet，并通过可微渲染（differentiable rasterization）进行训练：

# the refinement stage uses StableDiffusion, and requires ~5GB VRAM in training
python launch.py --config configs/magic3d-refine-sd.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger" system.geometry_convert_from=path/to/coarse/stage/trial/dir/ckpts/last.ckpt
# if you're unsatisfied with the surface extracted using the default threshold (25)
# you can specify a threshold value using `system.geometry_convert_override`
# decrease the value if the extracted surface is incomplete, increase if it is extruded
python launch.py --config configs/magic3d-refine-sd.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger" system.geometry_convert_from=path/to/coarse/stage/trial/dir/ckpts/last.ckpt system.geometry_convert_override.isosurface_threshold=10.

技巧

• 在粗处理阶段，DeepFloyd IF 的表现远远优于 StableDiffusion。
• Magic3D 采用神经网络预测表面法线，这可能与真实的几何法线不相符，降低了几何质量，因此我们改用解析法线。
• 如果您的场景充满了悬浮物/变得空洞，尝试增加或减少 system.loss.lambda_sparsity。
• 如果您的物体模糊不清/过度平滑，尝试增加或减少 system.loss.lambda_orient。
• 如果您发现模型错误地将背景当作物体的一部分，可以尝试通过设置 system.background.random_aug=true，以 0.5 的概率将背景替换为随机颜色。

分值雅可比链

由 threestudio（Stable Diffusion）获得的结果

https://user-images.githubusercontent.com/19284678/236694871-87a247c1-2d3d-4cbf-89df-450bfeac3aca.mp4

与论文中的显著差异：无。

示例运行命令

# train with sjc guidance in latent space
python launch.py --config configs/sjc.yaml --train --gpu 0 system.prompt_processor.prompt="A high quality photo of a delicious burger"
# train with sjc guidance in latent space, trump figure
python launch.py --config configs/sjc.yaml --train --gpu 0 system.prompt_processor.prompt="Trump figure" trainer.max_steps=30000 system.loss.lambda_emptiness="[15000,10000.0,200000.0,15001]" system.optimizer.params.background.lr=0.05 seed=42

技巧

• SJC 使用了子像素渲染技术，该技术解码 128x128 的潜在特征图以提升可视化质量。您可以通过设置 system.subpixel_rendering=false 来关闭此功能，以在验证/测试阶段节省显存。

Latent-NeRF

通过 threestudio（稳定扩散）获得的成果

https://user-images.githubusercontent.com/19284678/236694876-5a270347-6a41-4429-8909-44c90c554e06.mp4

论文中的显著差异：无。

目前我们仅实现了文本引导的 Latent-NeRF 和（文本、形状）引导的 Sketch-Shape 3D 生成。Latent-Paint 尚未实现。

示例运行命令

# train Latent-NeRF in Stable Diffusion latent space
python launch.py --config configs/latentnerf.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger"
# refine Latent-NeRF in RGB space
python launch.py --config configs/latentnerf-refine.yaml --train --gpu 0 system.prompt_processor.prompt="a delicious hamburger" system.weights=path/to/latent/stage/trial/dir/ckpts/last.ckpt

# train Sketch-Shape in Stable Diffusion latent space
python launch.py --config configs/sketchshape.yaml --train --gpu 0 system.guide_shape=load/shapes/teddy.obj system.prompt_processor.prompt="a teddy bear in a tuxedo"
# refine Sketch-Shape in RGB space
python launch.py --config configs/sketchshape-refine.yaml --train --gpu 0 system.guide_shape=load/shapes/teddy.obj system.prompt_processor.prompt="a teddy bear in a tuxedo" system.weights=path/to/latent/stage/trial/dir/ckpts/last.ckpt

Fantasia3D

由 threestudio（稳定扩散）得到的结果

由 threestudio（稳定扩散，网格初始化）得到的结果

与论文中的显著差异：

• 我们默认启用了切空间法线扰动功能，可以通过添加 system.material.use_bump=false 来关闭。

示例运行命令

# --------- Geometry --------- #
python launch.py --config configs/fantasia3d.yaml --train --gpu 0 system.prompt_processor.prompt="a DSLR photo of an ice cream sundae"
# Fantasia3D highly relies on the initialized SDF shape
# the default shape is a sphere with radius 0.5
# change the shape initialization to match your input prompt
python launch.py --config configs/fantasia3d.yaml --train --gpu 0 system.prompt_processor.prompt="The leaning tower of Pisa" system.geometry.shape_init=ellipsoid system.geometry.shape_init_params="[0.3,0.3,0.8]"
# or you can initialize from a mesh
# here shape_init_params is the scale of the shape
# also make sure to input the correct up and front axis (in +x, +y, +z, -x, -y, -z)
python launch.py --config configs/fantasia3d.yaml --train --gpu 0 system.prompt_processor.prompt="hulk" system.geometry.shape_init=mesh:load/shapes/human.obj system.geometry.shape_init_params=0.9 system.geometry.shape_init_mesh_up=+y system.geometry.shape_init_mesh_front=+z
# --------- Texture --------- #
# to train PBR texture continued from a geometry checkpoint:
python launch.py --config configs/fantasia3d-texture.yaml --train --gpu 0 system.prompt_processor.prompt="a DSLR photo of an ice cream sundae" system.geometry_convert_from=path/to/geometry/stage/trial/dir/ckpts/last.ckpt

技巧

• 如果您发现在训练初期形状容易发散，可以通过设置 system.guidance.guidance_scale=30. 使用较低的引导系数。

TextMesh

由 threestudio（DeepFloyd IF，批量大小为 4）获得的成果

https://github.com/threestudio-project/threestudio/assets/19284678/72217cdd-765a-475b-92d0-4ab62bf0f57a

与论文中的显著差异

• 大多数设置与 DreamFusion 模型相同。请参考 DreamFusion 模型的显著差异。
• 我们使用 NeuS 作为几何表示，而原论文使用 VolSDF。
• 我们采用了 Neuralangelo 中的技术在使用哈希网格时稳定法线计算。
• 我们目前仅实现了 TextMesh 的粗略阶段。

示例运行命令

# uses DeepFloyd IF, requires ~15GB VRAM
python launch.py --config configs/textmesh-if.yaml --train --gpu 0 system.prompt_processor.prompt="lib:cowboy_boots"

技巧

• TextMesh 采用基于表面的几何表示方法，因此在导出网格时无需手动调整等值面的阈值！

Control4D

这是使用 threestudio 的 Control4D 实验性实现！在论文被接受后，Control4D 将发布包括静态和动态编辑的完整代码。

通过 threestudio 获得的结果（512x512）

https://github.com/threestudio-project/threestudio/assets/24589363/97d9aadd-32c7-488f-9543-6951b285d588

我们目前不支持动态编辑。

使用这个 链接 下载 control4D 的数据样例。

示例运行命令

# --------- Control4D --------- #
# static editing with 128x128 NeRF + 512x512 GAN rendering, ~20GB VRAM
python launch.py --config configs/control4d-static.yaml --train --gpu 0 data.dataroot="YOUR_DATAROOT/twindom" system.prompt_processor.prompt="Elon Musk wearing red shirt, RAW photo, (high detailed skin:1.2), 8k uhd, dslr, soft lighting, high quality, film grain, Fujifilm XT3"

指导NeRF至NeRF

由threestudio获得的结果

https://github.com/threestudio-project/threestudio/assets/24589363/7aa43a2d-87d7-4ef5-94b6-f778ddb041b5

使用这个链接下载InstructNeRF2NeRF的数据样本。

示例运行命令

# --------- InstructNeRF2NeRF --------- #
# 3D editing with NeRF patch-based rendering, ~20GB VRAM
python launch.py --config configs/instructnerf2nerf.yaml --train --gpu 0 data.dataroot="YOUR_DATAROOT/face" data.camera_layout="front" data.camera_distance=1 data.eval_interpolation=[1,3,50] system.prompt_processor.prompt="Turn him into Albert Einstein"

Magic123

由threestudio（Zero123 + Stable Diffusion）获得的成果

https://github.com/threestudio-project/threestudio/assets/19284678/335a58a8-8fee-485b-ac27-c55a16f4a673

与论文中的显著差异

• 这是一个非官方的重新实现版本，与官方实现在整体思路上相同，但在某些方面（如超参数）有所不同。
• 不支持文本反转，这意味着训练时需要一个文本提示。

示例运行命令

首先训练粗略阶段的NeRF：

# Zero123 + Stable Diffusion, ~12GB VRAM
# data.image_path must point to a 4-channel RGBA image
# system.prompt_proessor.prompt must be specified
python launch.py --config configs/magic123-coarse-sd.yaml --train --gpu 0 data.image_path=load/images/hamburger_rgba.png system.prompt_processor.prompt="a delicious hamburger"

然后将 NeRF 从粗略阶段转换为 DMTet，并使用可微光栅化进行训练：

# Zero123 + Stable Diffusion, ~10GB VRAM
# data.image_path must point to a 4-channel RGBA image
# system.prompt_proessor.prompt must be specified
python launch.py --config configs/magic123-refine-sd.yaml --train --gpu 0 data.image_path=load/images/hamburger_rgba.png system.prompt_processor.prompt="a delicious hamburger" system.geometry_convert_from=path/to/coarse/stage/trial/dir/ckpts/last.ckpt
# if you're unsatisfied with the surface extracted using the default threshold (25)
# you can specify a threshold value using `system.geometry_convert_override`
# decrease the value if the extracted surface is incomplete, increase if it is extruded
python launch.py --config configs/magic123-refine-sd.yaml --train --gpu 0 data.image_path=load/images/hamburger_rgba.png system.prompt_processor.prompt="a delicious hamburger" system.geometry_convert_from=path/to/coarse/stage/trial/dir/ckpts/last.ckpt system.geometry_convert_override.isosurface_threshold=10.

技巧

• 如果图像中包含非正对物体，通过设置 data.default_elevation_deg 和 data.default_azimuth_deg 来指定大致的高度角和方位角可能会有所帮助。在 threestudio 中，顶部是高度 +90，底部是高度 -90；左侧是方位 -90，右侧是方位 +90。

Stable Zero123

安装

从 https://huggingface.co/stabilityai/stable-zero123 下载预训练的 Stable Zero123 检查点 stable-zero123.ckpt 到 load/zero123 目录。

threestudio 获得的结果（Stable Zero123 与 Zero123-XL 对比）

直接生成多视角图像 如果您只想生成多视角图像，请参考 threestudio-mvimg-gen。这个扩展可以使用 Stable Zero123 直接从多视角生成图像。

示例运行命令

1. 选择一张您喜欢的图像，或者使用您偏好的 AI 图像生成器（如 SDXL Turbo，https://clipdrop.co/stable-diffusion-turbo）从文本生成图像。例如：“一个友好的狗的简单 3D 渲染”
2. 使用 Clipdrop（https://clipdrop.co/remove-background）去除其背景
3. 保存到 load/images/ 目录中，最好使用 _rgba.png 作为后缀
4. 使用 Stable Zero123 检查点运行 Zero-1-to-3：

python launch.py --config configs/stable-zero123.yaml --train --gpu 0 data.image_path=./load/images/hamburger_rgba.png

重要提示：这是一个实验性实现，我们正在不断改进其质量。

重要提示：此实现扩展了下面的Zero-1-to-3实现，并深受https://github.com/ashawkey/stable-dreamfusion中Zero-1-to-3实现的启发！extern/ldm_zero123是从stable-dreamfusion/ldm借用的。

Zero-1-to-3

安装

将预训练的Zero123XL权重下载到load/zero123中：

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

由 threestudio 获取的成果（Zero-1-to-3）

https://github.com/threestudio-project/threestudio/assets/22424247/f4e7b66f-7a46-4f9f-8fcd-750300cef651

重要提示：这是一个实验性实现，我们正在不断优化其质量。

重要提示：此实现深受 https://github.com/ashawkey/stable-dreamfusion 中 Zero-1-to-3 实现的启发！extern/ldm_zero123 由 stable-dreamfusion/ldm 提供。

示例运行命令

1. 选择一张您喜欢的图片，或者使用您偏好的 AI 图片生成器，如 Stable Diffusion XL（https://clipdrop.co/stable-diffusion）从文本生成图片。例如：“一个友好狗狗的简单 3D 渲染”
2. 使用 Clipdrop（https://clipdrop.co/remove-background）去除图片背景
3. 将图片保存至 load/images/ 目录，最好以 _rgba.png 作为后缀
4. 运行 Zero-1-to-3：

python launch.py --config configs/zero123.yaml --train --gpu 0 data.image_path=./load/images/dog1_rgba.png

若需更多 Zero-1-to-3 脚本，请查阅 threestudio/scripts/run_zero123.sh。

之前 Zero-1-to-3 的权重可在 https://huggingface.co/cvlab/zero123-weights/ 找到。您可以将它们下载到 load/zero123 目录下，如上所述，并将路径替换为 system.guidance.pretrained_model_name_or_path。

指导评估

训练过程中还包括对指导的评估。如果 system.freq.guidance_eval 设置为大于 0 的值，则会保存渲染图像、噪声图像（左上角添加的噪声）、一步去噪图像、原始图像的一步预测、完全去噪图像。例如：

更多内容即将上线，敬请期待。

• Dream3D
• DreamAvatar

若您希望为 threestudio 贡献新的方法，请参阅这里。

提示库

为了便于比较，我们从 DreamFusion 网站收集了 397 个预设提示，并在 这个文件 中提供。您可以通过设置 system.prompt_processor.prompt=lib:keyword1_keyword2_..._keywordN 使用这些提示。请注意，提示应以 lib: 开头，且所有关键词应以 _ 分隔。提示处理器将匹配库中的所有提示，且只有在 完全匹配 时才会成功。使用的提示将被打印到控制台。请注意，您无法使用这种语法指向库中的每个提示，因为有些提示是其他提示的子集 lmao。我们将增强此功能的使用。

提高质量的建议

需要注意的是，现有技术将 2D T2I 模型提升到 3D 不能一致地产生满意的结果。来自 DreamFusion 和 Magic3D 等优秀论文的结果（在某种程度上）是精心挑选的，因此如果您在第一次尝试中没有得到预期的结果，请不要气馁。以下是一些建议，可能有助于您提高生成质量：

• 增加批量大小。大批量大小有助于收敛并提高几何体的 3D 一致性。最先进的方法声称使用大批量大小：DreamFusion 使用批量大小为 4；Magic3D 使用批量大小为 32；Fantasia3D 使用批量大小为 24；上述某些结果使用批量大小为 8。您可以通过设置 data.batch_size=N 轻松更改批量大小。增加批量大小需要更多的 VRAM。如果您 VRAM 有限但仍想获得大批量大小的优势，可以通过设置 trainer.accumulate_grad_batches=N 使用 PyTorch Lightning 提供的 梯度累积。这将累积几个批次的梯度，实现大的有效批量大小。请注意，如果您使用梯度累积，您可能需要将配置中的所有步数乘以 N 倍，例如名为 X_steps 和 trainer.val_check_interval 的值，因为现在 N 个批次等于一个大批量。

• 训练更长时间。如果您已经能够获得合理的结果并希望增强细节，这会有所帮助。如果经过几千步后结果仍然很乱，那么通常训练更长时间也不会有帮助。您可以通过 trainer.max_steps=N 设置总的训练迭代次数。

• 尝试不同的种子。如果您的结果具有正确的总体几何形状但受到多面 Janus 问题的困扰，这是一个简单的解决方案。您可以通过设置 seed=N 更改种子。祝您好运！

• 调整正则化权重。某些方法具有正则项，对于获得良好的几何形状至关重要。尝试通过设置 system.loss.lambda_X=value 调整这些正则化的权重。具体值取决于您的具体情况，您可以参考 每种支持模型的建议 以获得更详细的说明。

• 尝试去偏方法。当传统的 SDS 技术如 DreamFusion、Magic3D、SJC 等无法产生所需的 3D 结果时，去偏得分蒸馏采样（D-SDS）可以是一个解决方案。D-SDS 被设计用来解决诸如伪影或 Janus 问题等挑战，采用两种策略：得分去偏和提示去偏。您只需设置 system.guidance.grad_clip=[0,0.5,2.0,10000] 即可激活得分去偏，其中顺序为 start_step, start_value, end_value, end_step。您可以通过设置 system.prompt_processor.use_prompt_debiasing=true 启用提示去偏。使用提示去偏时，建议通过 system.prompt_processor.prompt_debiasing_mask_ids=[i1,i2,...] 设置要潜在删除的词的索引列表。例如，如果提示是 一个微笑的狗，而您只想为某些视角删除单词 微笑，则应将其设置为 [1]。您还可以通过设置 system.prompt_processor.prompt_side、system.prompt_processor.prompt_back 和 system.prompt_processor.prompt_overhead 手动指定每个视角的提示。有关这些技术的详细说明，请参阅 D-SDS 论文 或查看 项目页面。

• 尝试 Perp-Neg。Perp-Neg 算法 可能有助于减轻多面 Janus 问题。我们现在支持 stable-diffusion-guidance 和 deep-floyd-guidance 的 Perp-Neg，通过设置 system.prompt_processor.use_perp_neg=true。

VRAM 优化

如果您遇到 CUDA OOM 错误，请按以下顺序（大致按推荐顺序）尝试以满足您的 VRAM 要求。

• 如果您只在验证/测试时遇到 OOM，可以设置 system.cleanup_after_validation_step=true 和 system.cleanup_after_test_step=true 来在每个验证/测试步骤后释放内存。这将减慢验证/测试速度。
• 使用较小的批量大小或使用此处演示的 梯度累积。
• 如果您使用的是 PyTorch1.x，请通过设置 system.guidance.enable_memory_efficient_attention=true 启用 内存高效注意力。PyTorch2.0 已内置对此优化的支持，默认启用。
• 通过设置 system.guidance.enable_attention_slicing=true 启用 注意力切片。这将使训练速度减慢约 20%。
• 如果您使用的是 StableDiffusionGuidance，可以使用 Token Merging 来 显著 加速计算和节省内存。您可以通过设置 system.guidance.token_merging=true 轻松启用 Token Merging。您还可以通过设置 这里的参数 到 system.guidance.token_merging_params 来自定义 Token Merging 的行为。请注意，Token Merging 可能会降低生成质量。
• 通过设置 system.guidance.enable_sequential_cpu_offload=true 启用 顺序 CPU 卸载。这可能会节省大量 VRAM，但会使训练变得 极其缓慢。

文档

threestudio 使用 OmegaConf 来管理配置。您实际上可以更改 yaml 配置文件中的任何内容，或者通过添加不带 -- 的命令行参数来更改。我们列出了所有可以在配置中更改的参数，具体请查看我们的 文档。祝您实验愉快！

wandb（权重与偏差）日志记录

要启用（实验性）的 wandb 支持，请设置 system.loggers.wandb.enable=true，例如：

python launch.py --config configs/zero123.yaml --train --gpu 0 system.loggers.wandb.enable=true`

如果您正在使用企业级的 wandb 服务器，可能首先需要登录到您的 wandb 实例，例如： wandb login --host=https://COMPANY_XYZ.wandb.io --relogin

默认情况下，运行将具有一个随机名称，并记录在 threestudio 项目中。您可以覆盖它们以提供一个更具描述性的名称，例如：

python launch.py --config configs/zero123.yaml --train --gpu 0 system.loggers.wandb.enable=true system.loggers.wandb.name="zero123xl_accum;bs=4;lr=0.05"

贡献至 threestudio

• 从 main 分支派生仓库并创建您的分支。
• 安装开发依赖项：

pip install -r requirements-dev.txt

如果您正在使用 VSCode 作为文本编辑器：
(1) 安装 editorconfig 扩展。
(2) 将默认的代码检查器设置为 mypy 以启用静态类型检查。
(3) 将默认的格式化工具设置为 black。您可以手动格式化文档，或者通过设置 "editor.formatOnSave": true 让编辑器在每次保存时自动格式化文档。

• 执行 pre-commit install 来安装 pre-commit 钩子，这将自动在提交前格式化文件。

• 对代码进行修改，如有需要，更新 README 和文档，并创建一个 pull request。

代码结构

在这里，我们简要地介绍这个项目的代码结构。我们将在未来提供更详细的文档。

• 所有方法都是 BaseSystem（在 systems/base.py 中）的子类。一个系统中通常包含六个模块：几何、材料、背景、渲染器、引导和提示处理器。除了引导和提示处理器外，所有模块都是 BaseModule（在 utils/base.py 中）的子类，引导和提示处理器是 BaseObject 的子类，以防止它们被当作模型参数处理，并在多 GPU 环境中更好地控制它们的行为。
• 所有系统、模块和数据模块都有自己的配置数据类。
• 整个项目的基本配置可以在 utils/config.py 中找到。在 ExperimentConfig 数据类中，data、system 以及 system 下的模块配置被解析为上述每个类的配置。这些配置是严格类型的，这意味着您只能使用数据类中定义的属性，并且必须遵循每个属性定义的类型。这种配置范例 (1) 自然支持属性的默认值；(2) 有效地防止了这些属性的错误赋值（例如 yaml 文件中的拼写错误）或在运行时的不当使用。
• 这个项目同时使用了静态和运行时的类型检查。更多细节请见 utils/typing.py。
• 若要在每个训练步骤中更新模块的任何内容，简单地让它继承 Updateable 即可（见 utils/base.py）。在每个迭代的开始，Updateable 会更新自身，并更新所有也是 Updateable 的属性。请注意，BaseSystem、BaseModule 和 BaseObject 的子类默认继承了 Updateable。

已知问题

• 在 AMP 中，Vanilla MLP 参数的梯度为空（暂时通过禁用自动挡修复）。
• 在 32 位精度下，FullyFused MLP 可能会导致 NaN。

致谢

threestudio 是基于以下开源项目构建的：

• Lightning 创建高度组织化的 PyTorch 代码的框架。
• OmegaConf 灵活的 Python 配置系统。
• NerfAcc 即插即用的 NeRF 加速。

以下仓库对 threestudio 产生了巨大影响：

• Stable-DreamFusion
• Latent-NeRF
• Score Jacobian Chaining
• Fantasia3D.unofficial

感谢这些项目的维护者为社区做出的贡献！

引用 threestudio

如果您发现 threestudio 有帮助，请考虑引用：

@Misc{threestudio2023,
  author =       {Yuan-Chen Guo and Ying-Tian Liu and Ruizhi Shao and Christian Laforte and Vikram Voleti and Guan Luo and Chia-Hao Chen and Zi-Xin Zou and Chen Wang and Yan-Pei Cao and Song-Hai Zhang},
  title =        {threestudio: A unified framework for 3D content generation},
  howpublished = {\url{https://github.com/threestudio-project/threestudio}},
  year =         {2023}
}

当然，我会根据您的要求进行翻译。请您提供需要翻译的英文文本和Markdown格式，我将为您翻译成中文。