即时神经图形基元

你是否曾想在5秒内训练一个狐狸的NeRF模型？或者在工厂机器人的照片捕捉的场景中飞行？当然你想过！

在这里你会找到四种__神经图形基元__的实现，包括神经辐射场(NeRF)、有符号距离函数(SDFs)、神经图像和神经体积。在每种情况下，我们使用tiny-cuda-nn框架训练并渲染一个具有多分辨率哈希输入编码的MLP。

使用多分辨率哈希编码的即时神经图形基元
Thomas Müller, Alex Evans, Christoph Schied, Alexander Keller
ACM图形学汇刊 (SIGGRAPH), 2022年7月
项目页面 / 论文 / 视频 / 演示 / 实时直播 / BibTeX

如有商业咨询，请提交NVIDIA研究许可表格。

安装

如果你使用Windows，请下载以下对应你显卡的发布版本之一并解压。然后，启动instant-ngp.exe。

继续阅读以获得应用程序的指导性介绍，或者，如果你对创建自己的NeRF感兴趣，请观看视频教程或阅读书面说明。

如果你使用Linux，或需要开发者Python绑定，或者如果你的GPU不在上面列出（例如Hopper、Volta或Maxwell世代），你需要自己构建__instant-ngp__。

使用

__instant-ngp__带有一个交互式GUI，包含许多功能：

全面的控制用于交互式探索神经图形基元，
VR模式通过虚拟现实头戴设备查看神经图形基元，
保存和加载"快照"，以便你可以在互联网上分享你的图形基元，
用于创建视频的相机路径编辑器，
NeRF->Mesh和SDF->Mesh转换，
相机姿态和镜头优化，
以及更多功能。

NeRF狐狸

只需启动instant-ngp并将data/nerf/fox文件夹拖入窗口。或者，使用命令行：

instant-ngp$ ./instant-ngp data/nerf/fox

你可以使用__任何__与NeRF兼容的数据集，例如来自原始NeRF、SILVR数据集或DroneDeploy数据集。要创建你自己的NeRF，请观看视频教程或阅读书面说明。

SDF犰狳

将data/sdf/armadillo.obj拖入窗口或使用以下命令：

instant-ngp$ ./instant-ngp data/sdf/armadillo.obj

爱因斯坦图像

将data/image/albert.exr拖入窗口或使用以下命令：

instant-ngp$ ./instant-ngp data/image/albert.exr

要重现千兆像素的结果,请下载例如东京图像,并使用scripts/convert_image.py脚本将其转换为.bin格式。这种自定义格式可以在分辨率较高时提高兼容性和加载速度。现在你可以运行:

instant-ngp$ ./instant-ngp data/image/tokyo.bin

体积渲染器

下载迪士尼云的nanovdb体积,它源自这里(CC BY-SA 3.0)。然后将wdas_cloud_quarter.nvdb拖入窗口或使用以下命令:

instant-ngp$ ./instant-ngp wdas_cloud_quarter.nvdb

键盘快捷键和推荐控制

以下是__instant-ngp__应用程序的主要键盘控制。

按键	含义
WASD	前进/向左平移/后退/向右平移
空格键 / C	上升/下降
= 或 + / - 或 _	增加/减少相机速度(第一人称模式)或放大/缩小(第三人称模式)
E / Shift+E	增加/减少曝光
Tab	切换菜单可见性
T	切换训练。大约两分钟后训练往往会稳定下来,因此可以关闭
{ }	转到第一个/最后一个训练图像相机视图
[ ]	转到上一个/下一个训练图像相机视图
R	从文件重新加载网络
Shift+R	重置相机
O	切换累积误差图的可视化
G	切换地面真实情况的可视化
M	切换神经模型层的多视图可视化。视频中有更多解释
, / .	显示上一个/下一个可视化层;按M退出
1-8	在各种渲染模式之间切换,2是标准模式。你可以在控制界面中看到渲染模式名称列表

