sim2lerobot 文档

主题

实现状态 ​

维护约定：每次新增 / 调整 / 砍掉某个能力，都要同步本文档。这是新人入口的"真相"——文档与代码不一致比没有文档还误导。

图例：✅ 已完成、🚧 进行中、📋 计划、⏭️ 不在范围。

L2 数据生成层 ​

子目录状态要点
多任务支持架构✅基于任务注册表的可扩展架构，当前支持 lift_cube 和 stack_cube 两个任务，详见 src/sim2lerobot/tasks/
src/sim2lerobot/sources/scripted/✅Pick-and-Lift SM (lift_cube) / Pick-and-Stack SM (stack_cube)，8d IK-abs action，产 data/{task}/scripted/{run_id}/episodes.hdf5
src/sim2lerobot/sources/rl/✅rsl_rl PPO (joint_pos task) + rollout 录制重写成 8d IK-abs，产 data/{task}/rl/{run_id}/episodes.hdf5。详见 RL 数据采集
src/sim2lerobot/sources/teleop/✅keyboard 最小版，30Hz，8d IK-abs (rel→abs 在 adapter 里做)，产 data/{task}/teleop/{run_id}/episodes.hdf5
run 隔离输出布局✅四个命令统一落 data/{task}/{source}/{run_id}/（run_id 默认时间戳，--run_id/--output_dir 可覆盖），含统一文件名 episodes.hdf5 + videos/ + run.log + meta.json，重复执行不再互相覆盖
视频录制 (--video)✅三来源统一支持 --video 参数，录制 mp4 到 data/{task}/{source}/{run_id}/videos/，用于质量检查和演示展示
相机 obs (obs/images/*)📋scripted/rl/teleop 三来源都没出 RGB；VLA 训练必需。src/sim2lerobot/sources/scripted/env_cfg.py 已留 --with_camera 扩展点注释
SpaceMouse / VR / OpenXR teleop⏭️接口跟 keyboard 同形 (7d delta)，需硬件验证，留给生产仓库

L3 数据处理层 ​

组件状态要点
l3/convert.py✅HDF5 → LeRobot v2.1，GR00T N1.7 兼容（全局 stats.json + 6 字段）
三来源合并端到端 e2e🚧单来源已分别 verify，把 scripted_*.hdf5 + rl_*.hdf5 + teleop_*.hdf5 一次性合到同一个 dataset 还没正式跑过
质量过滤（噪声 / 抖动 episode 剔除）📋CLAUDE.md 列入硬性要求，目前 convert.py 只格式转换
统计 / 可视化工具✅tools/h5_inspect.py --stats + l2/scripts/visualize_episode.py 已实现
Cosmos 视觉增强接口文档📋CLAUDE.md 说"即使不实现也要在 doc 中说明接口和数据流向"

跨层 / 文档 ​

项状态要点
统一 CLI 入口 sim2lerobot✅采集/训练聚合为 sim2lerobot <source> <verb> --task <task_name>（scripted collect / teleop record / rl train|rollout|plot），dispatcher 在 cli/main.py，公共脚手架在 sources/_common.py。工具类入口（visualize_episode 等）保持独立
任务注册表✅src/sim2lerobot/tasks/registry.py 管理所有任务配置，支持动态添加新任务
tools/h5_inspect.py✅跨来源用，看 HDF5 schema 是否对齐。--stats 模式显示 obs/action 数值统计 + episode 长度分布
l2/scripts/visualize_episode.py✅可视化单条 episode：3D EE/cube 轨迹 + action 时序图
l2/scripts/verify_isaac.py✅L2 venv 烟雾测试
docs/ 体系✅guide / schema / research 三目录全部就位
仓库根 README 重构✅聚焦"这是什么 + 为什么 + 快速开始"，实现状态挪到本文档
快速理解文档✅docs/guide/quick-understanding.md（5 分钟入门）

详细说明 ​

L2 数据生成层 ​

✅ src/sim2lerobot/sources/scripted/ — 手写状态机 ​

核心功能：

  • Warp kernel 实现的 5-状态 FSM（REST → APPROACH_ABOVE → APPROACH → GRASP → LIFT）
  • GPU 并行 rollout（默认 4 envs）
  • 8d IK-abs action（xyz + quat_xyzw + gripper）
  • 自动过滤失败 episode（EXPORT_SUCCEEDED_ONLY）

产物：

  • data/lift_cube/scripted/{run_id}/episodes.hdf5（IsaacLab 官方 HDF5 schema）
  • data/lift_cube/scripted/{run_id}/videos/（可选，--video 参数启用）
  • data/lift_cube/scripted/{run_id}/{run.log,meta.json}（运行日志 + 元信息）

扩展点：

  • 换成 cuRobo motion planner
  • 通过 mimic 扩增数据
  • 加相机观测（env_cfg.py 已留 TODO）

域随机化 ✅：

  • 物体初始位置随机化（x, y 范围）
  • 物体质量随机化（±50%）
  • 物体摩擦系数随机化（0.4 ~ 1.2）
  • 机器人初始关节位置随机化（±5°）
  • 目标位置随机化（扩大范围）
  • 支持可调强度 --dr_scale（0.0 ~ 2.0+）
  • 批量生成脚本（Bash + Python）
  • 渐进式 curriculum 支持
  • 详见 域随机化文档

✅ src/sim2lerobot/sources/rl/ — PPO 训练 + rollout 录制 ​

核心功能：

  • rsl_rl PPO 训练（joint_pos task，默认 1024 envs × 600 iters）
  • rollout 时录制层重写 action（9d joint_pos → 8d IK-abs 等价）
  • 自定义 RecorderTerm（IKAbsActionRecorder + PolicySplitObsRecorder）
  • Tensorboard 监控（reward / episode_length / success_rate / loss）

产物：

  • data/lift_cube/rl/{run_id}/model_*.pt（PPO checkpoint，run_id 默认时间戳）
  • data/lift_cube/rl/latest.pt（symlink，指向最近一次 train run 的最终 checkpoint）
  • data/lift_cube/rl/{run_id}/episodes.hdf5（rollout 录制的 HDF5）
  • data/lift_cube/rl/{run_id}/videos/（可选，--video 参数启用）

关键设计：

  • 训练用 joint_pos（IsaacLab 只对 joint_pos 注册了 PPO cfg）
  • 写盘用 IK-abs（与 scripted/teleop 对齐 schema）
  • 详见 obs/action 对齐 "src/sim2lerobot/sources/rl 实现细节"

✅ src/sim2lerobot/sources/teleop/ — 人类遥操作 ​

核心功能：

  • keyboard 最小版（WASDQE/ZXTGCV 移动 + K 切夹爪）
  • 30Hz 控制频率
  • IK-rel → IK-abs 复合（在脚本侧做，保证写盘 schema 对齐）
  • 连续 N 步 success 判定（避免手抖触发 auto-reset）

产物：

  • data/lift_cube/teleop/{run_id}/episodes.hdf5
  • data/lift_cube/teleop/{run_id}/videos/（可选，--video 参数启用）

扩展点：

  • 接 SpaceMouse / VR（接口同形，需硬件验证）
  • 加多视角 RGB（VLA 训练必需）

✅ 视频录制功能 ​

核心功能：

  • 三来源统一支持 --video 参数
  • 基于 IsaacLab 内置 VideoRecorder + gymnasium RecordVideo wrapper
  • 录制 mp4 到 data/{task}/{source}/{run_id}/videos/
  • 支持 --video_interval N（每 N 个 episode 录一个，减少磁盘占用）

性能开销：

  • ~10-20% 运行时间
  • 每个 episode 约 1-5 MB 磁盘

用途：

  • 质量检查（看轨迹是否合理）
  • 演示展示（给别人看效果）

详见 视频录制技术细节。

📋 相机观测（RGB 图像） ​

当前状态：三来源都没出 RGB，只有 proprio + 物体姿态（特权信息）。

为什么需要：VLA 训练必需多视角 RGB。

扩展点：

  • src/sim2lerobot/sources/scripted/env_cfg.py:20-23 已留 --with_camera 扩展点注释
  • 需要同时加 scene.front_cam = CameraCfg(...) + observations.policy.front_cam = ObsTerm(...)
  • L3 转换时会自动把图像写到 videos/ 目录

工程量：~1 天（加相机 + 验证 L3 转换）

⏭️ SpaceMouse / VR / OpenXR teleop ​

当前状态：只实现了 keyboard 最小版。

为什么不在范围：

  • 需要硬件验证（SpaceMouse / VR 头显）
  • 接口跟 keyboard 同形（7d SE3 delta + gripper），后续接入工程量不大
  • 留给生产仓库（本仓库是教学型，keyboard 够演示概念）

L3 数据处理层 ​

✅ l3/convert.py — HDF5 → LeRobot v2 ​

核心功能：

  • 读取 IsaacLab HDF5（data/demo_{i}/ 布局）
  • 转换成 LeRobot v2.1 格式（parquet + meta/info.json + meta/stats.json）
  • GR00T N1.7 兼容（全局 stats.json + 6 字段：q01/q99）

产物：

  • data/lerobot/<dataset>/meta/info.json
  • data/lerobot/<dataset>/meta/stats.json
  • data/lerobot/<dataset>/data/chunk-000/*.parquet
  • data/lerobot/<dataset>/videos/（如果有相机观测）

关键约束：

  • GR00T 1.7 强依赖 v2.0 风格的全局 stats.json（带 q01/q99 6 字段）
  • 不写 episodes_stats.jsonl（纯 lerobot v2.1 用，但 GR00T 不读）
  • 详见 GR00T 1.7 Dataset 约束

🚧 三来源合并端到端 e2e ​

当前状态：单来源已分别 verify（scripted / rl / teleop 各自能转成 LeRobot v2），但把三个 HDF5 一次性合到同一个 dataset 还没正式跑过。

下一步：

  1. 修改 l3/convert.py 支持多输入 HDF5
  2. 在 episodes.jsonl 加 source 字段（scripted / rl / teleop）
  3. 验证 GR00T 1.7 能正确读取合并后的 dataset

工程量：~半天

📋 质量过滤（噪声 / 抖动 episode 剔除） ​

当前状态：convert.py 只做格式转换，不做质量过滤。

为什么需要：

  • RL rollout 可能产生抖动轨迹（action 变化率过大）
  • Teleop 可能有人为失误（手抖、误操作）
  • 过滤低质量 episode 能提升下游 BC 训练效果

扩展点：

  • 在 convert.py 加 --filter 参数
  • 过滤规则：action 变化率 > 阈值、episode 长度异常、success=False 但轨迹看起来成功（误判）

工程量：~1 天

✅ 统计 / 可视化工具 ​

已实现：

  • tools/h5_inspect.py --stats：数值统计（min/max/mean/std/NaN 检查）+ episode 长度分布
  • l2/scripts/visualize_episode.py：3D 轨迹图 + action 时序图

详见 数据检查与可视化。

📋 Cosmos 视觉增强接口文档 ​

当前状态：未实现，也未写文档。

为什么需要：CLAUDE.md 说"即使不实现也要在 doc 中说明接口和数据流向"。

扩展点：

  • 写一份 docs/guide/cosmos-integration.md
  • 说明 Cosmos 在哪个环节介入（L3 转换后？还是 L2 录制时？）
  • 数据流向（输入 / 输出格式）
  • 接口约定（API / CLI）

工程量：~半天（纯文档，不写代码）

更新日志 ​

2026-06-05 ​

  • ✅ 多任务支持架构
    • 新增任务配置基类 src/sim2lerobot/tasks/base.py
    • 新增任务注册表 src/sim2lerobot/tasks/registry.py
    • ✅ stack_cube scripted 采集修复完成
      • 状态机：8-状态 FSM（REST → ABOVE_C1 → APPROACH_C1 → GRASP_C1 → LIFT_C1 → ABOVE_C2 → LOWER_C2 → RELEASE_C2）
      • 根本修复：env_cfg.py 为 stack_cube IK action 补加 body_offset=[0,0,0.107]（与 lift_cube 对齐）；缺少此 offset 时 IK 控制点在 panda_hand 原点而非指尖，EE 始终卡在桌面
      • success 判定：cubes_stacked（atol/rtol=0.01 放宽容差）
    • 保留现有 lift_cube 任务（src/sim2lerobot/tasks/lift_cube/）
    • 所有来源（scripted/rl/teleop）通过 --task 参数选择任务

2026-06-04 ​

  • ✅ 统一 CLI 入口 sim2lerobot <source> <verb>
    • 5 个采集/训练脚本合并为单一入口（scripted collect / teleop record / rl train / rl rollout / rl plot）
    • 新增 dispatcher src/sim2lerobot/cli/main.py（两级 subparser，严格保证 AppLauncher 先于 isaaclab import）
    • 新增公共脚手架 src/sim2lerobot/sources/_common.py（去重 log / 输出路径 / 视频包装 / 结束日志 / 公共参数）
    • 各源脚本改为 register_args / pre_launch / run 形态，顶层不再 import isaaclab
    • 移除旧 [project.scripts] 入口（scripted_collect 等），全量更新 docs/scripts 命令名
    • 工具类入口（visualize_episode / verify_isaac / h5_inspect / convert_lerobot）保持独立不变
  • ✅ 域随机化功能（src/sim2lerobot/sources/scripted/env_cfg_with_dr.py）
    • 物体位置、质量、摩擦系数随机化
    • 机器人关节位置随机化
    • 目标位置范围扩大
    • 可调强度系数 --dr_scale
  • ✅ 批量生成脚本
    • Bash 版本：scripts/batch_generate_with_dr.sh
    • Python 版本：scripts/batch_generate_with_dr.py（支持 curriculum）
  • ✅ 域随机化文档：docs/guide/advanced/domain-randomization.md

2026-05-28 ​

  • ✅ 文档重组：删除 l2/{scripted,rl,teleop}/README.md，统一到 docs/guide/ 下
    • 新增 docs/guide/quick-start.md（三来源对比 + 快速命令）
    • 新增 docs/guide/scripted-collection.md（精简到 ~150 行）
    • 新增 docs/guide/rl-collection.md（精简到 ~200 行）
    • 新增 docs/guide/teleop-collection.md（精简到 ~180 行）
    • 原 README 从 400-500 行精简到 150-200 行，删除重复内容和详细代码导读
  • ✅ 新增 tools/h5_inspect.py --stats 模式（数值统计 + episode 长度分布）
  • ✅ 新增 l2/scripts/visualize_episode.py（3D 轨迹 + action 时序图）
  • ✅ 新增 docs/guide/quick-understanding.md（5 分钟快速理解）
  • ✅ 新增 docs/guide/data-inspection-and-visualization.md（数据检查与可视化完整指南）
  • ✅ 重构 README.md（聚焦"这是什么 + 为什么 + 快速开始"）
  • ✅ 新增本文档（实现状态独立维护）

2026-05-25 ​

  • ✅ 视频录制功能（三来源统一支持 --video 参数）
  • ✅ L2 三个数据源（scripted / rl / teleop）全部跑通
  • ✅ L3 转换器（HDF5 → LeRobot v2，GR00T 1.7 兼容）

相关文档 ​