简介：这是一份可作为复现模板与学习范式的 NERF-SLAM 技术笔记，面向希望从零跑通神经辐射场与即时定位建图结合三维重建算法的读者，尤其适合具备一定 SLAM 基础的研究生和算法工程人员。压缩包内仅含 1 个 docx 文档，大小约 11MB，内容兼顾原理推导与动手操作，方便在本地离线查阅。目前这份文档已有 2308 人浏览学习，说明其内容对同领域学习者确实有参考价值。笔记从 Tracking 阶段的稠密单目 SLAM 讲起，解释了协方差加权、RAFT 光流估计、Droid SLAM 与 DBA 层的关联，后续又深入 Mapping 阶段的概率体素 NeRF、Instant-NGP 哈希编码和 Mapping Loss，完整覆盖了 NERF-SLAM 的核心模块。除了算法原理，作者还整理了环境配置、依赖安装、数据集准备和常见编译报错的解决办法，能够显著降低复现门槛，适合想要深入理解或二次开发该框架的读者。

1. 复现 nerf-slam 到底在复现什么

做 SLAM 的人这两年很难绕开 nerf-slam 这个词。它把神经辐射场塞进实时 SLAM 框架里，让机器人一边定位一边用 NeRF 做稠密建图，而不是像传统方案那样只输出点云或八叉树。第一次跑通它的人通常会有一个反应：原来 NeRF 不只能离线渲染，还能在轨迹估计的同时把场景几何和颜色一起学出来。这个项目对入门者的价值在于，它是少数把 NeRF 训练、位姿估计、深度对齐和 mesh 提取串成一条完整管线的开源实现，值得花时间复现一遍。

这篇笔记适合两类人：一类是想把神经隐式表示用在自己的 RGB-D SLAM 项目里的研究者，另一类是遇到过 TSDF 地图不够细腻、想试试学习式建图效果的从业者。复现的最大意义不是把 README 里的命令跑通，而是搞清楚损失函数怎么把几何和颜色耦合在一起、特征网格为什么比纯 MLP 快。我会从环境准备讲到训练参数，再专门开一章写踩坑记录，最后落到评估和自定义数据上，尽量让照着做的人少走弯路。

2. 跑通 nerf-slam 的前提：设备、环境与数据长什么样

nerf-slam 的复现难点不在算法理解，而在环境依赖。它基于 PyTorch、tiny-cuda-nn 和 OpenGL 相关依赖，对 CUDA 版本很敏感。我第一次装的时候在编译扩展上卡了两天，后来发现是 PyTorch 和 CUDA 的匹配问题。

2.1 硬件底线：显存决定了你能跑哪个数据集

nerf-slam 的官方实现使用显式特征网格（feature grid）而不是纯 MLP，这让训练速度大幅提升，但代价是显存占用很高。Replica 数据集单场景的默认配置大约需要 8GB 显存，ScanNet 需要更多，因为输入分辨率更高。如果你只有 6GB 显存，建议先跑 Replica 的 office0，把 feature 网格分辨率调低。缩放tracking和mapping设置里的金字塔层级也能压显存，但定位精度会掉，这是第一个要接受的取舍。

显卡建议至少 RTX 2070 级别，CUDA 计算能力 7.5 以上。Ampere 架构（30系）和 Ada Lovelace（40系）都能正常跑，但要注意 PyTorch 和 tiny-cnn 的 CUDA 版本不能冲突。CPU 方面基本没有瓶颈，因为训练和追踪都在 GPU 上跑，CPU 主要负责数据加载。

2.2 环境安装：一个能复现的 conda 方案

官方仓库的安装文档写得比较简略，只给了依赖列表。常见的做法是先建独立 conda 环境，再单独安装 PyTorch，最后编译子模块。我一般用 Python 3.9 + PyTorch 1.13 + CUDA 11.7 这套组合，稳定性和兼容性都验证过。

conda create -n nerfslam python=3.9 conda activate nerfslam pip install torch==1.13.1+cu117 torchvision==0.14.1+cu117 --extra-index-url https://download.pytorch.org/whl/cu117 pip install -r requirements.txt

先装 PyTorch 再装 requirements.txt 是必须的顺序，因为依赖里的torch-scatter和torch-sparse需要检测已安装的 PyTorch 版本来选择编译版本。如果顺序反了，后面 import 时会出现undefined symbol错误。requirements.txt 里主要是 open3d、opencv-python、tqdm 这些常规库，没有特别冷门的包。

