Ubuntu 22.04 + ROS2 Humble 上部署 ScaRF‑SLAM指南

基于经典视觉 SLAM 和几何基础模型的稠密三维重建框架

作者：Yuhao Zhang, Yifu Tao, Frank Dellaert, Maurice Fallon

论文：arXiv:2606.00307 | 项目主页：ScaRF-SLAM

---

📌 软硬件要求

操作系统

• Ubuntu 22.04 LTS (Jammy)
• ROS2 Humble (如果仅使用离线重建，可不需要完整 ROS2，只需 Python 包 rosbags)

硬件建议

组件	最低要求	推荐配置（流畅运行）
CPU	8 核 @ 2.5 GHz	12 核 @ 3.0 GHz+
内存	16 GB	32 GB
GPU	NVIDIA GPU，8 GB 显存	16 GB 显存（RTX 3090/4080+）
硬盘	50 GB 可用空间（含数据集）	SSD，100 GB+

⚠️ 显存警告 ：Depth Anything 3 默认配置需要 10~16 GB 显存。实测 RTX 4060 Laptop 8GB 极易 OOM（显存溢出）。解决方法：

• 降低输入图像分辨率（例如 [480, 320]）
• 减小深度推理的 batch size
• 使用云端 GPU（如 A10, A100）

软件环境

• Conda (Miniconda 或 Anaconda)
• Python 3.11
• CUDA 11.8 / 12.1 / 12.2（需与 PyTorch 版本匹配）
• 可选：完整的 ROS2 Humble 桌面版（用于在线 SLAM 和多会话建图）

---

🚀 一、环境搭建（Conda + 基础依赖）

1.1 创建 Conda 环境

conda create -n scarf-slam python=3.11
conda activate scarf-slam

1.2 安装 PyTorch 与 xformers

由于 pip install xformers torch>=2 torchvision 经常因依赖解析或网络问题卡死，我们推荐使用 conda + mamba 或 pip + 国内镜像。

方案 A：使用 mamba（最快）

conda activate base
conda install mamba -c conda-forge -y
conda activate scarf-slam
mamba install pytorch torchvision xformers -c pytorch -c nvidia -y

方案 B：使用 pip + 清华/阿里云镜像（备用）

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install xformers -i https://pypi.tuna.tsinghua.edu.cn/simple

如果你的 CUDA 版本是 12.2，上述 cu121 可以正常工作。

验证安装：

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

应输出类似 2.5.1+cu121 True。

---

📦 二、安装 Depth Anything 3

cd ~/git
git clone git@github.com:ByteDance-Seed/Depth-Anything-3.git
cd Depth-Anything-3
pip install -e .

（可选）启用天空掩膜

编辑 da3.py，找到 NestedDepthAnything3Net 类的 forward 函数，在 return 前添加：

output.sky = metric_output.sky

---

🔧 三、安装其他 Python 依赖

pip install rosbags open3d gtsam vismatch

若 gtsam 安装失败（常见缺少 C++ 编译环境），可用 conda 安装：

conda install -c conda-forge gtsam

---

🧩 四、（可选）安装 OV‑SLAM（用于在线重建）

OV‑SLAM = OpenVINS + ov_secondary（位姿图优化）

sudo apt update
sudo apt install libeigen3-dev libboost-all-dev libceres-dev

cd ~/ros2_ws/src
git clone git@github.com:rpng/open_vins.git
git clone git@github.com:ori-drs/ov_secondary_scarf.git
cd ~/ros2_ws
colcon build --symlink-install

每次使用前 source 工作空间：

source ~/ros2_ws/install/setup.bash

---

📷 五、下载数据集

从 Google Drive 链接 下载五个序列（例如 R01～R05）。建议解压后放在 /data/scarf_dataset/ 下，目录结构：

r01/
├── r01_bag/
│   ├── metadata.yaml
│   └── r01_bag_0.mcap
└── r01_gt/
    ├── cloud_gt.pcd
    ├── cloud_gt_fov/
    ├── poses_gt.csv
    └── poses_gt.txt

---

🗺️ 六、离线重建（固定轨迹）

这种模式不需要 SLAM 前端，直接使用已有的轨迹文件（例如数据集提供的 GT 轨迹）。