instant-ngp GUI中有许多控件。首先,请注意该GUI可以移动和调整大小,同样"相机路径"GUI(必须先展开才能使用)也可以。

__instant-ngp__中推荐的用户控制有:

快照: 使用"保存"来保存训练好的NeRF,"加载"来重新加载。
渲染 -> DLSS: 打开此选项并将"DLSS锐化"设置为1.0通常可以提高渲染质量。
渲染 -> 裁剪大小: 裁剪周围环境以聚焦模型。"裁剪aabb"允许你移动兴趣体积的中心并进行微调。在我们的NeRF训练和数据集提示中查看有关此功能的更多信息。

"相机路径"GUI允许你创建用于渲染视频的相机路径。 "从相机添加"按钮可以从当前视角插入关键帧。然后,你可以渲染相机路径的.mp4视频或将关键帧导出到.json文件。这篇文章和这个创建自己视频的视频指南中有更多关于GUI的信息。

VR控制

要在VR中查看神经图形原语,首先启动你的VR运行时。这很可能是

如果你有Oculus Rift或Meta Quest(带链接线)头戴设备,则为__OculusVR__,
如果你有其他头戴设备,则为__SteamVR__。
任何兼容OpenXR的运行时都可以工作。

然后,在__instant-ngp__ GUI中按下__连接到VR/AR头戴设备__按钮,并戴上头戴设备。在进入VR之前,我们强烈建议你先完成训练(按"停止训练")或加载预训练的快照以获得最佳性能。

在VR中,你有以下控制。

控制	含义
左摇杆/触控板	移动
右摇杆/触控板	转动相机
按下摇杆/触控板	擦除手部周围的NeRF
抓取(单手)	拖动神经图形原语
抓取(双手)	旋转和缩放(像智能手机上的捏合缩放)

构建instant-ngp(Windows和Linux)

要求

一个__NVIDIA GPU__;可用的张量核心可以提高性能。所有显示的结果都来自RTX 3090。
支持__C++14__的编译器。推荐并已测试以下选择:
- Windows: Visual Studio 2019或2022
- Linux: GCC/G++ 8或更高版本
__CUDA__的最新版本。推荐并已测试以下选择:
- Windows: CUDA 11.5或更高版本
- Linux: CUDA 10.2或更高版本
CMake v3.21或更高版本。
__(可选)Python 3.7或更高版本__用于交互式绑定。另外,运行pip install -r requirements.txt。
__(可选)OptiX 7.6或更高版本__用于更快的网格SDF训练。
__(可选)Vulkan SDK__用于DLSS支持。如果您使用基于Debian的Linux发行版，请安装以下软件包：

sudo apt-get install build-essential git python3-dev python3-pip libopenexr-dev libxi-dev \
                     libglfw3-dev libglew-dev libomp-dev libxinerama-dev libxcursor-dev

或者，如果您使用Arch或Arch衍生版，请安装以下软件包：

sudo pacman -S cuda base-devel cmake openexr libxi glfw openmp libxinerama libxcursor

我们还建议在 /usr/local/ 目录下安装 CUDA 和 OptiX，并将CUDA安装路径添加到您的PATH中。

例如，如果您安装了CUDA 11.4，请将以下内容添加到您的 ~/.bashrc 文件中：

export PATH="/usr/local/cuda-11.4/bin:$PATH"
export LD_LIBRARY_PATH="/usr/local/cuda-11.4/lib64:$LD_LIBRARY_PATH"

编译

首先，使用以下命令克隆此仓库及其所有子模块：

$ git clone --recursive https://github.com/nvlabs/instant-ngp
$ cd instant-ngp

然后，使用CMake构建项目：（在Windows上，必须在开发者命令提示符中执行）

instant-ngp$ cmake . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
instant-ngp$ cmake --build build --config RelWithDebInfo -j

如果编译莫名其妙地失败或耗时超过一小时，可能是因为内存不足。在这种情况下，请尝试不使用 -j 参数运行上述命令。如果这仍然无法解决问题，请在提出issue之前查阅这份可能的解决方案列表。

