ORB-SLAM3 在 Ubuntu 24.04 下的完整安装记录

文章发布时间:

最后更新时间:

ORB-SLAM3 在 Ubuntu 24.04 下的完整安装记录

实验简介

之前我参考了很多 ORB-SLAM3 安装博客，但大多是基于 Ubuntu 18.04 或 20.04 写的。实际到了 Ubuntu 24.04，很多依赖版本、包名、编译器行为都发生了变化，照着旧教程一步步来，经常会报各种奇怪错误。

这篇文章不是简单转述旧博客，而是基于我自己在 Ubuntu 24.04 上从零开始、一路踩坑并最终编译成功的完整过程整理出来的。文中所有步骤都以最终能成功编译并生成 libORB_SLAM3.so 和各类示例程序为目标。

本文适合这类同学：

  • 使用 Ubuntu 24.04
  • 想在新系统上安装 ORB-SLAM3
  • 已经被 Pangolin、OpenCV、Sophus、Eigen、FFmpeg、Python 等兼容性问题折腾过
  • 希望拿到一份按新系统修正后的可复现流程

1. 实验环境

我的环境如下：

  • 虚拟机：VMware
  • 系统：Ubuntu 24.04.3 LTS
  • 编译器：GCC / G++ 13.3.0
  • CMake：系统源安装
  • OpenCV：4.6.0
  • Pangolin：v0.6
  • ORB-SLAM3：官方仓库源码

说明一下：
网上很多教程是基于 Ubuntu 18.04 + OpenCV 3.4.3 + 老版 Pangolin 写的，这套组合在新系统上问题很多。
我最后成功的关键路线是：

  • OpenCV 不再使用 3.4.3，而改用系统自带 OpenCV 4.6.0
  • Pangolin 不用新版本 0.9.x，而改用 v0.6
  • 关闭 Pangolin Python 绑定
  • 去掉 Sophus 里的 -Werror
  • 针对新编译器和新环境做少量兼容修补

2. 准备工作

建议先建立一个统一目录，把所有源码放一起，例如：

1
2
mkdir -p /mnt/d/code/codex/slam
cd /mnt/d/code/codex/slam

3. 基础依赖安装

先安装系统基础依赖：

1
2
3
4
5
6
7
sudo apt update
sudo apt install -y \
git cmake build-essential pkg-config \
libgl1-mesa-dev libglew-dev libegl1-mesa-dev \
libwayland-dev libxkbcommon-dev wayland-protocols \
libepoxy-dev libopencv-dev libeigen3-dev \
libboost-serialization-dev libssl-dev

这里有几个重点说明：

3.1 不再手工安装 OpenCV 3.4.3

很多旧教程会让你自己编译 OpenCV 3.4.3，甚至还要求把 ORB-SLAM3 里的 OpenCV 版本检查改成 3.4。
这在 Ubuntu 24.04 下不推荐。

原因很简单：

  1. ORB-SLAM3 源码本身要求 OpenCV 4.4 及以上
  2. OpenCV 3.4.3 在新系统上会遇到大量兼容问题：
    • OpenEXR 与 C++17 冲突
    • FFmpeg API 已变化
    • 新 GCC 会把老代码中的 warning 放大
    • TIFF/Anaconda/Windows 库污染等问题

所以最稳的方案是直接安装系统提供的 OpenCV 4：

1
sudo apt install libopencv-dev

安装后检查版本：

1
pkg-config --modversion opencv4

如果输出类似：

1
4.6.0

说明没问题。

3.2 Eigen3 直接用系统包即可

旧教程通常会说：

不要 apt install libeigen3-dev，否则 ORB-SLAM3 检测不到

这个说法在我的环境里不成立。
在 Ubuntu 24.04 下，直接安装系统包就可以：

1
sudo apt install libeigen3-dev

无需单独编译 eigen-git-mirror。
反而手工安装旧版 Eigen 后，容易和系统头文件混用，导致更多模板/警告问题。

4. 获取源码

4.1 ORB-SLAM3

1
2
cd /mnt/d/code/codex/slam
git clone https://github.com/UZ-SLAMLab/ORB_SLAM3.git

4.2 Pangolin

注意：
不要直接用 Pangolin 最新版。
我一开始装到了 0.9.5，后来发现 ORB-SLAM3 在这个版本上容易因为 sigslot、组件重构等问题出错。

最后成功的是 Pangolin v0.6：

1
2
cd /mnt/d/code/codex/slam
git clone --recursive --branch v0.6 https://github.com/stevenlovegrove/Pangolin.git

5. 安装 Pangolin（Ubuntu 24.04 兼容处理）

进入 Pangolin：

1
2
3
cd /mnt/d/code/codex/slam/Pangolin
mkdir build
cd build

5.1 先关闭 Python 绑定

这是非常关键的一步。
Ubuntu 24.04 默认是 Python 3.12，而 Pangolin v0.6 自带的旧版 pybind11 和 Python 3.12 不兼容，会报大量类似下面的错误：

1
2
invalid use of incomplete type 'PyFrameObject'
PyThreadState has no member named 'frame'

