首页/资讯中心/详情

Ubuntu 22.04 部署 ORB-SLAM3 完整指南：从环境搭建到实战运行

Ubuntu 22.04 部署 ORB-SLAM3 完整指南：从环境搭建到实战运行
📅 发布时间：2026/7/22 4:44:33

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 -y
  • build-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.0

OpenCV是计算机视觉的基石。ORB-SLAM3官方推荐并测试了OpenCV 4.6.0。使用特定版本可以最大程度保证兼容性。

  1. 创建开发目录并克隆源码： 我习惯在用户主目录下创建一个Dev或Workspace目录来存放所有从源码构建的软件。

    cd ~ mkdir -p Dev cd Dev git clone https://github.com/opencv/opencv.git cd opencv git checkout 4.6.0

    git checkout 4.6.0命令确保我们切换到4.6.0这个特定的发布标签。

  2. 配置与编译：

    mkdir build && cd build cmake -D CMAKE_BUILD_TYPE=Release \ -D WITH_CUDA=OFF \ -D WITH_GTK=ON \ -D BUILD_opencv_world=OFF \ -D BUILD_EXAMPLES=OFF \ -D BUILD_TESTS=OFF \ -D CMAKE_INSTALL_PREFIX=/usr/local ..
    • CMAKE_BUILD_TYPE=Release: 生成优化过的发布版本，性能更好。
    • WITH_CUDA=OFF: 对于初次安装，为了简化问题，我们先禁用CUDA支持。如果你有NVIDIA显卡并已安装好CUDA，可以设置为ON以利用GPU加速。
    • WITH_GTK=ON: 启用GTK支持，用于图像显示。
    • BUILD_opencv_world=OFF: 不生成单个大的opencv_world库，而是生成独立的模块库（如core,imgproc,highgui等）。这有助于减少链接时的库大小，并且是更常见的做法。
    • BUILD_EXAMPLES和BUILD_TESTS: 设为OFF以加快编译速度。
    • CMAKE_INSTALL_PREFIX=/usr/local: 指定安装路径为/usr/local，这是Linux系统安装本地软件的标准位置。

  3. 开始编译： 使用make -j$(nproc)命令启动编译，$(nproc)会自动获取你CPU的核心数，进行并行编译以大幅缩短时间。

    make -j$(nproc)

    这个过程根据你的机器性能，可能需要15分钟到1小时不等。如果遇到内存不足，可以减少并行任务数，例如make -j4。

  4. 安装： 编译成功后，执行安装命令，将编译好的库和头文件复制到/usr/local目录下。

    sudo make install sudo ldconfig

    sudo ldconfig命令更新系统的动态链接器运行时绑定，让系统立刻能找到新安装的OpenCV库。

实操心得：编译OpenCV是整个过程中最耗时且最容易出错的环节。如果cmake阶段报错，通常是缺少某个依赖库，请根据错误信息使用apt search和apt install来安装对应的-dev包。编译过程中如果卡死或报错，可以先尝试make clean后，减少-j后面的并行数重新编译。

3.2 编译安装Pangolin

Pangolin是一个轻量级的OpenGL显示/交互库，ORB-SLAM3用它来实时显示相机轨迹、地图点和关键帧。

  1. 克隆源码：

    cd ~/Dev git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin

  2. 配置与编译：

    mkdir build && cd build cmake -D CMAKE_BUILD_TYPE=Release .. make -j$(nproc) sudo make install sudo ldconfig

    Pangolin的依赖相对简单，如果之前基础依赖安装齐全，这里通常会很顺利。同样，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默认使用C++11标准，但在Ubuntu 22.04的默认编译器套件下，可能需要C++14标准来更好地支持某些特性。使用sed命令进行快速修改：

sed -i 's/++11/++14/g' CMakeLists.txt

这个命令将文件中所有的C++11替换为C++14。你可以用文本编辑器打开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.sh
  • chmod +x build.sh是赋予脚本可执行权限。
  • 执行./build.sh后，终端会输出大量的编译信息。这个过程会持续几分钟。

