ORB-SLAM2跑自己的图片序列：从编译到轨迹评估的完整指南

简介：这份资源面向视觉SLAM初学者与需要跑通自定义数据集的开发者，聚焦ORB SLAM2在自采图片序列上的实际应用，帮助解决从视频抽帧到生成rgb.txt、再到加载运行自有数据的完整链路问题。压缩包为gz格式，共4个文件，约4.38MB，包含2个Python脚本、1个mp4视频和1个txt文本，脚本可用于视频逐帧提取与rgb.txt时间戳生成，视频提供原始素材，文本则记录图片路径与时间戳，便于直接复现实验。已有5382人学习下载，说明其在SLAM入门实践中具有一定参考价值。资源围绕特征检测与匹配、关键帧选择、跟踪定位、闭环检测、重定位、稀疏建图与全局优化等环节，给出可对照的数据组织方式，读者可据此理解ORB SLAM2读取图片序列的输入规范，并借助示例素材完成自定义场景的定位与建图练习，积累配置参数调整与运行排错的实践经验。

1. 用 ORB-SLAM2 跑自己的图片序列：从一份能直接编译的源码包说起

手头有一批自己拍的图片序列，想验证一下视觉 SLAM 的位姿估计效果，结果卡在第一步——官方仓库只给了示例数据集，自己的图片怎么喂进去、相机内参怎么填、时间戳文件怎么生成，文档里一句没提。这份 ORB-SLAM2 源码包解决的正是这个断点：它把编译依赖、示例配置、图片序列入口都整理好了，拿到手改几个路径就能跑通单目、双目、RGB-D 三种模式。适合两类人：一是刚接触视觉 SLAM、想用真实图片验证课程里那些概念的新手；二是手里有自己采集的序列、需要快速搭一套基线做对比的从业者。下面按「资源是什么 → 怎么配 → 怎么跑 → 坑在哪」的顺序拆，参数和命令都能直接抄。

2. 先看清这份源码包的骨架：目录、依赖与三种模式入口

拿到一个 SLAM 源码包，最忌讳上来就cmake ..。先花十分钟把目录结构和依赖关系摸清楚，后面编译报错能少一半。ORB-SLAM2 的工程组织其实很规整，核心就三块：src/放算法实现，include/放头文件，Examples/放各传感器模式的入口程序和配置。真正决定你能不能跑通自己数据的，是Examples/下面那几个xxx.cc和配套的*.yaml。

2.1 目录结构与关键文件定位

一份典型的 ORB-SLAM2 源码包展开后大致是这样：

ORB_SLAM2/ ├── src/ # 核心算法：Tracking、LocalMapping、LoopClosing ├── include/ # 对应头文件 ├── Examples/ │ ├── Monocular/ # 单目入口 mono_xxx.cc + 相机配置 │ ├── Stereo/ # 双目入口 │ ├── RGB-D/ # RGB-D 入口 │ └── ROS/ # ROS 节点封装（可选） ├── Thirdparty/ # DBoW2、g2o、Pangolin 等依赖 ├── Vocabulary/ # ORB 词典 ORBvoc.txt └── CMakeLists.txt

你要改的只有两处：Examples/<模式>/下的入口程序里读图片的路径，以及同目录下*.yaml里的相机内参。Vocabulary/ORBvoc.txt是回环检测用的词典，文件不小，第一次加载会慢几秒，这是正常的，不是卡死。Thirdparty/里通常已经带了 DBoW2 和 g2o 的源码，Pangolin 需要系统里自己装，这是编译阶段最常见的依赖缺口。

2.2 编译依赖与版本边界

ORB-SLAM2 对依赖版本比较敏感，尤其是 OpenCV 和 Eigen。常见做法是 OpenCV 用 3.x 或 4.x 的早期版本，Eigen 用 3.2 以上，Pangolin 用较新的稳定版。C++ 标准要开到 C++11，老编译器（比如默认 C++98 的）会在CMakeLists.txt里直接报错。

编译流程分两步，先编 Thirdparty 再编主工程：

# 进入源码根目录 cd ORB_SLAM2 # 先给脚本执行权限，再编译第三方库 chmod +x build.sh ./build.sh

build.sh里实际做的是依次进入Thirdparty/DBoW2、Thirdparty/g2o执行 cmake 和 make，最后编译主工程并生成lib/libORB_SLAM2.so。如果这一步在某个 Thirdparty 子目录里失败，先单独进去手动cmake .. && make，看具体报错，比在脚本里被吞掉强。常见失败点是 g2o 找不到 Eigen，或者 Pangolin 头文件路径没被找到——前者检查 Eigen 是否装全（/usr/include/eigen3是否存在），后者确认 Pangolin 装完后find_package(Pangolin)能找到。

