ngp_pl

广告：快来了解一下最新的集成项目 nerfstudio 吧！最近在 NeRF 相关方法上有很多改进，其中就包括 Instant-NGP！

Instant-NGP（仅适用于 NeRF）基于 PyTorch 和 CUDA，并使用 PyTorch Lightning 进行训练（高质量且速度快）。本仓库旨在提供一个简洁的 PyTorch 接口，以促进未来的研究。如果你能分享这个项目，我将不胜感激；同时，也欢迎引用！

• 官方 CUDA 实现
• torch-ngp，另一个我高度参考的 PyTorch 实现。

:paintbrush: 作品集

https://user-images.githubusercontent.com/11364490/181671484-d5e154c8-6cea-4d52-94b5-1e5dd92955f2.mp4

其他代表性视频请参阅 GALLERY.md。

:computer: 安装

由于依赖于其他库，本实现对环境有 严格 的要求。如果因硬件或软件不兼容导致安装问题，很抱歉我们 无意 支持不同的平台（欢迎贡献）。

硬件

• 操作系统：Ubuntu 20.04
• NVIDIA GPU，计算能力 ≥ 75，显存 > 6GB（已测试 RTX 2080 Ti），CUDA 11.3（较旧版本也可能适用）
• 32GB 内存（以便加载全尺寸图像）

软件

• 克隆本仓库：git clone https://github.com/kwea123/ngp_pl

• Python≥3.8（推荐使用 Anaconda 安装，可执行 conda create -n ngp_pl python=3.8 创建 Conda 环境，并用 conda activate ngp_pl 激活）

• Python 库

  • 使用 pip install torch==1.11.0 --extra-index-url https://download.pytorch.org/whl/cu113 安装 PyTorch
  • 按照 torch-scatter 的说明安装 torch-scatter
  • 按照 tiny-cuda-nn 的说明安装 tinycudann（PyTorch 扩展）
  • 按照 NVIDIA Apex 的说明安装 apex
  • 使用 pip install -r requirements.txt 安装核心依赖项

• CUDA 扩展：将 pip 升级到 ≥ 22.1，并运行 pip install models/csrc/（每次拉取代码后请重新运行此命令）

:books: 支持的数据集

1. NSVF 数据

从 NSVF 下载预处理好的数据集（Synthetic_NeRF、Synthetic_NSVF、BlendedMVS、TanksAndTemples）。请勿更改文件夹名称，因为我的数据加载器中有一些硬编码的修复。

2. NeRF++ 数据

从 这里 下载数据。

3. Colmap 数据

对于自定义数据，运行 Colmap 并生成 sparse/0 文件夹，其中包含 cameras.bin、images.bin 和 points3D.bin。以下具有 Colmap 格式的数据也被支持：

• nerf_llff_data
• mipnerf360 数据
• HDR-NeRF 数据。此外，请从 这里 下载我的 Colmap 姿态估计文件，并解压到相同位置。

4. RTMV 数据

从 这里 下载数据。为了将 HDR 图像转换为 LDR 图像用于训练，运行 python misc/prepare_rtmv.py <path/to/RTMV>，它会在每个场景文件夹下创建 images/ 文件夹，并使用这些图像进行训练（以及测试）。

:key: 训练

快速入门：python train.py --root_dir <path/to/lego> --exp_name Lego

这将对乐高场景进行 30,000 步训练（每步 8,192 条光线），并在最后进行一次测试。整个训练过程大约需要 5 分钟完成（保存测试图像较慢，可添加 --no_save_test 来禁用）。最后会显示测试 PSNR。

更多选项请参阅 opt.py。

对于其他公开数据集的训练，请参考 benchmarking 目录下的脚本。

:mag_right: 测试

使用 test.ipynb 生成图像。乐高预训练模型可在 这里 获取。

GUI 使用方法：运行 python show_gui.py，并输入与训练时 完全相同 的超参数（dataset_name、root_dir 等），然后通过 --ckpt_path <path/to/.ckpt> 添加检查点路径。

与 torch-ngp 及论文的对比

我将质量（在 Synthetic-NeRF 上的平均测试 PSNR）和推理速度（在 Lego 场景上）与同期工作 torch-ngp（默认设置）以及论文中的方法进行了比较，所有实验均训练约 5 分钟：

方法	平均 PSNR	FPS	GPU
torch-ngp	31.46	18.2	2080 Ti
我的方法	32.96	36.2	2080 Ti
instant-ngp 论文	33.18	60	3090

在质量方面，我的方法略优于 torch-ngp，但结果可能会因不同运行而有所波动。

在速度方面，我的方法比 torch-ngp 快，但仍仅为 instant-ngp 的一半。速度取决于场景（如果场景大部分为空，则速度会更快）。

^{左：torch-ngp。右：我的方法。}

：图表：基准测试

要运行基准测试，请使用 benchmarking 目录下的脚本。

以下是我使用 1 张 RTX 2080 Ti 显卡训练得到的结果（定性结果见 这里）：

合成-NeRF

	微型场景	榕树	椅子	热狗	材质	鼓	船	乐高	平均
PSNR	35.59	34.13	35.28	37.35	29.46	25.81	30.32	35.76	32.96
SSIM	0.988	0.982	0.984	0.980	0.944	0.933	0.890	0.979	0.960
LPIPS	0.017	0.024	0.025	0.038	0.070	0.076	0.133	0.022	0.051
FPS	40.81	34.02	49.80	25.06	20.08	37.77	15.77	36.20	32.44
训练时间	3分9秒	3分12秒	4分17秒	5分53秒	4分55秒	4分7秒	9分20秒	5分5秒	5分00秒

