EROAM 快速上手指南

本指南帮助首次接触EROAM的开发者在15分钟内完成本地部署与运行。EROAM是实时事件相机旋转里程计与建图系统，可在纯CPU环境下实现1000Hz位姿解算与高分辨率全景地图生成。

1. 前置条件

运行EROAM前需满足以下软硬件要求，全部配置完成预计耗时5分钟：

  • 操作系统：Ubuntu 20.04 LTS（对应ROS1 Noetic官方支持版本）
  • 基础工具：ROS1 Noetic、CMake 3.5+、g++ 9+
  • 依赖库：Eigen3、Sophus、Glog、OpenCV、PCL、libtbb-dev
  • 硬件要求：x86架构4核及以上CPU、至少20G空闲磁盘空间（存储数据集与编译产物） 无需额外API密钥或环境变量配置。

2. 安装步骤

下图展示完整安装流程：

flowchart TD A[Create Catkin Workspace] --> B[Clone dv-ros & eroam repos] B --> C[Install missing system dependencies] C --> D[Run catkin_make to build] D --> E[Source workspace setup.bash] E --> F[Modify launch file for dataset path] F --> G[Run roslaunch to start EROAM]

步骤1：创建独立Catkin工作空间

执行命令：

mkdir -p ~/eroam_ws/src
cd ~/eroam_ws/src

预期输出：无任何报错，终端路径切换至~/eroam_ws/src 常见错误修复：若提示mkdir: cannot create directory ‘/home/xxx/eroam_ws’: File exists，直接执行cd ~/eroam_ws/src进入现有目录，或重命名原有冲突目录。

步骤2：克隆源码与依赖仓库

执行命令：

git clone https://gitlab.com/inivation/dv/dv-ros.git
git clone https://github.com/wlxing1901/eroam.git

预期输出：两个仓库克隆完成，终端显示Receiving objects: 100%，无连接错误 常见错误修复：若克隆超时或失败，配置Git代理，或使用国内镜像源加速克隆。

步骤3：编译项目

执行命令：

cd ~/eroam_ws
catkin_make -DCMAKE_BUILD_TYPE=Release

预期输出：编译进度到100%，最后显示Built target eroam.eroam_run与Built target eroam.rosbag_repack，无报错 常见错误修复：若提示找不到依赖库，执行以下命令安装系统级依赖：

sudo apt update && sudo apt install -y ros-noetic-dv-ros libeigen3-dev libsophus-dev libgoogle-glog-dev libpcl-dev libopencv-dev libtbb-dev

步骤4：配置工作区环境

执行命令：

source ~/eroam_ws/devel/setup.bash
# 可选：将该命令加入~/.bashrc，避免每次打开终端重复执行
echo "source ~/eroam_ws/devel/setup.bash" >> ~/.bashrc

预期输出：无任何报错 常见错误修复：若提示No such file or directory，回到第三步排查编译错误，确保编译成功生成setup.bash文件。

3. 首次运行

下图展示首次运行时各组件交互逻辑：

sequenceDiagram participant U as User participant CLI as ROS CLI participant B as EROAM Backend U->>CLI: Run roslaunch eroam eroam_run_campus.launch CLI->>CLI: Start roscore, rosbag play, RViz CLI->>B: Send event data stream from rosbag B->>B: Run tracking + mapping pipeline B->>CLI: Publish pose, point cloud data CLI->>U: Render real-time visualization in RViz U->>CLI: Press Ctrl+C to terminate CLI->>B: Send termination signal B->>B: Generate performance metrics, save panorama + pose B->>U: Print metrics to terminal, output files saved

步骤1：下载测试数据集

从EROAM数据集下载页下载campus_seq1.bag，保存至~/datasets/eroam目录下。 预期输出：文件大小约8G，完整性校验通过 常见错误修复：若下载中断，使用支持断点续传的下载工具（如wget、IDM）重新下载。

步骤2：修改启动文件配置

执行命令打开launch文件：

nano ~/eroam_ws/src/eroam/launch/eroam_run_campus.launch

找到以下行：

<node name="rosbag_play" pkg="rosbag" type="play" args="-d 3.0 path_to_your_data"/>

将path_to_your_data替换为数据集的绝对路径，例如/home/xxx/datasets/eroam/campus_seq1.bag，按Ctrl+O保存，Ctrl+X退出。 预期输出：launch文件修改后路径无拼写错误 常见错误修复：若使用相对路径或~导致找不到bag文件，统一使用绝对路径填写。

步骤3：启动EROAM

执行命令：

roslaunch eroam eroam_run_campus.launch

预期输出：

  1. 终端首先启动roscore，3秒后rosbag开始播放
  2. RViz窗口自动弹出，Fixed Frame设为world，可看到实时球面事件点云与位姿更新
  3. rosbag播放完成后，终端打印性能统计日志，格式如下：
I20250609 17:31:00.751452  8102 eroam.hpp:371] EROAM: done.
I20250609 17:31:00.751473  8102 timer.cc:12] >>> ===== Printing run time =====
I20250609 17:31:00.751477  8102 timer.cc:14] > [ EROAM: ev_sphere_frame warp ] average time usage: 0.060079 ms , called times: 36274
I20250609 17:31:00.751510  8102 timer.cc:14] > [ EROAM: event spherical icp ] average time usage: 0.585088 ms , called times: 36267
...
I20250609 17:31:00.751672  8102 timer.cc:19] >>> ===== Printing run time end =====
  1. ~/eroam_ws/src/eroam/output目录下生成全景图panoramic.png与位姿轨迹文件pose.txt 常见错误修复：若RViz无数据显示，检查RViz中事件话题订阅是否正常，Fixed Frame是否设置为world。

步骤4：终止运行

按Ctrl+C即可终止所有进程，输出文件会自动保存。

4. 核心配置项

配置项名称 必填？ 默认值 描述
rosbag_path 是 无 测试用rosbag文件的绝对路径
enable_rviz 否 true 是否启动RViz可视化窗口
output_dir 否 ~/eroam_ws/src/eroam/output 全景图、位姿文件的保存目录
event_topic 否 /dv/events 事件相机数据的ROS话题名
max_map_density 否 1000 单球面区域的最大点密度，超过会触发RDM清理

5. 常见错误

  1. 克隆EROAM仓库时提示Permission denied：修复：将SSH克隆地址替换为HTTPS地址git clone https://github.com/wlxing1901/eroam.git，或配置GitHub SSH密钥。
  2. catkin_make编译时提示找不到dv_ros_msgs：修复：确保dv-ros仓库已克隆到eroam_ws/src目录，或执行sudo apt install ros-noetic-dv-ros安装系统级dv-ros包。
  3. 运行roslaunch时提示[eroam_run_campus.launch] is not a launch file in package [eroam]：修复：执行source ~/eroam_ws/devel/setup.bash刷新ROS包路径。
  4. 运行结束后未生成全景图与位姿文件：修复：检查output目录写入权限，手动创建目录：mkdir -p ~/eroam_ws/src/eroam/output。

6. 下一步