单目+IMU SLAM部署：ORB-SLAM3编译与EuRoC实测

搞ORB-SLAM3部署这事，最气人的往往不是算法本身，而是环境、依赖、版本、数据格式这些琐碎问题。我最近在Ubuntu 20.04上把ORB-SLAM3从源码完整编译了一遍，用EuRoC数据集跑通了单目+IMU（Mono-Inertial）模式，期间踩了不少坑——有编译期的，有参数配置的，也有对IMU初始化机理理解不到位导致的误操作。这篇记录把整个过程完整复盘一遍，包括环境搭建、build.sh编译流程、配置参数改动、运行命令、日志输出解读，以及我在yaw慢漂和IMU初始化上的一些实际观察，希望能帮后来的人少走点弯路。不管你是在校学生、刚入门SLAM的工程师，还是准备用ORB-SLAM3做视觉惯性里程计验证的开发者，这篇都值得收藏。

1. 项目复盘：我为什么要写这篇运行记录

1.1 看似简单的部署其实暗坑不少

ORB-SLAM3开源四年多，网上教程一搜一大把，看起来无非就是克隆、装依赖、跑build.sh三步。但真动手实操，版本不匹配、依赖库冲突、数据集路径错误、yaml参数格式问题，随便一个都能让你卡上好几天。我自己就在Pangolin和OpenCV的兼容性上浪费了差不多一个下午，在IMU初始化失败的问题上又反复折腾了很久。

所以这篇记录的价值在于：把我在Ubuntu 20.04上从零到一跑通ORB-SLAM3单目+IMU模式的完整路径复现出来，包含我踩过的坑和对应的解决办法。读者照着走一遍，基本能在一两个小时内部署完成，剩下时间可以专心研究算法和改进实验，而不是跟CmakeLists.txt较劲。

1.2 单目+IMU到底能解决什么场景问题

纯单目SLAM有个天生的短板——尺度不可观测。相机在移动过程中，我们无法仅凭单帧图像判断物体到底离我们多远，场景是“放大”还是“靠近”了。这个问题在地图构建、机器人导航、AR叠加这些实际场景中非常致命，因为你需要真实的物理尺度来做路径规划和碰撞检测。

而单目+IMU的方案，恰恰是用IMU的加速度计和陀螺仪数据弥补单目视觉在尺度上的缺失。IMU能测量真实的加速度和角速度，这些是物理量、有绝对尺度，所以视觉惯性融合之后，系统能估计出真实的轨迹尺度，同时还能在视觉短暂丢失或者快速运动导致图像模糊的时候，用IMU的预测结果顶上去。这也是ORB-SLAM3中Monocular-Inertial模式存在的意义——它比纯单目更鲁棒，又比双目和RGB-D在硬件上更轻量、更省成本，特别适合无人机、手持设备、车载前视摄像头这类场景。

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

2.1 系统、硬件与基础工具

我用的系统是Ubuntu 20.04.6 LTS，内核5.15，这算是ORB-SLAM3比较主流的部署环境。官方推荐Ubuntu 18.04或20.04，20.04的优势是OpenCV 4.2可以直接用apt安装，不用自己从源码编译OpenCV，省事很多。硬件方面我用的是一台普通台式机，CPU是i5-10400，内存16GB，无独立显卡也能跑——ORB-SLAM3的视觉前端主要吃CPU，大多数环节对GPU没有硬性要求。

基础工具链直接一条命令装齐：

sudo apt update sudo apt install -y build-essential cmake git pkg-config

cmake版本在20.04上是3.16，完全够用。gcc默认是9.4，编译ORB-SLAM3也没有问题。

2.2 四大依赖库的选型与避坑

ORB-SLAM3的核心依赖是Pangolin、OpenCV、Eigen3，以及仓库自带的DBoW2、g2o、Sophus（在Thirdparty目录下）。前三个需要自己装，后三个在编译时由build.sh自动顺带编译。

先说Eigen3。Ubuntu 20.04的apt源里默认是Eigen 3.3.7，这个版本和ORB-SLAM3是兼容的。如果从源码装了Eigen 3.4以上版本，g2o编译时会出现模板匹配错误（常见报错形如“static assertion failed”）。所以我的建议很简单：直接用apt装Eigen，别折腾。

sudo apt install -y libeigen3-dev