接下来编译两个核心子模块。nerf-slam 依赖torch_scatter的 CUDA 扩展和tiny-cuda-nn的 PyTorch 绑定。tiny-cuda-nn 的编译是整个安装过程里最玄学的部分，它需要 CUDA 工具链和 gcc 版本匹配，我用 gcc 8.5 和 CUDA 11.7 一次通过，换到 gcc 11 在cuda_fp16.h上报过错。

pip install torch-scatter -f https://data.pyg.org/whl/torch-1.13.0+cu117.html git clone --recursive https://github.com/nvlabs/tiny-cuda-nn cd tiny-cuda-nn export TCNN_CUDA_ARCH=86 # 根据显卡计算能力调整 cd bindings/torch python setup.py install

TCNN_CUDA_ARCH这个环境变量最容易忽略。不设置时编译脚本会自动探测，但在某些 docker 环境里会探测失败，导致编译出来的库在运行时报“no kernel image available”。RTX 3080 是 86，RTX 2070 是 75，A100 是 80，按实际显卡填。

2.3 数据集：Replica 的下载与目录结构

nerf-slam 的官方复现用 Replica 数据集，它提供高精度 RGB-D 序列和稠密重建真值，适合量化评估。Replica 的下载需要通过 GitHub 仓库获取，下载后需要解压到datasets/Replica目录下，每个场景文件夹里要有results目录存放 frame 数据。目录结构必须严格符合代码里的路径拼接逻辑：

datasets/Replica/office0/ results/ frame-000000.color.jpg frame-000000.depth.png frame-000000.pose.txt ...

pose.txt是 4x4 变换矩阵，nerf-slam 的数据加载器会读取它做真值轨迹对比。如果你自己采集数据，这个文件的格式必须一致。Replica 每个场景约二三百帧，单帧分辨率是 1200x680，但代码里会按比例缩放。

数据准备好后，还需要确认 config 文件里的input_folder参数指向正确路径。官方配置默认相对于仓库根目录，所以如果仓库克隆到了~/work/nerf-slam，数据集放在~/work/nerf-slam/datasets/Replica下就不会有问题。

3. 训练与定位：从配置文件到输出 mesh 的完整流程

环境装好、数据就位后，就可以跑训练了。nerf-slam 的训练过程和传统 SLAM 不一样，它不区分单独的建图阶段和定位阶段，而是每来一帧先做跟踪（tracking），再把关键帧加入 map 做优化（mapping）。

3.1 配置文件里的关键参数：mode、feature 与损失权重

nerf-slam 的配置文件以 YAML 形式存在configs/目录下。打开 Replica 的配置文件，第一件事是确认mode参数。它有三个可选值：rgb、depth、rgbd。如果你只做定位不管建图质量，rgb模式就够了；但如果要输出几何一致的 mesh，必须用rgbd模式，同时利用颜色和深度损失。我用rgbd模式跑出来的 mesh 完整度比rgb模式高不少。

另一个影响巨大的是use_sphere_half和use_normalization这两个开关。前者控制网格初始化范围是否需要归一化到单位球内，后者控制输入坐标的归一化方式。在 ScanNet 上跑而不开use_normalization，loss 会直接发散到 NaN。这是换数据集最容易踩的坑。

model: grid_size: 4 # 特征网格分辨率基数 num_levels: 4 # 金字塔层级数 feature_dim: 8 # 每级特征维度 use_sphere_half: True use_normalization: True training: tracking: True mapping: True loss_weights: color: 5.0 depth: 0.5 sdf: 1.0 fs: 1.0 # free-space 损失，约束空区域

grid_size不是最终分辨率，而是2^grid_size的基数，默认 4 等于每个轴向 64 格。改成 3 会显著降低显存占用，但细节会糊。feature_dim对显存影响也很大，默认 8 可以压到 4，重建质量下降不明显，训练速度提升约 20%。

3.2 单卡训练命令与输出文件解读

配置调整完毕后，运行训练命令：

python scripts/run.py --config configs/Replica/office0.yaml

启动后终端会分两个线程打印信息：tracking 线程输出位姿估计的相对误差，mapping 线程输出当前损失值。第一次跑不需要看懂所有指标，只需要确认两个信号：loss 在下降，tracking 的相对漂移在 2cm 以内。如果 loss 平稳下降但漂移很大，说明跟踪线程的帧间匹配有问题，后面我会讲排查办法。

训练完成后，输出在outputs/Replica/office0/下：

output_www/ # 渲染结果，RGB、深度、正常图 output_mesh/ # 提取的三角网格 cpts.npy # 优化后的特征网格坐标 tracking_pose.npy # 估计轨迹 gt_pose.npy # 真值轨迹

