使用 Docker 运行 ORB-SLAM3（TUM 数据集）的完整实践记录

使用 Docker 运行 ORB-SLAM3（TUM 数据集）的完整实践记录

——从环境启动、Xvfb 显示、数据集挂载到轨迹导出

一、背景与目标

为了在服务器环境中复现实验并避免复杂的本地依赖，选择使用 Docker 容器运行 ORB-SLAM3，并在 **无物理显示设备（Headless）**的情况下，跑 TUM RGB-D 数据集（Monocular 模式），最终目标是：

  • 成功运行 ORB-SLAM3
  • 跑多个 TUM 序列（freiburg1 / freiburg2）
  • 导出 KeyFrameTrajectory.txt
  • 将结果从 Docker 容器安全拷贝回本地

二、Docker 启动方式的选择（第一个关键坑）

1. 最初的启动方式（有问题）

最开始使用了如下命令启动容器：

docker run --rm -it \
  --name orbslam3_run \
  -v /home/root/datasets:/datasets:ro \
  orbslam3:dev bash

2. 问题在哪？

  • --rm 表示 容器退出即自动删除

  • 一旦 exit：

    • 所有 容器内生成的结果文件都会消失
    • 无法再 docker cp
    • 无法 docker start 重新进入

📌 这在需要导出实验结果的场景下是非常危险的

✅ 正确的做法（后续采用）

docker run -it \
  --name orbslam3 \
  -v /home/root/datasets:/datasets:ro \
  -v /home/root/results:/results \
  orbslam3:dev bash

关键点：

  • ❌ 不使用 --rm
  • ✅ 单独挂载 /results 用于保存轨迹
  • 容器退出后数据仍然存在

三、TUM 数据集准备与挂载

1. 下载数据集（宿主机）

cd ~/datasets

wget https://vision.in.tum.de/rgbd/dataset/freiburg1/rgbd_dataset_freiburg1_xyz.tgz
tar -xzf rgbd_dataset_freiburg1_xyz.tgz

wget https://vision.in.tum.de/rgbd/dataset/freiburg1/rgbd_dataset_freiburg1_desk.tgz
tar -xzf rgbd_dataset_freiburg1_desk.tgz

wget https://vision.in.tum.de/rgbd/dataset/freiburg2/rgbd_dataset_freiburg2_xyz.tgz
tar -xzf rgbd_dataset_freiburg2_xyz.tgz

目录结构最终为：

~/datasets/
├── rgbd_dataset_freiburg1_xyz
├── rgbd_dataset_freiburg1_desk
└── rgbd_dataset_freiburg2_xyz

四、ORB-SLAM3 在 Docker 中的最大问题：显示系统（Pangolin）

1. 典型错误

在容器中直接运行：

./Examples/Monocular/mono_tum ...

会立刻报错：

terminate called after throwing an instance of 'std::runtime_error'
what(): Pangolin X11: Failed to open X display

2. 根本原因

  • ORB-SLAM3 默认启用 Pangolin Viewer
  • Docker 中没有真实的 X11 显示
  • 即使 --no-viewer，内部仍会触发显示初始化路径

五、解决方案：使用 Xvfb（虚拟显示）

1. 安装（只需一次）

apt update
apt install -y xvfb

2. 每次跑 SLAM 前的“固定流程”（非常关键）

这是我最终总结出的“稳定流程”

# 1. 清理残留 Xvfb（防止 display 被占用）
pkill -9 Xvfb || true
rm -f /tmp/.X99-lock
rm -rf /tmp/.X11-unix/X99

# 2. 启动虚拟显示
Xvfb :99 -screen 0 1024x768x24 -nolisten tcp -ac &

# 3. 设置 DISPLAY
export DISPLAY=:99

📌 如果不做这一步，很容易遇到：

Server is already active for display 99
xvfb-run: error: Xvfb failed to start

六、运行 ORB-SLAM3 + 导出轨迹

示例：freiburg1_xyz

cd /opt/ORB_SLAM3

./Examples/Monocular/mono_tum \
  Vocabulary/ORBvoc.txt \
  Examples/Monocular/TUM1.yaml \
  /datasets/rgbd_dataset_freiburg1_xyz

mv KeyFrameTrajectory.txt \
   /results/KeyFrameTrajectory_freiburg1_xyz.txt

其它序列（同理）

  • TUM1.yaml + freiburg1_desk
  • TUM2.yaml + freiburg2_xyz

最终 /results 中包含：

KeyFrameTrajectory_freiburg1_xyz.txt
KeyFrameTrajectory_freiburg1_desk.txt
KeyFrameTrajectory_freiburg2_xyz.txt

七、容器退出 & 结果保留

exit

由于使用了：

-v /home/root/results:/results

