如果你最近在Ubuntu上折腾视觉SLAM那ORB-SLAM1/2/3这套经典开源项目大概率是你绕不开的第一站。这个系列覆盖了单目、双目、RGB-D再到后期加入IMU紧耦合几乎就是一部“特征点SLAM进化史”。但说实话它的源码下载下来很多新手第一关不是算法而是编译环境。OpenCV版本、Pangolin版本、GCC版本、Eigen路径随便一个不对报错就能让你耗上一整天。我写这篇指南的目的很明确在Ubuntu环境下把ORB-SLAM1/2/3从头到尾复现跑通。不是那种“复制粘贴命令然后祈祷成功”的教程而是把版本选择、依赖原理、编译顺序、运行参数这些关键点讲透。适合刚接触SLAM、想在本地把经典算法跑起来的新手也适合那些已经编译过但被各种兼容问题折磨过的人对照排查。1. 先搞清楚三个版本再动手1.1 三个版本的核心差异对比ORB-SLAM1、2、3三个版本表面上目录结构很像都是Thirdparty加Examples加Vocabulary但实际上差别非常大。如果不看版本差异直接拿同一个思路去编译运行很容易被一些“奇怪”的问题绕进去。对比项ORB-SLAM1ORB-SLAM2ORB-SLAM3开源时间2015年2017年2021年支持传感器单目单目、双目、RGB-D单目、双目、RGB-D单目IMU、双目IMU核心亮点建立了整套基于ORB特征的SLAM框架加入双目标定复用与RGB-D鲁棒性明显提升多地图系统Atlas、IMU紧耦合、鱼眼相机模型典型数据集TUMTUM、KITTI、EuRoCEuRoC、TUM-VI、KITTI编译依赖复杂度较低中等较高额外需要Sophus源码体量紧凑适合学习工程化完善资料最多代码量大算法细节多ORB-SLAM1是单目SLAM的集大成者它提出了一套非常完整的思路用ORB特征做前端跟踪用词袋模型做回环检测用图优化做全局一致性的修正。整套代码结构清晰是很多人入门视觉SLAM的第一份源码。ORB-SLAM2则在1的基础上做了大量工程化的扩展最大变化是支持了双目和RGB-D相机输入。它不再只依赖单目三角化恢复深度而是可以主动利用传感器提供的深度信息因此初始化更快尺度也更稳定。ORB-SLAM3是一次大重构加入了很多新东西IMU和视觉的紧耦合、Atlas多地图系统、鱼眼相机模型甚至将单目、双目、RGB-D、视觉惯性这些传感器统一到了一个框架里。功能是强大了但代码复杂度也上了一个台阶。1.2 新手到底应该先编译哪个版本很多人一上来就问“我该从哪个版本开始”我的建议非常直接如果只是想跑通一次完整的SLAM流程先做ORB-SLAM2如果想深入学习单目SLAM的原始框架那就从ORB-SLAM1开始如果你的目标明确是视觉惯性导航VIO方向直接上ORB-SLAM3不要犹豫。ORB-SLAM2是最好的“入门版本”理由有三点第一它对传感器的包容度高单目、双目、RGB-D都能跑方便你横向对比不同输入的区别第二网络上关于它的教程、问答、避坑经验最多遇到问题基本都能搜到答案第三它的运行效果直观Pangolin界面里可以同时看到当前帧、关键帧、地图点和轨迹很适合建立对整个系统的感性认识。至于硬件需求这里要辟个谣ORB-SLAM系列并不是非要有NVIDIA显卡才能跑。它主要靠CPU做特征提取和优化Pangolin只是用OpenGL做可视化和渲染。所以一台普通的四核CPU、8GB内存的电脑就够了。硬盘尽量预留20GB以上因为TUM、KITTI、EuRoC这些数据集动辄几个GB下载解压都需要空间。2. Ubuntu环境准备与依赖逐个击破2.1 系统版本和基础工具怎么选Ubuntu版本选择这件事直接影响你后面要踩多少个坑。我分别说下三个主流版本的情况Ubuntu 18.04默认OpenCV 3.2、GCC 7这三个ORB-SLAM版本在它上面编译最省心基本不需要改源码。缺点是系统本身已经比较老了软件源可能存在问题。Ubuntu 20.04默认OpenCV 4.2、GCC 9这是目前最均衡的选择。编译ORB-SLAM2和ORB-SLAM3都很顺利ORB-SLAM1需要改几个兼容性宏。Ubuntu 22.04默认OpenCV 4.5、GCC 11这时候就要小心了。GCC 11对C标准检查更严格ORB-SLAM系列里很多文件没有显式包含unistd.h编译会报usleep未定义错误需要手动补头文件。我个人最推荐20.04。如果是虚拟机或者双系统先装好基础工具sudo apt update sudo apt install -y git cmake g build-essentialbuild-essential这个包一定要装它一次性打包了GCC、G、make等编译链核心工具。如果缺了这个后面任何源码编译都会在第一步直接失败。2.2 核心依赖安装实操编译ORB-SLAM系列需要四个核心依赖Eigen、OpenCV、Pangolin以及各个版本自带的第三方库ORB-SLAM1/2需要的DBoW2、g2oORB-SLAM3额外需要的Sophus。其中前三个需要你自己提前装好。先装Eigen。这是一个头文件库专门用于矩阵运算在SLAM里几乎所有坐标系变换、优化求解都离不开它。直接通过apt装最简单的版本即可sudo apt install -y libeigen3-dev装完以后头文件在/usr/include/eigen3下CMake通常会自己找到。需要注意的是Eigen不需要编译它只是头文件所以安装速度非常快。然后是OpenCV。这里有一个很典型的坑用apt还是源码编译我的建议是新手一律用aptsudo apt install -y libopencv-devUbuntu 20.04默认会给OpenCV 4.2这个版本对ORB-SLAM2和3完全够用。自己从源码编译OpenCV虽然能拿到更新版本但编译过程非常耗时还需要解决一堆Python绑定、FFmpeg依赖问题投入产出比太低。等到你把ORB-SLAM跑通了再考虑要不要折腾OpenCV版本也不迟。最后是Pangolin。这是ORB-SLAM用来画界面、显示轨迹的GUI库它的版本选择至关重要。我强烈建议你克隆Pangolin源码后手动切到v0.5分支再编译sudo apt install -y libglew-dev libboost-dev libboost-thread-dev libboost-filesystem-dev libpython3-dev ffmpeg git clone Pangolin仓库地址 cd Pangolin git checkout v0.5 mkdir build cd build cmake .. make -j4 sudo make install为什么要切到v0.5因为ORB-SLAM1/2的源码是2015到2017年写的里面大量使用了旧版Pangolin的API。Pangolin新版本改动很大很多头文件路径和函数接口都变了直接用新版本编译会报一堆错。v0.5虽然老但和ORB-SLAM全系列的兼容性是最好的。2.3 编译前的环境验证清单每次帮人排查编译问题我都发现很多报错其实在编译前就能避免。所以强烈建议在动手编译ORB-SLAM之前先花三分钟做一个环境自检cmake --version gcc --version pkg-config --modversion opencv4 ls /usr/include/eigen3/Eigen ls /usr/local/include/pangolin如果pkg-config --modversion opencv4返回了版本号说明OpenCV装好了如果提示找不到opencv4那就用pkg-config --modversion opencv试试Ubuntu 18.04上OpenCV 3.2的pkg-config名字就是opencv。Pangolin则直接看/usr/local/include/pangolin目录存不存在存在就没问题。这个验证清单能帮你把问题定位到“依赖缺失”还是“代码本身不兼容”省下很多瞎折腾的时间。我就是因为一开始跳过这步后面花了大半天才查出来是Pangolin版本太新导致ORB-SLAM2编译失败。3. 三个版本的编译与运行实操3.1 ORB-SLAM1编译与单目数据集运行先从ORB-SLAM1开始。把源码克隆下来之后先看目录结构Thirdparty里面放着DBoW2和g2oVocabulary里面是ORB词袋文件Examples下面是各个传感器的示例程序。整个项目是依靠根目录下的build.sh一键编译的它会依次编译DBoW2、g2o最后编译ORB-SLAM1本体。cd ORB_SLAM1 ./build.sh等待编译完成后下载一个TUM数据集。TUM数据集的压缩包解压后会得到类似rgbd_dataset_freiburg1_room这样的目录里面包含rgb和depth两个子目录。对ORB-SLAM1来说单目模式只需要rgb下面的彩色图序列。运行命令如下cd Examples/Monocular ./mono_tum ../../Vocabulary/ORBvoc.txt TUM1.yaml /path/to/rgbd_dataset_freiburg1_room第一个参数是词袋文件路径第二个是相机参数文件第三个是数据集根目录注意路径要写对否则程序不会报错而是直接卡在“等待图像”状态。如果你用的是Ubuntu 20.04及以上系统、通过apt安装了OpenCV 4那ORB-SLAM1大概率会报编译错误主要集中在几个OpenCV旧版宏失效的问题上。最常见的是CV_LOAD_IMAGE_UNCHANGED未声明需要手动把它改成cv::IMREAD_UNCHANGED。另一个常见问题是CV_RGB2GRAY未声明要改成cv::COLOR_RGB2GRAY。这些宏在OpenCV 3中还存在到OpenCV 4就被彻底移除了。3.2 ORB-SLAM2编译与三种传感器运行示例ORB-SLAM2是覆盖面最广的版本它的编译同样是一键脚本cd ORB_SLAM2 ./build.sh编译完成之后你可以体验三种不同传感器的运行流程。首先是单目TUM命令和ORB-SLAM1几乎一样./Examples/Monocular/mono_tum Vocabulary/ORBvoc.txt Examples/Monocular/TUM1.yaml /path/to/fr1_room其次是双目KITTI。KITTI数据集是自动驾驶场景图像分辨率大特征点分布密集对硬件要求也更高。运行前需要先下载KITTI的00序列解压后目录里是一系列PNG图像。命令如下./Examples/Stereo/stereo_kitti Vocabulary/ORBvoc.txt Examples/Stereo/KITTI00-02.yaml /path/to/KITTI/00最后是RGB-D TUM。这一步最容易出问题因为RGB-D模式要求你额外提供一个“关联文件”也就是associations.txt。这个文件的作用是把每一帧RGB图像和它对应的深度图在时间戳上对齐。TUM数据集官方提供了一对关联脚本如果你下载的数据集目录里有rgb.txt和depth.txt可以用这个命令生成python associate.py rgb.txt depth.txt associations.txt然后把关联文件作为第四个参数传给程序./Examples/RGB-D/rgbd_tum Vocabulary/ORBvoc.txt Examples/RGB-D/TUM1.yaml /path/to/fr1_room /path/to/associations.txt我还想给新手一个建议ORB-SLAM2的源码里包含ROS接口但你在首次复现时千万不要去碰ROS版。ROS的编译依赖、工作空间环境变量、还有与Pangolin窗口多线程的冲突会把你绕到云里雾里。先把非ROS版跑通理解整个流程再考虑扩展。3.3 ORB-SLAM3编译与EuRoC数据集运行ORB-SLAM3是所有版本里最复杂的也是最值得精心准备的。除了之前提到的Eigen、OpenCV、Pangolin之外它还需要Sophus这是一个用于李群李代数运算的库。好消息是ORB-SLAM3已经在Thirdparty/Sophus里内置了一份特定版本你不需要额外从系统安装编译时它会随着build.sh一起完成。cd ORB_SLAM3 ./build.sh如果是在Ubuntu 22.04上编译建议先给ORB-SLAM3的源代码打一个补丁在src目录下各.cc文件的头文件区域统一加上#include unistd.h否则GCC 11会在编译后期报出大量usleep未定义错误而且这个报错不是一次性出现在一个文件里的是散落在多个编译单元中逐个修改会非常烦人。ORB-SLAM3最常见的运行示例是EuRoC数据集这是一个无人机采集的双目IMU数据。下载MH_01序列解压后你会看到类似mav0的目录结构里面包含cam0、cam1、imu0等子目录。运行双目模式./Examples/Stereo/stereo_euroc Vocabulary/ORBvoc.txt Examples/Stereo/EuRoC.yaml /path/to/MH_01 Examples/Stereo/EuRoC_TimeStamps/MH01.txt这里第三个参数要指向包含mav0的上一级目录第四个参数是时间戳文件源码里已经提供好了。如果你想体验视觉惯性融合可以运行单目IMU版本./Examples/Monocular-Inertial/mono_inertial_euroc Vocabulary/ORBvoc.txt Examples/Monocular-Inertial/EuRoC.yaml /path/to/MH_01 Examples/Monocular-Inertial/EuRoC_TimeStamps/MH01.txt dataset-MH_01_mono_inertial3.4 运行效果验证与轨迹评估当你成功启动程序后屏幕上会出现一个Pangolin窗口里面能看到相机当前帧、特征点、共视关键帧以及全局地图点云。终端也会实时打印状态信息和处理帧率。以TUM fr1数据集为例正常运行时帧率大概在20到40 FPS之间如果只有个位数就要检查是不是后台跑了很多东西或者数据集精度太高导致特征提取耗时过长。单目模式运行时有一个细节程序一开始会显示“waiting for initialization”或者类似状态这是正常的因为单目SLAM需要等相机发生足够的平移运动才能通过三角化恢复出初始地图。第一帧到第二帧之间如果相机几乎没动初始化就一直无法完成。所以跑数据集时看到程序“停住”别急着杀进程给它几秒钟观察相机运动。程序运行完会自动退出并在当前目录生成KeyFrameTrajectory.txt和CameraTrajectory.txt。想评估精度的话可以用evo工具和数据集真值做对比pip install evo evo_ape tum KeyFrameTrajectory.txt groundtruth.txt -a -pTUM数据集的真值文件就是目录里的groundtruth.txtEuRoC则可以使用state_groundtruth_estimate0下的数据。-a表示自动对齐-p表示绘制曲线。4. 常见报错与排查实录4.1 高频编译错误速查表根据我接触过的案例ORB-SLAM系列编译报错其实就那么几类。我整理了一张速查表你可以对照排查现象根因解决方案编译时提示Eigen/Dense: No such fileEigen未安装或路径不对执行sudo apt install libeigen3-dev确认/usr/include/eigen3存在编译时提示usleep was not declaredGCC 11及以上版本对头文件检查更严格在所有src/*.cc中加入#include unistd.h提示CV_LOAD_IMAGE_UNCHANGED未声明OpenCV 4移除了旧版图像加载宏全局替换为cv::IMREAD_UNCHANGED提示CV_RGB2GRAY未声明OpenCV 4改用新的颜色空间常量全局替换为cv::COLOR_RGB2GRAYPangolin相关头文件找不到或API冲突Pangolin版本过新与旧代码不兼容切换到Pangolin v0.5分支重新编译安装链接阶段报错找不到libopencv_core.soOpenCV编译安装与CMake配置不一致用pkg-config --modversion opencv4验证删除build目录后重新cmake编译过程中内存不足直接卡死并行编译任务过多将make -j8改为make -j4或更小最后一条其实很关键。很多人拿到源码后习惯性地make -j8如果内存只有8GB编译过程和Pangolin、OpenCV这种大库同时启动很容易打到OOM。不要贪并行数-j4在大多数机器上是最稳妥的。4.2 运行阶段的典型问题编译过了不代表运行就一帆风顺。第一次把ORB-SLAM2跑起来时我遇到的第一个问题是Pangolin窗口完全不显示。后来发现是因为我通过SSH远程连到机器上执行程序没有图形显示环境。解决办法是在有桌面的系统上直接运行或者用虚拟机的图形界面。远程环境想显示窗口需要配置X11转发但新手阶段不建议折腾这个。第二个典型的运行问题是一启动就Segmentation fault。这种崩溃九成九是参数路径写错了。程序对数据集路径、YAML文件路径、关联文件路径都是直接读取不会做稳健性检查路径一旦失效就会在读取图像时直接访问非法内存。解决方法是仔细核对四个参数的路径尤其是关联文件RGB-D模式少了它几乎必崩。第三个是RGB-D模式下轨迹错乱、重影严重。这种情况通常是关联文件时间戳对齐精度不够。TUM的associate.py脚本默认的匹配容差是0.02秒如果数据集本身时间戳漂移较大可以尝试把容差放宽一点但不要超过0.05秒否则会引入大量的错误匹配。4.3 运行效果调优的几个方向跑通只是第一步把效果调好才是真正有价值的部分。我自己在调参过程中总结了几条经验第一不要盲目追求高帧率。有些新手看到帧率偏低就在YAML文件里猛降特征点数量结果地图质量直线下降。ORB-SLAM系列的基础是ORB特征特征太少会导致跟踪丢失。如果你觉得CPU扛不住优先检查系统负载而不是一上来就砍特征。第二想纯粹测试算法而不需要可视化可以在源码里关闭Viewer线程。ORB-SLAM的Viewer线程负责渲染和GUI交互它会占据不少CPU资源。跑批量实验时直接在System.cc里把mbUseViewer设成false或者不启动mpViewer能显著提升处理速度。第三YAML相机参数文件里有一个ORBextractor.nFeatures参数控制每帧提取的特征点数量默认通常是1000到1500。对于纹理稀疏的场景这个值可以提高到2000对于纹理丰富的高速运动场景反而建议降低到800左右并加快特征提取阈值这样能减少计算量并保持跟踪稳定性。第四EuRoC这类视觉惯性数据集IMU参数不能随便改。如果你用的不是官方提供的相机参数而是自己的设备必须先完成IMU标定包括噪声密度和随机游走否则单目IMU模式的轨迹会很快发散。新手跑官方数据集时尽量保持YAML原样。写在最后的一点经验把ORB-SLAM1/2/3都复现一遍之后我最大的感受是这套代码对新手真正的门槛不在算法而在环境。很多人一开始都以为是自己代码写得不好、调试能力不行反复重装系统最后发现就是某个依赖版本不匹配。所以再提醒一句动工之前一定先做环境验证清单并且把你装的所有依赖版本记录下来。哪天突然编译报错至少能判断是不是自己不小心升级了OpenCV或者Pangolin。另外三个版本最好放在不同目录各自使用独立的build文件夹不要图省事共用第三方库的编译产物。最后分享一个小技巧把常用的运行命令写成一个shell脚本保存下来数据集路径、词表路径、YAML路径都用绝对路径。这样每次复现只需要执行一行命令既减少手误也方便以后给别人做演示。希望这篇指南能帮你少走弯路顺利跑出自己的第一条SLAM轨迹。
如果你最近在Ubuntu上折腾视觉SLAM那ORB-SLAM1/2/3这套经典开源项目大概率是你绕不开的第一站。这个系列覆盖了单目、双目、RGB-D再到后期加入IMU紧耦合几乎就是一部“特征点SLAM进化史”。但说实话它的源码下载下来很多新手第一关不是算法而是编译环境。OpenCV版本、Pangolin版本、GCC版本、Eigen路径随便一个不对报错就能让你耗上一整天。我写这篇指南的目的很明确在Ubuntu环境下把ORB-SLAM1/2/3从头到尾复现跑通。不是那种“复制粘贴命令然后祈祷成功”的教程而是把版本选择、依赖原理、编译顺序、运行参数这些关键点讲透。适合刚接触SLAM、想在本地把经典算法跑起来的新手也适合那些已经编译过但被各种兼容问题折磨过的人对照排查。1. 先搞清楚三个版本再动手1.1 三个版本的核心差异对比ORB-SLAM1、2、3三个版本表面上目录结构很像都是Thirdparty加Examples加Vocabulary但实际上差别非常大。如果不看版本差异直接拿同一个思路去编译运行很容易被一些“奇怪”的问题绕进去。对比项ORB-SLAM1ORB-SLAM2ORB-SLAM3开源时间2015年2017年2021年支持传感器单目单目、双目、RGB-D单目、双目、RGB-D单目IMU、双目IMU核心亮点建立了整套基于ORB特征的SLAM框架加入双目标定复用与RGB-D鲁棒性明显提升多地图系统Atlas、IMU紧耦合、鱼眼相机模型典型数据集TUMTUM、KITTI、EuRoCEuRoC、TUM-VI、KITTI编译依赖复杂度较低中等较高额外需要Sophus源码体量紧凑适合学习工程化完善资料最多代码量大算法细节多ORB-SLAM1是单目SLAM的集大成者它提出了一套非常完整的思路用ORB特征做前端跟踪用词袋模型做回环检测用图优化做全局一致性的修正。整套代码结构清晰是很多人入门视觉SLAM的第一份源码。ORB-SLAM2则在1的基础上做了大量工程化的扩展最大变化是支持了双目和RGB-D相机输入。它不再只依赖单目三角化恢复深度而是可以主动利用传感器提供的深度信息因此初始化更快尺度也更稳定。ORB-SLAM3是一次大重构加入了很多新东西IMU和视觉的紧耦合、Atlas多地图系统、鱼眼相机模型甚至将单目、双目、RGB-D、视觉惯性这些传感器统一到了一个框架里。功能是强大了但代码复杂度也上了一个台阶。1.2 新手到底应该先编译哪个版本很多人一上来就问“我该从哪个版本开始”我的建议非常直接如果只是想跑通一次完整的SLAM流程先做ORB-SLAM2如果想深入学习单目SLAM的原始框架那就从ORB-SLAM1开始如果你的目标明确是视觉惯性导航VIO方向直接上ORB-SLAM3不要犹豫。ORB-SLAM2是最好的“入门版本”理由有三点第一它对传感器的包容度高单目、双目、RGB-D都能跑方便你横向对比不同输入的区别第二网络上关于它的教程、问答、避坑经验最多遇到问题基本都能搜到答案第三它的运行效果直观Pangolin界面里可以同时看到当前帧、关键帧、地图点和轨迹很适合建立对整个系统的感性认识。至于硬件需求这里要辟个谣ORB-SLAM系列并不是非要有NVIDIA显卡才能跑。它主要靠CPU做特征提取和优化Pangolin只是用OpenGL做可视化和渲染。所以一台普通的四核CPU、8GB内存的电脑就够了。硬盘尽量预留20GB以上因为TUM、KITTI、EuRoC这些数据集动辄几个GB下载解压都需要空间。2. Ubuntu环境准备与依赖逐个击破2.1 系统版本和基础工具怎么选Ubuntu版本选择这件事直接影响你后面要踩多少个坑。我分别说下三个主流版本的情况Ubuntu 18.04默认OpenCV 3.2、GCC 7这三个ORB-SLAM版本在它上面编译最省心基本不需要改源码。缺点是系统本身已经比较老了软件源可能存在问题。Ubuntu 20.04默认OpenCV 4.2、GCC 9这是目前最均衡的选择。编译ORB-SLAM2和ORB-SLAM3都很顺利ORB-SLAM1需要改几个兼容性宏。Ubuntu 22.04默认OpenCV 4.5、GCC 11这时候就要小心了。GCC 11对C标准检查更严格ORB-SLAM系列里很多文件没有显式包含unistd.h编译会报usleep未定义错误需要手动补头文件。我个人最推荐20.04。如果是虚拟机或者双系统先装好基础工具sudo apt update sudo apt install -y git cmake g build-essentialbuild-essential这个包一定要装它一次性打包了GCC、G、make等编译链核心工具。如果缺了这个后面任何源码编译都会在第一步直接失败。2.2 核心依赖安装实操编译ORB-SLAM系列需要四个核心依赖Eigen、OpenCV、Pangolin以及各个版本自带的第三方库ORB-SLAM1/2需要的DBoW2、g2oORB-SLAM3额外需要的Sophus。其中前三个需要你自己提前装好。先装Eigen。这是一个头文件库专门用于矩阵运算在SLAM里几乎所有坐标系变换、优化求解都离不开它。直接通过apt装最简单的版本即可sudo apt install -y libeigen3-dev装完以后头文件在/usr/include/eigen3下CMake通常会自己找到。需要注意的是Eigen不需要编译它只是头文件所以安装速度非常快。然后是OpenCV。这里有一个很典型的坑用apt还是源码编译我的建议是新手一律用aptsudo apt install -y libopencv-devUbuntu 20.04默认会给OpenCV 4.2这个版本对ORB-SLAM2和3完全够用。自己从源码编译OpenCV虽然能拿到更新版本但编译过程非常耗时还需要解决一堆Python绑定、FFmpeg依赖问题投入产出比太低。等到你把ORB-SLAM跑通了再考虑要不要折腾OpenCV版本也不迟。最后是Pangolin。这是ORB-SLAM用来画界面、显示轨迹的GUI库它的版本选择至关重要。我强烈建议你克隆Pangolin源码后手动切到v0.5分支再编译sudo apt install -y libglew-dev libboost-dev libboost-thread-dev libboost-filesystem-dev libpython3-dev ffmpeg git clone Pangolin仓库地址 cd Pangolin git checkout v0.5 mkdir build cd build cmake .. make -j4 sudo make install为什么要切到v0.5因为ORB-SLAM1/2的源码是2015到2017年写的里面大量使用了旧版Pangolin的API。Pangolin新版本改动很大很多头文件路径和函数接口都变了直接用新版本编译会报一堆错。v0.5虽然老但和ORB-SLAM全系列的兼容性是最好的。2.3 编译前的环境验证清单每次帮人排查编译问题我都发现很多报错其实在编译前就能避免。所以强烈建议在动手编译ORB-SLAM之前先花三分钟做一个环境自检cmake --version gcc --version pkg-config --modversion opencv4 ls /usr/include/eigen3/Eigen ls /usr/local/include/pangolin如果pkg-config --modversion opencv4返回了版本号说明OpenCV装好了如果提示找不到opencv4那就用pkg-config --modversion opencv试试Ubuntu 18.04上OpenCV 3.2的pkg-config名字就是opencv。Pangolin则直接看/usr/local/include/pangolin目录存不存在存在就没问题。这个验证清单能帮你把问题定位到“依赖缺失”还是“代码本身不兼容”省下很多瞎折腾的时间。我就是因为一开始跳过这步后面花了大半天才查出来是Pangolin版本太新导致ORB-SLAM2编译失败。3. 三个版本的编译与运行实操3.1 ORB-SLAM1编译与单目数据集运行先从ORB-SLAM1开始。把源码克隆下来之后先看目录结构Thirdparty里面放着DBoW2和g2oVocabulary里面是ORB词袋文件Examples下面是各个传感器的示例程序。整个项目是依靠根目录下的build.sh一键编译的它会依次编译DBoW2、g2o最后编译ORB-SLAM1本体。cd ORB_SLAM1 ./build.sh等待编译完成后下载一个TUM数据集。TUM数据集的压缩包解压后会得到类似rgbd_dataset_freiburg1_room这样的目录里面包含rgb和depth两个子目录。对ORB-SLAM1来说单目模式只需要rgb下面的彩色图序列。运行命令如下cd Examples/Monocular ./mono_tum ../../Vocabulary/ORBvoc.txt TUM1.yaml /path/to/rgbd_dataset_freiburg1_room第一个参数是词袋文件路径第二个是相机参数文件第三个是数据集根目录注意路径要写对否则程序不会报错而是直接卡在“等待图像”状态。如果你用的是Ubuntu 20.04及以上系统、通过apt安装了OpenCV 4那ORB-SLAM1大概率会报编译错误主要集中在几个OpenCV旧版宏失效的问题上。最常见的是CV_LOAD_IMAGE_UNCHANGED未声明需要手动把它改成cv::IMREAD_UNCHANGED。另一个常见问题是CV_RGB2GRAY未声明要改成cv::COLOR_RGB2GRAY。这些宏在OpenCV 3中还存在到OpenCV 4就被彻底移除了。3.2 ORB-SLAM2编译与三种传感器运行示例ORB-SLAM2是覆盖面最广的版本它的编译同样是一键脚本cd ORB_SLAM2 ./build.sh编译完成之后你可以体验三种不同传感器的运行流程。首先是单目TUM命令和ORB-SLAM1几乎一样./Examples/Monocular/mono_tum Vocabulary/ORBvoc.txt Examples/Monocular/TUM1.yaml /path/to/fr1_room其次是双目KITTI。KITTI数据集是自动驾驶场景图像分辨率大特征点分布密集对硬件要求也更高。运行前需要先下载KITTI的00序列解压后目录里是一系列PNG图像。命令如下./Examples/Stereo/stereo_kitti Vocabulary/ORBvoc.txt Examples/Stereo/KITTI00-02.yaml /path/to/KITTI/00最后是RGB-D TUM。这一步最容易出问题因为RGB-D模式要求你额外提供一个“关联文件”也就是associations.txt。这个文件的作用是把每一帧RGB图像和它对应的深度图在时间戳上对齐。TUM数据集官方提供了一对关联脚本如果你下载的数据集目录里有rgb.txt和depth.txt可以用这个命令生成python associate.py rgb.txt depth.txt associations.txt然后把关联文件作为第四个参数传给程序./Examples/RGB-D/rgbd_tum Vocabulary/ORBvoc.txt Examples/RGB-D/TUM1.yaml /path/to/fr1_room /path/to/associations.txt我还想给新手一个建议ORB-SLAM2的源码里包含ROS接口但你在首次复现时千万不要去碰ROS版。ROS的编译依赖、工作空间环境变量、还有与Pangolin窗口多线程的冲突会把你绕到云里雾里。先把非ROS版跑通理解整个流程再考虑扩展。3.3 ORB-SLAM3编译与EuRoC数据集运行ORB-SLAM3是所有版本里最复杂的也是最值得精心准备的。除了之前提到的Eigen、OpenCV、Pangolin之外它还需要Sophus这是一个用于李群李代数运算的库。好消息是ORB-SLAM3已经在Thirdparty/Sophus里内置了一份特定版本你不需要额外从系统安装编译时它会随着build.sh一起完成。cd ORB_SLAM3 ./build.sh如果是在Ubuntu 22.04上编译建议先给ORB-SLAM3的源代码打一个补丁在src目录下各.cc文件的头文件区域统一加上#include unistd.h否则GCC 11会在编译后期报出大量usleep未定义错误而且这个报错不是一次性出现在一个文件里的是散落在多个编译单元中逐个修改会非常烦人。ORB-SLAM3最常见的运行示例是EuRoC数据集这是一个无人机采集的双目IMU数据。下载MH_01序列解压后你会看到类似mav0的目录结构里面包含cam0、cam1、imu0等子目录。运行双目模式./Examples/Stereo/stereo_euroc Vocabulary/ORBvoc.txt Examples/Stereo/EuRoC.yaml /path/to/MH_01 Examples/Stereo/EuRoC_TimeStamps/MH01.txt这里第三个参数要指向包含mav0的上一级目录第四个参数是时间戳文件源码里已经提供好了。如果你想体验视觉惯性融合可以运行单目IMU版本./Examples/Monocular-Inertial/mono_inertial_euroc Vocabulary/ORBvoc.txt Examples/Monocular-Inertial/EuRoC.yaml /path/to/MH_01 Examples/Monocular-Inertial/EuRoC_TimeStamps/MH01.txt dataset-MH_01_mono_inertial3.4 运行效果验证与轨迹评估当你成功启动程序后屏幕上会出现一个Pangolin窗口里面能看到相机当前帧、特征点、共视关键帧以及全局地图点云。终端也会实时打印状态信息和处理帧率。以TUM fr1数据集为例正常运行时帧率大概在20到40 FPS之间如果只有个位数就要检查是不是后台跑了很多东西或者数据集精度太高导致特征提取耗时过长。单目模式运行时有一个细节程序一开始会显示“waiting for initialization”或者类似状态这是正常的因为单目SLAM需要等相机发生足够的平移运动才能通过三角化恢复出初始地图。第一帧到第二帧之间如果相机几乎没动初始化就一直无法完成。所以跑数据集时看到程序“停住”别急着杀进程给它几秒钟观察相机运动。程序运行完会自动退出并在当前目录生成KeyFrameTrajectory.txt和CameraTrajectory.txt。想评估精度的话可以用evo工具和数据集真值做对比pip install evo evo_ape tum KeyFrameTrajectory.txt groundtruth.txt -a -pTUM数据集的真值文件就是目录里的groundtruth.txtEuRoC则可以使用state_groundtruth_estimate0下的数据。-a表示自动对齐-p表示绘制曲线。4. 常见报错与排查实录4.1 高频编译错误速查表根据我接触过的案例ORB-SLAM系列编译报错其实就那么几类。我整理了一张速查表你可以对照排查现象根因解决方案编译时提示Eigen/Dense: No such fileEigen未安装或路径不对执行sudo apt install libeigen3-dev确认/usr/include/eigen3存在编译时提示usleep was not declaredGCC 11及以上版本对头文件检查更严格在所有src/*.cc中加入#include unistd.h提示CV_LOAD_IMAGE_UNCHANGED未声明OpenCV 4移除了旧版图像加载宏全局替换为cv::IMREAD_UNCHANGED提示CV_RGB2GRAY未声明OpenCV 4改用新的颜色空间常量全局替换为cv::COLOR_RGB2GRAYPangolin相关头文件找不到或API冲突Pangolin版本过新与旧代码不兼容切换到Pangolin v0.5分支重新编译安装链接阶段报错找不到libopencv_core.soOpenCV编译安装与CMake配置不一致用pkg-config --modversion opencv4验证删除build目录后重新cmake编译过程中内存不足直接卡死并行编译任务过多将make -j8改为make -j4或更小最后一条其实很关键。很多人拿到源码后习惯性地make -j8如果内存只有8GB编译过程和Pangolin、OpenCV这种大库同时启动很容易打到OOM。不要贪并行数-j4在大多数机器上是最稳妥的。4.2 运行阶段的典型问题编译过了不代表运行就一帆风顺。第一次把ORB-SLAM2跑起来时我遇到的第一个问题是Pangolin窗口完全不显示。后来发现是因为我通过SSH远程连到机器上执行程序没有图形显示环境。解决办法是在有桌面的系统上直接运行或者用虚拟机的图形界面。远程环境想显示窗口需要配置X11转发但新手阶段不建议折腾这个。第二个典型的运行问题是一启动就Segmentation fault。这种崩溃九成九是参数路径写错了。程序对数据集路径、YAML文件路径、关联文件路径都是直接读取不会做稳健性检查路径一旦失效就会在读取图像时直接访问非法内存。解决方法是仔细核对四个参数的路径尤其是关联文件RGB-D模式少了它几乎必崩。第三个是RGB-D模式下轨迹错乱、重影严重。这种情况通常是关联文件时间戳对齐精度不够。TUM的associate.py脚本默认的匹配容差是0.02秒如果数据集本身时间戳漂移较大可以尝试把容差放宽一点但不要超过0.05秒否则会引入大量的错误匹配。4.3 运行效果调优的几个方向跑通只是第一步把效果调好才是真正有价值的部分。我自己在调参过程中总结了几条经验第一不要盲目追求高帧率。有些新手看到帧率偏低就在YAML文件里猛降特征点数量结果地图质量直线下降。ORB-SLAM系列的基础是ORB特征特征太少会导致跟踪丢失。如果你觉得CPU扛不住优先检查系统负载而不是一上来就砍特征。第二想纯粹测试算法而不需要可视化可以在源码里关闭Viewer线程。ORB-SLAM的Viewer线程负责渲染和GUI交互它会占据不少CPU资源。跑批量实验时直接在System.cc里把mbUseViewer设成false或者不启动mpViewer能显著提升处理速度。第三YAML相机参数文件里有一个ORBextractor.nFeatures参数控制每帧提取的特征点数量默认通常是1000到1500。对于纹理稀疏的场景这个值可以提高到2000对于纹理丰富的高速运动场景反而建议降低到800左右并加快特征提取阈值这样能减少计算量并保持跟踪稳定性。第四EuRoC这类视觉惯性数据集IMU参数不能随便改。如果你用的不是官方提供的相机参数而是自己的设备必须先完成IMU标定包括噪声密度和随机游走否则单目IMU模式的轨迹会很快发散。新手跑官方数据集时尽量保持YAML原样。写在最后的一点经验把ORB-SLAM1/2/3都复现一遍之后我最大的感受是这套代码对新手真正的门槛不在算法而在环境。很多人一开始都以为是自己代码写得不好、调试能力不行反复重装系统最后发现就是某个依赖版本不匹配。所以再提醒一句动工之前一定先做环境验证清单并且把你装的所有依赖版本记录下来。哪天突然编译报错至少能判断是不是自己不小心升级了OpenCV或者Pangolin。另外三个版本最好放在不同目录各自使用独立的build文件夹不要图省事共用第三方库的编译产物。最后分享一个小技巧把常用的运行命令写成一个shell脚本保存下来数据集路径、词表路径、YAML路径都用绝对路径。这样每次复现只需要执行一行命令既减少手误也方便以后给别人做演示。希望这篇指南能帮你少走弯路顺利跑出自己的第一条SLAM轨迹。
