Ubuntu 20.04 部署 ORB_SLAM3 完整流程与踩坑总结

一、标准部署流程（按顺序执行）

1. 系统基础环境初始化

先确保系统工具和公共依赖齐全，避免底层缺库报错。

# 1. 更新系统包
sudo apt update && sudo apt upgrade -y

# 2. 安装编译工具链
sudo apt install build-essential cmake git pkg-config -y

# 3. 安装公共依赖（boost、稀疏矩阵求解、日志库等）
sudo apt install libboost-all-dev libssl-dev libgoogle-glog-dev \
                 libatlas-base-dev libsuitesparse-dev -y

说明：编译 g2o、运行大数据集容易内存溢出，物理内存<16G 建议配置 16G+ 交换内存（你当前32G交换内存完全满足）。

2. 核心依赖库安装（严格按顺序）

2.1 Eigen 3.3.7（矩阵运算基础）

Ubuntu 20.04 源默认版本即为 3.3.7，和 ORB_SLAM3 配套的 g2o 兼容性最好，优先 apt 安装。

sudo apt install libeigen3-dev -y
# 验证版本
pkg-config --modversion eigen3

2.2 Pangolin v0.6（可视化唯一依赖）

版本必须为 v0.6，Ubuntu 20.04 用最新版会出现可视化崩溃、窗口不显示等问题。

# 安装Pangolin图形依赖
sudo apt install libglew-dev libgtk2.0-dev libxkbcommon-dev libwayland-dev -y

# 克隆指定版本源码
git clone https://github.com/stevenlovegrove/Pangolin.git
cd Pangolin && git checkout v0.6

# 编译安装
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install

2.3 OpenCV 4.5.5（图像处理核心）

原版 ORB_SLAM3 原生适配 OpenCV3，OpenCV4 需要修改少量源码兼容；你使用的 4.5.5 属于稳定兼容版本，推荐源码编译带 contrib 模块。

# 安装OpenCV多媒体依赖
sudo apt install libjpeg-dev libpng-dev libtiff-dev libavcodec-dev \
                 libavformat-dev libswscale-dev libv4l-dev -y

# 下载对应版本的opencv和contrib
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git
cd opencv && git checkout 4.5.5
cd ../opencv_contrib && git checkout 4.5.5

# 编译安装（纯CPU版本关闭CUDA，避免驱动兼容问题）
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 ..
make -j$(nproc)
sudo make install

3. ORB_SLAM3 源码编译

3.1 克隆源码

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

3.2 OpenCV4 兼容修改（必做）

原版代码使用 OpenCV3 的旧宏，OpenCV4 下会编译报错，需要修改两处：

1. include/ORBextractor.h：将 #include <opencv/cv.h> 改为 #include <opencv2/imgproc/imgproc_c.h>
2. src/ORBextractor.cc：全局替换 CV_LOAD_IMAGE_GRAYSCALE 为 cv::IMREAD_GRAYSCALE

3.3 一键编译

chmod +x build.sh
./build.sh

说明：build.sh 会自动编译 Thirdparty 下的 DBoW2、g2o，再编译主程序；单步报错建议进入对应 build 目录单独排查。

3.4 编译验证

成功后 Examples 目录下会生成可执行文件，如 mono_tum、mono_inertial_euroc 等。

4. 数据集运行与轨迹评估

4.1 数据集准备

常用数据集：TUM RGBD（单目/双目）、EuRoC MAV（单目+IMU/双目+IMU），解压后保持原始目录结构。

4.2 典型运行命令

# 单目 TUM 数据集
./Examples/Monocular/mono_tum Vocabulary/ORBvoc.txt Examples/Monocular/TUM1.yaml /path/to/dataset

# 单目+IMU EuRoC 数据集
./Examples/Monocular-Inertial/mono_inertial_euroc Vocabulary/ORBvoc.txt \
Examples/Monocular-Inertial/EuRoC.yaml /path/to/dataset \
Examples/Monocular-Inertial/EuRoC_TimeStamps/MH01.txt

4.3 轨迹评估（evo 工具）

# 安装 evo
pip install evo --upgrade --no-binary evo