tracking_pose.npy和gt_pose.npy是评估定位精度的关键文件，后续要用工具脚本对齐比较。output_mesh里默认是.ply格式，但有些版本的 open3d 读取时需要注意顶点颜色格式。

3.3 评估脚本：定位误差和重建质量的量化

跑完训练后，用仓库里的scripts/eval.py做定量评估：

python scripts/eval.py --config configs/Replica/office0.yaml --mode all

评估输出包括了 ATE（绝对轨迹误差）的 RMSE、mesh 的精度和召回率、渲染 RGB 的 PSNR/SSIM。这些数值是论文对比表的核心依据，复现时如果跑出的 ATE 比论文高一个数量级，优先怀疑跟踪线程的参数，而不是网络结构。

我用默认配置在 Replica office0 上复现的结果是 ATE RMSE 约 0.7cm、PSNR 约 28dB，与论文量级一致。做到这个数字，复现就可以认定成功了。

提示：评估脚本会花费比训练更长的时间，因为要对所有测试视角做渲染推理，耐心等待。

4. 复现过程中最常遇到的 5 个坑与排查顺序

nerf-slam 的复现过程不会一帆风顺，我把高频问题按出现概率排序，每条按现象、原因、解决的思路展开。这些坑不是从文档里抄的，是实际跑过的血泪经验。

4.1 编译 tiny-cuda-nn 报错：变量符号未定义

现象：编译到最后一步python setup.py install时报undefined reference to cuda_fp16或者直接提示gcc: internal compiler error。这个问题在 Ubuntu 22.04 上尤其常见，因为系统默认 gcc 11 太新。

原因：tiny-cuda-nn 的旧版本对 gcc 版本敏感，模板实例化时与老版本 CUDA 头文件冲突。

解决：不要硬怼 gcc 版本，用 conda 装一个 gcc 8 并优先使用它：

conda install gcc=8.5 gxx=8.5 export CC=/opt/conda/envs/nerfslam/bin/gcc export CXX=/opt/conda/envs/nerfslam/bin/g++ python setup.py install

注意环境变量要在编译命令前立即生效，不要隔终端。

4.2 运行时提示 no kernel image available

现象：编译通过，但 import tiny_cuda_nn 或跑训练时出现RuntimeError: CUDA error: no kernel image is available for execution on the device。

原因：编译时的TCNN_CUDA_ARCH和实际 GPU 计算能力不匹配。最常见的是在 docker 里编译，宿主机是 A100，运行在 T4 上，或者反过来。

解决：先查显卡计算能力，nvidia-smi不显示这个信息，用python -c "import torch; print(torch.cuda.get_device_capability())"获取，然后回到编译步骤重设TCNN_CUDA_ARCH重新编译。必须rm -rf build清掉旧缓存，否则改了环境变量也没用。

4.3 训练 loss 变成 NaN

现象：训练开始几十步后 loss 突然变成nan，终端打印的数值变成loss: nan，跟踪线程卡死。

原因：训练数据里的深度值非常大或包含无效值，配合use_normalization关闭时，SDF 损失计算溢出。

解决：检查配置是否开了use_normalization，再检查深度图读取时是否做了尺度缩放。Replica 的深度值是毫米单位，数值在 3000-8000 之间，如果直接除以 1000 转成米，会改变 SDF 的计算尺度。正确做法是保持原始单位，让归一化层处理。我一般会额外写一个小脚本打印深度图的 min/max，避免数据本身有问题：

import cv2 import numpy as np depth = cv2.imread('frame-000000.depth.png', cv2.IMREAD_UNCHANGED).astype(np.float32) print(depth.min(), depth.max())

4.4 定位漂移大但建图质量正常

现象：mesh 看起来不错，但 ATE 评估误差在 10cm 以上。

原因：tracking 线程的前后端没有正确同步。nerf-slam 的跟踪线程会不断把当前帧和全局 map 做对齐，如果初始位姿给得不对，或者相机内参矩阵与数据集不匹配，漂移会快速累积。

解决：先确认 config 里的相机内参。Replica 仿真器的内参和真实相机不同，每个场景的配置里都写死了H、W、fx、fy、cx、cy，不要从别处复制。其次看tracking_pose.npy的第一行是不是单位矩阵，如果不是，说明初始化位姿设置有问题。

4.5 mesh 提取结果为空或只有碎片

现象：训练完成后打开output_mesh，.ply文件只有几百个顶点，或者完全为空。

