简介这份文档面向希望深入理解或复现NeRF-SLAM的研究者与工程实践者聚焦神经辐射场与SLAM结合的三维重建方案。内容围绕Tracking与Mapping两大阶段展开Tracking部分讲解基于Droid SLAM与RAFT光流估计的稠密单目SLAM以及DBA层如何借助舒尔补与Cholesky分解优化相机位姿和逆深度Mapping部分则剖析Instant-NGP哈希编码加速的概率体素化NeRF并说明Mapping Loss与深度损失函数如何平衡深度和颜色监督应对噪声深度图与无纹理区域。作者还记录了复现过程中遇到的问题与解决方案对理解该工作的技术细节具有较高参考价值。资源为单个docx文档压缩包约11.01MB结构紧凑便于系统阅读与对照实验。目前已有2316人学习适合具备一定SLAM与深度学习基础、希望快速上手NeRF-SLAM复现的读者参考。1. nerf-slam 复现环境搭建从单目图像到稠密重建的完整链路nerf-slam 的复现文档本质上是一份把 NeRF 和 SLAM 拼在一起的工程记录。传统视觉 SLAM 像 ORB-SLAM 走的是稀疏关键点路线工程上稳、跑得快但建出来的图是点云骨架稠密重建一直是个短板。nerf-slam 换了个思路Tracking 端用 Droid SLAM 从连续单目图像里估计位姿和深度Mapping 端用 Instant-NGP 的 NeRF 做概率体素化重建深度监督还带边缘协方差加权。听起来很美但装起来是真的折腾——cmake 版本、Boost 编译、GLEW 缺失、gtsam 的 Python wrapper每一步都可能卡住。这篇笔记面向的是想把这套环境从零跑通的开发者尤其是那些卡在编译环节、不确定该装哪个版本、报错不知道往哪查的人。下面按「装什么 → 怎么装 → 坏了怎么救」的顺序走一遍。2. 环境准备与依赖版本选择CUDA 11.3 torch 1.12.1 这条线怎么定2.1 先确认显卡驱动和 CUDA 版本nerf-slam 的 Tracking 端依赖 Droid SLAM 的 RAFT 光流估计Mapping 端依赖 Instant-NGP 的 hash 编码 NeRF两者都对 CUDA 版本敏感。项目正文里给出的 torch 安装命令是torch1.12.1cu113这意味着 CUDA 运行时版本要对应 11.3。我一般会先跑一遍nvidia-smi看驱动支持的 CUDA 上限再用nvcc --version确认本地 CUDA toolkit 版本。如果驱动太新、CUDA 太旧torch 装上去可能 import 就报libcudart.so找不到反过来 CUDA 太新Instant-NGP 编译时可能因为算力架构不匹配直接挂掉。# 查看驱动支持的 CUDA 版本上限 nvidia-smi # 查看本地 CUDA toolkit 版本 nvcc --version # 确认 gcc/g 版本Instant-NGP 对编译器有要求 gcc --version g --versionnvidia-smi右上角显示的 CUDA Version 是驱动能支持的最高运行时版本不是你实际装的 toolkit 版本。nvcc --version才是你编译时用的。两者不一致是常态但 torch 的 cu113 包要求运行时至少能兼容 11.3。如果本地是 CUDA 12.x建议用 conda 装一个 11.3 的运行时环境而不是硬降系统 CUDA。2.2 Python 虚拟环境与 torch 安装项目正文明确要求用 virtual environment这一步别省。nerf-slam 的依赖里既有 torch 这种大件又有 gtsam 的 Python wrapper混在系统 Python 里后面出问题很难排查。我一般用 conda 建一个 Python 3.8 或 3.9 的环境因为 torch 1.12.1 对 3.10 的支持还不算稳。# 创建并激活虚拟环境 conda create -n nerf-slam python3.9 -y conda activate nerf-slam # 安装 torch 1.12.1 cu113 pip install torch1.12.1cu113 torchvision0.13.1cu113 --extra-index-url https://download.pytorch.org/whl/cu113 # 验证 torch 能否正常调用 CUDA python -c import torch; print(torch.__version__, torch.cuda.is_available())--extra-index-url指向 PyTorch 官方的 cu113 轮子仓库不加这个参数 pip 会去默认源找大概率找不到对应版本。装完一定要跑一遍torch.cuda.is_available()返回 False 的话后面 Instant-NGP 编译出来也跑不了 GPU。如果返回 False先检查驱动版本是否满足 cu113 的最低要求再检查 conda 环境里有没有混入系统 torch。2.3 安装项目 requirements 和 gtsam Python 依赖torch 装好之后按项目正文的顺序装两层 requirements根目录的requirements.txt和thirdparty/gtsam/python/requirements.txt。后者是 gtsam Python wrapper 的依赖很多人只装第一层后面编译 gtsam 时才发现 Python 绑定缺东西。# 进入 nerf-slam 根目录 cd NeRF-SLAM # 安装主依赖 pip install -r requirements.txt # 安装 gtsam Python wrapper 依赖 pip install -r ./thirdparty/gtsam/python/requirements.txt这两步一般不会有大问题但如果requirements.txt里锁了某个和 torch 1.12.1 冲突的包版本pip 会尝试降级 torch。装完再跑一次pip show torch确认版本没被改掉。常见做法是先把 requirements 里的 torch 行注释掉装完其他依赖再单独装 torch。3. 编译 Instant-NGP 与 gtsamcmake 版本、GLEW、Boost 三个坑3.1 cmake 版本管理3.22 是底线项目正文里反复提到 cmake 版本问题Instant-NGP 要求 cmake 3.22。但系统自带的 cmake 往往是 3.16 甚至更低直接apt install cmake也升不到 3.22。正文里给了三种升级方式源码编译 3.22、3.9、3.26。我一般推荐直接上 3.26.3因为 3.22.0-rc2 是候选版有些环境里make install后cmake --version还是旧版本需要hash -r刷新 shell 的命令缓存。# 下载 cmake 3.26.3 源码 wget https://cmake.org/files/v3.26/cmake-3.26.3.tar.gz --no-check-certificate # 解压并编译安装 tar -xvf cmake-3.26.3.tar.gz cd cmake-3.26.3/ ./configure sudo make sudo make install # 刷新命令缓存并验证 hash -r cmake --version./configure不加--prefix默认装到/usr/local会覆盖系统旧版 cmake。hash -r是必须的否则 shell 还在用旧的路径缓存cmake --version显示的还是老版本。如果装完发现版本没变先which cmake看路径是不是/usr/local/bin/cmake不是的话检查/usr/local/bin是否在PATH前面。3.2 编译 Instant-NGPGLEW 缺失与 build 目录cmake 到位后进入 nerf-slam 目录编译 Instant-NGP。项目正文里的命令是cmake ./thirdparty/instant-ngp -B build_ngp这一步最常见的报错是Could NOT find GLEW。GLEW 是 OpenGL 扩展加载库Instant-NGP 的可视化部分依赖它但很多最小化安装的系统里没有。# 安装 GLEW 开发库 sudo apt install libglew-dev # 重新 cmake 配置 cmake ./thirdparty/instant-ngp -B build_ngp # 编译RelWithDebInfo 平衡速度和调试信息 cmake --build build_ngp --config RelWithDebInfo -j-B build_ngp指定构建目录避免污染源码树。--config RelWithDebInfo是 Release 加调试符号比纯 Release 慢一点但出问题能看栈。-j不加参数会用满所有核内存小的机器可能 OOM建议-j4或-j8保守一点。如果编译到一半报 CUDA 架构不匹配检查CMAKE_CUDA_ARCHITECTURES是否包含了你的显卡算力。3.3 编译 gtsamBoost 1.65 的源码安装gtsam 是 Droid SLAM 做 DBA 优化的后端项目正文要求-DGTSAM_BUILD_PYTHON1开启 Python wrapper。这一步的经典报错是Could NOT find Boost (missing: Boost_INCLUDE_DIR serialization system filesystem thread program_options date_time timer chrono regex)意思是系统 Boost 版本低于 1.65 或者缺组件。Ubuntu 自带的 Boost 往往版本够但组件不全最稳的办法是源码编译 Boost 1.73.0。# 下载 Boost 1.73.0 wget https://boostorg.jfrog.io/artifactory/main/release/1.73.0/source/boost_1_73_0.tar.bz2 --no-check-certificate # 解压并编译安装 tar xvf boost_1_73_0.tar.bz2 cd boost_1_73_0 ./bootstrap.sh sudo ./b2 --buildtypecomplete install--buildtypecomplete会编译所有库包括 gtsam 需要的 serialization、system、filesystem、thread、program_options、date_time、timer、chrono、regex。耗时比较长但省得后面缺组件再回来补。默认装到/usr/local/lib和/usr/local/include如果系统里有多个 Boost 版本编译 gtsam 时可能需要显式指定-DBOOST_ROOT/usr/local。装完 Boost 后重新跑 gtsam 的 cmakecmake ./thirdparty/gtsam -DGTSAM_BUILD_PYTHON1 -B build_gtsam-DGTSAM_BUILD_PYTHON1是开启 Python 绑定的关键不加的话后面 Python 里import gtsam会失败。如果 cmake 通过了但编译时报 Python 头文件找不到检查PYTHON_EXECUTABLE是否指向了当前 conda 环境的 Python。4. 避坑与常见问题排查编译失败、Python 绑定、数据集路径4.1 cmake 版本切换后命令缓存不刷新现象源码编译安装了 cmake 3.26cmake --version还是显示 3.16。原因shell 的命令哈希表缓存了旧路径hash -r没执行或者/usr/local/bin不在PATH前面。解决先hash -r再which cmake确认路径如果还是旧版在~/.bashrc里把/usr/local/bin加到PATH最前面重新source。4.2 Instant-NGP 编译报 GLEW 找不到现象cmake ./thirdparty/instant-ngp -B build_ngp报Could NOT find GLEW (missing: GLEW_INCLUDE_DIRS GLEW_LIBRARIES)。原因系统没装 GLEW 开发包或者装了但 cmake 找不到头文件路径。解决sudo apt install libglew-dev如果已经装了还报错检查/usr/include/GL/glew.h是否存在不存在的话可能是包名不对试libglew2.2或libglew-dev的具体版本。4.3 gtsam 编译时 Boost 组件缺失现象cmake 配置 gtsam 时报 Boost 缺少 serialization、system 等组件。原因系统 Boost 版本低于 1.65或者只装了部分组件。解决按 3.3 节源码编译 Boost 1.73.0--buildtypecomplete全量安装。如果不想全量至少确保--with-serialization --with-system --with-filesystem --with-thread --with-program_options --with-date_time --with-timer --with-chrono --with-regex这些组件都编译。4.4 Python 绑定 import gtsam 失败现象编译完 gtsam 后Python 里import gtsam报ModuleNotFoundError或ImportError: libgtsam.so not found。原因gtsam 的 Python 模块没装到当前 conda 环境的 site-packages或者LD_LIBRARY_PATH没包含 gtsam 的库路径。解决编译完 gtsam 后在build_gtsam目录里跑make python-install或者手动把build_gtsam/python加到PYTHONPATH。库路径问题的话在~/.bashrc里加export LD_LIBRARY_PATH/usr/local/lib:$LD_LIBRARY_PATH。4.5 数据集路径与配置文件不匹配现象跑Run步骤时程序报找不到图像或深度文件。原因nerf-slam 的配置文件里数据集路径是硬编码的相对路径和实际下载的数据集目录结构不一致。解决先看configs目录下的 yaml 文件确认data_path指向的目录层级再把下载的数据集按对应结构放好。常见做法是建一个data目录把数据集解压进去然后改 yaml 里的路径为绝对路径避免相对路径的歧义。5. 装完怎么验证跑通从单帧重建到轨迹一致性检查环境编译完只是第一步真正跑通要看 Tracking 和 Mapping 两端能不能对上。我一般会分三层验证先确认 Instant-NGP 能单独渲染再确认 gtsam 的 Python 绑定能调 DBA最后跑一段短序列看轨迹和重建结果是否一致。5.1 验证 Instant-NGP 独立渲染在build_ngp目录下应该有编译出来的可执行文件。先拿一张示例图像跑一遍 NeRF 训练确认 CUDA 和 hash 编码没问题。# 进入 Instant-NGP 构建目录 cd build_ngp # 用示例数据跑一次训练确认渲染管线正常 ./instant-ngp --scene data/nerf/fox --n_steps 1000--scene指向示例场景--n_steps限制训练步数先跑 1000 步看有没有报错。如果报 CUDA 错误检查 torch 和 Instant-NGP 用的 CUDA 运行时是否一致。如果渲染出来是黑图检查相机位姿文件格式是否匹配。5.2 验证 gtsam Python 绑定gtsam 的 Python wrapper 是 Droid SLAM 做 DBA 的关键验证方式是在 Python 里构造一个简单的因子图并求解。import gtsam import numpy as np # 构造一个简单的位姿图 graph gtsam.NonlinearFactorGraph() initial gtsam.Values() # 添加先验因子 prior_noise gtsam.noiseModel.Diagonal.Sigmas(np.array([0.1, 0.1, 0.1])) graph.add(gtsam.PriorFactorPose2(1, gtsam.Pose2(0, 0, 0), prior_noise)) initial.insert(1, gtsam.Pose2(0, 0, 0)) # 求解 params gtsam.LevenbergMarquardtParams() optimizer gtsam.LevenbergMarquardtOptimizer(graph, initial, params) result optimizer.optimize() print(result.atPose2(1))这段代码构造了一个最简单的 Pose2 因子图能跑通说明 gtsam 的 Python 绑定和底层库都正常。如果import gtsam就失败回到 4.4 节检查路径。如果求解时报IndeterminantLinearSystemException说明因子图约束不够这是正常的换一个带更多因子的例子再试。5.3 跑短序列验证 Tracking 与 Mapping 一致性前两步都过了之后找一段短的单目图像序列跑完整流程。重点看两个指标Tracking 输出的位姿轨迹是否平滑Mapping 重建的深度图边缘是否和 RGB 边缘对齐。# 在 nerf-slam 根目录跑短序列 python run.py --config configs/nerf_slam.yaml --data data/short_sequence --max_frames 50--max_frames 50限制帧数先跑 50 帧看有没有崩溃。跑完后检查输出目录里的轨迹文件和重建 mesh。轨迹文件如果出现跳变可能是 RAFT 光流估计在无纹理区域失效这是 Droid SLAM 的已知问题不是环境装错了。重建 mesh 如果边缘模糊检查深度损失的协方差加权是否生效λD参数在配置文件里默认是 1.0可以试着调到 0.5 或 2.0 看效果变化。5.4 一个我踩过的坑验证顺序不能反我第一次装的时候环境编译完直接跑完整序列结果 Tracking 跑到一半就崩了报的是 gtsam 的 DBA 求解失败。查了半天以为是 Boost 版本问题重装了两遍 Boost 还是不行。后来把 Instant-NGP 和 gtsam 分开验证才发现是 gtsam 的 Python 绑定没装到 conda 环境里程序实际调用的是系统 Python 的旧版 gtsam。从那以后我每次装完这套环境都强制走一遍「Instant-NGP 单帧渲染 → gtsam 因子图求解 → 短序列完整跑」这三步不跳步。希望帮到你。本文还有配套的精品资源点击获取