1. 项目概述最近在折腾机器人导航和三维重建ORB-SLAM3这个开源项目是绕不开的。作为目前视觉SLAM领域的标杆之一它支持单目、双目、RGB-D以及带IMU的多种传感器融合方案无论是学术研究还是工程落地参考价值都很大。不过它的编译安装过程尤其是在Ubuntu 22.04这个较新的LTS系统上堪称一道“劝退”关卡。依赖库版本冲突、编译参数设置、数据集准备每一步都可能藏着坑。我花了几天时间在几台不同的机器上包括物理机和虚拟机反复折腾总算把一套稳定、可复现的安装流程跑通了。这篇文章就是我这趟“踩坑之旅”的完整记录我会详细拆解从系统准备到最终运行测试的每一个步骤重点分享那些官方文档里不会写但实际编译中一定会遇到的细节问题和解决方案。无论你是刚接触SLAM的新手还是需要在22.04环境部署的老手希望这份经验能帮你省下大量查资料和排错的时间。2. 环境准备与核心依赖解析在Ubuntu 22.04上安装ORB-SLAM3第一步不是急着git clone代码而是把地基打牢。22.04系统自带的软件包版本比较新这既是优势性能更好也可能带来兼容性挑战。我们需要系统性地安装和配置好几类依赖基础编译工具、数学计算库、图像处理库OpenCV、以及用于可视化的Pangolin。2.1 系统更新与基础工具链首先确保你的系统是最新的。打开终端执行以下命令更新软件包列表并升级现有软件。这一步能避免很多因基础库版本过旧导致的问题。sudo apt update sudo apt upgrade -y接下来安装编译ORB-SLAM3所必需的基础开发工具。build-essential套件包含了gcc、g、make等核心工具cmake是项目构建的核心git用于拉取代码pkg-config帮助查找库文件。sudo apt install -y build-essential cmake git pkg-config2.2 关键依赖库的安装与版本考量ORB-SLAM3依赖于一系列第三方库我们需要一次性安装到位。这里给出的命令集合了多个来源的总结确保覆盖所有可能需要的库。sudo apt install -y libgtk2.0-dev libavcodec-dev libavformat-dev libswscale-dev \ libtbb-dev libjpeg-dev libpng-dev libtiff-dev libdc1394-22-dev libjasper-dev \ libglew-dev libboost-all-dev libssl-dev libeigen3-dev python3-dev python3-numpy重点解析几个关键库libeigen3-dev线性代数库ORB-SLAM3的核心数学运算依赖它。Ubuntu 22.04仓库默认提供的是3.4.0版本经过实测完全兼容无需手动编译特定版本。libboost-all-dev提供了大量C通用库ORB-SLAM3可能用到其中的线程、时间等模块。安装全部组件是最稳妥的做法。libglew-devOpenGL的扩展加载库是Pangolin后续安装的依赖用于跨平台的OpenGL功能管理。python3-dev 和 python3-numpy虽然ORB-SLAM3主体是C但其评估脚本如evaluate_ate_scale.py最初是为Python 2.7编写的。在22.04上我们更倾向于用Python 3环境来适配这些脚本所以这里先安装Python 3的开发包和NumPy。后续会对评估脚本做兼容性修改。注意网上有些教程会要求安装libpython2.7-dev和python-numpy这是因为ORB-SLAM3自带的评估工具链比较老。在Ubuntu 22.04上默认已不包含Python 2.7强行安装会引入复杂的依赖问题。我们的策略是优先使用Python 3并修改评估脚本这样更符合现代系统的维护方式。3. OpenCV 4.6.0 的编译与安装ORB-SLAM3官方明确测试并推荐使用OpenCV 4.6.0。虽然Ubuntu仓库有OpenCV但版本可能不符且预编译包可能缺少某些特性。从源码编译指定版本是最可靠的方法。3.1 源码下载与配置我们计划将第三方库都放在用户目录下的Dev文件夹中方便管理。cd ~ mkdir -p Dev cd Dev克隆OpenCV仓库并切换到4.6.0这个tag。这里注意我们同时克隆了opencv_contrib它包含了许多额外的模块虽然ORB-SLAM3不一定全部需要但为了功能完整性和避免未来其他应用缺少模块建议一并编译。git clone https://github.com/opencv/opencv.git git clone https://github.com/opencv/opencv_contrib.git cd opencv git checkout 4.6.0 cd ../opencv_contrib git checkout 4.6.0 cd ../opencv创建并进入构建目录开始配置。关键配置项解释如下-D CMAKE_BUILD_TYPERelease编译发布版本优化性能。-D WITH_CUDAOFF除非你确定需要CUDA加速且配置好了NVIDIA驱动和CUDA Toolkit否则先关闭。这能极大简化编译过程避免驱动版本不匹配等问题。-D OPENCV_EXTRA_MODULES_PATH../../opencv_contrib/modules指定额外模块的路径。-D BUILD_EXAMPLESOFF关闭示例编译加快速度。-D CMAKE_INSTALL_PREFIX/usr/local安装路径通常设为/usr/local这样系统能自动找到。mkdir build cd build cmake -D CMAKE_BUILD_TYPERelease \ -D WITH_CUDAOFF \ -D OPENCV_EXTRA_MODULES_PATH../../opencv_contrib/modules \ -D BUILD_EXAMPLESOFF \ -D CMAKE_INSTALL_PREFIX/usr/local ..3.2 编译安装与环境验证配置完成后使用make进行编译。参数-j$(nproc)表示使用所有可用的CPU核心并行编译能显著加快速度。make -j$(nproc)编译过程可能需要20分钟到1小时不等取决于你的机器性能。完成后执行安装命令将编译好的库文件、头文件等复制到/usr/local目录下。sudo make install sudo ldconfig最后验证安装是否成功。打开一个新的终端或执行source ~/.bashrc运行pkg-config --modversion opencv4如果正确显示4.6.0则说明OpenCV安装配置成功。这一步非常关键很多后续的编译错误都源于OpenCV路径没有正确被系统识别。4. Pangolin可视化库的安装Pangolin是一个轻量级的OpenGL显示与交互库ORB-SLAM3用它来实时显示相机轨迹、地图点云等。它的安装相对简单。4.1 源码获取与编译进入Dev目录克隆Pangolin的仓库。注意ORB-SLAM3对Pangolin的版本有一定要求直接克隆主分支通常可以但如果遇到问题可以尝试切换到较新的稳定tag。cd ~/Dev git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin最佳的实践是创建一个构建目录进行“out-of-source”构建保持源码目录的清洁。mkdir build cd build执行CMake配置。这里同样建议关闭CUDA支持以简化安装除非你后续有其他用途。cmake .. -D CMAKE_BUILD_TYPERelease -D WITH_CUDAOFF make -j$(nproc) sudo make install安装完成后Pangolin的头文件和库文件也会被放置到/usr/local下。4.2 可能遇到的问题与解决有时即使安装成功在编译ORB-SLAM3时仍可能找不到Pangolin。这可能是因为CMake的配置文件路径问题。一个排查方法是检查/usr/local/lib/cmake目录下是否存在Pangolin文件夹。如果不存在可以尝试手动设置环境变量但更根本的解决方法是确保/usr/local/lib和/usr/local/include在系统的默认搜索路径中sudo ldconfig命令通常能更新库的缓存。5. ORB-SLAM3本体的编译与配置依赖全部就绪后终于可以开始编译ORB-SLAM3本体了。这是整个过程中最容易出错的一环。5.1 源码下载与C标准修订克隆官方的ORB-SLAM3仓库。cd ~/Dev git clone https://github.com/UZ-SLAMLab/ORB_SLAM3.git cd ORB_SLAM3第一个关键修改C标准。ORB-SLAM3原版CMakeLists.txt中设置的C标准可能是C11。而一些较新的依赖库如Eigen 3.4中的特性可能需要C14或更高标准来支持。使用sed命令或直接编辑文件将标准改为C14。sed -i s/set(CMAKE_CXX_STANDARD 11)/set(CMAKE_CXX_STANDARD 14)/g CMakeLists.txt你可以用cat CMakeLists.txt | grep “CMAKE_CXX_STANDARD”来确认修改是否成功。5.2 使用build.sh脚本编译项目提供了一个方便的build.sh脚本。直接运行它它会自动创建build目录并执行编译。chmod x build.sh ./build.sh这里是我踩过的一个大坑脚本可能会因为并行编译-j参数而在链接阶段失败报错类似/usr/bin/ld: 找不到 -lboost_serialization或其他库的未定义引用。这并不是真的缺少库而是编译顺序或并行任务间的竞争条件导致的。解决方案方法一推荐编辑build.sh脚本找到make -j这一行通常在靠近末尾处将其改为make -j1即单线程编译。虽然慢但极其稳定。编译成功后你可以再改回去用于后续开发。# 编辑build.sh # 将 make -j 改为 make -j1 sed -i s/make -j/make -j1/g build.sh ./build.sh方法二如果单线程编译成功但你想利用多核可以尝试先清理再指定稍小的并行数例如make -j4。cd build make clean make -j45.3 手动CMake编译流程详解如果脚本编译问题太多我强烈推荐手动进行CMake编译这样对过程有完全的控制权也便于调试。cd ~/Dev/ORB_SLAM3 mkdir build cd build cmake .. -D CMAKE_BUILD_TYPERelease make -j1 # 首次编译建议单线程成功后可用 -j$(nproc) 加速在CMake配置阶段请密切关注终端的输出。你需要确认以下几项关键信息Found OpenCV:版本应为4.x。Found Eigen3:版本应为3.3.x或3.4.x。Found Pangolin:应成功找到。 如果任何一项显示为NOT FOUND则说明之前的依赖安装或环境配置有问题需要根据提示路径去解决。编译成功后在build目录下的lib文件夹中会生成libORB_SLAM3.so动态库在Examples的子目录下会生成各个可执行文件如mono_euroc,stereo_euroc等。6. 数据集准备与运行测试编译成功只是第一步让ORB-SLAM3跑起来并看到结果才是最终目标。我们使用经典的EuRoC MAV数据集进行测试。6.1 下载与解压数据集创建一个专门的数据集目录并下载其中一个轻量级序列例如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,imu0,leica0等子文件夹分别存放图像、IMU数据和真值。6.2 运行单目SLAM示例进入ORB-SLAM3的目录运行单目示例。命令的各个参数需要正确对应可执行文件路径./Examples/Monocular/mono_euroc词袋文件./Vocabulary/ORBvoc.txt(项目自带)配置文件./Examples/Monocular/EuRoC.yaml(需要根据数据集路径微调)数据集路径~/Datasets/EuRoc/MH01时间戳文件./Examples/Monocular/EuRoC_TimeStamps/MH01.txt输出轨迹文件名前缀dataset-MH01_monocd ~/Dev/ORB_SLAM3 ./Examples/Monocular/mono_euroc ./Vocabulary/ORBvoc.txt ./Examples/Monocular/EuRoC.yaml ~/Datasets/EuRoc/MH01 ./Examples/Monocular/EuRoC_TimeStamps/MH01.txt dataset-MH01_mono运行前的重要检查打开EuRoC.yaml配置文件检查VocabPath和SystemPath是否正确。通常它们默认是相对路径../如果从其他目录运行可能会出错。一个稳妥的做法是将其改为绝对路径或者确保在ORB_SLAM3根目录下执行命令。如果一切顺利你将看到一个Pangolin窗口弹出左侧显示相机实时画面和特征点匹配右侧显示3D地图点和相机轨迹。这是SLAM系统正在运行的标志。6.3 运行其他传感器配置示例ORB-SLAM3的强大之处在于支持多种模式。你可以用类似的命令运行其他示例双目./Examples/Stereo/stereo_euroc ...单目IMU./Examples/Monocular-Inertial/mono_inertial_euroc ...双目IMU./Examples/Stereo-Inertial/stereo_inertial_euroc ...每个模式都有对应的可执行文件和配置文件如Stereo/EuRoC.yaml运行前务必确认配置文件中的传感器参数如基线、IMU噪声参数是否适合你的数据集。7. 轨迹评估与Python环境适配运行结束后系统会生成一个轨迹文件如f_dataset-MH01_stereo.txt。我们可以用项目自带的Python脚本将估计的轨迹与数据集提供的真实轨迹进行对比评估精度。7.1 Python 3环境适配官方脚本evaluate_ate_scale.py是为Python 2.7编写的。在Ubuntu 22.04上我们需要将其适配到Python 3。主要修改两处修改脚本解释器将脚本第一行#!/usr/bin/env python改为#!/usr/bin/env python3。修改print语法将脚本中所有的print “something”改为Python 3的print(“something”)。你可以使用sed命令快速完成这些修改cd ~/Dev/ORB_SLAM3/evaluation sed -i 1s/python/python3/ evaluate_ate_scale.py sed -i s/print \(.*\)$/print(\1)/g evaluate_ate_scale.py此外确保你的Python 3已安装numpy和matplotlib。pip3 install numpy matplotlib # 如果系统提示没有pip3先安装sudo apt install python3-pip7.2 执行评估并可视化首先确保你已经运行了某个示例并生成了轨迹文件例如f_dataset-MH01_stereo.txt。然后使用修改后的评估脚本进行计算和绘图。cd ~/Dev/ORB_SLAM3 python3 evaluation/evaluate_ate_scale.py evaluation/Ground_truth/EuRoC_left_cam/MH01_GT.txt f_dataset-MH01_stereo.txt --plot MH01_stereo.pdf这条命令会计算绝对轨迹误差ATE并生成一个名为MH01_stereo.pdf的PDF文件。该文件会以图形方式展示真实轨迹Ground Truth和估计轨迹Estimate的对比。你可以用文档查看器打开它。xdg-open MH01_stereo.pdf在图表中两条曲线越接近说明SLAM的定位精度越高。这是定量评估算法性能最直观的方式。8. 常见编译与运行问题全记录即使按照步骤操作你也可能会遇到一些“特色”问题。这里我整理了最常遇到的几个及其解决方案。8.1 编译阶段错误排查表错误现象可能原因解决方案fatal error: Eigen/Core: No such file or directoryEigen3未安装或CMake未找到1. 确认已安装libeigen3-dev。2. 检查/usr/include/eigen3是否存在。3. 在ORB-SLAM3的CMakeLists.txt中可以尝试显式设置Eigen3路径set(Eigen3_DIR /usr/include/eigen3)。error: ‘pangolin::’ has not been declaredPangolin库未正确链接或版本不兼容1. 确认Pangolin已成功sudo make install。2. 运行sudo ldconfig更新库缓存。3. 尝试在ORB-SLAM3的build目录中手动指定Pangolin路径cmake .. -DPangolin_DIR/usr/local/lib/cmake/Pangolin。undefined reference to ‘cv::xxx’OpenCV链接错误1. 确认OpenCV 4.6.0编译安装成功且pkg-config --modversion opencv4输出正确。2. 可能是并行编译导致的尝试make clean后使用make -j1单线程编译。3. 检查CMakeCache.txt中OpenCV_DIR的路径是否正确指向你编译的OpenCV 4.6.0的build目录。error: #error This file requires compiler and library support for the ISO C 2011 standard.C标准设置过低确保已按照前文所述将ORB_SLAM3根目录下CMakeLists.txt中的CMAKE_CXX_STANDARD从11改为14或17。CMake Error at CMakeLists.txt:79 (find_package): Could not find a package configuration file provided by “Pangolin”CMake找不到Pangolin的配置文件Pangolin安装后其CMake配置文件通常在/usr/local/lib/cmake/Pangolin。可以尝试手动设置变量cmake .. -D Pangolin_DIR/usr/local/lib/cmake/Pangolin。8.2 运行时错误与解决思路错误现象可能原因解决方案Segmentation fault (core dumped)运行时崩溃最常见原因配置文件路径错误或数据集路径错误。1.绝对路径大法在YAML配置文件中将所有相关路径如VocabPath,SystemPath都改为绝对路径从根目录/开始的完整路径。2.确认数据集结构确保数据集路径指向包含mav0文件夹的那一层并且时间戳文件与数据集序列匹配。Pangolin窗口一闪而过终端报错缺少OpenGL驱动或显示环境问题常见于无GUI的服务器或通过SSH连接时。1. 对于有显示器的机器安装显卡驱动。2. 对于无头服务器或远程SSH需要禁用Pangolin的图形界面。在运行命令前设置环境变量export PANGOLIN_WINDOW_URIheadless。但这样就无法可视化轨迹了。Could not open vocabulary file词袋文件ORBvoc.txt路径不对或文件损坏。1. 使用绝对路径指定词袋文件。2. 检查文件大小完整的ORBvoc.txt约50MB。可以重新从GitHub仓库下载。运行后没有生成输出轨迹文件程序可能因异常而提前终止或者输出路径没有写权限。1. 仔细查看终端输出的所有日志寻找ERROR或Warning信息。2. 尝试在/tmp目录下运行确保有写入权限。3. 检查命令行最后一个参数输出前缀是否有效。8.3 个人实操心得与建议隔离开发环境如果你经常需要配置不同的ROS或SLAM项目强烈建议使用Docker。为ORB-SLAM3创建一个包含所有依赖的Docker镜像可以保证环境纯净且可移植。这比在宿主机上反复折腾要高效得多。善用ccmake或cmake-gui当CMake配置出错时不要只盯着终端输出。使用sudo apt install cmake-curses-gui安装ccmake在build目录下运行它可以提供一个交互式界面来查看和修改所有CMake变量这对于排查路径问题非常直观。从最简单的模式开始首次运行建议从单目Monocular模式开始因为它不需要双目校正或IMU参数配置文件最简单最容易跑通。成功后再尝试更复杂的双目或VIO模式。备份你的配置文件一旦你调通了一个数据集如EuRoC的某个模式如双目将对应的YAML配置文件备份。以后在其他数据集或真实机器人上部署时这个文件是重要的参考基准你只需要修改相机内参、畸变系数、基线等硬件相关参数即可。理解输出信息ORB-SLAM3运行时会在终端打印大量信息包括特征点提取数量、跟踪状态LOST/OK、局部建图信息等。学会阅读这些信息能帮你快速判断系统是否在正常工作。例如如果频繁出现TRACKING LOST可能是光照变化太剧烈、特征太少或者相机运动过快。