然后是OpenCV。20.04默认是4.2.0，ORB-SLAM3官方支持OpenCV 3.x和4.x，4.2用下来没有任何问题。这里有个容易踩的坑：如果你之前装了OpenCV 4.5或4.6，编译时可能会遇到cv::bow::Dictionary之类的符号问题，因为ORB-SLAM3的DBoW2第三方库对OpenCV的接口依赖比较老。建议先检查系统里OpenCV版本：

pkg-config --modversion opencv4

如果是4.2.0，直接往下走就行。如果你系统里已经装过别的版本，可以开个干净的虚拟环境或者干脆卸载重装，别硬凑。

Pangolin是用来做界面可视化的，也是整套依赖里最容易出问题的。我用的版本是Pangolin v0.8（官方仓库master分支在2023年之后做了一次比较大的重构，接口变化不小，直接编最新版可能会和ORB-SLAM3源码不兼容）。安装命令如下：

git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin git checkout v0.8 ./scripts/install_prerequisites.sh --dry-run mkdir build && cd build cmake .. make -j8 sudo make install

install_prerequisites.sh脚本主要是安装一些系统级依赖，比如libglew-dev、libgl1-mesa-dev、libegl1-mesa-dev、libxkbcommon-dev这些，如果网络不好可以手动apt安装。如果你不需要可视化（比如在服务器上跑），也可以在CMake时加-D BUILD_EXAMPLES=OFF或者干脆不装Pangolin、改掉ORB-SLAM3里的相关头文件，但这样操作风险大，不推荐新手尝试。

2.3 库的安装顺序为什么重要

很多教程会忽略构建顺序，但这其实是编译成败的关键细节之一。ORB-SLAM3的编译链路是这样的：先编Thirdparty里的DBoW2，再编g2o，然后编Sophus，最后才编译Examples里的可执行文件。build.sh脚本内部默认按这个顺序执行，而它假设Pangolin和OpenCV已经提前装好并能被Cmake找到。

所以实际操作顺序是：先装Eigen和OpenCV，再编Pangolin并install，最后进入ORB-SLAM3目录执行build.sh。如果你把顺序反过来，比如先跑build.sh再装Pangolin，cmake阶段就会报Could not find Pangolin，白白等半天。

提示：Pangolin编译完成后一定要sudo make install，否则ORB-SLAM3的CMakeLists.txt里find_package(Pangolin)会找不到库。装完可以用这个命令验证：ls /usr/local/lib/libpangolin*。

3. 编译ORB-SLAM3全过程：从克隆到build.sh

3.1 获取源码与目录结构

源码从官方GitHub仓库拉取：

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

拉下来之后，目录里的关键结构大概是这样的：

• Examples/：存放各个模式下的运行程序源码和配置文件，比如Monocular、Stereo、RGB-D、Monocular-Inertial等子目录
• Vocabulary/：ORB词典文件，可以用工具生成，仓库里也直接提供了训练好的ORBvoc.txt
• Thirdparty/：DBoW2、g2o、Sophus三个第三方库的源码
• build.sh：一键编译脚本

值得说明的是，ORB-SLAM3的源码仓库已经比较稳定，大部分文件不会频繁变动，所以不需要锁定特定commit，直接pull最新master即可。唯一需要注意的是仓库比较大（里面有EuRoC的配置文件和一些测试数据），克隆时如果网络慢可以加--depth 1只拉取最新一次提交。

3.2 编译过程中的验收点

执行编译：

chmod +x build.sh ./build.sh

这里建议你观察编译输出，不要干等。整个编译链路有五个主要编译目标：DBoW2、g2o、Sophus、ORB_SLAM3主库、可执行程序。每编译完一个目标，屏幕上会出现对应的marker。

关键点是：编译到Sophus时，编译器会报一些warning，这很正常，别慌。Sophus是一个比较老的李代数库，在gcc 9下会有一堆未使用变量和隐式类型转换的warning，只要不是error就能继续跑。

整个编译过程视机器性能，大概需要10到20分钟。结束后，Examples/Monocular-Inertial/下应该生成mono_inertial_euroc和mono_inertial_tum_vi两个可执行文件。前者用于EuRoC数据集的单目+IMU模式，后者用于TUM-VI数据集。

3.3 我在编译时实际碰到的三个问题

第一个问题是Pangolin的版本兼容。我最初直接clone了Pangolin的master分支，编译ORB-SLAM3时在Viewer.cc报了一堆setWindowTitle相关的错误。后来发现是Pangolin v0.9把接口改了。解决办法是切回v0.8 tag重新编译安装，立马就过。