所以必须关闭 Python 绑定：

1
cmake .. -DBUILD_PANGOLIN_PYTHON=OFF

5.2 处理旧源码缺少标准头的问题

在新编译器下，Pangolin v0.6 有几个文件缺少 <cstdint> 头文件，会报：

1
2
uint8_t was not declared in this scope
uint32_t does not name a type

需要手动补三个地方。

修改 1：image_io_jpg.cpp

1
sed -i '10i #include <cstdint>' /mnt/d/code/codex/slam/Pangolin/src/image/image_io_jpg.cpp

修改 2：packetstream_tags.h

1
sed -i '1i #include <cstdint>' /mnt/d/code/codex/slam/Pangolin/include/pangolin/log/packetstream_tags.h

修改 3：packetstream.cpp

1
sed -i '1i #include <cstdint>' /mnt/d/code/codex/slam/Pangolin/src/log/packetstream.cpp

5.3 编译安装 Pangolin

1
2
3
4
cd /mnt/d/code/codex/slam/Pangolin/build
make -j1
sudo make install
sudo ldconfig

这里建议先用 -j1，因为如果还有兼容错误，单线程更容易看到第一个真实报错。

安装完成后可以检查：

1
find /usr/local -name "PangolinConfig.cmake"

6. 旧 Pangolin 的清理说明

如果你之前已经装过 Pangolin 0.9.x，尤其是 0.9.5，需要先把它从 /usr/local 移开，否则 ORB-SLAM3 会优先找到不兼容的新版本。

我当时的做法是把旧版备份到别处：

1
2
3
4
5
6
7
8
sudo mkdir -p /usr/local/pangolin_0.9.5_backup

sudo mv /usr/local/include/pangolin /usr/local/pangolin_0.9.5_backup/ 2>/dev/null
sudo mv /usr/local/include/sigslot /usr/local/pangolin_0.9.5_backup/ 2>/dev/null
sudo mv /usr/local/lib/libpango* /usr/local/pangolin_0.9.5_backup/ 2>/dev/null
sudo mv /usr/local/lib/cmake/Pangolin /usr/local/pangolin_0.9.5_backup/ 2>/dev/null

sudo ldconfig

确认旧版不再生效：

1
2
3
find /usr/local -name "PangolinConfig.cmake"
find /usr/local -name "signal.hpp" | grep sigslot
ls /usr/local/lib | grep libpango

如果输出里只剩备份目录，就说明清理成功。

7. 处理 OpenCV 遗留问题

如果你之前跟旧教程一样装过 OpenCV 3.4.3，并且执行过 sudo make install，那么 /usr/local 下面可能残留旧版配置文件，导致 ORB-SLAM3 明明系统里有 OpenCV 4.6.0，却仍然去找到旧版 3.4.3。

典型报错如下：

1
2
3
Could not find a configuration file for package "OpenCV" that is compatible with requested version "4.4"
...
/usr/local/share/OpenCV/OpenCVConfig.cmake, version: 3.4.3

如果遇到这个问题，需要把旧的 OpenCV 配置移开。

7.1 移走旧版 CMake 配置

1
sudo mv /usr/local/share/OpenCV /usr/local/share/OpenCV_3.4.3_backup

7.2 移走旧版 pkg-config 文件

1
2
3
sudo mv /usr/local/lib/pkgconfig/opencv.pc /usr/local/lib/pkgconfig/opencv_3.4.3.pc.bak
sudo ldconfig
hash -r

7.3 检查当前 OpenCV 4

1
pkg-config --modversion opencv4

如果输出 4.6.0，说明 ORB-SLAM3 接下来能正确找到系统 OpenCV。

8. ORB-SLAM3 编译前的兼容处理

进入 ORB-SLAM3：

1
cd /mnt/d/code/codex/slam/ORB_SLAM3

8.1 Sophus 去掉 -Werror

ORB-SLAM3 自带的 Thirdparty/Sophus 在新编译器下会因为很多 warning 被当成 error 而失败。
典型报错类似：

1
2
3
cc1plus: all warnings being treated as errors
test_so3.cpp
test_rxso3.cpp

根因在 Thirdparty/Sophus/CMakeLists.txt 里硬编码了 -Werror。

直接删掉：

1
sed -i 's/-Werror//g' /mnt/d/code/codex/slam/ORB_SLAM3/Thirdparty/Sophus/CMakeLists.txt

8.2 建议关闭 Sophus 测试

如果 Thirdparty/Sophus/CMakeLists.txt 里有：

1
add_subdirectory(test)

建议注释掉。
因为 ORB-SLAM3 只需要 Sophus 库本身，不需要编译它的测试程序。

9. 编译 ORB-SLAM3

先清理旧缓存：

1
2
3
cd /mnt/d/code/codex/slam/ORB_SLAM3
rm -rf build
rm -rf Thirdparty/Sophus/build

然后执行官方脚本：

1
2
chmod +x build.sh
./build.sh

10. 我实际遇到过的主要报错与解决方法