提示：编译前先确认cmake --version不低于 2.8，gcc --version支持 C++11。版本不满足时不要硬改 CMakeLists 里的标准号，先升级工具链，否则后面运行期会出现莫名其妙的段错误。

2.3 三种模式怎么选：先想清楚你的数据长什么样

单目、双目、RGB-D 的入口程序不同，配置文件的字段也不同，选错模式会直接跑不起来。判断依据很简单：你采集的是单摄像头视频帧，就走单目；是左右两个同步摄像头，走双目；是有深度图配彩色图，走 RGB-D。

单目模式有个绕不开的特性：尺度不可观。你跑出来的轨迹形状对，但绝对尺度是任意的，这是单目 SLAM 的固有性质，不是代码 bug。如果你的应用需要真实尺度，要么上双目/RGB-D，要么在单目轨迹上额外做尺度对齐。这一点在选模式时就要想清楚，别跑完才发现尺度对不上。

3. 把自己的图片序列喂进去：时间戳、内参与配置文件三件套

这一章是整篇的核心。官方示例用的是打包好的数据集，路径和格式都固定；换成自己的图片，要补的是三样东西：图片命名与时间戳、相机内参 yaml、入口程序里的路径。三样缺一不可，顺序也别乱——先定格式，再填内参，最后改入口。

3.1 图片命名与时间戳文件生成

ORB-SLAM2 读图片序列时，入口程序里通常是一个循环，按索引拼文件名，同时从一个时间戳文件里逐行读时间。所以你的图片要么按固定宽度数字命名（如000001.png、000002.png），要么改入口程序里的拼接逻辑。最省事的做法是统一重命名成六位补零的格式。

时间戳文件的格式是每行一个时间戳（秒，浮点），行数与图片数一一对应。如果你采集时没记录时间，常见做法是按固定帧率反推，比如 30fps 就每帧间隔 1/30 秒。下面这段脚本把任意命名的图片批量重命名并生成时间戳文件：

import os img_dir = "my_sequence" # 你的图片目录 fps = 30.0 # 采集帧率，没有记录就按这个反推 ext = ".png" # 图片扩展名，按实际改 files = sorted([f for f in os.listdir(img_dir) if f.endswith(ext)]) with open(os.path.join(img_dir, "times.txt"), "w") as fout: for i, fname in enumerate(files): # 六位补零重命名，保持顺序 new_name = f"{i:06d}{ext}" os.rename(os.path.join(img_dir, fname), os.path.join(img_dir, new_name)) # 时间戳从 0 开始，按帧率累加 fout.write(f"{i / fps:.6f}\n") print(f"处理 {len(files)} 帧，时间戳写入 times.txt")

这段脚本做了两件事：重命名保证字典序与采集顺序一致，生成times.txt供入口程序读取。参数上，fps只影响时间戳的绝对间隔，不影响位姿估计的相对结果，但如果你后面要做轨迹对齐或速度估计，这个值要尽量准。ext一定要和实际图片格式一致，混用.jpg和.png会导致读图失败。重命名前建议先备份原图，os.rename是不可逆的。

3.2 相机内参 yaml 怎么填

内参是单目 SLAM 精度的命门。fx、fy、cx、cy四个值来自相机标定，没有标定数据的话，跑出来的轨迹会明显漂移甚至跟踪丢失。yaml 文件的结构大致如下（以单目为例）：

%YAML:1.0 # 相机内参，单位像素 Camera.fx: 517.3 Camera.fy: 516.5 Camera.cx: 318.6 Camera.cy: 255.3 # 畸变系数，k1 k2 p1 p2 k3 Camera.k1: 0.2624 Camera.k2: -0.9531 Camera.p1: -0.0054 Camera.p2: 0.0026 Camera.k3: 0.0 # 图像尺寸 Camera.width: 640 Camera.height: 480 # 帧率 Camera.fps: 30.0 # RGB 转灰度，彩色图设为 1 Camera.RGB: 1

fx、fy是焦距的像素表示，cx、cy是主点坐标，通常接近图像中心但不完全等于中心。畸变系数如果相机已经做过去畸变，可以全填 0；没做过就按标定结果填，ORB-SLAM2 内部会做去畸变处理。Camera.RGB: 1表示输入是彩色图、内部转灰度，如果你的图本来就是灰度，填 0。Camera.fps要和实际帧率一致，它影响跟踪时的运动模型假设。