第二个问题是OpenCV的cv::Mat和cv::FileStorage头文件冲突。这个主要出现在同时装了多个OpenCV版本的系统里。我检查发现系统里既有OpenCV 4.2又有ROS自带的OpenCV 4.5，CMake优先找到了4.5，结果DBoW2编译时报了找不到cv::FileNodeIterator的错误。处理方法是把/usr/local/lib/cmake/opencv4临时移到别处，强制CMake使用系统的/usr/lib/x86_64-linux-gnu/cmake/opencv4，编完再移回来。

第三个问题是内存不足。编译g2o时，很多模板实例化非常吃内存。我的16GB内存机器上，只开make -j8会偶发内存不足导致编译器崩溃。后来改成make -j4就稳定多了。如果你的机器内存只有8GB，建议直接make -j2，慢一点但是不会崩。

3.4 单目+IMU模式的可执行程序清单

编译完成后，我习惯先打个表确认一下生成的可执行文件，方便后续对号入座：

如果编译完这些文件都在，说明主程序编译成功，可以进入下一步。

4. 单目+IMU的核心原理：为什么系统能工作

4.1 视觉惯性融合的底层逻辑

在正式跑数据之前，我花了不少时间重新梳理ORB-SLAM3单目+IMU的数学原理。理解原理不是为了发论文，而是为了在实际问题中定位故障。IMU和视觉的融合，本质上是一个状态估计问题。系统状态包括：相机位姿（位置和姿态）、速度、IMU零偏（bias）、以及当前地图点的逆深度或三维坐标。视觉部分提供重投影误差约束，IMU部分提供预积分约束，二者通过因子图（Factor Graph）或滑动窗口优化联合求解。

IMU的数据频率高（通常是100Hz到200Hz），视觉帧率低（通常是20Hz到30Hz）。两者融合的直观好处是：在两次视觉帧之间，IMU可以频繁积分，给出短时间内的相对运动预测；而视觉观测则周期性地修正IMU积分带来的累积漂移。反过来，当相机快速旋转或者运动模糊导致视觉失配时，IMU依然能维持一段时间的合理位姿估计。

4.2 初始化阶段：尺度、重力、速度与零偏的估计

单目+IMU模式对初始化极其敏感，我实际测试中至少有一半的失败都发生在初始化阶段。ORB-SLAM3的初始化主要做了这么几件事：

1. 视觉初始化：利用基础矩阵或者单应矩阵恢复初始的稀疏特征点深度和初始帧间运动，这个阶段得到一个无尺度的相机轨迹。
2. IMU联合初始化：利用视觉给出的帧间相对位姿和IMU的角速度/加速度测量，估计出一个真实的尺度因子、重力方向（相对于相机坐标系的朝向）以及每一帧的速度。这一步的核心思路是构建一个线性最小二乘问题，将IMU预积分项和视觉相对运动之间的残差最小化。
3. 零偏初始化：对加速度计和陀螺仪的零偏做初始估计，这一步在后续优化中会不断细化。

这个过程要求IMU有充分的激励。什么叫充分的激励？就是IMU在初始化阶段必须经历足够的加速度变化和角速度变化。如果你把设备放在桌上静止不动，或者用极其缓慢均匀的速度平移，IMU无法观测到重力之外的其他加速度信息，线性化系统会退化，初始化就会失败或者给出一个离谱的尺度。这在我实际操作中体会特别深——我一开始用一段很“温和”的手持数据去跑，结果初始化花了很长时间，而且尺度偏差巨大。换上一段有加速、有转弯的数据之后，系统几乎在1秒内就完成了初始化。

4.3 相机-IMU外参：标定值的准确度决定上限

ORB-SLAM3的配置文件中，需要给定相机到IMU的外参，即IMU坐标系在相机坐标系下的位置（平移向量）和姿态（旋转四元数）。这个外参的重要性常常被忽略。如果你用的数据集是EuRoC，官方文档里给出了精确的外参，直接用即可。但是如果你使用自己采集的数据，这个外参必须经过标定。

外参不准有什么后果？最典型的表现是：初始化阶段即使成功了，优化后的轨迹会呈现出系统性的漂移，特别是旋转部分。因为视觉和IMU两个传感器对同一个运动的观测视角不同，如果外参错误，残差计算从一开始就是错的，优化器只能通过调节其他状态变量（比如零偏）来“硬凑”，长期下来零偏估计也会有偏，最终位姿精度大幅下降。

我自己在测试时故意把旋转外参的一个分量改错5度，结果轨迹的终点误差从0.3米变成了1.8米，差距非常明显。所以如果你用的是自采数据，建议先用Kalibr或imu_utils做一次完整的相机内参、IMU内参和相机-IMU外参标定，再进ORB-SLAM3。

