Ubuntu 20.04下ORB-SLAM3完整安装与运行指南：从依赖编译到实战调试

1. 项目概述与核心价值

在机器人、自动驾驶和增强现实这些前沿领域，让机器“看见”并理解自己所处的三维环境，是核心的底层能力。SLAM（即时定位与地图构建）技术就是实现这一能力的钥匙。而ORB-SLAM3，作为当前开源SLAM方案中的佼佼者，以其卓越的精度、鲁棒性和对多地图、多传感器的支持，成为了众多研究者和工程师进行算法验证、二次开发乃至产品原型搭建的首选。然而，对于刚接触这个领域的朋友来说，在Ubuntu 20.04上搭建一个完整、可运行的ORB-SLAM3环境，常常是第一个，也是最令人头疼的“拦路虎”。各种依赖库版本冲突、编译错误、数据集跑不通等问题层出不穷。

这篇内容，就是为你彻底扫清这个障碍。我将基于在Ubuntu 20.04 LTS这个长期支持且生态成熟的系统上，手把手带你完成从零开始，到成功运行ORB-SLAM3的完整过程。这不仅仅是一份安装清单，我会深入解释每一个步骤背后的原因，分享我踩过的坑和总结出的最佳实践，确保你不仅能“装得上”，更能“懂得为什么这么装”，为后续的算法学习和应用开发打下坚实的基础。无论你是机器人方向的学生、刚入行的工程师，还是对SLAM技术感兴趣的爱好者，这份详尽的指南都将是你宝贵的起点。

2. 环境准备与核心依赖解析

在动手编译ORB-SLAM3之前，一个干净、配置正确的底层环境至关重要。Ubuntu 20.04默认的软件源和包管理器apt是我们主要的工具，但ORB-SLAM3对某些库的版本有特定要求，我们需要进行针对性的准备。

2.1 系统更新与基础工具安装

首先，确保你的系统是最新的。打开终端，执行以下命令更新软件包列表并升级现有软件。这一步能避免很多因系统组件过旧导致的兼容性问题。

sudo apt update sudo apt upgrade -y

接下来，安装一些编译和开发所必需的基础工具。build-essential包含了GCC编译器、make等核心工具链；cmake是ORB-SLAM3使用的跨平台编译系统；git用于克隆代码；wget和curl用于下载文件；unzip用于解压数据集。

sudo apt install -y build-essential cmake git wget curl unzip

2.2 Pangolin：不可或缺的可视化工具

Pangolin是一个轻量级的OpenGL显示与交互库，ORB-SLAM3用它来实时显示相机轨迹、特征点和三维地图。它是运行时必须的，而非可选的。

安装Pangolin需要先安装其依赖。这些依赖包括OpenGL开发库、窗口系统库、图像处理库等。

sudo apt install -y libgl1-mesa-dev libglew-dev libwayland-dev libxkbcommon-dev wayland-protocols libegl1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev

然后，我们从GitHub克隆Pangolin的源代码进行编译安装。我推荐使用一个特定的稳定版本分支，以避免主分支可能存在的未稳定变更。

cd ~ git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin git checkout v0.8

注意：这里明确指定了v0.8版本。ORB-SLAM3的代码与Pangolin的API紧密相关，使用未经测试的新版本（如main分支）极有可能因API变动导致编译失败。v0.8是一个经过广泛验证的、与ORB-SLAM3兼容良好的版本。

接下来，使用CMake进行配置、编译和安装。我们采用“外部构建”的方式，即在源代码目录外新建一个build目录进行编译，这样可以保持源码目录的整洁。

mkdir build && cd build cmake .. cmake --build . sudo make install

安装完成后，Pangolin的头文件和库文件会被安装到系统的标准路径（如/usr/local/include和/usr/local/lib）。你可以通过ls /usr/local/include/pangolin来验证头文件是否已存在。

2.3 OpenCV：计算机视觉的基石