👉 所有轨迹文件都安全保存在宿主机

八、从服务器下载到本地（scp 的坑）

1. 遇到的问题（zsh）

zsh: no matches found: root@1.2.3.4:/home/root/results/KeyFrameTrajectory_*.txt

2. 原因

  • zsh 会在本地先展开 *
  • 远端路径的通配符必须避免被本地 shell 解析

✅ 正确做法

scp "bistu@server:/home/root/results/KeyFrameTrajectory_*.txt" \
    ~/Downloads/orbslam3_results/

或者：

scp -r root@1.2.3.4:/home/root/results ~/Downloads/orbslam3_results

九、最终稳定工作流总结（强烈推荐）

Docker 启动（一次）

docker run -it \
  --name orbslam3 \
  -v ~/datasets:/datasets:ro \
  -v ~/results:/results \
  orbslam3:dev bash

每个数据集跑之前

pkill -9 Xvfb || true
rm -f /tmp/.X99-lock
rm -rf /tmp/.X11-unix/X99
Xvfb :99 -screen 0 1024x768x24 -nolisten tcp -ac &
export DISPLAY=:99

跑 SLAM + 导出

./Examples/Monocular/mono_tum ...
mv KeyFrameTrajectory.txt /results/xxx.txt

好，这里我给你完整、系统、事无巨细地整理一篇技术博客，把你这次 用 Docker 跑 ORB-SLAM3 的全过程全部记下来——
包括：为什么用 Docker、数据集下载踩的坑（尤其是 EuRoC 403 / SSL 问题）、Xvfb 显示问题、--rm 的坑、结果如何正确导出、以及最终形成一套“可复现固定流程”。

下面这篇你可以直接发博客 / 知乎 / Notion / GitHub README，我已经帮你组织成「工程复盘型博客」结构，而不是零散笔记。

十、EuRoC 数据集：下载失败的完整踩坑记录

1️⃣ ORB-SLAM3 官方文档提到的第一个数据集

ORB-SLAM3 README 中提到：

“We provide examples to run ORB-SLAM3 in the EuRoC dataset”

官方给出的链接是：

http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/

2️⃣ 实际下载时遇到的问题

尝试下载：

wget http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/machine_hall/MH_01_easy/MH_01_easy.zip

发生的情况：

  • 301 重定向
  • 跳转到 wiki.asl.ethz.ch
  • 最终 404 / 403

3️⃣ HTTPS + SSL 证书问题（核心）

继续尝试：

wget https://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/...

结果：

ERROR: no certificate subject alternative name matches requested host name

curl 同样失败：

curl: (60) SSL: no alternative certificate subject name matches target host name

即使尝试：

  • --user-agent
  • --no-check-certificate
  • curl -L -O

👉 服务器 SSL 证书配置已不兼容现代 wget / curl

4️⃣ 访问文档页面 ≠ 下载数据

wget https://projects.asl.ethz.ch/datasets/doku.php?id=kmavvisualinertialdatasets

这个只会下载一个 HTML 页面：

Length: 3907 [text/html]

并不是数据集本身。

# docker # 容器 # 运维
Logo
魔乐社区

魔乐社区（Modelers.cn) 是一个中立、公益的人工智能社区，提供人工智能工具、模型、数据的托管、展示与应用协同服务，为人工智能开发及爱好者搭建开放的学习交流平台。社区通过理事会方式运作，由全产业链共同建设、共同运营、共同享有，推动国产AI生态繁荣发展。

更多推荐

cover

全家桶集齐！Qwen3.5四款小模型上线魔乐社区，附昇腾全套实践教程

avatar 魔乐社区

Pont - 搭建前后端之桥：高效、灵活的接口管理工具

Pont 是一款强大的数据服务层解决方案，它能够帮助开发者快速搭建前后端之间的桥梁，实现接口的高效管理和代码自动生成。无论是新手还是有经验的开发者，都能通过 Pont 轻松处理接口文档、生成类型安全的 API 代码，从而显著提升开发效率。[![Pont 工具标志](https://raw.gitcode.com/gh_mirrors/po/pont/raw/3f1b7d4bbba3fd2dda

avatar 魔乐社区

如何快速上手 hvac：HashiCorp Vault Python 客户端零基础入门指南

**hvac** 是 HashiCorp Vault 的 Python 3.X 客户端库，专为开发者提供简单高效的 Vault 交互方式。无论你是需要管理密钥、配置身份验证，还是实现安全的秘密数据存储，hvac 都能帮助你轻松搞定 Vault 的各项操作。本文将带你零基础快速入门，从安装到基础操作，让你在几分钟内即可上手使用这个强大的工具。[![hvac 客户端 Logo](https://r

avatar 魔乐社区