4.4 yaw方向的慢漂移：为什么会有、能不能消除

在实际测试EuRoC序列的时候，我注意到一个现象：即使整个SLAM过程没有丢帧、没有重定位，轨迹的yaw角（偏航角）依然会存在一个非常慢的漂移。这其实是单目+IMU模式下的一个共性问题。

原因要从可观测性角度去理解。IMU的重力向量在观测方程中扮演了“绝对参考”的角色，它决定了roll（横滚）和pitch（俯仰）两个方向的可观性，也就是说这两个方向的角度误差会被重力观测持续修正。但是yaw方向呢？重力向量是一个平行于竖直方向的向量，绕竖直方向的旋转不会改变重力向量，所以IMU无法提供yaw方向的绝对参考。yaw的收敛只能依赖视觉观测，而纯单目视觉本身也没有绝对的yaw参考（单目无法感受绝对的偏航角），只能通过特征点的三角化和连续帧匹配来慢慢积累。

这带来的直观结果就是：yaw必然存在慢漂移，这是系统固有属性，不是Bug。解决方案通常是引入额外的绝对观测，比如磁力计（提供地磁航向角）、GPS航向、或者地图中的已知方向特征。如果你的应用对航向角精度要求比较高，单靠单目+IMU是做不到长期无漂移的。理解了这一点，你在看轨迹误差的时候就不会过度惊慌。

4.5 配置文件中的IMU噪声参数

ORB-SLAM3给出的EuRoC yaml配置文件里，有一组和IMU相关的参数，关键项是：

• Tbc：相机到IMU的外参平移和旋转
• Rate：IMU数据频率
• NoiseGyro：陀螺仪噪声密度（rad/s/sqrt(Hz)）
• NoiseAcc：加速度计噪声密度（m/s^2/sqrt(Hz)）
• Gravity：重力加速度大小

这些噪声参数是IMU预积分和滤波器协方差矩阵的基础。如果你的IMU和EuRoC上的IMU（ADIS16448）差异较大，务必替换成自己标定的噪声参数。否则可能出现两种典型症状：噪声参数设置过小，优化器过分信任IMU，视觉偏差被忽略，轨迹平滑但精度差；噪声参数设置过大，优化器几乎只信任视觉，IMU的作用被削弱，初始化容易失败。

我在测试中用的是一颗消费级IMU（MPU6050），和EuRoC的IMU噪声水平差了不止一个数量级。所以我直接把噪声密度调大了一倍左右，再结合视觉初始化，效果会好很多。但这只是一个经验性的调参方向，具体数值还是要依靠Allan方差标定。

5. EuRoC数据集实测：跑通第一个单目+IMU序列

5.1 数据集下载与目录整理

EuRoC MAV数据集是苏黎世联邦理工（ETH）发布的无人机视觉惯性数据集，里面有双目灰度图像和IMU数据，并提供了Vicon和Leica的ground truth轨迹。我们用它的MH_01到MH_05序列测试单目+IMU模式。

下载时要注意版本。EuRoC提供ASL格式和ROS bag两种格式，ORB-SLAM3官方示例使用的是ASL格式，目录结构是：

MH_01/ ├── mav0/ │ ├── cam0/ │ ├── cam1/ │ ├── imu0/ │ ├── leica0/ │ └── state_groundtruth_estimate0/

下载解压后，MH_01目录下的路径就是这个结构。ORB-SLAM3运行程序接收的第二个参数就是指向这个mav0目录的路径，所以解压之后别擅自改动目录结构。

下载建议用官网的网盘或者学术镜像，文件比较大（MH序列每个大约2到4GB），注意预留磁盘空间。我通常是放在/data/euroc/MH_01/mav0这种路径下。

5.2 配置文件参数解读

运行单目+IMU模式的EuRoC程序，需要显式指定三个内容：ORB词表文件、配置文件、时间戳文件。其中配置文件是关键，路径是Examples/Monocular-Inertial/EuRoC.yaml。这个文件是ORB-SLAM3对EuRoC数据集预先标定好的参数文件。

打开这个yaml，能看到几个关键参数：

• Camera.fx/fy/cx/cy：相机内参，EuRoC的MH序列用的是全局快门相机，内参基本一致
• Camera.k1/k2/p1/p2：畸变系数
• Camera.width/height：图像尺寸，EuRoC左目是752x480
• Camera.fps：视觉帧率，EuRoC是20fps
• IMU.Tbc：相机到IMU的外参，这里是四元数+平移的写法
• IMU.NoiseGyro/NoiseAcc：IMU噪声参数
• ORBextractor.nFeatures：每帧提取的特征点数量，默认1000
• Viewer和System相关参数：线程数、可视化开关等

