sim2lerobot 文档

主题

Scripted 数据采集 ​

L2 数据生成层最容易上手的一支：用确定性的状态机在 IsaacLab 仿真环境里 GPU 并行 rollout，把成功轨迹写到 HDF5。

数据金字塔角色：量级最大（10⁵+ 条/天），覆盖底座技能。

核心原理 ​

状态机（5 个状态）
  ↓
REST → APPROACH_ABOVE → APPROACH → GRASP → LIFT
  ↓
输出 8d IK-abs action [x, y, z, qx, qy, qz, qw, gripper]
  ↓
IsaacLab env.step() + RecorderManager
  ↓
data/lift_cube/scripted/{run_id}/episodes.hdf5

关键特点：

  • 确定性：同样输入 → 同样输出
  • GPU 并行：Warp kernel，1024 envs 同时跑
  • 自动过滤：只保留 success=True 的 episode（EXPORT_SUCCEEDED_ONLY）

使用方法 ​

bash
# 基础采集
uv run sim2lerobot scripted collect --num_demos 10 --num_envs 4

# 录制视频（每 5 个 episode 录一个）
uv run sim2lerobot scripted collect --num_demos 50 --num_envs 4 --video --video_interval 5

# 检查 schema
uv run h5_inspect data/lift_cube/scripted/{run_id}/episodes.hdf5

状态机逻辑 ​

状态目标转移条件
REST等待 0.2s时间到
APPROACH_ABOVEcube 上方 10cm距离 < 1cm + 停留 0.5s
APPROACHcube 位置距离 < 1cm + 停留 0.6s
GRASP闭合夹爪（gripper=-1）等待 0.3s
LIFT目标位姿到达后停留（等 TerminationManager 判定 success）

Warp kernel 并行：所有 env 的状态机在 GPU 上同时推进，比 CPU for 循环快 10-100 倍。

关键设计 ​

1. IK-abs action 空间 ​

状态机输出 8d action：

  • 位置：3d (x, y, z)
  • 朝向：4d quat (qx, qy, qz, qw)，固定为 panda down-grasp (0, 1, 0, 0)
  • 夹爪：1d gripper ∈

2. Success 自动判定 ​

env_cfg.py 加了 terminations.success = DoneTerm(object_reached_goal)：

  • RecorderManager 在 reset 时读 termination_manager["success"]
  • success=True → 写 HDF5
  • success=False → 丢弃 buffer（EXPORT_SUCCEEDED_ONLY）

3. HDF5 Schema ​

使用 IsaacLab 官方 RecorderManager + HDF5DatasetFileHandler：

/data/demo_{i}/
├── attrs: num_samples=T, success=1.0, seed=-
├── actions (T, 8)                    # IK-abs action
├── obs/joint_pos (T, 9)              # 7 panda joints + 2 fingers
├── obs/joint_vel (T, 9)
├── obs/object_position (T, 3)
├── obs/target_object_position (T, 7)
├── obs/actions (T, 8)                # last_action
├── initial_state (nested dict)
├── states (nested dict)
└── processed_actions (T, 8)

详见 HDF5 Schema。

代码结构 ​

文件作用
src/sim2lerobot/sources/scripted/collect.py主入口：构造 env、循环驱动 SM、统计成功数
src/sim2lerobot/sources/scripted/state_machine.pyPickAndLiftSm，Warp kernel 实现的 5-状态 FSM
src/sim2lerobot/sources/scripted/env_cfg.py在 Isaac-Lift-Cube-Franka-IK-Abs-v0 上加 success term + RecorderManager

关键函数：

  • collect.py:gather_sm_inputs() — 从 env 读 ee_pose / obj_pose / goal_pose
  • state_machine.py:infer_state_machine() — Warp kernel，GPU 并行推进 SM
  • env_cfg.py:make_env_cfg() — 构造 env 配置

常见问题 ​

Q: 为什么用 Warp kernel？ ​

A: GPU 并行推进所有 env 的状态机，比 CPU for 循环快 10-100 倍。4 个 env 时差异不大，但 1024 个 env 时差异显著。

Q: 为什么 obj_pose 的 quat 要硬塞 (0,1,0,0)？ ​

A: 这是 panda down-grasp 朝向（绕 Y 轴 180°）。SM 假设永远自上而下抓，不关心 cube 真实朝向。换非对称物体时需要改成真实 quat。

Q: RecorderManager 在哪个时机写 HDF5？ ​

A:

  • record_pre_step: 每步写 (obs, action) 到内存 buffer
  • record_pre_reset: episode 结束时，把 buffer 落盘到 HDF5（如果 success=True）

扩展方向 ​

  • 把 SM 换成 cuRobo motion planner
  • 通过 mimic（isaaclab_mimic）把单条 SM demo 扩增上百倍
  • 加域随机化（光照 / 摩擦 / 物体位置）
  • 加 camera 观测（env_cfg.py 里有 TODO）

参考 ​