合成-NSVF

	酒架	蒸汽火车	牛蛙	机器人	自行车	宫殿	宇宙飞船	生活方式	平均
PSNR	31.64	36.47	35.57	37.10	37.87	37.41	35.58	34.76	35.80
SSIM	0.962	0.987	0.980	0.994	0.990	0.977	0.980	0.967	0.980
LPIPS	0.047	0.023	0.024	0.010	0.015	0.021	0.029	0.044	0.027
FPS	47.07	75.17	50.42	64.87	66.88	28.62	35.55	22.84	48.93
训练时间	3分58秒	3分44秒	7分22秒	3分25秒	3分11秒	6分45秒	3分25秒	4分56秒	4分36秒

坦克与寺庙

	伊格纳修斯	卡车	谷仓	毛毛虫	家庭	平均
PSNR	28.30	27.67	28.00	26.16	34.27	28.78
*FPS	10.04	7.99	16.14	10.91	6.16	10.25

*在 test-traj 上评估

BlendedMVS

	*玉器	*喷泉	角色	雕像	平均
PSNR	25.43	26.82	30.43	26.79	27.38
**FPS	26.02	21.24	35.99	19.22	25.61
训练时间	6分31秒	7分15秒	4分50秒	5分57秒	6分48秒

*我手动将背景从黑色改为白色，因此该数值无法直接与论文中的数据进行比较。

**在 test-traj 上评估

#待办事项

• 在 GUI 中使用超分辨率技术以提升 FPS
• 使用多球面图像作为背景

ngp_pl 快速上手指南

ngp_pl 是一个基于 PyTorch + CUDA 实现的 Instant-NGP（NeRF）项目，旨在提供简洁的接口以实现高质量与高速度的训练。本指南将帮助你快速在本地部署并运行该工具。

1. 环境准备

本项目对硬件和软件版本有严格要求，请确保满足以下条件以避免兼容性问题。

硬件要求

• 操作系统: Ubuntu 20.04 (其他平台未官方支持)
• GPU: NVIDIA GPU，计算能力 (Compute Capability) >= 7.5，显存 > 6GB (推荐 RTX 2080 Ti 或更高)
• 内存: 32GB RAM (用于加载全尺寸图像)
• CUDA 版本: 11.3

软件依赖

• Python >= 3.8
• Git

2. 安装步骤

建议使用 Conda 创建独立的虚拟环境。

第一步：克隆代码与创建环境

git clone https://github.com/kwea123/ngp_pl
cd ngp_pl

# 创建并激活 conda 环境
conda create -n ngp_pl python=3.8
conda activate ngp_pl

第二步：安装核心依赖

按顺序安装以下组件，注意 PyTorch 版本必须匹配 CUDA 11.3。

1. 安装 PyTorch:

   pip install torch==1.11.0 --extra-index-url https://download.pytorch.org/whl/cu113
   

   (国内用户可使用清华源加速：pip install torch==1.11.0 --extra-index-url https://download.pytorch.org/whl/cu113 -i https://pypi.tuna.tsinghua.edu.cn/simple)

2. 安装 torch-scatter: 请参考 官方安装指令，通常命令如下（需根据具体环境调整 wheel 地址）：

   pip install torch-scatter -f https://data.pyg.org/whl/torch-1.11.0+cu113.html
   

3. 安装 tinycudann (PyTorch 扩展): 请参考 官方安装指令。

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

4. 安装 apex: 请参考 官方安装指令。通常需要源码安装：

   git clone https://github.com/NVIDIA/apex
   cd apex
   pip install -v --disable-pip-version-check --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./
   cd ..
   

5. 安装项目其余依赖:

   pip install -r requirements.txt
   

第三步：编译 CUDA 扩展

重要：每次拉取（pull）新代码后，都必须重新执行此步骤。请先升级 pip 至 22.1 以上。

pip install --upgrade pip "pip>=22.1"
pip install models/csrc/

3. 基本使用

数据准备

本项目支持多种数据集格式（NSVF, NeRF++, Colmap, RTMV）。 以经典的 Lego 场景为例，你需要先下载预处理好的 NSVF 数据集（包含 Synthetic_NeRF 等），并确保文件夹名称未被修改。

开始训练

使用以下命令快速启动训练。以下示例将训练 Lego 场景 30k 步（约 5 分钟），并在结束时进行一次测试。

python train.py --root_dir <path/to/lego> --exp_name Lego

• <path/to/lego>: 替换为你本地数据集的实际路径。
• 训练结束后会显示测试 PSNR。若不想保存测试图像以加快速度，可添加 --no_save_test 参数。

推理与可视化

训练完成后，你可以使用 Jupyter Notebook 生成图像，或使用 GUI 进行交互式查看。

方式一：使用 Notebook 生成图像 运行 test.ipynb，加载预训练模型或你刚刚训练的 checkpoint。 Lego 预训练模型下载地址: Releases v1.0

方式二：使用 GUI 交互查看 运行以下命令启动图形界面。注意：必须传入与训练时完全相同的超参数（如 dataset_name, root_dir 等），并指定检查点路径。

python show_gui.py --dataset_name synthetic_nerf --root_dir <path/to/lego> --ckpt_path <path/to/your_model.ckpt>

性能参考

在单张 RTX 2080 Ti 上，Lego 场景的训练时间约为 5 分钟，推理速度可达 36 FPS 左右，质量略优于同类的 torch-ngp 实现。