Dagger 使用说明

简介

Dagger 是一个用于机器人数据采集和控制的工具，支持：

• 四臂机械臂的主从控制和数据采集
• 模型推理模式和人工接管模式切换
• 同步和异步两种数据采集模式

快速开始

1. 基本启动命令

cd /home/agilex/work_space_hqr/dagger
python dagger.py --ckpt_dir /path/to/checkpoint

2. 常用参数

必需参数：

• --ckpt_dir: checkpoint 目录路径（用于数据保存路径组织）

常用可选参数：

• --task_id: 任务ID/权重名称（例如: policy_epoch_2000_seed_0），如果不指定则使用 ckpt_dir 的文件夹名
• --scene_dir: 场景名称（默认: fold_towels）
• --collection_mode: 数据采集模式，sync（默认）或 async
• --save_data_base_dir: 数据保存基础目录（默认: /home/agilex/Limx-Benchmark-RL/buffer）
• --debug: 开启调试日志

完整示例：

python dagger.py \
  --ckpt_dir /home/agilex/checkpoint/act/model_name \
  --task_id policy_epoch_2000_seed_0 \
  --scene_dir fold_towels \
  --collection_mode async \
  --debug

键盘操作

程序运行后，可以通过键盘快捷键控制：

按键	功能	说明
s	开始采集	启动数据采集，所有机械臂切换为从臂模式
h	人工接管	切换到人工控制模式，后臂作为主臂
i	模型推理	切换回模型推理模式，所有臂从模型接收指令
r	结束采集	停止采集，询问成功/失败，然后归位
q	退出程序	退出程序并归位

使用流程

标准数据采集流程

1. 启动程序

   python dagger.py --ckpt_dir /path/to/checkpoint

2. 开始采集 - 按 s 键

   • 所有机械臂切换为从臂模式
   • 开始接收模型指令并采集数据

3. 切换模式（可选）

   • 按 h 键：切换到人工接管模式（后臂作为主臂）
   • 按 i 键：切换回模型推理模式

4. 结束采集 - 按 r 键

   • 停止数据采集
   • 输入 1（成功）或 0（失败）
   • 如果成功，输入分数（0-5）
   • 机械臂自动归位

5. 退出程序 - 按 q 键

   • 退出程序
   • 机械臂自动归位

数据采集模式

同步模式（sync，默认）

• 特点：先同步所有传感器数据，再保存
• 优点：数据时间戳完全对齐
• 缺点：如果某个传感器数据缺失，整帧数据可能丢失
• 适用场景：需要严格时间对齐的数据

python dagger.py --ckpt_dir /path/to/checkpoint --collection_mode sync

异步模式（async）

• 特点：每个传感器独立保存，先在线采集，再离线同步
• 优点：不会因为单个传感器缺失而丢失整帧数据
• 缺点：时间戳可能不完全对齐（需要后续同步）
• 适用场景：传感器采集频率不一致或可能缺失数据

python dagger.py --ckpt_dir /path/to/checkpoint --collection_mode async

数据保存路径

数据保存路径结构：

{save_data_base_dir}/{scene_dir}/{YYYYMMDD}/{checkpoint_folder_name}/{task_id}/
  └── episode_XXX/
      ├── sensor_index.json  # 传感器索引文件
      ├── images/            # 图像数据
      │   ├── cam_high_high/
      │   ├── cam_left_wrist/
      │   └── cam_right_wrist/
      └── actions/           # 动作数据
          ├── action_raw_left_*.npy
          ├── action_raw_right_*.npy
          ├── puppet_arm_left_*.npy
          └── puppet_arm_right_*.npy

示例路径：

/home/agilex/Limx-Benchmark-RL/buffer/fold_towels/20251222/RealRobot_AgileX_xxx/policy_epoch_2000_seed_0/episode_000/

常见问题

Q1: 如何查看数据是否正在保存？

使用 --debug 参数启动，会打印详细的保存信息：

python dagger.py --ckpt_dir /path/to/checkpoint --debug

Q2: 数据保存在哪里？

默认保存在 /home/agilex/Limx-Benchmark-RL/buffer/，可以通过 --save_data_base_dir 参数修改。

Q3: 如何区分成功和失败的 episode？

在按 r 键结束采集时，程序会询问：

• 输入 1 表示成功
• 输入 0 表示失败
• 如果成功，还会询问分数（0-5）

Q4: 同步模式和异步模式有什么区别？

• 同步模式：所有传感器数据必须同时到达才保存，时间戳完全对齐
• 异步模式：每个传感器独立保存，时间戳可能不完全对齐，需要后续使用 sync_timestamps.py 工具同步

Q5: 如何查看已保存的数据？

数据保存在 episode 目录下，每个 episode 包含：

• sensor_index.json: 所有传感器数据的时间戳索引
• images/: 图像文件
• actions/: 动作数据文件

可以使用 tools/visualize_actions_new.py 工具可视化数据。

相关工具

Dagger 提供了多个工具脚本，位于 tools/ 目录：

• visualize_actions_new.py: 可视化动作数据
• sync_timestamps.py: 同步异步模式下的时间戳（待测试！！！）
• convert_data_format.py: 转换数据格式（废弃）

注意事项

1. 启动前确保 ROS 环境正常：确保所有必要的 ROS topic 都在发布
2. 检查机械臂状态：确保机械臂已正确初始化
3. 数据保存空间：确保有足够的磁盘空间保存数据
4. 时间戳同步：如果使用异步模式，建议采集后使用 sync_timestamps.py 同步时间戳