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 unzip2.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_CUDAOFF: 对于初次安装我建议先关闭CUDA支持。虽然CUDA能加速某些操作但会极大增加编译的复杂度和时间且容易出错。我们先确保基础版本能工作。-D BUILD_EXAMPLESOFF: 不编译例子节省时间。-D BUILD_opencv_python3ON: 如果你也需要Python接口可以打开。但ORB-SLAM3的C编译不依赖此选项。cd opencv mkdir build cd build cmake -D CMAKE_BUILD_TYPERELEASE \ -D CMAKE_INSTALL_PREFIX/usr/local \ -D OPENCV_EXTRA_MODULES_PATH~/opencv_contrib/modules \ -D WITH_CUDAOFF \ -D BUILD_EXAMPLESOFF \ -D BUILD_opencv_python3ON \ ..配置完成后检查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/localCMake通常能自动找到它们。但为了保险起见特别是当你系统中有多个OpenCV版本时显式指定路径是个好习惯。cmake .. -DCMAKE_BUILD_TYPERelease实操心得在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-SLAM3ORB-SLAM3提供了针对不同传感器配置单目、双目、RGB-D、单目IMU、双目IMU的示例程序。我们先从单目开始因为它对数据要求最简单。首先需要准备两个东西词汇表文件路径我们已经有了。配置文件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创建的图形窗口。你应该能看到左侧窗口当前相机图像上面叠加了提取的ORB特征点绿色点。右侧窗口三维可视化界面显示估计的相机轨迹红色、关键帧蓝色和地图点黑色。按空格键可以暂停/继续运行。程序运行结束后会在终端输出估计的轨迹并自动与真值轨迹进行对齐比较输出绝对轨迹误差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 编译阶段错误问题1CMake找不到OpenCV或PangolinCMake 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.排查与解决确认安装成功运行pkg-config --modversion opencv4和ls /usr/local/lib/libpangolin*确认库已安装。手动指定路径在CMake命令中显式指定路径。rm -rf build/* # 清除旧的CMake缓存 cmake .. -DCMAKE_BUILD_TYPERelease \ -DOpenCV_DIR/usr/local/lib/cmake/opencv4 \ -DPangolin_DIR/usr/local/lib/cmake/PangolinOpenCV的Config文件通常在/usr/local/lib/cmake/opencv4Pangolin的在/usr/local/lib/cmake/Pangolin。如果路径不同请根据你的实际安装位置调整。问题2fatal error: Eigen/Core: No such file or directory排查与解决Eigen是只有头文件的库不需要链接。这个错误通常是因为CMake没有找到Eigen。确保已安装libeigen3-dev。有时需要手动指定EIGEN3_INCLUDE_DIR。cmake .. -DCMAKE_BUILD_TYPERelease -DEIGEN3_INCLUDE_DIR/usr/include/eigen3问题3链接错误如undefined reference to ‘cv::imread(...)’排查与解决这通常是链接阶段找不到OpenCV库。原因可能是编译OpenCV时没有sudo make install或者安装到了非标准路径。系统中有多个OpenCV版本链接了错误的那个。解决确保OpenCV已正确安装到/usr/local。可以尝试在CMake时更明确地指定OpenCV路径如问题1所示。也可以检查build/CMakeCache.txt文件搜索OpenCV_LIBS变量看其值是否指向了你安装的正确版本。5.2 运行阶段错误问题1启动时崩溃提示Segmentation fault (core dumped)这是最令人沮丧的错误之一原因多样。词汇表文件问题首先检查ORBvoc.txt文件路径是否正确文件是否完整大小约50MB。可以尝试重新下载解压。配置文件路径错误确保YAML配置文件的路径正确并且文件内容格式无误YAML对缩进敏感。特别检查图像路径和时间戳文件路径。库链接问题虽然编译成功但运行时动态链接库找不到。使用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文件中。问题2Pangolin窗口黑屏或图像不显示驱动问题确保你的显卡驱动已正确安装特别是对于NVIDIA显卡。可以尝试安装nvidia-driver-xxx具体版本号和nvidia-utils-xxx。Pangolin编译选项可能是Pangolin编译时没有包含必要的显示后端。重新编译Pangolin时可以尝试更简单的配置确保BUILD_PANGOLIN_GUI和BUILD_PANGOLIN_VARS为ON。问题3运行速度极慢每帧处理要好几秒编译模式确认你是以Release模式编译的而不是Debug模式。Debug模式包含大量调试信息会严重拖慢程序速度。在CMake时使用-DCMAKE_BUILD_TYPERelease。ORB特征点数量检查YAML配置文件中的ORBextractor.nFeatures参数。默认值如1000对于有些场景可能偏高可以尝试降低到500或800能在一定程度上提升速度但会牺牲一些精度和鲁棒性。系统资源检查CPU占用率。ORB-SLAM3是计算密集型程序确保没有其他大型程序在后台占用资源。5.3 数据集相关错误问题程序读取不到图像或者时间戳对不上图像路径绝对确认你提供的图像目录路径是正确的并且该目录下确实有.png或.jpg文件。图像命名EUROC数据集的图像命名是时间戳如1403715283412143104.png。ORB-SLAM3默认会按文件名排序读取。如果时间戳文件MH01.txt里的时间戳与文件名对不上程序会跳过或报错。确保你下载的数据集序列和时间戳文件是匹配的。配置文件中的图像分辨率检查YAML文件中的Camera.width和Camera.height是否与你实际图像的分辨率一致。不一致可能导致特征提取出错。6. 进阶配置与性能调优指南成功运行基础示例后你可能希望根据自己的需求或硬件调整ORB-SLAM3以获得更好的性能或适配自己的传感器。6.1 使用自己的相机或数据集这是最常见的需求。你需要为ORB-SLAM3准备两样东西相机配置文件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: 金字塔层数。图像与时间戳程序需要按顺序读取图像。你需要准备一个图像序列按数字或时间戳命名以及一个对应的时间戳文件每行一个时间戳单位秒。对于单目时间戳文件是必须的对于双目程序默认按文件名排序读取左右目图像要求左右目图像文件名严格对应如left_001.png和right_001.png。6.2 启用IMU融合仅限VIO版本ORB-SLAM3最大的亮点之一是其出色的视觉惯性里程计VIO能力。要运行VIO单目IMU或双目IMU你需要数据集必须包含同步的图像和IMU数据如EUROC、TUM-VI数据集。使用对应的示例程序如mono_inertial_euroc或stereo_inertial_euroc。配置文件需要使用对应的惯性配置文件如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社区通常能找到解决方案。