当前位置：首页 > news >正文

Ubuntu 22.04下ORB-SLAM3完整安装与编译指南：从依赖配置到运行测试

news 2026/6/17 7:01:45

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-config

2.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-dev：OpenGL的扩展加载库，是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_TYPE=Release：编译发布版本，优化性能。
-D WITH_CUDA=OFF：除非你确定需要CUDA加速且配置好了NVIDIA驱动和CUDA Toolkit，否则先关闭。这能极大简化编译过程，避免驱动版本不匹配等问题。
-D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules：指定额外模块的路径。
-D BUILD_EXAMPLES=OFF：关闭示例编译，加快速度。
-D CMAKE_INSTALL_PREFIX=/usr/local：安装路径，通常设为/usr/local，这样系统能自动找到。

mkdir build && cd build cmake -D CMAKE_BUILD_TYPE=Release \ -D WITH_CUDA=OFF \ -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \ -D BUILD_EXAMPLES=OFF \ -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_TYPE=Release -D WITH_CUDA=OFF 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++标准可能是C++11。而一些较新的依赖库（如Eigen 3.4）中的特性可能需要C++14或更高标准来支持。使用sed命令或直接编辑文件，将标准改为C++14。

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 -j4
```

5.3 手动CMake编译流程详解

如果脚本编译问题太多，我强烈推荐手动进行CMake编译，这样对过程有完全的控制权，也便于调试。

cd ~/Dev/ORB_SLAM3 mkdir build cd build cmake .. -D CMAKE_BUILD_TYPE=Release 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_mono

cd ~/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-pip

7.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 directory`	Eigen3未安装或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 declared`	Pangolin库未正确链接或版本不兼容	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_URI=headless`。但这样就无法可视化轨迹了。
`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，可能是光照变化太剧烈、特征太少或者相机运动过快。