6.1 使用 ROS2 bag + 轨迹话题

配置 config/scarf_slam/ori_insta_offline.yaml，确认：

use_slam: false
slam_image_topic: /insta/cam0/image_raw/compressed
slam_final_trajectory_topic: /insta/poses_gt

运行：

cd ~/git/ScaRF-SLAM
python3 run_mapping.py \
  --slam_folder ./output_offline \
  --input_bag /data/scarf_dataset/r01/r01_bag/r01_bag_0.mcap \
  --config config/scarf_slam/ori_insta_offline.yaml

6.2 使用图像文件夹 + 轨迹文件

准备图像文件（命名格式 image_<sec>_<nsec>.jpg）和轨迹文件（CSV 或 TUM）。运行：

python3 run_mapping.py \
  --slam_folder ./output_offline \
  --image_folder /path/to/images \
  --poses /path/to/trajectory.txt \
  --config config/scarf_slam/ori_insta_offline.yaml

如果图像已经是去畸变的针孔图像，请在配置中填写 pinhole_intrinsics 和 pinhole_resolution，并删除 fisheye_cam* 段。

---

🚙 七、在线重建（使用 OV‑SLAM）

7.1 录制 SLAM bag

终端1 启动 OV‑SLAM（自动记录 bag）：

cd ~/git/ScaRF-SLAM
ros2 launch launch/run_ov_slam.launch.py output_path:=./output_online

终端2 播放数据集的原始 bag（慢速）：

ros2 bag play /data/scarf_dataset/r05/r05_bag/r05_bag_0.mcap --clock --rate 0.25

等待播放结束，SLAM bag 将自动保存到 ./output_online/ov_slam/ov_slam_bag。

7.2 运行在线建图

使用 ori_insta_slam.yaml 配置，指定 SLAM bag：

python3 run_mapping.py \
  --slam_folder ./output_online \
  --input_bag ./output_online/ov_slam/ov_slam_bag \
  --config config/scarf_slam/ori_insta_slam.yaml

7.3 可视化（RViz2）

在配置文件中开启 ROS2 发布：

publish_ros2_pointcloud: true
publish_ros2_trajectory: true

然后运行：

rviz2 -d launch/scarf_slam.rviz

由于点云消息较大，默认会降采样到 0.05 m 才发布，避免网络拥堵。

查看最终重建点云：

python3 scripts/vis_utils/visualize_pcd.py \
  --pcd ./output_online/recon/ov_slam/pts_global.pcd \
  --downsample 0.25

---

🔀 八、多会话建图

适用场景：多个行驶轨迹需要融合成一个全局一致的地图。

8.1 第一会话（例如 R01）

# SLAM
ros2 launch launch/run_ov_slam.launch.py output_path:=./R01
ros2 bag play /data/r01_bag_0.mcap --clock --rate 0.5

# 建图
python3 run_mapping.py --slam_folder ./R01 --input_bag ./R01/ov_slam/ov_slam_bag \
    --config config/scarf_slam/ori_insta_slam.yaml

8.2 第二会话（例如 R02）------加载前一会话的位姿图和优化图

# SLAM 加载前一图
ros2 launch launch/run_ov_slam.launch.py output_path:=./R02 \
    pose_graph_load_path:=./R01/ov_slam/pose_graph
ros2 bag play /data/r02_bag_0.mcap --clock --rate 0.5

# 建图加载前一优化图
python3 run_mapping.py --slam_folder ./R02 \
    --input_bag ./R02/ov_slam/ov_slam_bag \
    --prev_slam_folder ./R01/recon/ov_slam/opt_graph_xxxx \
    --config config/scarf_slam/ori_insta_slam.yaml

注意：多会话要求前一会话的时间戳全部早于新会话。

---

⚙️ 九、配置参数详解

主要配置文件位于 config/scarf_slam/：