如果构建成功，您现在可以通过 ./instant-ngp 可执行文件或下面描述的 scripts/run.py 脚本运行代码。

如果自动GPU架构检测失败（例如在安装了多个GPU的情况下），请为您想使用的GPU设置 TCNN_CUDA_ARCHITECTURES 环境变量。下表列出了常见GPU的值。如果您的GPU未列出，请查阅这份详尽列表。

H100	40X0	30X0	A100	20X0	TITAN V / V100	10X0 / TITAN Xp	9X0	K80
90	89	86	80	75	70	61	52	37

Python绑定

构建 instant-ngp 后，您可以使用其Python绑定以自动化方式进行受控实验。交互式GUI的所有功能（甚至更多！）都有Python绑定，可以轻松地进行操作。有关如何从Python内部实现和扩展 ./instant-ngp 应用程序的示例，请参见 ./scripts/run.py，它支持 ./instant-ngp 的命令行参数的超集。

如果您更愿意从哈希编码和快速神经网络构建新模型，请考虑使用 tiny-cuda-nn 的PyTorch扩展。

祝您编码愉快！

其他资源

常见问题解答（FAQ）

问：我的自定义数据集的NeRF重建效果不佳；我该怎么办？

答：可能存在多个问题：

COLMAP可能无法重建相机姿态。
捕获过程中可能出现移动或模糊。不要将捕获视为艺术任务；将其视为摄影测量。您希望数据集中的模糊程度 *尽可能小*（包括运动、散焦或其他原因），并且所有物体在整个捕获过程中必须 *保持静止*。如果您使用广角镜头（iPhone广角镜头效果很好），那就更好了，因为它比窄角镜头覆盖更多空间。
数据集参数（特别是 aabb_scale）可能未得到最佳调整。我们建议从 aabb_scale=128 开始，然后以2的倍数增加或减少，直到获得最佳质量。
仔细阅读我们的NeRF训练和数据集提示。

问：如何保存训练好的模型并在以后再次加载？

答：有两种选择：

使用GUI的"快照"部分。
使用Python绑定的 load_snapshot / save_snapshot（参见 scripts/run.py 中的示例用法）。

问：这个代码库可以同时使用多个GPU吗？

答：只有在VR渲染时可以，每只眼睛使用一个GPU。否则，不可以。要选择特定的GPU运行，请使用 CUDA_VISIBLE_DEVICES 环境变量。要针对特定GPU优化编译，请使用 TCNN_CUDA_ARCHITECTURES 环境变量。

问：如何在无头模式下运行 instant-ngp？

答：使用 ./instant-ngp --no-gui 或 python scripts/run.py。您也可以通过 cmake -DNGP_BUILD_WITH_GUI=off ... 编译不带GUI的版本。

问：这个代码库可以在 Google Colab 上运行吗？

答：可以。请参见这个示例，它受到用户 @myagues 创建的笔记本的启发。注意：这个代码库需要大量的GPU内存，可能无法在您分配的GPU上运行。它在较旧的GPU上运行也会较慢。

问：有Docker容器吗？

答：是的。我们提供了一个Visual Studio Code开发容器，其中的.devcontainer/Dockerfile也可以单独使用。

如果你想在不使用VSCode的情况下运行容器：

docker-compose -f .devcontainer/docker-compose.yml build instant-ngp
xhost local:root
docker-compose -f .devcontainer/docker-compose.yml run instant-ngp /bin/bash

然后像平常一样运行构建命令。

问：如何编辑和训练底层的哈希编码或神经网络用于新任务？

答：使用__tiny-cuda-nn__的PyTorch扩展。

问：坐标系统的约定是什么？

答：请参看用户@jc211提供的这个有帮助的图表。

问：为什么在NeRF训练期间背景颜色是随机的？

答：训练数据中的透明度表示希望学习到的模型具有透明度。使用固定的背景颜色时，模型可以通过简单地预测该背景颜色而非透明度（零密度）来最小化损失。通过随机化背景颜色，模型被迫学习零密度以让随机颜色"透过"。