注意：内参填错最典型的表现是「能初始化但很快跟丢」或「轨迹整体缩放不对」。如果跑自己的数据一直丢，先别怀疑算法，拿标定板重新标一次内参，比调任何参数都管用。

3.3 改入口程序：路径、词典与配置加载

入口程序里要改的通常是三处：图片目录、时间戳文件路径、yaml 配置路径。以单目入口为例，核心逻辑是构造System对象、逐帧读图、调用TrackMonocular：

// 加载词典和配置，路径按你的实际目录改 ORB_SLAM2::System SLAM( "/path/to/Vocabulary/ORBvoc.txt", // 词典路径 "/path/to/my_mono.yaml", // 相机配置 ORB_SLAM2::System::MONOCULAR, // 模式 true); // 是否开可视化 // 读时间戳 std::ifstream fTimes("/path/to/my_sequence/times.txt"); std::string line; int ni = 0; while (std::getline(fTimes, line)) { double t = std::stod(line); // 按六位补零拼图片名 char buf[100]; snprintf(buf, sizeof(buf), "/path/to/my_sequence/%06d.png", ni); cv::Mat im = cv::imread(buf, cv::IMREAD_UNCHANGED); if (im.empty()) break; // 读不到就停，避免空帧崩溃 SLAM.TrackMonocular(im, t); // 时间戳单位秒 ni++; } SLAM.Shutdown();

几个参数要留意：TrackMonocular的第二个参数是时间戳，单位是秒，和times.txt里的一致；IMREAD_UNCHANGED保留原始通道，彩色图后面由Camera.RGB控制转换；im.empty()的判断不能省，图片数比时间戳多或少都会在这里暴露。词典路径和 yaml 路径用绝对路径最稳，相对路径在不同工作目录下跑容易找不到文件。改完重新make一次即可，不用重编 Thirdparty。

4. 跑通之后看什么：轨迹保存、可视化与结果判读

程序不报错、窗口里能看到特征点和轨迹，只说明跑起来了，不代表结果可信。这一章讲怎么把轨迹存下来、怎么判断这次跑得对不对，以及结果异常时从哪几个方向排查。

4.1 轨迹文件保存与格式

ORB-SLAM2 在Shutdown()时会自动把轨迹写到当前工作目录，单目模式通常是CameraTrajectory.txt和KeyFrameTrajectory.txt。前者是每帧位姿，后者是关键帧位姿。格式是每行「时间戳 tx ty tz qx qy qz qw」，四元数顺序是 x y z w，别和别的工具搞混。

如果没生成文件，检查入口程序里System构造时最后一个参数（是否保存）以及Shutdown是否被调用。有些改过的入口程序把保存逻辑注释掉了，跑完窗口一关什么都没留下，这是血泪经验——第一次跑一定先确认轨迹文件落地了再谈精度。

4.2 用 evo 做轨迹对齐与误差评估

轨迹存下来后，最直接的验证是和自己采集时的参考轨迹（如果有）做对比，或者至少看轨迹形状是否合理。evo是常用的轨迹评估工具，支持 TUM 格式。把CameraTrajectory.txt转成 TUM 格式（时间戳 + 位置 + 四元数，空格分隔）后可以直接喂进去：

# 安装 evo pip install evo --upgrade # 画轨迹，看形状是否闭合、是否有跳变 evo_traj tum CameraTrajectory.txt --plot # 有参考轨迹时做绝对位姿误差评估 evo_ape tum groundtruth.txt CameraTrajectory.txt --align --plot

--align会先做尺度或刚体对齐再算误差，单目轨迹必须加这个参数，否则尺度差异会让误差大得没法看。evo_traj画出来的图重点看两处：轨迹有没有突然的折返或飞点（跟踪丢失后重定位的典型表现），以及整体形状是否和你实际走的路线一致。形状对但尺度不对，是单目正常现象；形状都不对，回去查内参和图片顺序。

4.3 结果异常的四个排查方向

跑出来结果不对，按这个顺序查，能覆盖大部分情况：

第一，图片顺序。重命名后确认字典序和采集顺序一致，000010排在000009后面没问题，但如果原始命名是img1、img10、img2这种，排序会乱，必须补零。