这里特别提醒一个细节：Camera.fps参数不仅影响时间戳读取，还影响ORBextractor中特征点金字塔层数和关键帧判定。如果你用的是自采数据，这里必须改成你相机实际帧率，不能照抄EuRoC的20。

还有IMU.Rate，它定义的是IMU传感器数据频率。ORB-SLAM3的IMU预积分代码会用这个频率来计算相邻IMU测量之间的时间间隔。如果实际IMU数据频率和配置不一致，预积分的时间间隔就会出错，位姿估计会快速发散。

5.3 运行命令与日志关键输出

运行命令如下：

./Examples/Monocular-Inertial/mono_inertial_euroc \ Vocabulary/ORBvoc.txt \ Examples/Monocular-Inertial/EuRoC.yaml \ /data/euroc/MH_01 \ Examples/Monocular-Inertial/EuRoC_TimeStamps/MH01.txt

这里的第四个参数是时间戳文件，ORB-SLAM3会根据这个文件去数据集中读取对应的图像。时间戳文件每一行是一个时间戳，必须和cam0目录中的图像文件名对应。EuRoC自带的时间戳文件在Examples/Monocular-Inertial/EuRoC_TimeStamps/目录下，文件名类似MH01.txt。

运行之后，终端会有大量输出。关键看几行：

• 初始化相关：程序会在视觉初始化完成后开始联合初始化IMU。如果看到类似Initialization from IMU has been completed的日志，说明IMU初始化成功，这是整个过程中最关键的节点。
• Tracking（跟踪）状态：实时输出当前图像帧的编号、关键帧数量、局部地图点数量、相机位姿等。
• 在运行结束时会输出统计信息，包含平均跟踪时间、关键帧数量、局部地图优化次数等。

如果你的终端没有出现初始化完成的日志，而是一直在Attempting initialization循环，说明IMU初始化失败。这时候不要急着改代码，先回忆一下我前面说的IMU激励条件，大概率是数据太温和或者IMU噪声设置不合理。

5.4 轨迹输出与精度评估

ORB-SLAM3在运行结束后会生成一个以f开头的轨迹文件，比如f_vio_estimated.txt或者KeyFrameTrajectory_TUM_Format.txt，位置一般在可执行文件所在的目录下。如果你没有显式关闭保存，默认就会生成。

这个轨迹文件主要记录的是每一帧相机在世界坐标系下的位姿（位置和四元数）。要和EuRoC的ground truth做对比，可以用evo工具：

pip install evo evo_ape tum groundtruth.txt estimated.txt -a

-a参数表示先做一次Umeyama对齐，因为单目+IMU虽然恢复了尺度，但和ground truth的坐标系定义可能没有完全对齐。对齐后的ATE（Absolute Trajectory Error）是你的SLAM系统精度的直接体现。

我在MH_01上跑出来的ATE大概是0.4到0.6米左右的误差水平，具体数值取决于运行次数和初始化质量。值得注意的是，ORB-SLAM3在多次运行时结果并不完全一致，因为ORB特征提取、RANSAC、以及线程调度都存在随机性，这是很正常的现象，评估时应取多次运行的平均值。

6. 高频问题与排查速查表

6.1 编译期问题

6.2 运行期问题

6.3 我的调参经验

在调参上，我最深的体会是：不要一开始就动ORB特征点数量，先检查输入的IMU信息是否正确。很多初始化问题其实不是特征点数量不够，而是IMU数据的频率、时间戳、外参这些底层的“物理参数”不对。

如果说有一点实用的调参技巧，那就是在拿到一个完全陌生的数据集时，先把视觉跟踪跑起来（只跑纯单目模式，不启用IMU），确认视觉本身没问题，再加上IMU做联合初始化。这样能精准定位问题出在视觉环节还是惯导环节，避免一次改一堆参数导致问题更难排查。我在调试自采数据时，基本都是这个套路。

最后再分享一个小技巧：在调试IMU相关问题时，把ORB-SLAM3的轨迹输出和IMU原始数据一起画出对比图。在evo里跑一个evo_traj对比，能让漂移问题看得一清二楚。纸上分析数据永远比盯着终端日志更高效。这也是我个人在整个运行记录中最受益的操作方式。