OpenCV是计算机视觉的“标准库”，ORB-SLAM3用它进行图像读取、特征提取、几何计算等几乎所有图像处理任务。ORB-SLAM3官方推荐使用OpenCV 4.4及以上版本。Ubuntu 20.04官方源中的OpenCV版本较低，我们需要从源码编译安装一个较新的版本。

首先，安装OpenCV所需的大量依赖库。这些依赖涵盖了图像编解码（JPEG, PNG, TIFF）、视频处理（FFmpeg）、优化计算（BLAS, LAPACK）、图形界面（GTK）等。

sudo apt install -y libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev libatlas-base-dev gfortran libtbb-dev libopenblas-dev liblapack-dev

然后，下载OpenCV的源代码。这里我们选择OpenCV 4.5.5，这是一个稳定且功能完善的版本。

cd ~ wget -O opencv.zip https://github.com/opencv/opencv/archive/4.5.5.zip wget -O opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/4.5.5.zip unzip opencv.zip unzip opencv_contrib.zip mv opencv-4.5.5 opencv mv opencv_contrib-4.5.5 opencv_contrib

接下来是关键的编译配置步骤。进入OpenCV源码的build目录，使用CMake生成构建文件。这里有几个重要参数：

• -D OPENCV_EXTRA_MODULES_PATH: 指定贡献模块的路径，这些模块包含了许多额外的、有用的功能（如SIFT、SURF等非免费特征，但在ORB-SLAM3中我们主要用ORB，所以影响不大，但装上以备不时之需）。
• -D WITH_CUDA=OFF: 对于初次安装，我建议先关闭CUDA支持。虽然CUDA能加速某些操作，但会极大增加编译的复杂度和时间，且容易出错。我们先确保基础版本能工作。
• -D BUILD_EXAMPLES=OFF: 不编译例子，节省时间。
• -D BUILD_opencv_python3=ON: 如果你也需要Python接口，可以打开。但ORB-SLAM3的C++编译不依赖此选项。

cd opencv mkdir build && cd build cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \ -D WITH_CUDA=OFF \ -D BUILD_EXAMPLES=OFF \ -D BUILD_opencv_python3=ON \ ..

配置完成后，检查CMake的输出。确保“Python 3”和“Numpy”被正确找到（如果你需要的话），并且没有显示重要的、红色的“NOT FOUND”错误。

最后，开始编译和安装。这个过程会消耗大量时间和CPU资源（在我的机器上大约需要30-60分钟）。-j$(nproc)参数表示使用所有可用的CPU核心并行编译，以加快速度。

make -j$(nproc) sudo make install sudo ldconfig # 更新系统的动态链接库缓存

安装完成后，可以通过pkg-config --modversion opencv4命令来验证安装的版本。

2.4 Eigen3：线性代数运算库

Eigen是一个高性能的C++模板库，用于线性代数、矩阵和向量运算。ORB-SLAM3内部大量使用Eigen进行几何变换、优化问题的构建等数学计算。Ubuntu 20.04官方源中的Eigen3版本（3.3.7）已经足够新，可以直接安装。

sudo apt install -y libeigen3-dev

安装后，头文件位于/usr/include/eigen3。ORB-SLAM3的CMakeLists.txt会自动去寻找它。

2.5 DBoW2 与 g2o：词袋与图优化

ORB-SLAM3包含了两个关键的第三方库：DBoW2（用于回环检测的词袋模型）和g2o（用于后端优化的图优化库）。好消息是，ORB-SLAM3的源码包里已经自带了这两个库的修改版，我们通常不需要单独安装。在后续编译ORB-SLAM3时，它们会作为项目的一部分被自动编译。这是ORB-SLAM3项目设计上的一个便利之处，确保了库版本的兼容性。

3. ORB-SLAM3源码获取与编译实战

当所有依赖就绪后，我们就可以开始处理主角——ORB-SLAM3本身了。编译过程本身不复杂，但细节决定成败。

3.1 克隆源码与准备

