sim2lerobot 文档

主题

数据检查与可视化 ​

本指南介绍如何使用仓库提供的工具检查和可视化 L2 生成的 HDF5 数据。

快速开始 ​

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

# 2. 查看数值统计
uv run h5_inspect data/lift_cube/scripted/{run_id}/episodes.hdf5 --stats

# 3. 可视化单条 episode
uv run visualize_episode data/lift_cube/scripted/{run_id}/episodes.hdf5 --episode demo_0

工具 1: tools/h5_inspect.py — HDF5 Schema 检查 ​

基础模式（默认） ​

打印 HDF5 文件的结构信息：

bash
uv run h5_inspect data/lift_cube/scripted/{run_id}/episodes.hdf5

输出：

  • 顶层 attrs（format_version、env_args）
  • 每个 episode 的 num_samples、success、seed
  • 第一个 episode 的完整 dataset 树（shape + dtype）

统计模式（--stats） ​

计算所有 episode 的数值统计：

bash
uv run h5_inspect data/lift_cube/scripted/{run_id}/episodes.hdf5 --stats

输出：

  • Episode 长度分布：总数、成功率、min/max/mean/std
  • Actions 统计：整体 min/max/mean/std + 按维度分解（xyz / quat / gripper）
  • Observations 统计：每个 obs term 的 min/max/mean/std
  • NaN 检查：如果数据中有 NaN，会显示警告

用途：

  • 快速 sanity check：action 范围是否合理？有没有 NaN？
  • 对比三来源（scripted / rl / teleop）的数据分布
  • 检测异常 episode（长度过长/过短、数值爆炸）

查看特定 episode ​

bash
uv run h5_inspect data/lift_cube/scripted/{run_id}/episodes.hdf5 --episode demo_5

打印 demo_5 的完整 dataset 树。

工具 2: l2/scripts/visualize_episode.py — 轨迹可视化 ​

生成单条 episode 的 4 子图可视化：

bash
uv run visualize_episode data/lift_cube/scripted/{run_id}/episodes.hdf5 --episode demo_0

输出 episode_demo_0.png，包含：

  1. 3D 轨迹图：

    • EE trajectory（蓝色线）
    • Cube trajectory（橙色线）
    • Target position（紫色星）
    • 起点/终点标记

  2. EE Position (xyz) 时序：

    • x / y / z 随时间变化

  3. EE Orientation (quat) 时序：

    • qx / qy / qz / qw 随时间变化

  4. Gripper + Cube Z 时序：

    • Gripper state（+1=open, -1=close）
    • Cube Z 高度（叠加显示，看 lift 过程）

用途：

  • 直观看到 EE 和 cube 的运动轨迹
  • 检查 gripper 开合时机是否合理
  • 对比 scripted / rl / teleop 的轨迹差异
  • Debug：为什么某个 episode 失败了？

指定输出路径 ​

bash
uv run visualize_episode \
    data/lift_cube/scripted/{run_id}/episodes.hdf5 \
    --episode demo_0 \
    --output my_viz.png

典型工作流 ​

采集后立即检查 ​

bash
# 1. 采集数据
uv run sim2lerobot scripted collect --num_demos 10

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

# 3. 查看统计（确认数据范围正常）
uv run h5_inspect data/lift_cube/scripted/{run_id}/episodes.hdf5 --stats

# 4. 可视化几条 episode（spot check）
uv run visualize_episode data/lift_cube/scripted/{run_id}/episodes.hdf5 --episode demo_0
uv run visualize_episode data/lift_cube/scripted/{run_id}/episodes.hdf5 --episode demo_5

对比三来源数据 ​

bash
# 分别查看三来源的统计
uv run h5_inspect data/lift_cube/scripted/{run_id}/episodes.hdf5 --stats > /tmp/scripted_stats.txt
uv run h5_inspect data/lift_cube/rl/{run_id}/episodes.hdf5 --stats > /tmp/rl_stats.txt
uv run h5_inspect data/lift_cube/teleop/{run_id}/episodes.hdf5 --stats > /tmp/teleop_stats.txt

# 对比 action 范围、episode 长度分布
diff /tmp/scripted_stats.txt /tmp/rl_stats.txt

Debug 失败 episode ​

如果 --stats 显示成功率低于预期：

bash
# 1. 找出失败的 episode（手动看 h5_inspect 输出，或写脚本过滤 success=False）
uv run h5_inspect data/lift_cube/rl/{run_id}/episodes.hdf5 | grep "success=False"

# 2. 可视化失败 episode，看轨迹哪里出问题
uv run visualize_episode data/lift_cube/rl/{run_id}/episodes.hdf5 --episode demo_42

注意事项 ​

  • h5_inspect.py 不依赖 IsaacLab：可以在 L2 venv 或 L3 venv 跑，甚至在没有 GPU 的机器上跑。
  • visualize_episode.py 需要 matplotlib：L2 venv 已包含，但如果在其他环境跑需要手动装。
  • 大文件性能：--stats 模式会读取所有 episode 的数据到内存，如果 HDF5 文件很大（>1GB），可能需要几秒到几十秒。
  • 三来源 schema 必须对齐：如果 h5_inspect.py 显示 scripted / rl / teleop 的 actions shape 不一致（不都是 (T, 8)），说明 schema 漂移了，L3 转换会失败。

扩展 ​

如果需要更复杂的可视化（例如多 episode 对比、动画、3D 交互），可以：

  1. 用 h5py 直接读 HDF5，用 matplotlib / plotly / mayavi 自定义画图
  2. 参考 l2/scripts/visualize_episode.py 的代码结构，添加新的子图
  3. 用 tensorboard 的 SummaryWriter 把 episode 数据写成 tensorboard 格式，在浏览器里交互查看

相关文档 ​