1. 从零到一为什么你的ORB-SLAM3编译总失败搞视觉SLAM的谁没在环境配置上栽过跟头尤其是ORB-SLAM3这个集成了视觉、视觉惯导、多地图系统的“全家桶”功能强大但依赖复杂堪称新手劝退器。网上的教程五花八门有的基于Ubuntu 18.04有的依赖库版本过时照着做十有八九会在编译的某个环节卡住报出一堆看不懂的链接错误或找不到包的提示。2023年了Ubuntu 22.04 LTS已经成为主流一些依赖库的API也发生了变化老教程很多已经不再适用。这篇内容就是基于最新的Ubuntu 22.04系统带你走通一遍完整的ORB-SLAM3配置与安装流程我会把每一步的原理、可能遇到的坑以及我自己的解决方案都讲清楚。目标很简单让你在干净的Ubuntu 22.04系统上成功编译并运行ORB-SLAM3的示例为后续自己的研究和开发铺平道路。2. 环境基石系统准备与核心依赖库部署在动手编译任何大型C项目之前搭建一个稳定、兼容的底层环境是重中之重。ORB-SLAM3严重依赖一系列开源库我们必须先为它们打好地基。2.1 操作系统与编译器选择我强烈推荐使用Ubuntu 22.04 LTS作为你的开发环境。LTS意味着长期支持软件源稳定社区资源丰富。ORB-SLAM3的代码对C标准有要求我们需要较新版本的编译器。打开终端首先更新系统软件源并升级现有软件包这是一个好习惯能避免很多因版本过旧导致的依赖冲突。sudo apt update sudo apt upgrade -y接下来安装编译ORB-SLAM3所必需的构建工具和C编译器。我们选择GCC 11和G 11它们完全支持C17标准并且是Ubuntu 22.04的默认版本兼容性最好。sudo apt install -y build-essential cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev sudo apt install -y gcc-11 g-11安装完成后可以通过gcc-11 --version和g-11 --version确认版本。为了让系统默认使用我们安装的版本可以配置一下替代方案如果你系统里有多个版本的话sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 110 sudo update-alternatives --install /usr/bin/g g /usr/bin/g-11 1102.2 Pangolin不可或缺的轻量级可视化工具Pangolin是ORB-SLAM3用于显示相机轨迹、地图点、关键帧的图形界面。它非常轻量封装了OpenGL的复杂操作是SLAM研究中的标配可视化工具。我们将从源码编译安装以确保获得最新且兼容的版本。首先安装Pangolin所需的一系列依赖。这些依赖包括窗口系统、OpenGL、字体渲染等底层库。sudo apt install -y libglew-dev libboost-dev libboost-thread-dev libboost-filesystem-dev libeigen3-dev注意这里安装的是libeigen3-dev。Eigen是一个高性能的C模板库用于线性代数运算ORB-SLAM3内部大量使用它进行矩阵、向量计算。通常系统源的Eigen版本足够新Ubuntu 22.04是3.4版本可以直接使用无需单独编译。然后我们克隆Pangolin的官方仓库。我推荐使用v0.8这个稳定版本分支主分支有时会有一些实验性改动。cd ~ git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin git checkout v0.8开始编译安装。这里使用CMake的“out-of-source”构建方式即在单独的build目录中编译保持源码目录干净。mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease make -j$(nproc) sudo make install-j$(nproc)参数会让make使用你电脑所有的CPU核心进行并行编译能显著加快速度。sudo make install会将编译好的库文件和头文件安装到系统默认路径通常是/usr/local/lib和/usr/local/include这样其他项目就能直接找到它。2.3 OpenCV计算机视觉的“标准答案”OpenCV是ORB-SLAM3处理图像、提取ORB特征、进行几何计算的核心。ORB-SLAM3需要OpenCV 3.2以上版本。Ubuntu 22.04的软件源提供了OpenCV 4.5.4这是一个非常稳定且功能完善的版本我们直接安装即可省去漫长的源码编译时间。sudo apt install -y libopencv-dev安装完成后可以验证一下版本和安装是否成功pkg-config --modversion opencv4如果显示4.5.4或类似版本号说明安装成功。ORB-SLAM3的CMakeLists.txt能够很好地适配OpenCV 4所以不用担心兼容性问题。2.4 Eigen3线性代数的“瑞士军刀”如前所述Eigen已经通过libeigen3-dev安装。但我们需要确认它的位置以便ORB-SLAM3能找到。Eigen是一个纯头文件库没有.so动态库文件因此安装后只需确保头文件路径正确。# 查找Eigen头文件位置 sudo updatedb locate eigen3 | grep /usr/include通常路径是/usr/include/eigen3。在后续编译ORB-SLAM3时CMake会自动通过find_package(Eigen3 REQUIRED)找到它。3. ORB-SLAM3本体获取、编译与基础测试当所有依赖就位后我们就可以请出今天的主角了。编译过程本身不复杂但细节决定成败。3.1 克隆代码与准备第三方库ORB-SLAM3官方仓库包含了一个重要的子模块submodule——DBoW2和g2o。DBoW2用于词袋模型回环检测g2o是用于图优化的后端库。我们必须递归克隆确保这些子模块代码一并下载。cd ~ git clone https://github.com/UZ-SLAMLab/ORB_SLAM3.git ORB_SLAM3 cd ORB_SLAM3 git submodule update --init --recursive这一步非常关键如果你只克隆了主仓库而没有初始化子模块编译时一定会报错提示找不到DBoW2或g2o的头文件。我见过太多人在这里卡住。3.2 编译配置与参数解读进入ORB-SLAM3目录创建并进入构建目录。mkdir build cd build接下来是配置CMake。这里有几个关键参数需要理解cmake .. -DCMAKE_BUILD_TYPERelease -DPANGOLIN_VIEWER_DEFAULTON-DCMAKE_BUILD_TYPERelease指定编译为发布版本。与Debug版本相比Release版本编译器会进行大量优化如-O3去除调试信息生成的二进制文件运行速度更快但不利于调试。对于首次安装和测试用Release就行。-DPANGOLIN_VIEWER_DEFAULTON这是一个重要的选项。ORB-SLAM3支持多种可视化工具如Pangolin、OpenCV的简单窗口等。这个选项将Pangolin设置为默认的可视化器。如果你不开启运行时可能需要额外参数指定对于新手容易造成困惑。执行cmake ..后终端会输出一大段信息仔细查看是否有Found Pangolin、Found OpenCV、Found Eigen3等字样并确认它们都指向正确的版本。如果某个库显示NOT FOUND就需要回头检查该库的安装。3.3 编译过程与常见错误排查配置成功后开始编译。make -j$(nproc)这是最考验耐心的阶段。如果一切顺利几分钟后你会在build目录下看到生成的可执行文件例如mono_euroc、stereo_euroc、mono_inertial_euroc等分别对应单目、双目、单目惯导等不同传感器配置的示例程序。但更可能的情况是你会遇到编译错误。下面是我总结的几个高频错误及解决方案错误1fatal error: Eigen/Core: No such file or directory这通常是因为CMake没有正确找到Eigen。虽然我们安装了libeigen3-dev但有时Eigen的头文件路径比较特殊。解决方法是手动指定Eigen3的路径。首先找到Eigen3的配置文件sudo find /usr -name Eigen3Config.cmake -o -name eigen3-config.cmake 2/dev/null假设找到的路径是/usr/lib/cmake/eigen3/Eigen3Config.cmake。那么在运行CMake时可以显式指定cmake .. -DCMAKE_BUILD_TYPERelease -DPANGOLIN_VIEWER_DEFAULTON -DEigen3_DIR/usr/lib/cmake/eigen3/错误2链接错误提示undefined reference topangolin::或DBoW2::等这是典型的链接阶段错误意味着编译器找到了头文件编译通过但链接器找不到对应的库文件实现。可能的原因和解决步骤库未安装或安装失败回顾Pangolin的sudo make install是否成功执行。可以检查/usr/local/lib下是否有libpangolin.so文件。库路径未加入链接器搜索范围系统默认的库搜索路径可能不包含/usr/local/lib。编辑/etc/ld.so.conf文件或在/etc/ld.so.conf.d/目录下创建一个新文件如local.conf里面加入一行/usr/local/lib然后执行sudo ldconfig更新缓存。CMake未正确找到库有时CMake的find_package会找到错误版本或找不到。可以尝试在ORB-SLAM3的CMakeLists.txt中位于项目根目录在find_package(Pangolin REQUIRED)前面手动设置库路径不推荐新手直接修改可作为最后手段。错误3OpenCV 4.x requires enabled C11 support这个错误在较新的OpenCV版本中可能出现。解决方法是在ORB-SLAM3的CMakeLists.txt中明确设置C标准。找到CMakeLists.txt中设置编译标志的地方添加set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON)或者更简单的方法是在CMake命令中指定cmake .. -DCMAKE_BUILD_TYPERelease -DPANGOLIN_VIEWER_DEFAULTON -DCMAKE_CXX_STANDARD113.4 运行第一个示例EuRoC MAV数据集编译成功后我们需要数据来测试。ORB-SLAM3官方示例使用著名的EuRoC MAV数据集。这是一个在室内环境下由微型飞行器采集的包含双目图像和IMU数据的数据集。下载数据集从 EuRoC官网 下载一个轻量级序列例如MH_01_easy.zip。解压并组织将下载的zip文件解压你会得到一个类似MH_01_easy的文件夹里面包含mav0子文件夹。准备词汇表ORB-SLAM3需要预先训练好的词袋模型Vocabulary来进行回环检测和重定位。在ORB_SLAM3源码目录下有一个Vocabulary文件夹里面有一个文本文件ORBvoc.txt。这就是我们需要的词汇表文件。确保你后续运行程序时能正确指定这个文件的路径。运行单目示例假设你的数据集路径是~/Datasets/EuRoC/MH_01_easy/mav0词汇表路径是~/ORB_SLAM3/Vocabulary/ORBvoc.txtORB-SLAM3的配置文件路径是~/ORB_SLAM3/Examples/Monocular/EuRoC.yaml。那么运行命令如下cd ~/ORB_SLAM3/build ./mono_euroc \ ../../Vocabulary/ORBvoc.txt \ ../../Examples/Monocular/EuRoC.yaml \ /home/你的用户名/Datasets/EuRoC/MH_01_easy/mav0 \ ../../Examples/Monocular/EuRoC_TimeStamps/MH01.txt命令解释./mono_euroc: 运行单目EuRoC示例程序。第一个参数词袋文件路径。第二个参数相机配置文件路径里面包含了相机内参、畸变系数、ORB特征提取参数等。第三个参数数据集序列的根目录路径即包含cam0,imu0等文件夹的mav0目录的上一级。第四个参数时间戳文件路径该文件告诉程序按什么顺序读取图像。如果一切配置正确你将看到一个Pangolin窗口弹出显示相机实时跟踪的画面、地图点云和估计的轨迹。终端也会输出跟踪状态、帧率等信息。看到这个画面恭喜你ORB-SLAM3已经成功在你的系统上跑起来了4. 进阶配置与深度集成指南成功运行示例只是第一步。要想把ORB-SLAM3用在自己的项目或机器人上还需要了解一些进阶配置和集成技巧。4.1 理解关键配置文件ORB-SLAM3的行为很大程度上由YAML配置文件决定。以EuRoC.yaml为例我们看几个关键部分%YAML:1.0 # 相机参数 Camera.type: PinHole Camera.fx: 458.654 Camera.fy: 457.296 Camera.cx: 367.215 Camera.cy: 248.375 Camera.k1: -0.28340811 Camera.k2: 0.07395907 Camera.p1: 0.00019359 Camera.p2: 1.76187114e-05 # ORB特征参数 ORBextractor.nFeatures: 1200 ORBextractor.scaleFactor: 1.2 ORBextractor.nLevels: 8 ORBextractor.iniThFAST: 20 ORBextractor.minThFAST: 7 # 相机帧率 Camera.fps: 20.0 # 其他系统参数 Viewer.KeyFrameSize: 0.05 Viewer.KeyFrameLineWidth: 1 Viewer.GraphLineWidth: 0.9相机参数fx, fy, cx, cy, k1, k2, p1, p2这是相机的内参和畸变系数。这是最重要的部分你必须使用自己相机的标定结果替换这些值否则SLAM系统无法正确理解图像几何必然导致跟踪失败。可以使用OpenCV的calibrateCamera或Kalibr等工具进行相机标定。ORB特征参数nFeatures: 每帧图像提取的最大ORB特征点数。越多则匹配越鲁棒但计算量越大。对于VGA分辨率640x4801200是个合理的值对于高清图像可能需要增加到2000-3000。scaleFactor: 图像金字塔的尺度因子用于提取尺度不变特征。1.2是常用值。nLevels: 图像金字塔层数。8层是一个较好的平衡。iniThFAST和minThFAST: FAST角点检测的阈值。初始阈值高如果找不到足够角点则使用更低的最小阈值。调整它们可以控制特征点的数量和分布。Viewer参数控制Pangolin窗口中关键帧、地图点等元素的显示大小和线宽按个人喜好调整即可。4.2 如何接入自己的相机或视频流ORB-SLAM3的示例都是从图片序列或数据集读取数据。要接入USB摄像头或ROS话题需要修改代码。这里以接入OpenCV的VideoCapture为例提供一个最简单的思路在Examples/Monocular/mono_euroc.cc附近创建一个新的主程序文件例如my_mono_camera.cc。复制mono_euroc.cc的框架但将读取图片序列的循环替换为从cv::VideoCapture读取帧的循环。关键步骤是时间戳。SLAM系统需要每一帧图像对应的时间戳以秒为单位double类型。对于实时视频可以使用std::chrono::system_clock来生成。确保在创建SLAM系统对象时传入正确的配置文件路径包含你的相机内参。这是一个高度简化的示例片段#include opencv2/videoio.hpp #include chrono // ... 省略SLAM系统初始化代码 (ORB_SLAM3::System SLAM(...)) cv::VideoCapture cap(0); // 打开默认摄像头 if(!cap.isOpened()) { cerr Failed to open camera! endl; return -1; } cv::Mat im; auto start_time std::chrono::system_clock::now(); while(true) { cap im; if(im.empty()) break; auto now std::chrono::system_clock::now(); std::chrono::durationdouble timestamp now - start_time; // 将图像传给SLAM系统 SLAM.TrackMonocular(im, timestamp.count()); // 处理可视化、退出等 // ... }注意这只是一个概念性示例。实际集成需要考虑图像去畸变使用配置文件中的畸变系数、分辨率缩放、线程同步、系统初始化和退出逻辑等复杂问题。对于严肃的项目建议仔细研究Examples目录下的源码结构。4.3 与ROS机器人操作系统集成ORB-SLAM3官方提供了ROS接口包位于ORB_SLAM3/Examples/ROS/ORB_SLAM3。这允许你轻松地将ORB-SLAM3作为一个ROS节点运行订阅/camera/image_raw等图像话题并发布/orb_slam3/camera_pose等位姿话题。集成步骤大致如下安装ROS确保你安装了ROS Noetic对应Ubuntu 20.04或ROS 2 Humble对应Ubuntu 22.04。ORB-SLAM3的ROS包主要针对ROS 1设计。设置ROS工作空间mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src复制ROS包并编译cp -r ~/ORB_SLAM3/Examples/ROS/ORB_SLAM3 ~/catkin_ws/src/ cd ~/catkin_ws catkin_make -j$(nproc)编译过程可能会报错常见问题是找不到Pangolin、OpenCV或Eigen3。你需要确保ROS环境能找到这些库。一个可靠的方法是在ROS包的CMakeLists.txt中通过find_package和include_directories、target_link_libraries显式指定路径。配置启动文件ROS包提供了.launch文件你需要在其中指定词汇表文件路径、配置文件路径、相机话题名等参数。运行source devel/setup.bash后使用roslaunch启动相应的launch文件。ROS集成会引入额外的复杂性但它是将ORB-SLAM3应用到真实机器人上的标准方式可以方便地与激光雷达、IMU、控制节点等进行数据交换和系统集成。5. 性能调优、问题诊断与实战心得即使程序能跑起来你可能还会遇到跟踪不稳定、容易丢失、精度不高或者速度慢的问题。这一部分分享一些调优和诊断的经验。5.1 提升跟踪稳定性和速度特征点数量与质量配置文件中的ORBextractor.nFeatures是首要调节参数。在计算资源允许的范围内适当增加特征点数如从1200到2000可以提升在纹理稀疏区域的跟踪鲁棒性。同时确保图像对比度足够过于模糊或过曝/欠曝的图像会导致特征提取失败。图像金字塔scaleFactor和nLevels决定了特征点的尺度不变性。对于相机运动剧烈、尺度变化大的场景如无人机快速升降可以适当增加nLevels例如到10或减小scaleFactor例如到1.1让系统能在更多尺度上找到匹配但会增加计算量。初始化策略ORB-SLAM3的单目模式需要一段初始化过程来估计初始地图和尺度。这段时期相机需要做明显的平移运动不能是纯旋转并且场景要有足够的视差和纹理。如果初始化总是失败尝试在更有纹理的区域以“左右平移”的方式移动相机开始。使用IMU如果可用ORB-SLAM3最大的亮点之一是其出色的视觉惯性融合能力。如果你的设备有IMU强烈建议使用mono_inertial或stereo_inertial模式。IMU提供的短期高精度姿态和尺度信息能极大提升系统的鲁棒性、精度并解决单目视觉的尺度模糊问题。配置文件中需要正确设置IMU的参数噪声密度、随机游走等这些通常需要根据IMU的 datasheet 来设置或通过工具标定。5.2 常见运行问题诊断问题跟踪状态频繁在OK和LOST之间切换。可能原因1相机运动过快。ORB特征匹配基于描述子在相邻帧间运动过大时匹配会失败。尝试降低相机运动速度。可能原因2图像模糊。检查相机是否失焦或者快门速度是否过慢导致运动模糊。可以考虑在图像预处理中加入去模糊或使用全局快门相机。可能原因3场景纹理缺失或重复。如白墙、长走廊。ORB特征在缺乏角点或纹理高度重复的区域难以进行唯一匹配。这是视觉SLAM的固有难题可以考虑加入其他传感器如IMU、激光雷达或使用基于直接法或深度学习的特征。诊断方法运行程序时观察Pangolin窗口。如果跟踪正常你应该能看到稳定的绿色地图点当前帧观察到的和红色的关键帧。如果跟踪丢失地图点会消失。可以尝试开启Viewer中显示特征点的选项看看每帧实际提取到了多少特征点。问题轨迹漂移严重回环检测没有生效。可能原因1词袋模型文件路径错误或损坏。确保ORBvoc.txt路径正确并且文件完整文件很大约50MB。可能原因2回环检测阈值设置。在系统头文件ORB_SLAM3/include/LoopClosing.h或相关配置中有关于回环相似度分数的阈值。如果场景外观变化很大光照剧烈变化、季节变化可能需要调整这些阈值但需谨慎避免误检。可能原因3运行时间不够长。回环检测需要积累一定数量的关键帧后才开始工作并且需要回到之前去过的地方。运行一个闭环的序列才能看到效果。5.3 个人实战心得与避坑总结环境隔离是美德强烈建议使用Docker或虚拟环境来配置ORB-SLAM3。这样你可以创建一个纯净、可复现的环境避免与系统其他软件的依赖冲突。编译成功后将整个容器或环境镜像保存下来以后换电脑或重装系统可以瞬间恢复。版本管理ORB-SLAM3及其依赖库都在持续更新。记录下你成功编译时使用的各库的git commit hash或版本号如Pangolin v0.8, OpenCV 4.5.4。未来更新代码后如果出现问题可以快速回退到稳定版本。调试利器GDB和日志当程序崩溃或出现诡异行为时不要慌。用gdb启动可执行文件发生崩溃时可以打印堆栈信息定位问题代码。同时ORB-SLAM3内部有丰富的日志输出可以通过修改include/System.h中的VERBOSE宏定义来开启不同级别的调试信息。从数据集开始再到真实世界不要一开始就用自己的摄像头。先用EuRoC、KITTI等标准数据集验证你的安装是否正确感受不同参数下的效果。这能帮你建立一个性能基准并排除硬件和数据采集带来的问题。理解原理比跑通代码更重要ORB-SLAM3是一个复杂的系统。花时间阅读其论文了解各个模块跟踪、局部建图、回环检测、地图融合是如何协同工作的。这样当出现问题时你才能有的放矢地去调整参数或修改代码而不是盲目试错。配置ORB-SLAM3就像拼装一台精密仪器每一步的严谨都能为后续的研究开发节省大量时间。希望这篇详细的指南能帮你跨过环境配置这道坎把精力真正投入到SLAM算法的学习和创新中去。