1. 项目概述与核心价值在机器人、自动驾驶和增强现实这些前沿领域让机器“看见”并理解自己所处的三维环境是核心技术之一。这就是SLAM即时定位与地图构建技术要解决的问题。而ORB-SLAM3作为该领域一个里程碑式的开源项目因其出色的精度、鲁棒性和对单目、双目、RGB-D以及惯性等多种传感器模式的完整支持成为了众多研究者和工程师入门的首选。然而对于刚接触这个领域特别是使用Ubuntu 22.04 LTS这个当前主流且稳定的Linux发行版的朋友来说从零开始搭建ORB-SLAM3的开发环境绝对是一个不小的挑战。这个过程不仅涉及复杂的依赖库管理还需要处理不同版本软件包之间的兼容性问题一个环节出错就可能导致数小时的排查。我自己在Ubuntu 22.04上部署ORB-SLAM3的经历可以说是一步一个坑走过来的。网上的教程五花八门有的基于旧版Ubuntu有的依赖版本已经过时直接照搬大概率会失败。这篇文章我将结合自己的实战经验为你提供一份在纯净的Ubuntu 22.04系统上从零开始成功编译、安装并运行ORB-SLAM3的完整指南。我会详细拆解每一个步骤背后的原理解释为什么需要安装某个库以及遇到常见错误时如何高效地排查和解决。无论你是计算机视觉方向的学生还是正在开发相关应用的工程师这份指南都能帮你绕过我踩过的那些坑高效地搭建起这个强大的视觉SLAM工具。2. 环境准备与系统基础配置在开始安装ORB-SLAM3之前确保你有一个全新的或者至少是干净的Ubuntu 22.04 LTS系统环境至关重要。我强烈建议使用物理机安装或者分配了足够资源的虚拟机建议至少4核CPU、8GB内存、50GB硬盘空间。如果你使用WSL2虽然也可以但在图形显示Pangolin和某些硬件加速方面可能会遇到额外问题本文主要针对标准桌面环境。2.1 系统更新与基础构建工具首先打开终端进行系统更新并安装最基础的编译工具链。这是所有后续工作的基石。sudo apt update sudo apt upgrade -y sudo apt install build-essential cmake git pkg-config -ybuild-essential: 这个元数据包包含了GCC/G编译器、make工具以及一些必要的C/C标准库头文件。没有它你无法编译任何C项目。cmake: ORB-SLAM3及其依赖如OpenCV, Pangolin都使用CMake作为构建系统。它是现代C项目的事实标准用于生成平台相关的Makefile或项目文件。git: 用于从GitHub克隆ORB-SLAM3及其依赖库的源代码。pkg-config: 一个帮助在编译和链接时查找库文件路径和头文件路径的工具很多开源库的CMake脚本会用到它。注意sudo apt upgrade -y会升级所有已安装的软件包。如果你在关键的生产环境中可能需要更谨慎地选择升级的包。但对于学习和开发环境保持系统最新可以减少很多潜在的库冲突。2.2 安装必要的第三方依赖库ORB-SLAM3依赖于一系列强大的开源库来处理图像、数学运算、图形显示等。以下命令将一次性安装大部分必需的开发包。sudo apt install libgtk-3-dev libavcodec-dev libavformat-dev libswscale-dev libtbb-dev libjpeg-dev libpng-dev libtiff-dev libopenexr-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev libdc1394-22-dev libopenblas-dev libeigen3-dev libglew-dev libboost-all-dev libssl-dev libomp-dev -y让我们拆解一下这些库的作用libgtk-3-dev: GTK图形工具包主要用于OpenCV的高层GUI功能如imshow。即使你打算在无头服务器上运行某些OpenCV功能也可能需要它。libavcodec-dev, libavformat-dev, libswscale-dev: FFmpeg的库用于视频文件的编解码和缩放是OpenCV视频IO模块的核心依赖。libtbb-dev: Intel线程构建模块用于提供跨平台的并行编程支持能显著提升OpenCV在多核CPU上的性能。图像编解码库(libjpeg-dev, libpng-dev, libtiff-dev): 处理JPEG, PNG, TIFF等常见图像格式。libopenexr-dev: 用于支持OpenEXR高动态范围图像格式。libdc1394-22-dev: 提供对IEEE 1394火线相机驱动的支持。libopenblas-dev: 一个优化的BLAS基础线性代数子程序库实现为线性代数运算提供加速。libeigen3-dev:极其重要。Eigen是一个用于线性代数、矩阵和向量运算的C模板库。ORB-SLAM3内部大量使用Eigen进行几何变换、优化等数学计算。Ubuntu 22.04仓库中的版本3.4.0完全兼容。libglew-dev: OpenGL扩展加载库是Pangolin用于3D可视化的窗口管理库的必需依赖。libboost-all-dev: Boost C库提供了大量通用工具如智能指针、线程、文件系统等ORB-SLAM3的某些组件会用到。libssl-dev: OpenSSL开发库某些网络相关的功能可能会间接依赖。libomp-dev: OpenMP运行时库用于支持基于共享内存的并行编程有助于提升性能。3. 核心依赖库的编译与安装ORB-SLAM3对OpenCV和Pangolin的版本有特定要求而Ubuntu 22.04官方仓库提供的版本可能不匹配或缺少某些特性因此我们需要从源码编译安装。3.1 编译安装OpenCV 4.6.0OpenCV是计算机视觉的基石。ORB-SLAM3官方推荐并测试了OpenCV 4.6.0。使用特定版本可以最大程度保证兼容性。创建开发目录并克隆源码 我习惯在用户主目录下创建一个Dev或Workspace目录来存放所有从源码构建的软件。cd ~ mkdir -p Dev cd Dev git clone https://github.com/opencv/opencv.git cd opencv git checkout 4.6.0git checkout 4.6.0命令确保我们切换到4.6.0这个特定的发布标签。配置与编译mkdir build cd build cmake -D CMAKE_BUILD_TYPERelease \ -D WITH_CUDAOFF \ -D WITH_GTKON \ -D BUILD_opencv_worldOFF \ -D BUILD_EXAMPLESOFF \ -D BUILD_TESTSOFF \ -D CMAKE_INSTALL_PREFIX/usr/local ..CMAKE_BUILD_TYPERelease: 生成优化过的发布版本性能更好。WITH_CUDAOFF: 对于初次安装为了简化问题我们先禁用CUDA支持。如果你有NVIDIA显卡并已安装好CUDA可以设置为ON以利用GPU加速。WITH_GTKON: 启用GTK支持用于图像显示。BUILD_opencv_worldOFF: 不生成单个大的opencv_world库而是生成独立的模块库如core,imgproc,highgui等。这有助于减少链接时的库大小并且是更常见的做法。BUILD_EXAMPLES和BUILD_TESTS: 设为OFF以加快编译速度。CMAKE_INSTALL_PREFIX/usr/local: 指定安装路径为/usr/local这是Linux系统安装本地软件的标准位置。开始编译 使用make -j$(nproc)命令启动编译$(nproc)会自动获取你CPU的核心数进行并行编译以大幅缩短时间。make -j$(nproc)这个过程根据你的机器性能可能需要15分钟到1小时不等。如果遇到内存不足可以减少并行任务数例如make -j4。安装 编译成功后执行安装命令将编译好的库和头文件复制到/usr/local目录下。sudo make install sudo ldconfigsudo ldconfig命令更新系统的动态链接器运行时绑定让系统立刻能找到新安装的OpenCV库。实操心得编译OpenCV是整个过程中最耗时且最容易出错的环节。如果cmake阶段报错通常是缺少某个依赖库请根据错误信息使用apt search和apt install来安装对应的-dev包。编译过程中如果卡死或报错可以先尝试make clean后减少-j后面的并行数重新编译。3.2 编译安装PangolinPangolin是一个轻量级的OpenGL显示/交互库ORB-SLAM3用它来实时显示相机轨迹、地图点和关键帧。克隆源码cd ~/Dev git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin配置与编译mkdir build cd build cmake -D CMAKE_BUILD_TYPERelease .. make -j$(nproc) sudo make install sudo ldconfigPangolin的依赖相对简单如果之前基础依赖安装齐全这里通常会很顺利。同样CMAKE_INSTALL_PREFIX默认为/usr/local。4. ORB-SLAM3的获取、修改与编译核心依赖就绪后我们就可以着手处理主角了。4.1 克隆源码与关键修改cd ~/Dev git clone https://github.com/UZ-SLAMLab/ORB_SLAM3.git cd ORB_SLAM3克隆完成后有一个至关重要的修改。ORB-SLAM3的CMakeLists.txt默认使用C11标准但在Ubuntu 22.04的默认编译器套件下可能需要C14标准来更好地支持某些特性。使用sed命令进行快速修改sed -i s/11/14/g CMakeLists.txt这个命令将文件中所有的C11替换为C14。你可以用文本编辑器打开CMakeLists.txt确认第2行附近set(CMAKE_CXX_STANDARD 11)是否已变为set(CMAKE_CXX_STANDARD 14)。4.2 执行编译脚本ORB-SLAM3提供了一个便捷的build.sh脚本它会自动编译第三方依赖如DBoW2, g2o以及ORB-SLAM3本身。chmod x build.sh ./build.shchmod x build.sh是赋予脚本可执行权限。执行./build.sh后终端会输出大量的编译信息。这个过程会持续几分钟。常见问题与排查错误fatal error: Eigen/Core: No such file or directory这通常意味着系统找不到Eigen头文件。虽然我们安装了libeigen3-dev但它的头文件可能安装在/usr/include/eigen3下。ORB-SLAM3默认在/usr/include下寻找。解决方法是创建一个符号链接sudo ln -s /usr/include/eigen3/Eigen /usr/include/Eigen sudo ln -s /usr/include/eigen3/unsupported /usr/include/unsupported然后重新运行./build.sh。错误与OpenCV或Pangolin相关的链接错误确保OpenCV和Pangolin已正确安装到/usr/local并且运行了sudo ldconfig。你可以手动检查pkg-config --modversion opencv4 # 应返回 4.6.0如果返回找不到可能需要手动设置PKG_CONFIG_PATHexport PKG_CONFIG_PATH/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH将这条命令添加到你的~/.bashrc文件中使其永久生效。编译过程卡住或报错 脚本可能会因为网络问题下载第三方依赖失败。你可以尝试多运行几次./build.sh。或者进入Thirdparty/目录手动检查DBoW2和g2o文件夹是否为空尝试手动git clone对应的仓库。当编译成功完成后你会在Examples/目录下的各个子文件夹如Monocular,Stereo等中看到生成的可执行文件如mono_eurocstereo_euroc等。5. 数据集下载与运行测试编译成功只是第一步我们需要用真实的数据来验证ORB-SLAM3是否正常工作。这里以著名的EuRoC MAV数据集为例。5.1 下载EuRoC数据集EuRoC数据集包含在微型飞行器上采集的视觉惯性数据广泛用于SLAM算法评估。我们下载其中一个简单的序列MH_01_easy。cd ~ mkdir -p Datasets/EuRoc cd Datasets/EuRoc wget -c http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/machine_hall/MH_01_easy/MH_01_easy.zip mkdir MH01 unzip MH_01_easy.zip -d MH01/下载完成后MH01文件夹内应包含mav0目录其中有cam0图像、imu0IMU数据等子文件夹。5.2 运行ORB-SLAM3进行测试ORB-SLAM3提供了多种运行模式对应不同的传感器配置。我们以双目模式为例因为它不需要初始化且结果相对稳定。准备词汇表ORB-SLAM3使用一个预先训练好的视觉词汇表ORBvoc.txt进行特征匹配加速。项目已自带位于Vocabulary/目录下。运行双目SLAMcd ~/Dev/ORB_SLAM3 ./Examples/Stereo/stereo_euroc ./Vocabulary/ORBvoc.txt ./Examples/Stereo/EuRoC.yaml ~/Datasets/EuRoc/MH01 ./Examples/Stereo/EuRoC_TimeStamps/MH01.txt dataset-MH01_stereo逐项解释命令参数./Examples/Stereo/stereo_euroc: 编译生成的双目Euroc数据集可执行程序。./Vocabulary/ORBvoc.txt: ORB特征词汇表文件路径。./Examples/Stereo/EuRoC.yaml: 双目相机的配置文件内含相机内参、畸变系数、双目基线等。~/Datasets/EuRoc/MH01: 数据集序列MH01的根目录路径。./Examples/Stereo/EuRoC_TimeStamps/MH01.txt: 该序列对应的时间戳文件确保程序按正确顺序读取图像。dataset-MH01_stereo: 输出的轨迹文件名称前缀。观察运行结果 如果一切顺利终端会开始输出初始化、跟踪、局部建图等信息。同时Pangolin窗口会弹出显示三个视图主视图当前相机视角看到的图像以及提取和匹配的ORB特征点。轨迹视图显示估计的相机运动轨迹通常为红色和构建的地图点蓝色点云。帧视图显示关键帧及其关系。 你可以用鼠标在Pangolin窗口中拖拽旋转视角用滚轮缩放。程序会一直运行直到处理完所有图像。6. 轨迹精度评估与可视化运行结束后我们得到了估计的相机轨迹文件例如f_dataset-MH01_stereo.txt。为了定量评估算法性能我们需要将其与数据集中提供的真实轨迹Ground Truth进行比较。ORB-SLAM3提供了评估脚本。6.1 安装Python 2.7评估环境评估脚本基于Python 2.7编写。Ubuntu 22.04默认已不安装Python 2.7我们需要手动安装并配置。sudo apt install python2 curl -y cd /tmp curl https://bootstrap.pypa.io/pip/2.7/get-pip.py --output get-pip.py sudo python2 get-pip.py sudo pip2 install numpy matplotlib注意matplotlib可能需要一些系统依赖如果安装失败可以尝试先安装sudo apt install python2-tk。6.2 执行轨迹评估首先确保你已经运行了上一节的双目示例生成了轨迹文件f_dataset-MH01_stereo.txt。cd ~/Dev/ORB_SLAM3 python2 evaluation/evaluate_ate_scale.py evaluation/Ground_truth/EuRoC_left_cam/MH01_GT.txt f_dataset-MH01_stereo.txt --plot MH01_stereo.pdfevaluate_ate_scale.py: 评估脚本计算绝对轨迹误差ATE并考虑尺度对齐因为单目/双目SLAM的尺度是未知的。evaluation/Ground_truth/EuRoC_left_cam/MH01_GT.txt: 数据集提供的左相机真实轨迹。f_dataset-MH01_stereo.txt: 上一步ORB-SLAM3估计出的轨迹文件。--plot MH01_stereo.pdf: 指定输出PDF格式的对比图。运行后终端会输出ATE的统计结果包括均方根误差RMSE、均值、中位数等。同时会在当前目录生成MH01_stereo.pdf文件。用文档查看器打开它你可以看到估计轨迹绿色与真实轨迹黑色在空间上的对齐情况直观地了解算法的精度。7. 进阶配置与深度优化指南成功运行示例只是起点。要让ORB-SLAM3在你的实际项目或研究中发挥作用还需要进行一系列深度配置和优化。7.1 使用ROS进行实时数据流处理ORB-SLAM3官方提供了ROS接口这是将其应用于真实机器人如无人机、移动机器人的桥梁。ROS节点可以订阅相机/camera/image_raw和IMU/imu/data话题实时调用ORB-SLAM3进行处理。安装ROS 2 HumbleUbuntu 22.04对应版本 请参考ROS官方文档进行安装。通常包括设置软件源、安装核心包等步骤。编译ORB-SLAM3 ROS节点 在ORB-SLAM3目录下有一个ros文件夹。你需要创建一个ROS工作空间并将ORB-SLAM3链接或复制过去然后使用catkin_make或colcon进行编译。编译前务必确保你的ROS_PACKAGE_PATH环境变量包含了ORB-SLAM3的路径并且所有非ROS依赖OpenCV, Pangolin, Eigen已正确安装。配置启动文件 你需要编写或修改ROS启动文件.launch.py正确设置相机参数文件路径、词汇表路径并连接到正确的ROS话题。ORB-SLAM3的ROS包装器对话题名称和数据格式有严格要求。7.2 参数文件详解与调优ORB-SLAM3的行为由YAML配置文件精细控制。以Examples/Stereo/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 # 双目基线单位米 Camera.bf: 47.90639384423901 # 图像尺寸 Camera.width: 752 Camera.height: 480 # 帧率 Camera.fps: 20.0 # ORB特征提取参数 ORBextractor.nFeatures: 1200 # 每帧提取的特征点数量 ORBextractor.scaleFactor: 1.2 # 图像金字塔尺度因子 ORBextractor.nLevels: 8 # 金字塔层数 ORBextractor.iniThFAST: 20 # FAST角点检测初始阈值 ORBextractor.minThFAST: 7 # FAST角点检测最小阈值 # 其他系统参数 System.LoadAtlasFromFile: 0 # 是否从文件加载地图 Viewer.KeyFrameSize: 0.05 Viewer.KeyFrameLineWidth: 1 Viewer.GraphLineWidth: 0.9 Viewer.PointSize: 2 Viewer.CameraSize: 0.08 Viewer.CameraLineWidth: 3 Viewer.ViewpointX: 0 Viewer.ViewpointY: -0.7 Viewer.ViewpointZ: -1.8 Viewer.ViewpointF: 500性能调优点ORBextractor.nFeatures: 增加此值可以提取更多特征提高匹配鲁棒性但会增加计算量。对于纹理丰富的场景可以适当降低如800-1000对于纹理稀疏的场景需要提高如1500-2000。ORBextractor.scaleFactor和ORBextractor.nLevels: 尺度金字塔参数。更大的scaleFactor和更多的nLevels有助于处理尺度变化但同样增加计算成本。通常1.2和8是一个较好的平衡。针对你的相机最重要的调优是替换相机内参和畸变系数。你必须使用相机标定工具如OpenCV的calibrateCamera或Kalibr工具包获取你自己相机的fx, fy, cx, cy, k1, k2, p1, p2等参数并更新到YAML文件中。错误的相机参数是导致SLAM失败的最常见原因之一。7.3 常见问题深度排查与解决实录即使按照步骤操作你也可能遇到各种问题。以下是我在多次部署中总结的“坑点”与解决方案Pangolin窗口无法打开或闪退现象运行示例时终端输出正常但没有任何图形窗口弹出或者窗口一闪而过。排查首先确认系统安装了图形驱动和OpenGL支持。运行glxinfo | grep “OpenGL version”查看。检查Pangolin是否编译了GUI支持。在Pangolin的build目录下查看CMakeCache.txt确认HAVE_PANGOLIN_GUI是否为ON。如果你通过SSH远程连接服务器无图形界面需要设置X11转发ssh -X并且服务器上安装了xorg相关包。对于纯无头服务器可以考虑禁用Pangolin可视化修改ORB-SLAM3代码中相关的可视化调用。解决对于桌面环境确保安装了libgl1-mesa-dev和libglu1-mesa-dev。重新编译Pangolin前可以尝试cmake .. -D CMAKE_BUILD_TYPERelease -D BUILD_PANGOLIN_GUION。运行时提示“找不到libopencv_core.so.406”等动态库错误现象运行ORB-SLAM3可执行文件时报错error while loading shared libraries: libopencv_core.so.406: cannot open shared object file。原因系统动态链接器找不到我们编译安装的OpenCV 4.6.0库。虽然我们安装到了/usr/local/lib但链接器的缓存可能没有更新或者路径不在默认搜索范围内。解决运行sudo ldconfig刷新缓存。检查库文件是否存在ls /usr/local/lib/libopencv_core.so.4*。将/usr/local/lib添加到链接器路径创建文件/etc/ld.so.conf.d/opencv.conf写入/usr/local/lib然后再次运行sudo ldconfig。特征跟踪丢失频繁轨迹很快漂移现象程序能启动但跟踪状态经常在LOST和OK之间切换地图点很少轨迹不连续。排查首要怀疑相机参数确认YAML配置文件中的相机内参、畸变系数、图像尺寸是否与你的数据完全匹配。一个像素的误差都可能导致特征匹配失败。检查数据集路径和时间戳确保数据集路径正确且时间戳文件与图像文件一一对应。时间戳文件中的每一行对应一个图像文件名或时间。调整ORB特征参数尝试增加ORBextractor.nFeatures或者降低ORBextractor.iniThFAST以检测更多角点。环境问题数据集场景是否纹理足够丰富、光照是否变化剧烈ORB特征在低纹理或运动模糊下表现会变差。编译时内存不足OOM Killer现象在编译OpenCV或ORB-SLAM3时编译进程突然被终止系统日志显示Out of memory。解决减少并行编译任务数使用make -j2或make -j1替代make -j$(nproc)。增加系统交换空间Swap如果虚拟机或物理机内存较小如4GB增加2-4GB的交换空间可以缓解压力。关闭其他占用内存大的应用程序。希望使用更新的OpenCV版本ORB-SLAM3官方测试基于OpenCV 4.6.0但理论上兼容OpenCV 4.x系列。如果你想使用OpenCV 4.8或4.9克隆源码后切换到对应标签如git checkout 4.8.0即可。但需要注意新版本可能废弃某些旧的API可能导致ORB-SLAM3编译失败需要手动修改少量代码。这是一个进阶操作建议在熟悉代码后进行。整个安装和调试过程本质上是对一个复杂软件生态系统的理解和搭建。耐心和仔细阅读错误信息是关键。每一次成功的运行都意味着你向掌握视觉SLAM这项强大的技术又迈进了一步。希望这份详尽的指南能成为你探索过程中的可靠地图。