首先，将ORB-SLAM3的源代码克隆到本地。建议使用--recursive参数，因为它会同时初始化并更新子模块（虽然ORB-SLAM3主仓库目前似乎没有设置子模块，但这是一个好习惯）。

cd ~ git clone https://github.com/UZ-SLAMLab/ORB_SLAM3.git ORB_SLAM3 cd ORB_SLAM3

进入目录后，你可以查看一下目录结构。主要源码在src和include目录，示例程序在Examples目录，配置文件在Vocabulary和config目录。

3.2 编译配置与构建

和编译Pangolin、OpenCV一样，我们采用外部构建的方式。

mkdir build cd build

现在，运行CMake来配置项目。这里最关键的是指定OpenCV_DIR和Pangolin_DIR，如果你按照上述步骤将OpenCV和Pangolin安装到了/usr/local，CMake通常能自动找到它们。但为了保险起见，特别是当你系统中有多个OpenCV版本时，显式指定路径是个好习惯。

cmake .. -DCMAKE_BUILD_TYPE=Release

实操心得：在CMake配置时，务必关注终端的输出信息。你需要仔细检查以下几行是否被正确找到：

• Found OpenCV: /usr/local (found version "4.5.5")
• Found Pangolin: /usr/local/include (found version "0.8.0")
• Found Eigen: /usr/include/eigen3 (found version "3.3.7")如果其中任何一项显示为NOT FOUND，编译必定失败。你需要根据错误信息，检查对应库的安装路径，并通过-DOpenCV_DIR=/path/to/opencv/build这样的CMake变量手动指定。

配置成功后，开始编译。

make -j$(nproc)

编译过程会持续几分钟。如果一切顺利，你将在build目录下看到生成的可执行文件，例如Examples/Monocular/mono_euroc（单目EUROC数据集运行程序）、Examples/Stereo/stereo_euroc（双目程序）等，以及核心的共享库libORB_SLAM3.so。

3.3 词汇表文件下载

ORB-SLAM3使用一个预先训练好的词袋模型（Vocabulary）来进行特征匹配和回环检测。这个文件比较大，没有包含在Git仓库中，需要单独下载并放到指定位置。

cd ~/ORB_SLAM3 cd Vocabulary # 使用wget下载词汇表文件 wget https://github.com/raulmur/ORB_SLAM3/raw/master/Vocabulary/ORBvoc.txt.tar.gz # 解压 tar -xf ORBvoc.txt.tar.gz

解压后，你会在Vocabulary目录下得到一个ORBvoc.txt文件。请确保这个文件的路径正确，因为ORB-SLAM3的代码里默认会去../Vocabulary/ORBvoc.txt寻找它。

4. 运行测试与数据集处理

编译成功只是第一步，让ORB-SLAM3真正“跑起来”，看到它输出相机轨迹和地图，才是最有成就感的时刻。我们以公开的EUROC MAV数据集为例进行测试。

4.1 下载与准备数据集

EUROC数据集包含双目图像、IMU数据和真值轨迹，非常适合测试SLAM系统的完整功能。我们下载其中一个简单的序列（例如MH_01_easy）。

你可以从EUROC数据集官网下载，也可以使用我提供的直接链接（请注意链接可能随时间失效，建议从官网获取最新信息）。这里我们下载MH_01_easy序列。

cd ~ # 创建一个目录存放数据集 mkdir -p Datasets/EUROC && cd Datasets/EUROC # 下载数据集压缩包 (示例链接，请以官网为准) wget http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/machine_hall/MH_01_easy/MH_01_easy.zip # 解压 unzip MH_01_easy.zip

解压后，你会得到一个MH_01_easy文件夹，里面包含mav0子目录，其下便是cam0（左目图像）、cam1（右目图像）、imu0等数据。

4.2 运行单目ORB-SLAM3

ORB-SLAM3提供了针对不同传感器配置（单目、双目、RGB-D、单目+IMU、双目+IMU）的示例程序。我们先从单目开始，因为它对数据要求最简单。

首先，需要准备两个东西：

