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-nscarf-slampython=3.11conda activate scarf-slam

1.2 安装 PyTorch 与 xformers

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

方案 A：使用 mamba（最快）

conda activate base condainstallmamba-cconda-forge-yconda activate scarf-slam mambainstallpytorch torchvision xformers-cpytorch-cnvidia-y

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

pipinstalltorch torchvision --index-url https://download.pytorch.org/whl/cu121 pipinstallxformers-ihttps://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~/gitgitclone git@github.com:ByteDance-Seed/Depth-Anything-3.gitcdDepth-Anything-3 pipinstall-e.

（可选）启用天空掩膜

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

output.sky=metric_output.sky

🔧 三、安装其他 Python 依赖

pipinstallrosbags open3d gtsam vismatch

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

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

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

sudoaptupdatesudoaptinstalllibeigen3-dev libboost-all-dev libceres-devcd~/ros2_ws/srcgitclone git@github.com:rpng/open_vins.gitgitclone git@github.com:ori-drs/ov_secondary_scarf.gitcd~/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:falseslam_image_topic:/insta/cam0/image_raw/compressedslam_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\--configconfig/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\--configconfig/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--rate0.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\--configconfig/scarf_slam/ori_insta_slam.yaml

7.3 可视化（RViz2）

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

publish_ros2_pointcloud:truepublish_ros2_trajectory:true

然后运行：

rviz2-dlaunch/scarf_slam.rviz

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

查看最终重建点云：

python3 scripts/vis_utils/visualize_pcd.py\--pcd./output_online/recon/ov_slam/pts_global.pcd\--downsample0.25

🔀 八、多会话建图

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

8.1 第一会话（例如 R01）

# SLAMros2 launch launch/run_ov_slam.launch.py output_path:=./R01 ros2 bag play /data/r01_bag_0.mcap--clock--rate0.5# 建图python3 run_mapping.py--slam_folder./R01--input_bag./R01/ov_slam/ov_slam_bag\--configconfig/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--rate0.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\--configconfig/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-size0.02--threshold0.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-size0.02--threshold0.03\--chamfer-threshold0.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-m10.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} }