# 常用命令
# 单轨迹可视化
evo_traj tum CameraTrajectory.txt
# 计算绝对位姿误差
evo_ape tum groundtruth.txt CameraTrajectory.txt -va
# TUM 格式转 KITTI 格式
evo_traj tum input.txt --save_as_kitti output.txt

---

二、全场景踩坑问题汇总

（一）依赖安装类

问题现象	根本原因	解决方案
Pangolin 编译报错：找不到 GLEW / GTK 未定义	缺少图形后端依赖	提前执行：sudo apt install libglew-dev libgtk2.0-dev libxkbcommon-dev libwayland-dev
OpenCV 编译报错：ffmpeg / avcodec 相关未定义	缺少多媒体编解码依赖	安装完整依赖：sudo apt install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev
g2o 编译报错：eigen 模板错误	Eigen 版本过高（3.4+），不兼容 ORB_SLAM3 配套的 g2o	卸载高版本，安装 apt 默认 3.3.7：sudo apt install libeigen3-dev

（二）编译错误类

1. OpenCV4 下 CV_LOAD_IMAGE_GRAYSCALE 未声明

   • 原因：OpenCV4 移除了 OpenCV3 的 C 风格宏
   • 解决：全局替换该宏为 cv::IMREAD_GRAYSCALE，同步更新对应头文件

2. CMake 报错：找不到 Eigen3 / Pangolin / OpenCV

   • 原因：库未安装到系统路径，或 CMake 搜索路径不匹配
   • 解决：确认执行过 sudo make install；可在 CMakeLists.txt 手动指定路径，例如：```
     set(EIGEN3_INCLUDE_DIR /usr/include/eigen3)

3. boost::filesystem 链接错误

   • 原因：Ubuntu 20.04 的 boost 版本较高，与默认配置不兼容
   • 解决：在 CMakeLists.txt 中添加：add_definitions(-DBOOST_NO_CXX11_SCOPED_ENUMS)

（三）运行时问题

1. 运行数据集段错误（core dumped）
   • 常见原因：数据集路径错误、Pangolin 版本不对、内存不足
   • 排查：先打印路径确认文件存在；换回 Pangolin v0.6；检查交换内存状态
2. 可视化窗口不显示 / 黑屏
   • 原因：Wayland 显示协议与 Pangolin 兼容问题，或 GTK 后端未启用
   • 解决：运行前执行 export GDK_BACKEND=x11 强制使用 X11；重新编译带 GTK 支持的 Pangolin
3. 单目+IMU 初始化失败/跟踪丢失
   • 原因：IMU 参数配置与数据集不匹配、时间戳未对齐
   • 解决：使用数据集对应的官方 yaml 配置；检查时间戳文件格式是否正确

（四）evo 评估工具类

1. 报错：No module named 'tkinter'
   • 原因：Ubuntu 20.04 默认未安装 Python3 图形库
   • 解决：sudo apt install python3-tk
2. 报错：时间戳不重叠（times do not overlap）
   • 原因：估计轨迹与真值轨迹时间戳范围不一致、格式不统一
   • 解决：确认均为 TUM 格式；用 --t_offset 校准时间偏移，或先通过 evo_traj 对齐时间戳
3. pip 安装 evo 权限不足
   • 解决：用户目录安装：pip install evo --user

（五）系统环境类

1. 编译时系统卡死 / 死机

   • 原因：编译线程数过多，内存负载超限
   • 解决：减少线程数，例如 make -j4（每线程约占 2G 内存，按物理内存调整）

2. 多版本 OpenCV 冲突

   • 原因：系统同时存在 apt 版和源码编译版 OpenCV，链接混乱
   • 解决：卸载 apt 版：sudo apt remove libopencv-dev；编译时明确指定路径：```
     cmake -D OpenCV_DIR=/usr/local/lib/cmake/opencv4 ...

---

三、快速排障指南

1. 编译报错：优先查「依赖版本是否匹配」→「头文件/库路径是否正确」→「是否做了 OpenCV4 兼容修改」
2. 运行崩溃：优先查「数据集路径」→「Pangolin 版本」→「内存是否充足」
3. 评估报错：优先查「轨迹格式」→「时间戳对齐」→「evo 依赖是否完整」