简介：《nerf-slam的复现文档》是一份面向三维重建、视觉同步定位与建图以及神经辐射场方向学习者的复现型参考资料，适合具备一定深度学习基础、希望理解神经辐射场与同步定位建图结合思路并排查复现难点的人群。文档围绕追踪与建图两条主线展开，涵盖带协方差的稠密同步定位建图、即时神经图形基元、光流估计、稠密束调整中的舒尔补与乔列斯基分解，以及概率体素化神经辐射场、深度与颜色联合监督等内容，并结合深度图噪声、无纹理区域和位姿精度等情形说明重建表现。压缩包共1个docx文件，约11.01MB，以图文笔记形式组织，便于按模块查阅与对照。已有2326人学习，文档还记录了作者复现过程中遇到的问题与解决思路，可帮助读者建立从原理到工程实现的对照框架，提升复现与排错效率。
1. 复现 NeRF-SLAM 之前，先搞清它把哪些工作分给了哪些模块
把 NeRF-SLAM 的仓库拉下来跑通，和把它的论文读明白，是两件难度完全不同的事。前者卡在 cmake 版本、Boost 编译、gtsam 的 Python wrapper 上，后者卡在 DBA 的舒尔补求解顺序，以及深度协方差怎么变成损失权重。这份复现文档的价值就在中间那段：它把 Tracking 里的 RAFT 光流、Droid-SLAM 的协方差、DBA 的求解链路，以及 Mapping 里 Instant-NGP 的哈希编码和概率体素深度监督，按工程落地的顺序摊开写了一遍，连编译时报的错都是原样贴出来的。
它的输入只需要连续单目 RGB 图像，不需要 RGB-D，稠密重建质量却明显好于 ORB-SLAM 那类稀疏关键点方案，这是它跟同路线方案拉开差距的地方。适合已经跑过传统视觉 SLAM、想往稠密建图方向走的人，也适合手里有序列数据、想直接拿 NeRF 出高质量重建、但不想从零搭环境的人。这份复现文档更像一份可以照着抄的工程日志，不太像学术材料。
2. 环境链：cmake、torch、Boost 与 gtsam 的版本咬合
这套代码的编译链是整篇复现文档里最费时间的部分，涉及的依赖跨度很大：instant-ngp 需要新版 cmake，gtsam 对 Boost 版本有硬性下限，torch 又必须和 CUDA 运行时对上 ABI。三者的版本互相牵制，随便升级其中一个，另外两个就可能编译不过。我的建议是先把版本组合固定下来，再动手编译，不要一边报错一边升级。
2.1 先固定 torch 与 CUDA 的版本组合
复现文档里验证过的是 CUDA 11.3 配 torch 1.12.1 和 torchvision 0.13.1。这个组合不是随便挑的：instant-ngp 的 Python binding 和 gtsam 的 wrapper 都会链接 torch 的 C++ 扩展，torch 版本一变，底层 CUDA runtime 和 cuDNN 的符号就可能对不上，表现出来的现象往往是 import 时报 undefined symbol，或者跑到一半提示 no kernel image is available。先把版本固定在这个组合上，后面排错才有起点。
# 建独立虚拟环境，别装在系统 python 里，gtsam wrapper 会污染全局路径 python3 -m venv ~/venvs/nerfslam source ~/venvs/nerfslam/bin/activate # 装 torch：+cu113 表示这个 wheel 自带 CUDA 11.3 运行时 pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 \ --extra-index-url https://download.pytorch.org/whl/cu113 # 两套 requirements 分开装，gtsam 的 wrapper 依赖是单独维护的 pip install -r requirements.txt pip install -r ./thirdparty/gtsam/python/requirements.txt--extra-index-url的作用是把 PyTorch 的 cu113 源加进检索列表，否则 pip 只会去默认源找，而默认源里的 torch 不带 CUDA 后缀。torchvision 必须跟 torch 同源同版本，混装是最常见的坑：装了 0.13.0 配 1.12.1，import 时不报错，跑数据增强才崩。两个 requirements 文件分开装，是因为 gtsam 的 Python wrapper 自己维护了一套 pybind11 和 numpy 版本约束，混在一起装容易出现依赖互相覆盖。
装完先做一次最小验证，确认 CUDA 可用再往下走：
python -c "import torch; print(torch.__version__, torch.cuda.is_available())" # 期望输出 1.12.1+cu113 True如果cuda.is_available()返回 False，先查驱动版本，再查是不是装成了 CPU 版 wheel。这一步不验证，后面 instant-ngp 编译成功但一跑就退，很难定位到是 torch 的问题。
2.2 多套 cmake 并存时怎么切换
instant-ngp 明确要求 cmake 大于 3.22，而 gtsam 的某些老配置在高版本 cmake 下会触发 policy 报错。实际复现时机器上往往要同时存在 3.22 和 3.26，偶尔还要退到 3.9 做对照。复现文档里贴了三套版本的源码编译过程，思路都是一样的：下载、解压、configure、make install，把可执行文件装到/usr/local/bin。
# 以 3.22 为例，其他版本只改版本号 wget https://cmake.org/files/v3.22/cmake-3.22.0-rc2-linux-x86_64.tar.gz --no-check-certificate tar -zxvf cmake-3.22.0-rc2-linux-x86_64.tar.gz cd cmake-3.22.0-rc2-linux-x86_64 sudo cp -r bin /usr/local/ sudo cp -r share /usr/local/ # 关键一步：清掉 shell 对 cmake 路径的缓存，否则 which cmake 还指向旧版本 hash -r cmake --versionhash -r是这一步的核心。bash 会缓存命令的实际路径，你装完新版本后直接敲cmake --version，返回的可能还是系统自带的老版本，然后你会误以为安装失败，反复重装。这个坑我在别的项目上也踩过，属于看着很傻但确实会卡住半天的类型。
| 版本 | 用途 | 安装方式 |
|---|---|---|
| 3.22 | 编译 instant-ngp 的最低要求 | 官方预编译包解压 |
| 3.26 | 编译 gtsam 与日常使用 | 源码 configure + make |
| 3.9 | 老配置对照排查 | 源码 configure + make |
这张表可以直接当成环境搭建的模板抄下来。表格里没写“推荐版本”，是因为这套代码对版本的态度是“能用就别动”，一旦某套组合编译通过，就把版本号记下来锁死，别为了追新去升级。
2.3 Boost 1.73 源码编译与 gtsam wrapper 打通
编译 gtsam 时报的错很典型：找不到 Boost 的 serialization、system、filesystem、thread 等一串组件，要求最低 1.65。系统包管理器装的 Boost 经常缺组件，或者版本低于要求，所以复现文档选择了源码编译 1.73.0。
# 下载 1.73.0 源码包，解压后进入目录 tar xvf boost_1_73_0.tar.bz2 cd boost_1_73_0 # 生成 b2 构建工具，默认探测系统 python ./bootstrap.sh # 全量编译安装；如果只要部分库，用 --with- 指定，这里图省事全装 sudo ./b2 --buildtype=complete install # 装完刷新动态库缓存，否则链接阶段找不到新装的 so sudo ldconfig--buildtype=complete表示完整构建，包含 debug 和 release 两套；只想快点装完可以去掉，但 gtsam 链接时可能因为缺 release 版本而失败，第一次复现建议保留。--prefix=/some/path可以改安装位置，代价是之后要手动把lib和include加进环境变量，CMake 才能找到，不如默认装到/usr/local省事。系统里有多个 Python 时，用--with-python=python3明确指定，不指定就走系统默认，虚拟环境里的解释器可能被忽略。
Boost 装好后重新配置 gtsam，并且显式打开 Python wrapper：
cmake ./thirdparty/gtsam -DGTSAM_BUILD_PYTHON=1 -B build_gtsam cmake --build build_gtsam -j # 验证 wrapper 产物是否生成 find build_gtsam -name "*.so" | grep -i gtsam-DGTSAM_BUILD_PYTHON=1是开关，不加这一项，编译能过，但build_gtsam/python目录下不会有可 import 的模块。验证时不要只看编译日志的 “100%”，要实际找到.so文件。找到之后还得把目录加进PYTHONPATH，否则import gtsam依然失败，这一步在避坑章还会展开。
3. Tracking 管线：RAFT 光流、Droid 协方差与 DBA 舒尔补
Tracking 阶段容易被误解成“估计相机位姿”，实际上它还承担了给 Mapping 生产监督信号的任务：每一帧的深度图、每个像素的置信度，都是从这里流出去的。整条链路是 RAFT 提供光流匹配的能力，Droid-SLAM 把更新量改造成作用在帧图边上，DBA 层把网络输出映射回几何量。理解这个分工，比记住某一行代码更重要。
3.1 RAFT 的三个组件与 4D 相关体
RAFT 做光流估计，结构分三块。特征编码器从两张输入图像里各提一组逐像素特征；上下文编码器只从第一张图提特征，供后续更新算子使用；相关层把两组特征做内积，构建一个四维的 W×H×W×H 相关体，表达“图一任意像素与图二任意像素的匹配强度”。这个四维张量太大，实际会在最后两维上做多尺度池化，得到一组由粗到细的相关体。
更新算子是 RAFT 里迭代的部分：用当前光流估计去相关体里查表，取出匹配代价，连同上下文特征一起送进 convGRU，输出光流的增量，反复迭代若干次。这里的“查表”是双线性插值采样，不是硬索引，所以梯度能回传。理解这一点，才能看懂 Droid-SLAM 为什么能把查表位置换成投影点。
3.2 Droid-SLAM 把更新量改成了投影残差
Droid-SLAM 在 RAFT 基础上动了更新部分。它不再让 convGRU 直接输出位姿和深度的残差，而是让网络输出一个投影残差量 r_ij 和一个置信度 w_ij。具体做法是：对第 i 帧的像素 p_i，用当前估计的位姿和逆深度做投影反投影，得到它在第 j 帧上的对应点 p_ij；再用 p_ij 去相关体里查表，拿到匹配代价 C_ij，作为 convGRU 的输入之一。
这么改的意义在于把网络输出和几何优化解耦了。网络只负责回答“这个投影点偏了多少、有多可信”，至于这个残差怎么变成位姿和深度的修正，交给后面的 DBA 层用最小二乘统一处理。好处是几何约束是硬的，不会出现网络直接回归位姿导致的漂移累积；代价是 DBA 层的实现必须和前端严格对齐，投影模型、相机内参、逆深度参数化任何一处对不上，残差就会系统性偏。
3.3 DBA：先消元求位姿，再回代求逆深度
Dense Bundle Adjustment 层是整个 Tracking 的求解核心。优化变量分两类：相机位姿 ξ 和路标点逆深度 d。路标点数量远大于相机数量，所以不能直接把 H 矩阵整个求逆，要用舒尔补先消掉路标块，解出位姿增量，再回代求深度增量。
H 矩阵按变量分块写成[[B, E], [E^T, C]]，其中 B 是位姿块，C 是深度块（块对角，求逆很便宜），E 是耦合块。消掉深度变量后得到 S = B − E C⁻¹ Eᵀ，对 S 做 Cholesky 分解S = L Lᵀ，解出位姿增量，再回代得到每个路标的逆深度增量。这个 Cholesky 因子还能复用来计算边缘协方差，也就是后面传给 Mapping 当深度损失权重的 Σ_D。
import numpy as np def dba_solve(B, E, C, b_cam, b_depth, damping=1e-4): # H = [[B, E], [E^T, C]]；b 为负残差；C 为深度块，块对角求逆便宜 # damping 是 LM 阻尼，跟踪失败时调大能稳住求解 B = B + damping * np.eye(B.shape[0]) C = C + damping * np.eye(C.shape[0]) # 舒尔补：消掉逆深度变量，只留位姿 S = B - E @ np.linalg.solve(C, E.T) rhs = -b_cam + E @ np.linalg.solve(C, b_depth) # Cholesky 分解后解位姿增量；L 复用于边缘协方差 L = np.linalg.cholesky(S) delta_pose = np.linalg.solve(L.T, np.linalg.solve(L, rhs)) # 回代求每个路标的逆深度增量 delta_depth = np.linalg.solve(C, -b_depth - E.T @ delta_pose) return delta_pose, delta_depth这段是结构示意，不是仓库里的原代码，但求解顺序和复现文档描述的一致：先位姿、后深度。damping对应 LM 里的 λ，跟踪在无纹理区域抖动时，把它从 1e-4 调到 1e-2 往往能压住；调得太大则收敛变慢，表现为位姿估计滞后于真实运动。C必须是块对角才能这么便宜地求逆，如果实现里把深度变量做了跨帧耦合，这个前提就不成立，舒尔补的收益会大打折扣。
4. Mapping 管线：Instant-NGP 哈希编码与概率体素深度监督
Mapping 阶段要做的是用 Tracking 给的位姿和深度，训练一个概率体素化的 NeRF。这里的核心矛盾是速度：原始 NeRF 训练一个场景要几小时，SLAM 要求秒级到分钟级出结果。Instant-NGP 的哈希编码解决速度问题，概率体素的加权深度损失解决噪声问题，两者缺一不可。
4.1 哈希编码为什么能把 NeRF 拉到秒级
原始 NeRF 用位置编码把坐标映射到高维，MLP 要自己学会高频细节，收敛慢。Instant-NGP 换了个思路：把空间划分成多分辨率的网格，每个网格顶点存一个可学习的特征向量，查表取值后拼接再送 MLP。分辨率越高，网格数量指数增长，显存扛不住，所以用哈希表做冲突映射，不同空间位置可能落到同一个槽位。
冲突不是免费的，但梯度会自己消化：多个位置共享一个特征槽时，反传的梯度是叠加的，训练过程会把共享特征推向对多数位置都合理的方向。低分辨率层冲突少、负责整体结构，高分辨率层冲突多、负责细节。这种多层级联的结构，让 MLP 可以做得又小又浅，推理速度自然就上来了。复现文档里以两层分辨率为例讲了编码拼接，实际配置里的层数更多，但机制一样。
4.2 深度损失按协方差加权
深度监督不能一刀切，这是复现文档里最值得看的部分。Tracking 给的深度图在无纹理区、遮挡边缘、弱视差区域质量很差，如果等权加进损失，NeRF 会被这些错误深度带偏，表现为重建表面出现鼓包或者拉丝。
文档给的解法是用边缘协方差 Σ_D 加权，损失写成加权平方误差，权重取协方差的倒数，再做归一化，使得 λ_D 的量纲仍然有效。文档里 λ_D 设为 1.0，这个值平衡的是深度监督和颜色监督。
def depth_loss(depth_pred, depth_meas, cov, lam_d=1.0, eps=1e-6): # cov 来自 Droid-SLAM 的边缘协方差，越大多信越低 w = 1.0 / (cov + eps) # 归一化：避免整体权重尺度变化把颜色损失压没 w = w / w.mean() l_depth = (w * (depth_pred - depth_meas) ** 2).mean() return lam_d * l_deptheps防止协方差接近零时除零溢出，这是必须加的。归一化那一步容易被忽略：不做归一化，不同场景的协方差绝对值差异很大，同一个 λ_D 在一个场景合适、换一个场景就把颜色项压死，重建出来一片模糊。做完归一化，λ_D 才是可迁移的超参。
4.3 收敛判断与配置项
文档里有一组对比很有说服力：真值位姿加真值深度，收敛又快又好；只有真值位姿、没有深度，NeRF 也能收敛，只是慢；给噪声位姿且不给深度，60 秒内根本不收敛；给真值深度配噪声位姿，结果反而不错；噪声位姿配噪声深度，只有按不确定性加权才能拿到接近真值的结果。这组对比说明两件事：深度比位姿更关键，加权比不加权更关键。
实际跑的时候，我一般先确认三个开关再调参：
| 配置项 | 作用 | 调整方向 |
|---|---|---|
| λ_D | 深度损失权重 | 默认 1.0，深度噪声大时降到 0.3~0.5 |
| 协方差权重开关 | 是否启用 Σ_D 加权 | 必须开，关了在无纹理区必崩 |
| 哈希表规模 | 控制细节上限与显存 | 先按默认跑通，显存不够再降 |
收敛判断不要只看 loss 曲线。更直接的做法是每训练若干步渲染一张深度图，和 Tracking 给的深度图叠着看：边缘贴合、无纹理区平滑但不错位，才算收敛。loss 在降但深度图整体偏移，通常是位姿和深度的时间戳或者坐标系对不上，属于数据对齐问题，不是训练问题。
5. 复现翻车记录：五类报错的现象、原因与处理
这套代码的报错有个特点：编译期的错和运行期的错长得完全不一样，但根因经常是同一个依赖版本问题。下面五条是我在复现时按出现频率排的，每条都按现象、原因、解决三段记，方便对照。
5.1 编译期：cmake、GLEW 与 Boost
第一条，cmake 版本不够。现象是配置 instant-ngp 时直接报 cmake 版本低于要求，或者报一堆 policy 相关的警告后中断。原因是系统自带 cmake 往往在 3.16 左右，低于 3.22 的硬性门槛。解决办法是按 2.2 节装 3.22 以上版本，装完必须hash -r，否则你以为切了版本，实际调用的还是老的。
第二条，GLEW 找不到。现象是Could NOT find GLEW (missing: GLEW_INCLUDE_DIRS GLEW_LIBRARIES)。原因是 instant-ngp 依赖 OpenGL 相关的开发库，系统只装了运行时没装开发头文件。解决是一条命令：sudo apt install libglew-dev，装完重新 cmake，不要删 build 目录，增量配置就能过。
第三条，Boost 组件缺失。现象是 gtsam 配置阶段报找不到 serialization、system、filesystem 等一串库，要求最低 1.65。原因是包管理器装的 Boost 版本低或者拆包不全。解决是按 2.3 节源码编译 1.73.0，装完ldconfig刷新缓存，再重新配置 gtsam。这条最容易反复，因为编译日志很长，Boost 的错误藏在中间，要往下翻。
5.2 运行期：submodule、torch ABI 与 gtsam import
第四条，thirdparty 目录是空的。现象是 cmake 报找不到./thirdparty/instant-ngp或者 gtsam 目录不存在。原因是 clone 时没加--recurse-submodules，子模块只有空目录。解决是进仓库根目录执行git submodule update --init --recursive，跑完检查 thirdparty 下每个子目录里是否有实际文件，而不是只有.git。
第五条，gtsam 编译成功但 import 失败。现象是import gtsam报 ModuleNotFoundError。原因是 wrapper 编出来的.so在build_gtsam/python下，没进 Python 的搜索路径。解决是把这个目录加进PYTHONPATH，或者在虚拟环境里做个.pth文件指向它。注意别把整个 build 目录加进去，里面还有别的同名模块，容易 import 到错的那个。
这五条里，前三条是环境问题，后两条是路径和状态问题。判断方法很简单：报错发生在 cmake 配置阶段，往依赖上查；发生在 python 运行时，往路径和 ABI 上查。
6. 跑通之后：用短序列验证，别急着上长数据
第一次跑通就上几百帧的长序列，是最容易打击积极性的一步。长序列会把 Tracking 的漂移、Mapping 的收敛速度、显存占用三个问题同时暴露出来，你分不清是哪一环出的错。我一般先用二三十帧的短序列做冒烟测试，确认 Tracking 输出的位姿轨迹没有明显跳变，再跑 Mapping 看深度图是否贴合，最后才换长数据。
6.1 两段式冒烟测试
第一段只跑 Tracking，把估计位姿和真值位姿画在同一张图上，看轨迹形状和尺度。轨迹整体缩放但形状对，多半是单目尺度问题，正常；轨迹在中途突然折返或者跳变，是跟踪丢了，先查帧间重叠和协方差阈值。第二段接 Mapping，每隔固定步数存一张渲染深度图，和输入深度图对比，重点看无纹理区域和遮挡边缘，这两处最能暴露加权损失有没有生效。
如果短序列都过不了，不要怀疑网络结构，九成是数据对齐问题：时间戳、相机内参、图像分辨率的缩放系数，任何一处不一致都会让投影残差系统性偏。我的习惯是把这几项打印出来逐帧核对，比看 loss 曲线快得多。
6.2 一个能立刻用的技巧：按协方差阈值控制深度监督
深度损失按协方差加权是文档给的做法，实际使用时可以再加一道硬阈值：协方差超过某个分位数的像素，直接不参与深度监督，只保留颜色监督。原因是加权只能降低坏像素的影响，权重再小也在贡献梯度，而遮挡边缘的深度误差往往是数量级的，加权压不住。
def masked_depth_loss(depth_pred, depth_meas, cov, lam_d=1.0, q=0.9, eps=1e-6): # 按协方差分位数做硬阈值，最不可信的一批像素直接不监督 thr = np.quantile(cov, q) mask = cov <= thr if mask.sum() == 0: return 0.0 w = 1.0 / (cov[mask] + eps) w = w / w.mean() l_depth = (w * (depth_pred[mask] - depth_meas[mask]) ** 2).mean() return lam_d * l_depthq控制保留比例，0.9 表示丢掉协方差最高的 10%，无纹理场景可以降到 0.7，纹理丰富的室内场景保持 0.9 就够。这个阈值不要设得太狠，丢太多像素会让深度监督失效，重建表面会变平。从那以后我每次复现这类带置信度的 SLAM 前端，都会先把协方差分布画出来，再决定阈值放哪，不再凭感觉设。
希望帮到你。
本文还有配套的精品资源，点击获取
