做视觉定位和机器人感知这行的ORB-SLAM这个名字基本绕不过去。不管你是要做一个室内的移动机器人、做 AR 的位姿跟踪、还是单纯想搞明白相机怎么知道自己走到了哪儿它都是一个极佳的起点——开源、论文写得清楚、社区活跃、跑数据集能出结果。而ORB-SLAM2作为它的第二代补上了双目和 RGB-D 的完整支持把回环、重定位、全局优化这一整套流程做成了开箱可用的形态成了后来无数 SLAM 系统的性能对照基线。但这东西有个很典型的特点论文看着顺装起来烦。依赖库版本对不上、Pangolin 编译报错、OpenCV 4 和 3 的 API 打架、Vocabulary 加载慢得像卡死、跑完不知道结果到底好不好——这些坑几乎每个人都得踩一遍。我这几年帮同事、帮学生装过不下二十遍 ORB-SLAM2从 Ubuntu 16 一路装到 22从裸机装到虚拟机、Docker多少攒了点经验。这篇东西就是把这些经验摊开讲。前半部分聊 ORB-SLAM 到底是怎么工作的为什么它能跑得又快又稳后半部分是完整的安装、编译、测试流程包括三种传感器模式的跑法、轨迹精度的评估方法以及一张我自己整理的报错速查表。适合刚开始接触 SLAM 的本科生、研究生也适合需要在项目里快速搭一个视觉里程计基线的工程同学。不需要你先精通图优化只要会基本的 Linux 操作和一点 C 就能跟上。1. 先把 ORB-SLAM 这件事说清楚1.1 它是怎么把看变成走的视觉 SLAM 的核心问题可以一句话概括给我一串图像我得同时算出相机每一帧的位置以及周围环境的三维结构。这两件事是互相依赖的——你知道自己在哪才能正确地把观测到的点放到地图上你有了一张准确的地图才能反推自己现在在哪。这就是所谓的鸡生蛋问题也是 SLAM 和普通的三维重建最本质的区别。ORB-SLAM 的解法是基于特征点的稀疏方法。它在每一帧里提取 ORB 特征点用 oFAST 做关键点检测用旋转不变的 rBRIEF 做描述子。这套特征的最大优点是快而且带方向信息图像旋转后还能匹配上。默认每帧提取 1000 个点构建 8 层图像金字塔尺度因子取 1.2。这三个参数不是随手定的金字塔层数决定了系统能容忍多大的尺度变化8 层配合 1.2 的因子理论上能覆盖大约 2.5 倍的尺度跨度每层内部还有一个 FAST 阈值的自适应策略先用较高阈值iniThFAST通常 20提点如果某层提不够就把阈值降到 minThFAST通常 7再提一次保证在纹理弱的场景下也能凑够特征。提取完之后帧与帧之间做描述子匹配用 RANSAC 剔除外点再通过三角化把匹配点变成三维地图点。相机位姿就用这些三维点做 PnP 求解。这套流程听起来很像传统的视觉里程计但 ORB-SLAM 真正厉害的地方在于它把局部一致性和全局一致性分成了不同层次来处理。1.2 三线程加全局 BA四个角色各司其职ORB-SLAM 最经典的设计是多线程并行架构初代是三个线程ORB-SLAM2 又加了第四个。我习惯把它类比成一个四人小组Tracking 线程跟踪线程跑得最快负责实时处理每一帧图像。它要做的事是提取特征、跟上一帧或者局部地图做匹配、估计当前位姿、决定这一帧是不是关键帧。这个线程必须保证帧率所以它只做必要的最小计算。如果跟丢了它会触发重定位用词袋模型在已有关键帧里找候选再用 PnP RANSAC 把位姿找回来。Local Mapping 线程局部建图线程把新来的关键帧插进地图三角化新的地图点剔除质量差的观测然后在一个滑动窗口内一般是关键帧共视图里邻近的几十帧做局部光束法平差Local BA。它解决的是局部地图准不准的问题。Loop Closing 线程回环检测线程用 DBoW2 词袋模型在历史关键帧里找相似场景。一旦判定回环它会先算一个 Sim3 相似变换因为单目有尺度漂移回环两端的尺度不一致然后做位姿图优化把累积的漂移拉回去。Full BA 线程全局 BA 线程这是 ORB-SLAM2 才独立出来的。回环完成之后它会在后台对整个地图做一次完整的束调整同时把地图点做融合和冗余关键帧剔除。因为全局 BA 很慢放后台跑可以避免拖慢实时跟踪。这四个线程之间的同步靠互斥锁和标记位控制逻辑写得相当紧凑。理解这个架构之后你看它的代码结构会清晰很多——System.cc是总调度Tracking.cc、LocalMapping.cc、LoopClosing.cc各管一摊Map、KeyFrame、MapPoint是数据结构ORBextractor和ORBmatcher是底层工具。注意很多新手第一次读代码会卡在Track()函数里那几种模式切换SYSTEM_NOT_READY、NO_IMAGES_YET、NOT_INITIALIZED、OK、LOST上。建议先跑通再读代码带着现在系统在什么状态、为什么走这个分支的问题去看效率会高很多。1.3 单目、双目、RGB-D三条路的差别在哪ORB-SLAM2 同时支持三种传感器配置但它们的初始化方式和难度完全不同这块必须讲清楚否则你装完了不知道选哪个跑。单目模式最麻烦。单张图像没法直接恢复尺度所以系统启动时必须做一次地图初始化它会并行计算两张图之间的单应矩阵 H 和基础矩阵 F看哪个模型的得分更高、内点更多就用哪个来恢复初始位姿和一组三维点。这个过程可能需要等相机平移一段距离才成功启动阶段很容易失败。而且单目天然存在尺度不确定和尺度漂移回环的时候必须用 Sim3 处理。双目模式简单得多。左右目图像直接三角化就能得到三维点第一帧就能初始化尺度由基线物理长度确定不会漂。代价是你需要事先做好双目校正代码里是通过KITTI例子那种已经 rectified 好的图像对来跑的。RGB-D 模式同样是第一帧就初始化。深度图直接给出每个像素的距离省掉了三角化但深度相机的量程和噪声是硬伤——太近没有深度太远噪声爆炸玻璃、镜面、黑色物体直接测不到。代码里通过DepthMapFactor把 16 位无符号深度值换算成米TUM 数据集的这个因子是 5000。选哪个如果你只是学习建议从 RGB-D 的 TUM 数据集入手初始化简单、失败率低、结果直观。如果做室外大场景或者车载就上双目 KITTI。单目放在最后因为它最考验调参和耐心。2. 装之前先想清楚环境与依赖的取舍2.1 系统和硬件以及你可能低估的时间成本官方 README 里写的依赖是 Ubuntu 14.04/16.04 加 OpenCV 2.4.3 以上但那套描述已经很老了。按我实际的经验Ubuntu 18.04 是甜点区20.04 也能跑但 OpenCV 和 Pangolin 需要额外处理22.04 走通的人少一些因为默认 OpenCV 版本更高、Boost 和 Eigen 的路径有变化。如果条件允许直接用 Ubuntu 18.04 的 Docker 镜像是省事的选择如果只能用本机那就做好折腾版本的准备。硬件方面编译阶段最吃的是内存。ORB-SLAM2 本身不大但它要带你编译 Thirdparty 里的 g2o 和 DBoW2再加一个 OpenCV 源码编译——OpenCV 3.4 编译期间单个编译单元峰值可能吃掉 1GB 以上内存。如果机器只有 2GB 内存还开make -j4大概率会看到编译进程被 OOM Killer 干掉报出来的错还特别迷惑比如internal compiler error: Killed (program cc1plus)。这种情况九成是内存不够不是代码问题。时间上我给个大致参考i5 四核8GB 内存环节大致耗时说明装基础依赖包3-5 分钟apt 安装看网速编译 Pangolin3-8 分钟体量小编译 OpenCV 3.430-60 分钟最慢的一步-j别开太大编译 ORB-SLAM2 主工程10-25 分钟含 g2o、DBoW2下载测试数据集视情况TUM 一个序列几百 MBKITTI 一个序列 20GB 上下实操心得编译 OpenCV 的时候别闲着手贱去开一堆浏览器。我见过好几次编译到 80% 被系统杀掉的回头重来一遍气到想砸键盘。要么留足内存要么make -j1慢慢磨。2.2 五个依赖库各自的定位和版本红线ORB-SLAM2 的依赖可以分成必须自己装和仓库自带两类分清楚了能省不少事。必须自己装的三位OpenCV负责图像读写、特征相关的一些辅助、以及cv::Mat这套数据结构。版本红线在这里官方代码是按 OpenCV 3 写的如果系统里是 OpenCV 4编译一定会报错。最常见的是CV_LOAD_IMAGE_UNCHANGED、CV_LOAD_IMAGE_GRAYSCALE这些宏在 4.x 里被删掉了得改成cv::IMREAD_UNCHANGED、cv::IMREAD_GRAYSCALE另外cv::FileStorage的一些行为也有差异。要么装 OpenCV 3.4.x要么手动改代码适配 4.x两条路都有人走但新手我强烈建议前者。Eigen3是线性代数库做矩阵运算、求解器都要用。要求 3.1.0 以上一般apt install libeigen3-dev装的版本就够。唯一要注意的是 Eigen 的内存对齐问题——它为了 SIMD 加速会对固定大小的矩阵类型做 16 字节对齐如果你把这些类型放进 STL 容器里又没加EIGEN_MAKE_ALIGNED_OPERATOR_NEW会直接段错误而且崩的位置往往离问题源头很远极难查。ORB-SLAM2 里已经处理好了但你自己改代码加容器的时候要留心。Pangolin是可视化库负责弹那个带轨迹和点云的窗口。这块是版本冲突的重灾区。Pangolin v0.5 和 ORB-SLAM2 是同一个时代的产物配合最顺。v0.6 之后 API 变了会出现glLineWidth相关报错、头文件路径变化、字体加载路径问题。我一般直接git checkout v0.5别贪新。仓库自带的两位DBoW2是词袋模型库负责回环检测和重定位。它依赖一个离线训练好的字典文件ORBvoc.txt仓库里自带大约 145MB。第一次运行程序时会加载这个字典耗时可能到 5-20 秒屏幕上一个字都不输出看起来像卡死了。别急着 CtrlC等一下就好。g2o是通用图优化库负责所有的位姿图优化和 BA。ORB-SLAM2 把它放在Thirdparty/g2o里编译主工程时会一起编译。它有个老生常谈的坑在较新的 GCC 下编译会报usleep was not declared in this scope因为unistd.h没被隐式包含手动加一行#include unistd.h就行。2.3 一张版本兼容对照表我把实际验证过的组合列一下照着选能避开大部分坑组件推荐版本可接受范围高风险版本备注系统Ubuntu 18.0416.04 / 20.0422.0422.04 需处理 OpenCV 4OpenCV3.4.163.2 - 3.4.x4.x4.x 需改源码宏定义Eigen33.3.4≥3.1.0—apt 版本通常够用Pangolinv0.5v0.5 - v0.6v0.8新版 API 变化大CMake3.10≥2.8—apt 版本即可GCC7.55 - 910新版本注意 usleep3. 从零编译 ORB-SLAM2 的完整实操3.1 基础工具链与源码落位先把编译工具和一票系统库装上。这一步骤看着平淡但漏装某个-dev包后面就会在莫名其妙的地方报找不到头文件。我习惯一次性打全sudo apt update sudo apt install -y build-essential cmake git pkg-config sudo apt install -y libglew-dev libboost-dev libboost-thread-dev sudo apt install -y libgtk2.0-dev libavcodec-dev libavformat-dev sudo apt install -y libjpeg-dev libswscale-dev libtiff5-dev sudo apt install -y libeigen3-dev libpython2.7-dev这里几个包的用途值得说明libglew-dev是 Pangolin 需要的 OpenGL 扩展加载库libboost-*-dev提供线程和系统支持libgtk2.0-dev是 OpenCV 的 highgui 模块弹窗用的如果没有它OpenCV 编译会静默去掉窗口显示功能后面 Pangolin 也可能出问题libavcodec-dev那一串是视频编解码读视频文件用的。很多人图省事只装前两行结果 OpenCV 编完了发现没法显示图像回头重编白等一小时。目录规划上我建议建一个统一的工作区别到处乱放mkdir -p ~/slam_ws cd ~/slam_ws后面的 Pangolin、OpenCV、ORB_SLAM2、数据集全都放这个目录下路径清晰出问题好排查也方便后面写脚本一键清理。3.2 Pangolin 与 OpenCV 的编译细节Pangolin 先编而且必须锁 v0.5cd ~/slam_ws git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin git checkout v0.5 mkdir build cd build cmake -DCMAKE_BUILD_TYPERelease .. make -j2 sudo make install sudo ldconfig-DCMAKE_BUILD_TYPERelease这个参数别省。默认是空构建类型等于没开优化Pangolin 这种要频繁调 OpenGL 的库Debug 下跑起来会明显卡顿而且体积也大。make -j2而不是-j4是因为 Pangolin 的某些编译单元很吃内存双核并行更稳。OpenCV 一定要装 3.4.x装到一个独立前缀更方便管理cd ~/slam_ws git clone https://github.com/opencv/opencv.git cd opencv git checkout 3.4.16 mkdir build cd build cmake -D CMAKE_BUILD_TYPERelease \ -D CMAKE_INSTALL_PREFIX/usr/local \ -D OPENCV_ENABLE_NONFREEOFF \ -D BUILD_EXAMPLESOFF \ -D BUILD_TESTSOFF \ .. make -j2 sudo make install sudo ldconfig几个参数解释一下。BUILD_EXAMPLESOFF和BUILD_TESTSOFF能省掉大量编译时间你又不看官方示例没必要编。OPENCV_ENABLE_NONFREEOFF关掉专利算法ORB-SLAM2 用不到。装到/usr/local之后再ldconfig刷新动态库缓存让系统能找到新装的.so文件。注意如果你系统里之前用 apt 装过libopencv-dev会和源码安装的 3.4 打架。检查方法是pkg-config --modversion opencv和pkg-config --modversion opencv4都跑一下看返回什么版本。冲突严重的话先把 apt 版本卸干净再编源码版。验证一下装好了没pkg-config --modversion opencv # 应该输出 3.4.163.3 build.sh 编译全过程与踩坑源码和编译cd ~/slam_ws git clone https://github.com/raulmur/ORB_SLAM2.git ORB_SLAM2 cd ORB_SLAM2 chmod x build.sh ./build.shbuild.sh这个脚本干的事很直白先编译Thirdparty/DBoW2再编译Thirdparty/g2o最后编译主工程然后把生成的库复制到lib/目录。但它有个众所周知的毛病——make -j的并行度是写死在脚本里的机器弱一点就直接被压垮。打开build.sh你会看到类似make -j$(nproc)的写法。如果内存小于 8GB我建议手动改成make -j2# 编辑 build.sh把 make -j 改成 make -j2 sed -i s/make -j/make -j2/g build.sh ./build.sh编译过程中最容易撞上的几个报错我先在这里说清楚你遇到了可以直接对照第一个g2o 的usleep报错。报错信息形如error: usleep was not declared in this scope。原因是新版 glibc 收紧了头文件包含解决方法是在Thirdparty/g2o/g2o/stuff/timeutil.cpp顶部加上#include unistd.h第二个OpenCV 4 的宏报错。形如CV_LOAD_IMAGE_UNCHANGED was not declared in this scope。如果你非要用 OpenCV 4就全局替换这两个宏sed -i s/CV_LOAD_IMAGE_UNCHANGED/cv::IMREAD_UNCHANGED/g src/*.cc include/*.h sed -i s/CV_LOAD_IMAGE_GRAYSCALE/cv::IMREAD_GRAYSCALE/g src/*.cc include/*.h sed -i s/CV_LOAD_IMAGE_COLOR/cv::IMREAD_COLOR/g src/*.cc include/*.h第三个Boost 链接错误。形如undefined reference to symbol _ZN5boost6system15system_categoryEv说明boost_system没链上。在CMakeLists.txt里找到链接部分补上-lboost_system就行。第四个C11 相关的报错。如果报std::... is not a member之类的去CMakeLists.txt确认有-stdc11这个编译选项有些系统默认标准还在 C98。第五个OOM 中断。前面提过报错通常是c: internal compiler error: Killed。降并行度、加 swap 或者换机器。3.4 环境变量、库路径与装好了的判定标准编译顺利结束后ORB_SLAM2/lib/下应该有三个.so文件libORB_SLAM2.so、libDBoW2.so、libg2o.so。这三个都在说明主体编译成功。接下来是把它们挂到系统库路径上让运行时能找到sudo echo /home/$USER/slam_ws/ORB_SLAM2/lib /etc/ld.so.conf.d/orb-slam2.conf sudo echo /home/$USER/slam_ws/ORB_SLAM2/Thirdparty/DBoW2/lib /etc/ld.so.conf.d/orb-slam2.conf sudo echo /home/$USER/slam_ws/ORB_SLAM2/Thirdparty/g2o/lib /etc/ld.so.conf.d/orb-slam2.conf sudo ldconfig更简单的做法是直接在~/.bashrc里加一行export LD_LIBRARY_PATH$LD_LIBRARY_PATH:~/slam_ws/ORB_SLAM2/lib:~/slam_ws/ORB_SLAM2/Thirdparty/DBoW2/lib:~/slam_ws/ORB_SLAM2/Thirdparty/g2o/lib然后source ~/.bashrc。但要注意LD_LIBRARY_PATH会影响所有程序如果和你项目里其他软件冲突还是用ld.so.conf.d的方式更干净。验证一下ldd lib/libORB_SLAM2.so | grep not found如果没有输出说明所有依赖都能找到这才是真正装好了的标志。很多人以为build.sh跑完没报错就完事结果一运行就error while loading shared libraries白折腾半天。4. 测试数据集跑通与精度评估4.1 三种模式对应的数据集与配置ORB-SLAM2 的Examples/目录下把三种模式的启动程序都编好了配置文件也都在你需要做的就是下数据、对号入座。模式推荐数据集可执行文件配置文件单目TUM RGB-D 的 RGB 部分Examples/Monocular/mono_tumExamples/Monocular/TUM1.yaml双目KITTI Odometry / EuRoCExamples/Stereo/stereo_kittiExamples/Stereo/KITTI00-02.yamlRGB-DTUM RGB-D 完整序列Examples/RGB-D/rgbd_tumExamples/RGB-D/TUM1.yaml为什么配置文件要分 TUM1、TUM2、TUM3因为 TUM 的三个序列组是用不同相机拍的fr1 对应 Kinect 的某个标定参数fr2、fr3 各对应另外一组。内参不一样用错了 yaml 跑出来的轨迹会明显偏移。所以下数据的时候下的是freiburg1_xyz就配TUM1.yaml下的是freiburg2_desk就配TUM2.yaml。KITTI 同理00-02、03、04-12 分了三套标定年份不同的采集车激光和相机的外参有差异。先下一个小的试水TUM 的fr1/xyz序列只有几百兆跑起来大概三十秒非常适合验证环境cd ~/slam_ws wget https://vision.in.tum.de/rgbd/dataset/freiburg1/rgbd_dataset_freiburg1_xyz.tgz tar -xzf rgbd_dataset_freiburg1_xyz.tgz序列目录里会有rgb/、depth/、groundtruth.txt还有一个关键文件associations/fr1_xyz.txt——它把每一帧彩色图和对应时间戳的深度图配好了对。ORB-SLAM2 只接受这种配套输入不会自己去猜哪张深度图对应哪张彩色图所以这个文件不能少。4.2 逐条命令与输出解读RGB-D 模式跑起来cd ~/slam_ws/ORB_SLAM2 ./Examples/RGB-D/rgbd_tum \ Vocabulary/ORBvoc.txt \ Examples/RGB-D/TUM1.yaml \ /home/$USER/slam_ws/rgbd_dataset_freiburg1_xyz \ /home/$USER/slam_ws/rgbd_dataset_freiburg1_xyz/associations/fr1_xyz.txt命令停下来之后你会发现目录里多了两个文件CameraTrajectory.txt和KeyFrameTrajectory.txt。前者是每一帧的位姿后者是只包含关键帧的位姿。评估精度要用前者。跑起来之后屏幕上会不断滚动日志行每一行里有一堆数字。挑两个新手最关心的说日志里的Track time、LocalMap time、LoopClos time分别是三个线程的单帧耗时单位是秒。在正常桌面机器上Tracking 耗时应稳定在 0.01-0.03 秒之间。如果 Track time 涨到 0.1 秒以上帧率就跟不上数据集了会出现跳帧轨迹质量变差。这时候要看看是不是提取点数太多ORBextractor.nFeatures调大到了 2000 以上或者分辨率太高。窗口里能看到红色的当前特征点、黑色的历史地图点以及一条青色或白色的相机轨迹和红色的小方块关键帧位置。如果回环检测成功你会看到轨迹在某个位置啪地一下被拉直那一下很爽。双目模式跑 KITTI 的命令./Examples/Stereo/stereo_kitti \ Vocabulary/ORBvoc.txt \ Examples/Stereo/KITTI00-02.yaml \ /home/$USER/slam_ws/dataset/sequences/00KITTI 的目录结构和 TUM 不一样sequences/00/下面要有image_0/和image_1/两个文件夹里面是名字形如000000.png的灰度图。文件名必须六位数补零顺序错了系统就乱了。这套数据量大00 序列有 4541 帧跑完得十几分钟建议先跑它的小样本验证。单目模式./Examples/Monocular/mono_tum \ Vocabulary/ORBvoc.txt \ Examples/Monocular/TUM1.yaml \ /home/$USER/slam_ws/rgbd_dataset_freiburg1_xyz注意单目模式传的是整个序列目录不是 associations 文件因为单目压根不用深度图。实操心得单目启动时请务必温柔一点。初始化阶段需要相机有足够的平移视差如果一开始只是原地打转系统会一直卡在初始化。跑数据集的时候这个不是问题但如果你录了自己的数据记得开头先横向平移一段。4.3 用 evo 评估绝对轨迹误差跑完程序只是第一步你得知道跑得准不准。SLAM 圈子里评轨迹精度的标准工具是evoPython 写的装起来方便pip install evo --upgrade --no-binary evo如果懒得处理依赖用 conda 装更省心conda install -c conda-forge evo评估绝对轨迹误差ATEAbsolute Trajectory Errorevo_ape tum groundtruth.txt CameraTrajectory.txt \ --align --correct_scale -va --plot --save_results result.zip参数含义逐个说清楚因为这几个开关直接影响你看到的数字--align把估计轨迹和真值做对齐Umeyama 对齐因为两者坐标系原点不一样不对齐比出来的误差毫无意义。--correct_scale同时估计尺度。单目必须加因为单目有尺度不确定性双目和 RGB-D 理论上尺度是确定的但加上了也无妨只是想看纯尺度下的精度就不该加。-va输出 verbose 的统计会打印 RMSE、均值、中位数、标准差、最大最小值。最该看的是 RMSE它是最常被引用的指标。--plot画出轨迹对比图和误差曲线。在 TUM fr1/xyz 上RGB-D 模式跑出来的 ATE RMSE 通常在0.01-0.02 米这个量级也就是一两厘米。如果跑到 0.1 米以上说明有问题了。KITTI 00 序列上双目模式的平移误差通常在百分之一量级相对轨迹长度也就是跑一公里偏几米到十几米。也可以看相对位姿误差RPE它衡量的是短时间内的局部精度漂移对评估里程计部分更有意义evo_rpe tum groundtruth.txt CameraTrajectory.txt \ --align --delta 1 --delta_unit f -va --plot--delta 1 --delta_unit f表示帧间隔为 1 帧f是 frames 的意思。也可以设成m米来做基于距离的采样。注意CameraTrajectory.txt里的时间戳格式是秒.纳秒groundtruth.txt是从数据集拿的两者时间基准一致可以直接比。但如果你跑的是自己录的数据真值格式要自己整理成 TUM 标准的四元数格式timestamp tx ty tz qx qy qz qw顺序不能乱。4.4 换成自己的相机标定与 yaml 改写跑通公开数据集之后下一步肯定是想用自己的设备。这时候要做三件事。第一件标定内参。单目和 RGB-D 都需要相机的内参矩阵和畸变系数。ROS 环境里可以用camera_calibration包拿棋盘格对着拍十几张不同角度的照片它会输出fx, fy, cx, cy和畸变系数k1, k2, p1, p2, k3。没有 ROS 的话用 OpenCV 的calibrateCamera自己写个小脚本也行。这一步千万别偷懒用别人的参数哪怕是同型号的手机不同个体的镜头也有差异用错内参轨迹会整体形变。第二件改 yaml。复制一份现成的TUM1.yaml改这几个字段Camera.fx: 535.4 Camera.fy: 539.2 Camera.cx: 320.1 Camera.cy: 247.6 Camera.k1: 0.0 Camera.k2: 0.0 Camera.p1: 0.0 Camera.p2: 0.0 Camera.k3: 0.0 Camera.width: 640 Camera.height: 480 Camera.fps: 30.0 Camera.RGB: 1 ORBextractor.nFeatures: 1000 ORBextractor.scaleFactor: 1.2 ORBextractor.nLevels: 8 ORBextractor.iniThFAST: 20 ORBextractor.minThFAST: 7 DepthMapFactor: 5000.0Camera.RGB: 1表示图像是彩色通道顺序如果读进来的图像偏蓝或者偏红把它在 0 和 1 之间切换一下就能修好——这是个很小但很容易卡住人的参数。DepthMapFactor是深度图的缩放因子如果你的深度图是毫米单位的 16 位整数就填 1000如果是 TUM 那种 5000 标度的就填 5000。填错了要么地图尺度大五倍要么小得看不见。第三件整理输入数据。RGB-D 模式需要图片序列加 associations 文件。图片命名要统一比如000001.png这种递增格式。associations 文件两列时间戳加两列路径1305031102.175304 rgb/1305031102.175304.png 1305031102.160407 depth/1305031102.160407.png时间戳的匹配容差不能太大一般控制在几十毫秒以内否则彩色和深度会对不上地图点全飘。如果你用 ROS 录的 bag 包可以用rosbag工具导出成图片和这个文件网上有现成的小脚本。5. 问题排查速查与经验沉淀5.1 编译期报错速查表报错关键词真实原因处理方式usleep was not declaredg2o 缺 unistd.h在 timeutil.cpp 顶部加#include unistd.hCV_LOAD_IMAGE_* not declared装了 OpenCV 4换成cv::IMREAD_*或改装 OpenCV 3.4internal compiler error: Killed内存不足被 OOM降-j并行度加 swapundefined reference to boost::system没链 boost_systemCMakeLists 补-lboost_systempangolin/gl/gl.h: No such filePangolin 版本太新切回 v0.5 重新编译安装fatal error: Eigen/Core: No such fileEigen 没装或路径不对apt install libeigen3-devcannot find -lORB_SLAM2库没编出来检查 build.sh 是否完整跑完Pangolin could not be found找不到 PangolinConfig确认sudo make install执行过5.2 运行期异常速查表现象可能原因排查方向启动后长时间无输出正在加载 ORBvoc.txt正常等 5-20 秒error while loading shared libraries库路径没配检查 LD_LIBRARY_PATH 或 ldconfig窗口黑屏、无轨迹Pangolin 显示问题显卡驱动 / OpenGL 支持轨迹抖动剧烈特征匹配外点多检查 yaml 内参、图像质量原地打转就丢失初始化视差不足起点先平移一段距离RGB-D 地图尺度明显不对DepthMapFactor 填错按深度图单位改成 1000 或 5000图像颜色异常RGB 通道顺序反了切Camera.RGB的值跑到一半越来越慢关键帧和地图点爆了减小 nFeatures检查回环是否触发段错误且位置飘忽Eigen 内存对齐检查自定义容器是否加了对齐宏5.3 精度不达标该从哪几处下手如果你跑出来了但 ATE 明显偏高按这个顺序排查命中率最高先看配置别急着怀疑算法。内参、畸变、深度因子这三样有一个错了结果是系统性偏差表现是轨迹整体缩放或者扭曲。用公开数据集跑出来的数字做基准对比——如果公开数据集也跑不准那就是环境或配置问题跟你自己的数据无关。再看特征提取参数。nFeatures默认 1000 对室内小场景够用但如果场景纹理丰富、分辨率高调到 1500-2000 会稳一些代价是耗时上升。iniThFAST和minThFAST的阈值在弱纹理场景白墙、走廊可以适当调低让系统能提到足够的点。这两个参数调低了会引入更多噪声点所以要配合回环和 BA 一起看效果不要只看单帧。然后看图像质量本身。运动模糊是视觉 SLAM 的头号杀手如果录制时手抖或者车开得快图像糊了特征点全废。建议录制时就控制运动速度曝光时间尽量短宁可图像暗一点也别糊。最后才考虑系统本身的局限。ORB-SLAM2 是稀疏特征法它在纹理弱、重复纹理多、剧烈光照变化这三类场景下都不太行。走廊里一排一模一样的门、反光的玻璃幕墙、突然从暗处走到强光下这些情况它跟丢是正常的。真要在这些场景下工作得考虑加 IMU、加轮式里程计做融合那就是另一个话题了。实操心得调试阶段把Camera.fps设成比实际帧率低一点比如实际 30 就填 25能让系统在偶尔处理不过来的时候不那么容易丢帧。这是个土办法但实测在弱一点的机器上挺管用。6. 我个人在这套东西上的一些体会写了这么多最后说几个我自己的使用感受。第一别一上来就调参。我见过太多人跑出来结果不理想第一反应就是改nFeatures、改阈值改了一轮发现没用。正确顺序永远是先用公开数据集确认环境正确再确认自己的标定参数正确最后才动算法参数。前面两步占问题来源的八成以上。第二留一份能跑通的配置快照。装了这么多次我现在的习惯是每装好一套就把 OpenCV 版本、Pangolin commit、编译参数、yaml 全部记到一个文本文件里连同机器信息一起存着。换个项目、换台机器的时候照着复现比重新摸索快十倍。第三Docker 值得认真考虑。如果你的主要工作是跑算法而不是折腾环境把整个 ORB-SLAM2 打包成一个镜像一次做好到处用。镜像做出来之后换机器、换系统版本、跟别人协作都不再有我这儿能跑你那儿不行的问题。代价是第一次得花点时间写 Dockerfile但绝对赚回来。第四关于后续扩展。ORB-SLAM2 的代码结构其实很适合当二次开发的骨架比如把 Tracking 线程换成自己的特征提取、把回环检测换成别的描述子、或者在 Local Mapping 里加入额外的约束。改动的时候有个原则尽量别动线程间的同步逻辑那块很容易改出死锁你会看到程序随机卡死而且没有报错特别难查。这套东西跑通了之后你会发现它给你的不只是一个能用的位姿估计器更是一个把 SLAM 各个模块怎么协同工作讲清楚的活教材。等你把回环那一瞬间轨迹被拉直的效果看到一次很多东西自然就理解了。