常见问题与排查：

  1. 错误：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。

  2. 错误：与OpenCV或Pangolin相关的链接错误确保OpenCV和Pangolin已正确安装到/usr/local，并且运行了sudo ldconfig。你可以手动检查：

    pkg-config --modversion opencv4 # 应返回 4.6.0

    如果返回找不到，可能需要手动设置PKG_CONFIG_PATH：

    export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH

    将这条命令添加到你的~/.bashrc文件中使其永久生效。

  3. 编译过程卡住或报错： 脚本可能会因为网络问题下载第三方依赖失败。你可以尝试多运行几次./build.sh。或者，进入Thirdparty/目录，手动检查DBoW2和g2o文件夹是否为空，尝试手动git clone对应的仓库。

当编译成功完成后，你会在Examples/目录下的各个子文件夹（如Monocular,Stereo等）中看到生成的可执行文件，如mono_euroc，stereo_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（图像）、imu0（IMU数据）等子文件夹。

5.2 运行ORB-SLAM3进行测试

ORB-SLAM3提供了多种运行模式，对应不同的传感器配置。我们以双目模式为例，因为它不需要初始化，且结果相对稳定。

  1. 准备词汇表：ORB-SLAM3使用一个预先训练好的视觉词汇表ORBvoc.txt进行特征匹配加速。项目已自带，位于Vocabulary/目录下。

  2. 运行双目SLAM：

    cd ~/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: 输出的轨迹文件名称前缀。

  3. 观察运行结果： 如果一切顺利，终端会开始输出初始化、跟踪、局部建图等信息。同时，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.pdf
  • evaluate_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进行处理。

  1. 安装ROS 2 Humble（Ubuntu 22.04对应版本）： 请参考ROS官方文档进行安装。通常包括设置软件源、安装核心包等步骤。

  2. 编译ORB-SLAM3 ROS节点： 在ORB-SLAM3目录下，有一个ros文件夹。你需要创建一个ROS工作空间，并将ORB-SLAM3链接或复制过去，然后使用catkin_make或colcon进行编译。编译前，务必确保你的ROS_PACKAGE_PATH环境变量包含了ORB-SLAM3的路径，并且所有非ROS依赖（OpenCV, Pangolin, Eigen）已正确安装。

  3. 配置启动文件： 你需要编写或修改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 常见问题深度排查与解决实录

即使按照步骤操作，你也可能遇到各种问题。以下是我在多次部署中总结的“坑点”与解决方案：

  1. 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_TYPE=Release -D BUILD_PANGOLIN_GUI=ON。

  2. 运行时提示“找不到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。

  3. 特征跟踪丢失频繁，轨迹很快漂移：

    • 现象：程序能启动，但跟踪状态经常在LOST和OK之间切换，地图点很少，轨迹不连续。
    • 排查：
      • 首要怀疑相机参数：确认YAML配置文件中的相机内参、畸变系数、图像尺寸是否与你的数据完全匹配。一个像素的误差都可能导致特征匹配失败。
      • 检查数据集路径和时间戳：确保数据集路径正确，且时间戳文件与图像文件一一对应。时间戳文件中的每一行对应一个图像文件名（或时间）。
      • 调整ORB特征参数：尝试增加ORBextractor.nFeatures，或者降低ORBextractor.iniThFAST以检测更多角点。
      • 环境问题：数据集场景是否纹理足够丰富、光照是否变化剧烈？ORB特征在低纹理或运动模糊下表现会变差。

  4. 编译时内存不足（OOM Killer）：

    • 现象：在编译OpenCV或ORB-SLAM3时，编译进程突然被终止，系统日志显示Out of memory。
    • 解决：
      • 减少并行编译任务数：使用make -j2或make -j1替代make -j$(nproc)。
      • 增加系统交换空间（Swap）：如果虚拟机或物理机内存较小（如4GB），增加2-4GB的交换空间可以缓解压力。
      • 关闭其他占用内存大的应用程序。

  5. 希望使用更新的OpenCV版本：

    • ORB-SLAM3官方测试基于OpenCV 4.6.0，但理论上兼容OpenCV 4.x系列。如果你想使用OpenCV 4.8或4.9，克隆源码后切换到对应标签（如git checkout 4.8.0）即可。但需要注意，新版本可能废弃某些旧的API，可能导致ORB-SLAM3编译失败，需要手动修改少量代码。这是一个进阶操作，建议在熟悉代码后进行。

整个安装和调试过程，本质上是对一个复杂软件生态系统的理解和搭建。耐心和仔细阅读错误信息是关键。每一次成功的运行，都意味着你向掌握视觉SLAM这项强大的技术又迈进了一步。希望这份详尽的指南能成为你探索过程中的可靠地图。