1. 词汇表文件路径：我们已经有了。
2. 配置文件：ORB-SLAM3在Examples/Monocular目录下提供了针对不同数据集的配置文件模板，例如EuRoC.yaml。这个文件里设置了相机内参、ORB特征提取参数、运行参数等。

运行单目示例的命令格式如下：

cd ~/ORB_SLAM3 ./build/Examples/Monocular/mono_euroc \ Vocabulary/ORBvoc.txt \ Examples/Monocular/EuRoC.yaml \ /home/your_username/Datasets/EUROC/MH_01_easy/mav0/cam0/data \ Examples/Monocular/EuRoC_TimeStamps/MH01.txt

参数详解：

• ./build/Examples/Monocular/mono_euroc: 编译生成的单目EUROC数据集可执行文件。
• Vocabulary/ORBvoc.txt: 词袋文件路径。
• Examples/Monocular/EuRoC.yaml: 配置文件路径。这里有个关键点：你需要根据你使用的相机（这里是EUROC数据集的双目相机中的左目）来调整配置文件中的相机内参。虽然ORB-SLAM3提供的EuRoC.yaml里已经包含了EUROC相机的近似参数，但对于追求精度的场景，建议使用数据集标定文件cam0/camera.txt中的精确参数替换EuRoC.yaml里的fx, fy, cx, cy, k1, k2, p1, p2等值。
• /path/to/mav0/cam0/data: 图像序列所在的目录。
• Examples/Monocular/EuRoC_TimeStamps/MH01.txt: 时间戳文件，告诉程序按什么顺序读取图像。

执行命令后，会弹出Pangolin创建的图形窗口。你应该能看到：

1. 左侧窗口：当前相机图像，上面叠加了提取的ORB特征点（绿色点）。
2. 右侧窗口：三维可视化界面，显示估计的相机轨迹（红色）、关键帧（蓝色）和地图点（黑色）。

按空格键可以暂停/继续运行。程序运行结束后，会在终端输出估计的轨迹，并自动与真值轨迹进行对齐比较，输出绝对轨迹误差（ATE）的均方根误差（RMSE），这是衡量SLAM精度的一个重要指标。

4.3 运行双目ORB-SLAM3

双目版本能直接估计尺度，性能通常比单目更稳定。运行命令类似：

./build/Examples/Stereo/stereo_euroc \ Vocabulary/ORBvoc.txt \ Examples/Stereo/EuRoC.yaml \ /home/your_username/Datasets/EUROC/MH_01_easy/mav0/cam0/data \ /home/your_username/Datasets/EUROC/MH_01_easy/mav0/cam1/data \ Examples/Stereo/EuRoC_TimeStamps/MH01.txt

注意，这里需要提供左目和右目两个图像目录的路径，并且配置文件换成了Examples/Stereo/EuRoC.yaml。双目版本的配置文件里包含了基线长度等双目相机特有的参数。

5. 编译与运行中的常见问题深度排查

即使按照步骤操作，你也可能会遇到各种问题。下面我汇总了最常见的一些错误及其解决方案。

5.1 编译阶段错误

问题1：CMake找不到OpenCV或Pangolin

CMake Error at CMakeLists.txt:xxx (find_package): By not providing "FindOpenCV.cmake" in CMAKE_MODULE_PATH this project has asked CMake to find a package configuration file provided by "OpenCV", but CMake did not find one.

排查与解决：