第二，时间戳单调性。times.txt必须严格递增，重复或倒序会让跟踪的运动模型失效。生成脚本里按索引累加天然单调，手动改过的要复查。

第三，内参和实际分辨率。yaml 里的Camera.width/height必须和图片实际尺寸一致，图片被缩放过的尤其容易漏改，表现是特征点提取正常但位姿明显偏。

第四，纹理条件。白墙、纯色地面、强逆光这些场景 ORB 特征本来就少，跟踪丢失是数据问题不是代码问题。遇到这种序列，要么换场景，要么接受它跑不完全程。

5. 避坑与常见问题：编译、运行、精度三类翻车现场

这一章按「现象 → 原因 → 解决」列几条实际踩过的坑，都是跑自己数据时高频出现的，照着对号入座能省不少时间。

现象：build.sh在 g2o 处报找不到 Eigen。原因：Eigen 装了但头文件路径没被 CMake 找到，或者装的是不完整版本。 解决：确认/usr/include/eigen3/Eigen存在，在 g2o 的 CMakeLists 里显式加include_directories(/usr/include/eigen3)，再单独编译 g2o。

现象：程序启动即崩，报 Pangolin 相关符号未定义。原因：Pangolin 版本与源码不匹配，或编译时链接顺序有问题。 解决：重装 Pangolin 稳定版，装完sudo ldconfig刷新库缓存，再重编主工程。实在搞不定可以先关掉可视化（System构造最后一个参数设 false）验证算法本身是否正常。

现象：能初始化，跑几十帧后跟踪丢失，反复重定位。原因：内参不准、时间戳间隔与实际运动不匹配，或图片序列本身有大量模糊帧。 解决：先重标内参；再检查times.txt间隔是否和实际采集帧率一致；最后抽几帧看清晰度，运动过快导致的模糊帧 ORB 提不出稳定特征，属于数据质量问题。

现象：轨迹形状对，但和参考轨迹比尺度差一个常数。原因：单目 SLAM 尺度不可观，这是固有性质。 解决：不要试图调参「修」尺度，用evo_ape --align做对齐后评估，或改用双目/RGB-D 数据。需要真实尺度时，在轨迹后处理阶段用已知距离做尺度恢复。

现象：RGB-D 模式跑出来深度全错，轨迹乱飞。原因：DepthMapFactor没按深度图的实际量化单位填。深度图若是 16 位、单位毫米，这个因子通常是 1000；单位米则是 1。 解决：查深度图的编码方式，改 yaml 里的DepthMapFactor，用单帧深度值对照真实距离验证一次再跑全程。

6. 进阶：用关键帧轨迹做快速回归，把每次改动都验一遍

跑通一次不算完，真正省时间的是把「改配置 → 重跑 → 看结果」变成一个可重复的回归流程。我一般会固定一段短序列（一两百帧、纹理充足、运动平缓），把它当作基线，每次动内参、动入口程序、换编译选项之后都拿它跑一遍，用关键帧轨迹的终点位置和轨迹长度做快速比对。关键帧轨迹比每帧轨迹短，噪声小，适合做这种粗粒度回归。

具体做法是写个小脚本，跑完后自动提取KeyFrameTrajectory.txt的帧数和终点坐标，和上一次的记录比：

import numpy as np def summarize(path): data = np.loadtxt(path) # 每行: t tx ty tz qx qy qz qw pos = data[:, 1:4] # 取平移部分 length = np.sum(np.linalg.norm(np.diff(pos, axis=0), axis=1)) return len(data), pos[-1], length n, end, length = summarize("KeyFrameTrajectory.txt") print(f"关键帧数 {n}, 终点 {end}, 轨迹长度 {length:.3f}")

np.diff算相邻关键帧的位移再累加，得到轨迹总长度；终点坐标反映整体漂移方向。这两个指标不用很精确，只要同一段序列两次运行的差异在可接受范围内，就说明改动没有引入明显退化。如果关键帧数突然大幅减少，多半是跟踪变差、丢帧增多，回去查最近改的那处配置。

这个习惯的价值在于把「感觉跑得还行」变成「有数字可比」。SLAM 的玄学之处就在于很多改动单看一次结果看不出好坏，跑三次两次不一样，没有基线就只能凭印象。固定序列加固定指标，至少能挡住那些明显让结果变差的改动。从那以后我每次动 ORB-SLAM2 的配置或入口代码，都强制先跑一遍这段基线序列再往下做，省下来的返工时间远比写脚本的几分钟多。希望帮到你。

本文还有配套的精品资源，点击获取