原因：mesh 提取阶段依赖深度图的截断阈值（truncation参数）。如果深度图尺度不对，等值面提取时采样点全部落在截断范围外，自然提不出面。

解决：检查配置文件里truncation的值，Replica 场景一般设 0.1（单位同深度图）。如果深度图单位是毫米，这里要写 100。同样的，grid_size太小时网格分辨率不够，小物体会被平滑掉，适当提高到 5 或 6。

5. 评估可视化和打开黑匣子：定位轨迹与重建质量的验证方法

训练完成只是第一步，真正判断复现成功与否，要看量化指标和可视化的对齐结果。很多人只看 loss 曲线就说复现成功，这是不够的。我一般会做两组验证。

5.1 轨迹对齐与 ATE 计算

nerf-slam 的评估脚本内部实现了 Umeyama 算法对齐估计轨迹和真值轨迹，但如果你想深入理解对结果的影响，可以自己做一次：

import numpy as np from scipy.spatial.transform import Rotation def umeyama_alignment(src, dst): src_mean = src.mean(axis=0) dst_mean = dst.mean(axis=0) src_c = src - src_mean dst_c = dst - dst_mean cov = dst_c.T @ src_c u, _, vt = np.linalg.svd(cov) r = u @ vt if np.linalg.det(r) < 0: vt[-1] *= -1 r = u @ vt scale = np.trace(np.diag(np.ones(3)) @ np.linalg.inv(np.cov(src_c.T))) if False else 1.0 return r, scale, dst_mean - scale * r @ src_mean

这段代码就是最简单的 Umeyama 求解刚体变换。对齐后逐帧计算位移误差，再求 RMSE 就是 ATE 值。注意评估坐标系需要先对齐，否则 SLAM 轨迹坐标系和真值坐标系不一致，误差恒大于真实水平。跑这套验证能帮你判断 nerf-slam 的位姿估计是否真的收敛。

5.2 渲染质量验证：新视角合成

定位误差之外，神经辐射场的核心优势在于新视角合成质量。评估脚本输出的 PSNR 和 SSIM 是渲染质量的量化指标，但可视化更有说服力。在output_www目录里对比同一视角的 GT 和渲染图，如果纹理边缘模糊，通常是feature_dim太低或者训练轮次不足。如果全局偏暗，检查 loss 里color权重是否太小，默认 5.0 是合理的。

做完这些验证，你才算真正把 nerf-slam 从黑匣子变成了手里能调的工具。

6. 让 nerf-slam 跑在自己的数据上：定制流程与三个关键调整

最后这章讲复现超出官方数据集后的常见做法。Replica 只是起步，实际项目里很少有人对仿真数据感兴趣，大家更关心能不能跑自己的 RGB-D 数据。答案是能，但要做三件事。

6.1 准备符合加载器的数据目录

nerf-slam 的数据加载器要求每帧一个 color 图、一个 depth 图、一个 pose 文件。pose.txt是 4x4 矩阵，前 3 行是旋转和平移，最后一行是0, 0, 0, 1。注意这里坐标系定义比较绕，实际相机坐标系到世界坐标系的变换取决于你自己的标定方式。如果你的相机标定结果是世界到相机矩阵，需要先求逆再写入文件。我第一次用自己采集的数据时把方向搞反，跑出来的轨迹像喝醉了一样。

6.2 调整相机内参与深度单位

这一步直接决定成败，常见做法是先把深度图从 uint16 转成 float32，再统一除以深度尺度因子。RealSense 的深度单位是毫米，Replica 也是毫米，但有些开源数据集是 0.1mm 甚至米。转换后，把内参填进配置文件的cam段。注意depth_scale参数要和训练损失里的深度值单位对齐，否则 SDF 损失会按错误尺度优化。

6.3 训练时长和关键帧采样

少量自己的数据（比如 200 帧）通常不需要 1 小时训练。nerf-slam 每帧都会参与优化，但关键帧选择频率越高显存消耗越大。默认配置在 200 帧内会跑得比官方更好看，增加 30 轮迭代，还是有限的显存下更频繁地参与全局优化？这是一个围绕时间和资源的取舍。我会先在低分辨率下快速跑通，确认没有局部抖动后再降低keyframe_every值追求质量。

走完这几步，nerf-slam 在你的工作流里就算真正落地了。我个人的习惯是每改一个参数就记录轨迹误差和 PSNR，输出到一张表里，这样回滚时能直接知道后悔药在哪。复现论文不是目的，把神经辐射场 SLAM 的边界和脾气摸清楚才是。希望这篇笔记能帮你在复现路上省下几个通宵。

本文还有配套的精品资源，点击获取