1. 确认安装成功：运行pkg-config --modversion opencv4和ls /usr/local/lib/libpangolin*确认库已安装。
2. 手动指定路径：在CMake命令中显式指定路径。

   rm -rf build/* # 清除旧的CMake缓存 cmake .. -DCMAKE_BUILD_TYPE=Release \ -DOpenCV_DIR=/usr/local/lib/cmake/opencv4 \ -DPangolin_DIR=/usr/local/lib/cmake/Pangolin

   OpenCV的Config文件通常在/usr/local/lib/cmake/opencv4，Pangolin的在/usr/local/lib/cmake/Pangolin。如果路径不同，请根据你的实际安装位置调整。

问题2：fatal error: Eigen/Core: No such file or directory排查与解决：Eigen是只有头文件的库，不需要链接。这个错误通常是因为CMake没有找到Eigen。确保已安装libeigen3-dev。有时需要手动指定EIGEN3_INCLUDE_DIR。

cmake .. -DCMAKE_BUILD_TYPE=Release -DEIGEN3_INCLUDE_DIR=/usr/include/eigen3

问题3：链接错误，如undefined reference to ‘cv::imread(...)’排查与解决：这通常是链接阶段找不到OpenCV库。原因可能是：

1. 编译OpenCV时没有sudo make install，或者安装到了非标准路径。
2. 系统中有多个OpenCV版本，链接了错误的那个。解决：确保OpenCV已正确安装到/usr/local。可以尝试在CMake时更明确地指定OpenCV路径（如问题1所示）。也可以检查build/CMakeCache.txt文件，搜索OpenCV_LIBS变量，看其值是否指向了你安装的正确版本。

5.2 运行阶段错误

问题1：启动时崩溃，提示Segmentation fault (core dumped)这是最令人沮丧的错误之一，原因多样。

1. 词汇表文件问题：首先检查ORBvoc.txt文件路径是否正确，文件是否完整（大小约50MB+）。可以尝试重新下载解压。
2. 配置文件路径错误：确保YAML配置文件的路径正确，并且文件内容格式无误（YAML对缩进敏感）。特别检查图像路径和时间戳文件路径。
3. 库链接问题：虽然编译成功，但运行时动态链接库找不到。使用ldd命令检查可执行文件依赖的库。

   ldd ./build/Examples/Monocular/mono_euroc | grep "not found"

   如果发现有libpangolin.so或libopencv_core.so.4.5等显示“not found”，说明系统运行时库路径没有包含这些库的安装位置。执行sudo ldconfig更新缓存，或者将/usr/local/lib添加到LD_LIBRARY_PATH环境变量中（临时生效）：

   export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH ./build/Examples/Monocular/mono_euroc ... # 再运行你的命令

   为了使环境变量永久生效，可以将其添加到~/.bashrc文件中。

问题2：Pangolin窗口黑屏或图像不显示

1. 驱动问题：确保你的显卡驱动已正确安装，特别是对于NVIDIA显卡。可以尝试安装nvidia-driver-xxx（具体版本号）和nvidia-utils-xxx。
2. Pangolin编译选项：可能是Pangolin编译时没有包含必要的显示后端。重新编译Pangolin时，可以尝试更简单的配置，确保BUILD_PANGOLIN_GUI和BUILD_PANGOLIN_VARS为ON。

问题3：运行速度极慢，每帧处理要好几秒

1. 编译模式：确认你是以Release模式编译的，而不是Debug模式。Debug模式包含大量调试信息，会严重拖慢程序速度。在CMake时使用-DCMAKE_BUILD_TYPE=Release。
2. ORB特征点数量：检查YAML配置文件中的ORBextractor.nFeatures参数。默认值（如1000）对于有些场景可能偏高，可以尝试降低到500或800，能在一定程度上提升速度，但会牺牲一些精度和鲁棒性。
3. 系统资源：检查CPU占用率。ORB-SLAM3是计算密集型程序，确保没有其他大型程序在后台占用资源。

5.3 数据集相关错误

问题：程序读取不到图像，或者时间戳对不上

1. 图像路径：绝对确认你提供的图像目录路径是正确的，并且该目录下确实有.png或.jpg文件。
2. 图像命名：EUROC数据集的图像命名是时间戳（如1403715283412143104.png）。ORB-SLAM3默认会按文件名排序读取。如果时间戳文件MH01.txt里的时间戳与文件名对不上，程序会跳过或报错。确保你下载的数据集序列和时间戳文件是匹配的。
3. 配置文件中的图像分辨率：检查YAML文件中的Camera.width和Camera.height是否与你实际图像的分辨率一致。不一致可能导致特征提取出错。

6. 进阶配置与性能调优指南

成功运行基础示例后，你可能希望根据自己的需求或硬件调整ORB-SLAM3，以获得更好的性能或适配自己的传感器。

6.1 使用自己的相机或数据集

这是最常见的需求。你需要为ORB-SLAM3准备两样东西：

1. 相机配置文件（YAML）：复制一份现有的配置文件（如EuRoC.yaml），然后修改其中的关键参数。

   • Camera.fx,Camera.fy,Camera.cx,Camera.cy: 相机内参，需要通过标定获取。
   • Camera.k1,Camera.k2,Camera.p1,Camera.p2,Camera.k3: 畸变系数。
   • Camera.width,Camera.height: 图像分辨率。
   • ORBextractor.nFeatures: 每帧提取的ORB特征数量，影响速度和精度。
   • ORBextractor.scaleFactor: 图像金字塔的尺度因子。
   • ORBextractor.nLevels: 金字塔层数。

2. 图像与时间戳：程序需要按顺序读取图像。你需要准备一个图像序列（按数字或时间戳命名），以及一个对应的时间戳文件（每行一个时间戳，单位秒）。对于单目，时间戳文件是必须的；对于双目，程序默认按文件名排序读取左右目图像（要求左右目图像文件名严格对应，如left_001.png和right_001.png）。

6.2 启用IMU融合（仅限VIO版本）

ORB-SLAM3最大的亮点之一是其出色的视觉惯性里程计（VIO）能力。要运行VIO（单目+IMU或双目+IMU），你需要：

1. 数据集必须包含同步的图像和IMU数据（如EUROC、TUM-VI数据集）。
2. 使用对应的示例程序，如mono_inertial_euroc或stereo_inertial_euroc。
3. 配置文件需要使用对应的惯性配置文件，如EuRoC_vi.yaml。这个文件里包含了IMU的噪声参数IMU.NoiseGyro,IMU.NoiseAcc,IMU.GyroWalk等，这些参数对精度影响巨大，通常需要根据你使用的具体IMU型号进行标定和设置。直接使用数据集提供的参数是一个不错的起点。

6.3 保存与加载地图

ORB-SLAM3支持将构建的稀疏地图保存到文件，并在下次启动时加载，实现长期定位和地图复用。相关参数在配置文件中：

• System.LoadMap: 设置为true则启动时尝试加载地图。
• System.MapFile: 指定要加载或保存的地图文件路径。 在代码层面，当系统关闭时（按ESC退出），如果System.MapFile不为空，它会自动保存地图。你也可以在运行过程中通过按键盘上的s键来手动保存当前地图。这个功能对于机器人长期在已知环境中运行非常有用。

6.4 性能监控与调试

• 终端输出：关注终端输出的信息，如TRACKING状态（OK或LOST）、当前帧ID、局部地图中的地图点和关键帧数量等。
• 轨迹文件：程序运行结束后，会在当前目录生成CameraTrajectory.txt（估计轨迹）和KeyFrameTrajectory.txt（关键帧轨迹）。你可以用EVO、Python的Matplotlib等工具绘制轨迹，或与真值比较计算误差。
• 可视化调试：Pangolin窗口是主要的调试界面。观察特征点跟踪是否稳定，地图点是否稠密，回环检测是否被正确触发（地图中突然出现一条蓝色线连接两个相距较远的关键帧）。

在整个安装和调试过程中，耐心和细致是最重要的品质。SLAM系统涉及计算机视觉、几何、优化等多个层面，任何一个环节的小问题都可能导致系统无法工作。希望这份超详细的指南能帮你顺利跨过ORB-SLAM3入门的第一道门槛，开启你的SLAM探索之旅。如果在实践中遇到本指南未覆盖的新问题，多查阅ORB-SLAM3的GitHub Issues页面和相关的ROS、OpenCV社区，通常能找到解决方案。