参数	说明
use_slam	false：离线重建；true：在线重建
slam_odometry_topic	在线重建必需，里程计话题（如 /ov_slam/odometry）
slam_trajectory_topic	在线重建必需，轨迹快照话题
slam_final_trajectory_topic	离线重建必需，最终轨迹话题
is_mono	单目模式（非度量轨迹）。系统会自动缩放轨迹尺度
kf_distance	关键帧平移阈值（米）
kf_angle_deg	关键帧旋转阈值（度）
max_distance	深度点云最大范围（0 表示动态计算）
pinhole_intrinsics	针孔相机内参 [fx, fy, cx, cy]
pinhole_resolution	[width, height]
fisheye_cam0	鱼眼相机标定参数（如果输入是畸变图）

输出文件说明 （--slam_folder 目录下）：

• poses_<model_name>.csv -- 关键帧位姿（世界到相机）
• recon/<trajectory>/pts_global_*.pcd -- 全局点云
• recon/<trajectory>/pts_local_*/ -- 逐帧点云（用于分块评估）
• recon/<trajectory>/opt_graph_*/ -- 优化图存档（用于多会话）

---

📊 十、评估重建质量

需要下载数据集的 GT 文件夹（包含 cloud_gt.pcd 和 cloud_gt_fov/）。

10.1 全局评估

精度 & 重建误差（使用稠密 GT 地图）：

python3 scripts/eval_utils/compare_pts.py \
  --gt /data/r01_gt/cloud_gt.pcd \
  --gt-traj /data/r01_gt/poses_gt.txt \
  --recon ./output_offline/recon/ov_slam/pts_global.pcd \
  --recon-traj ./output_offline/poses_ov_slam.txt \
  --voxel-size 0.02 --threshold 0.03 \
  --precision --icp --vis-all

召回率（使用视场点云）：

python3 scripts/eval_utils/compare_pts.py \
  --gt /data/r01_gt/cloud_gt_fov \
  --gt-traj /data/r01_gt/poses_gt.txt \
  --recon ./output_offline/recon/ov_slam/pts_global.pcd \
  --recon-traj ./output_offline/poses_ov_slam.txt \
  --voxel-size 0.02 --threshold 0.03 \
  --chamfer-threshold 0.1 \
  --recall --icp

10.2 分块评估（避免全局对齐误差）

将点云按 10 米分块，分别计算精度/召回：

python3 scripts/eval_utils/compare_pts.py \
  --gt /data/r01_gt/cloud_gt_fov \
  --gt-traj /data/r01_gt/poses_gt.txt \
  --recon ./output_offline/recon/ov_slam/pts_local_xxx \
  --recon-traj ./output_offline/poses_ov_slam.txt \
  --chunk-m 10.0 \
  --recall --icp

---

🧪 常见问题与排错

Q1: pip install xformers torch 一直卡在 "Solving environment"

• 解决：改用 mamba 或 pip+国内镜像（见第一节）。

Q2: 运行 run_mapping.py 报错 ModuleNotFoundError: No module named 'rosbags'

• 解决 ：pip install rosbags

Q3: OV‑SLAM 编译失败，找不到 libceres

• 解决 ：sudo apt install libceres-dev

Q4: 运行中显存不足 (CUDA out of memory)

• 解决 ：在配置文件中将 pinhole_resolution 改为 [480, 320]，或改为 CPU 推理（设置环境变量 CUDA_VISIBLE_DEVICES=""，但极慢）。

Q5: 重建点云出现大量"漂浮物"或尺度不对

• 检查 ：单目模式 is_mono: true 时，确保轨迹具有适当尺度（不极小）；多鱼眼相机请正确填写 fisheye_cam* 标定。

Q6: 如何在不安装 ROS2 的情况下使用离线重建？

• 答 ：rosbags 是纯 Python 库，不需要 ROS2。只需用 --input_bag 指定 bag 路径即可。

---

📄 许可与引用

本项目采用 GNU GPL v3.0 许可证。商业用途请联系作者。

如果 ScaRF‑SLAM 对您的研究有帮助，请引用：

@article{zhang2026scarfslam,
  title={ScaRF-SLAM: Scale-Consistent Reconstruction with Feed-Forward Models and Classical Visual SLAM},
  author={Zhang, Yuhao and Tao, Yifu and Dellaert, Frank and Fallon, Maurice},
  journal={arXiv preprint arXiv:2606.00307},
  year={2026}
}

---