这一节建议保留在博客里，别人搜索报错时很有帮助。

10.1 OpenCV > 4.4 not found

原因：
系统里虽然装了 OpenCV 4，但 /usr/local 里残留了旧版 OpenCV 3.4.3 的配置文件，CMake 优先找到了它。

解决：
把旧版 /usr/local/share/OpenCV 和 /usr/local/lib/pkgconfig/opencv.pc 移走。

10.2 Could not find PangolinConfig.cmake

原因：
Pangolin 没装，或者 CMake 找不到它。

解决：
安装 Pangolin v0.6，并确保 /usr/local 下存在 PangolinConfig.cmake。

10.3 sigslot/signal.hpp 相关模板报错

原因：
装的是 Pangolin 0.9.x，新版组件重构后和 ORB-SLAM3 不兼容。

解决：
移除 Pangolin 0.9.x，改装 Pangolin v0.6。

10.4 uint8_t / uint32_t not declared in this scope

原因：
Pangolin v0.6 的老源码在 GCC 13 / Ubuntu 24.04 下缺少 <cstdint>。

解决：
给以下文件补 <cstdint>：

  • src/image/image_io_jpg.cpp
  • include/pangolin/log/packetstream_tags.h
  • src/log/packetstream.cpp

10.5 invalid use of incomplete type 'PyFrameObject'

原因：
Pangolin 的 Python 绑定使用旧 pybind11，与 Python 3.12 不兼容。

解决：
CMake 时加：

1
-DBUILD_PANGOLIN_PYTHON=OFF

10.6 MD5_Init / MD5_Update / MD5_Final deprecated

这是 OpenSSL 3.0 的弃用警告。
在我的最终成功构建里，它没有继续阻塞主流程。如果遇到 warning 被当成 error，可以在根目录 CMakeLists.txt 里追加：

1
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-error=deprecated-declarations")

11. 编译成功后的验证

成功后，在 ORB-SLAM3 根目录下执行：

1
2
3
4
cd /mnt/d/code/codex/slam/ORB_SLAM3
ls lib
ls Examples/Monocular
ls Vocabulary

如果能看到类似输出：

1
2
3
4
5
libORB_SLAM3.so
mono_euroc
mono_kitti
mono_tum
ORBvoc.txt

说明编译成功。

进一步确认：

1
ls /mnt/d/code/codex/slam/ORB_SLAM3/lib/libORB_SLAM3.so

如果文件存在，说明主库已经生成成功。

12. 运行前检查

运行示例前，建议先确认动态库能正常找到：

1
ldd ./Examples/Monocular/mono_tum

如果有 not found，先设置库路径：

1
export LD_LIBRARY_PATH=/mnt/d/code/codex/slam/ORB_SLAM3/lib:/mnt/d/code/codex/slam/ORB_SLAM3/Thirdparty/g2o/lib:/mnt/d/code/codex/slam/ORB_SLAM3/Thirdparty/DBoW2/lib:$LD_LIBRARY_PATH

13. 数据集运行示例

13.1 TUM 单目

1
2
3
4
5
./Examples/Monocular/mono_tum \
Vocabulary/ORBvoc.txt \
Examples/Monocular/TUM1.yaml \
/path/to/rgb.txt \
/path/to/TUM_dataset

13.2 EuRoC 单目

1
2
3
4
5
./Examples/Monocular/mono_euroc \
Vocabulary/ORBvoc.txt \
Examples/Monocular/EuRoC.yaml \
/path/to/EuRoC_folder \
Examples/Monocular/EuRoC_TimeStamps/MH01.txt

13.3 KITTI 单目

1
2
3
4
./Examples/Monocular/mono_kitti \
Vocabulary/ORBvoc.txt \
Examples/Monocular/KITTI00-02.yaml \
/path/to/KITTI_sequence_folder

14. 最终可复现配置总结

这是我最终成功的配置组合：

  • Ubuntu 24.04.3 LTS
  • GCC / G++ 13.3.0
  • OpenCV 4.6.0（系统包）
  • Eigen3（系统包）
  • Pangolin v0.6
  • BUILD_PANGOLIN_PYTHON=OFF
  • Sophus 去掉 -Werror
  • Pangolin 部分源码补 <cstdint>

在这套配置下，ORB-SLAM3 最终成功生成了：

  • lib/libORB_SLAM3.so
  • Examples/Monocular/mono_tum
  • Examples/Monocular/mono_euroc
  • Examples/Monocular/mono_kitti

15. 结语

网上很多 ORB-SLAM3 教程的问题，不是作者写错了，而是它们大多基于老系统。
一旦系统换成 Ubuntu 24.04，很多过去能跑通的步骤都会出问题：

  • 老版 OpenCV 不再合适
  • Pangolin 新旧版本差异很大
  • Python 3.12 让老 pybind11 失效
  • GCC 13 对旧代码更严格

所以如果你也是新系统环境，不建议再机械照搬 Ubuntu 18.04 的老教程。
按照本文这套实际踩坑后修正过的流程，复现成功率会高很多。