问：如何在NeRF训练中屏蔽像素（例如用于动态对象移除）？

答：对于任何包含动态对象的训练图像xyz.*，你可以在同一文件夹中提供一个dynamic_mask_xyz.png。这个文件必须是PNG格式，其中非零像素值表示被屏蔽的区域。

编译错误故障排除

在进一步调查之前，请确保所有子模块都是最新的，然后再次尝试编译。

instant-ngp$ git submodule sync --recursive
instant-ngp$ git submodule update --init --recursive

如果__instant-ngp__仍然无法编译，请将CUDA和编译器更新到系统可安装的最新版本。更新两者都很重要，因为较新的CUDA版本并不总是与早期编译器兼容，反之亦然。如果问题仍然存在，请参考以下已知问题表。

*每次操作后，删除build文件夹并让CMake重新生成它，然后再次尝试。*

问题	解决方案
CMake错误：未找到CUDA工具集 / 目标"cmTC_0c70f"的CUDA_ARCHITECTURES为空	Windows： Visual Studio的CUDA集成未正确安装。按照这些说明修复问题，无需重新安装CUDA。(#18)
	Linux： CUDA安装的环境变量可能设置不正确。你可以使用`cmake . -B build -DCMAKE_CUDA_COMPILER=/usr/local/cuda-<你的cuda版本>/bin/nvcc`来解决这个问题 (#28)
CMake错误： CXX编译器"MSVC"没有已知特性	重新安装Visual Studio并确保从开发者shell运行CMake。确保在再次构建前删除build文件夹。(#21)
编译错误：指定输出文件时非链接阶段需要单个输入文件	确保__instant-ngp__的路径中没有空格。某些构建系统似乎对此有问题。(#39 #198)
编译错误： "cudaGraphExecUpdate"的未定义引用 / 标识符"cublasSetWorkspace"未定义	将CUDA安装更新（可能是11.0）到11.3或更高版本。(#34 #41 #42)
编译错误：函数调用的参数太少	使用上述两个`git`命令更新子模块。(#37 #52)
Python错误：没有名为'pyngp'的模块	CMake可能没有检测到你的Python安装，因此没有构建`pyngp`。检查CMake日志以验证这一点。如果`pyngp`构建在`build`以外的文件夹中，Python将无法检测到它，你需要在导入语句中提供完整路径。(#43)

如果你在表格中找不到你的问题，请尝试搜索讨论板和问题区寻求帮助。如果你仍然遇到困难，请提出一个issue并寻求帮助。

致谢

非常感谢Jonathan Tremblay和Andrew Tao测试此代码库的早期版本，以及Arman Toorians和Saurabh Jain提供工厂机器人数据集。我们还要感谢Andrew Webb注意到空间哈希中的一个素数实际上不是素数；这个问题已经修复。本项目使用了多个优秀的开源库，包括：

tiny-cuda-nn 用于快速CUDA网络和输入编码
tinyexr 用于EXR格式支持
tinyobjloader 用于OBJ格式支持
stb_image 用于PNG和JPEG支持
Dear ImGui 一个出色的即时模式GUI库
Eigen 一个用于线性代数的C++模板库
pybind11 用于无缝C++ / Python互操作
以及其他！请参阅dependencies文件夹。

非常感谢这些出色项目的作者们！

许可证和引用

@article{mueller2022instant,
    author = {Thomas M\"uller and Alex Evans and Christoph Schied and Alexander Keller},
    title = {Instant Neural Graphics Primitives with a Multiresolution Hash Encoding},
    journal = {ACM Trans. Graph.},
    issue_date = {July 2022},
    volume = {41},
    number = {4},
    month = jul,
    year = {2022},
    pages = {102:1--102:15},
    articleno = {102},
    numpages = {15},
    url = {https://doi.org/10.1145/3528223.3530127},
    doi = {10.1145/3528223.3530127},
    publisher = {ACM},
    address = {New York, NY, USA},
}