实验流程

# 化学实验台清理数据集说明 ## 1. 数据集简介 本数据集用于训练双臂机器人在化学实验结束后执行实验台清理任务。 完整清理流程持续时间较长，并包含多个语义明确、前后衔接的操作阶段，因此没有把整条长任务保存成一个超长数据集，而是按照任务顺序拆分为多个 **section**。每个 section 都是一个可以独立加载、训练和评估的 LeRobot Dataset v3 数据集。 当前根目录名为 `chemical_experient`。这是现有目录名称；本文使用规范表述“chemical experiment”。 当前包含： | 顺序 | Section 目录 | 操作语义 | Episodes | Frames | FPS | 约合时长 | |---:|---|---|---:|---:|---:|---:| | 1 | `S1_turn_off_lamp` | 关闭实验台照明灯 | 50 | 21,615 | 30 | 12 分 00.5 秒 | | 2 | `S2_pick_up_tube` | 拿起实验管/试管 | 50 | 29,950 | 30 | 16 分 38.3 秒 | | 合计 | 2 个 sections | 当前已采集部分 | 100 | 51,565 | 30 | 28 分 38.8 秒 | 以上统计来自 2026-08-18 各 section 的 `meta/info.json`。后续增加或续采 section 后，应同步更新此表。 ## 2. 长任务与 Section 的关系 `S1`、`S2` 等前缀表示各阶段在完整清理流程中的执行顺序： ```text 化学实验结束 → S1_turn_off_lamp → S2_pick_up_tube → S3_... → ... → 实验台清理完成 ``` 一个 section 不是完整长任务，而是长任务中的一个可复现操作阶段。每个 section 内的一个 episode 表示该阶段的一次双臂示范轨迹。 建议遵守以下约定： - `S<number>_<action>` 中的编号表示全任务顺序； - 新阶段继续使用 `S3_...`、`S4_...` 等名称； - 每个 section 保持为独立 LeRobot 数据集； - 不要直接把不同 section 的逐帧数据首尾拼接成一个 episode； - 如果训练完整长任务，应在 section 层面进行顺序调度或分阶段策略切换； - 训练集和验证集必须按 episode 划分，不能随机按帧划分。 ## 3. 根目录布局 ```text chemical_experient/ ├── README.md ├── S1_turn_off_lamp/ │ ├── data/ │ ├── meta/ │ └── videos/ ├── S2_pick_up_tube/ │ ├── data/ │ ├── meta/ │ └── videos/ └── S3_.../ # 后续 section ``` 每个 `S*` 目录都是一个完整、独立的 LeRobot Dataset v3 根目录。加载数据时，应把 section 目录传给 LeRobot，而不是把最外层 `chemical_experient` 直接当成单个 LeRobot 数据集。 例如： ```python from pathlib import Path from lerobot.datasets.lerobot_dataset import LeRobotDataset root = Path("/path/to/chemical_experient/S1_turn_off_lamp") dataset = LeRobotDataset( repo_id=f"local/{root.name}", root=root, ) print("episodes:", dataset.num_episodes) print("frames:", dataset.num_frames) print(dataset[0].keys()) ``` ## 4. 单个 Section 的物理目录 每个 section 的内部结构如下： ```text S1_turn_off_lamp/ ├── data/ │ └── chunk-000/ │ ├── file-000.parquet │ ├── file-001.parquet │ └── ... ├── meta/ │ ├── episodes/ │ │ └── chunk-000/ │ │ └── file-*.parquet │ ├── info.json │ ├── stats.json │ └── tasks.parquet └── videos/ ├── observation.images.left.third_view/ │ └── chunk-000/file-*.mp4 ├── observation.images.left.wrist/ │ └── chunk-000/file-*.mp4 └── observation.images.right.wrist/ └── chunk-000/file-*.mp4 ``` `file-000`、`file-001` 等只是 LeRobot 的物理分块，不等于 episode 编号。一个文件可以包含多个 episodes，一个 episode 的逻辑边界由 metadata 和索引字段确定。不要手工按文件名拼接 Parquet 或 MP4。 ## 5. 每帧包含的内容 每个控制周期保存四个低维机器人 feature、三路 RGB，以及 LeRobot 自动维护的索引信息： | Feature | Dtype | Shape | 含义 | |---|---|---:|---| | `observation.state` | `float32` | `[14]` | 双臂实际关节角与实际夹爪反馈 | | `observation.state.endpose` | `float32` | `[12]` | 双臂实际末端执行器位姿 | | `action` | `float32` | `[14]` | 本周期实际发送的双臂关节目标与夹爪目标 | | `action.endpose` | `float32` | `[12]` | 本周期控制链实际采用的末端执行器目标 | | `observation.images.left.third_view` | `video` | `[480,640,3]` | 第三人称 RGB | | `observation.images.left.wrist` | `video` | `[480,640,3]` | 左腕 RGB | | `observation.images.right.wrist` | `video` | `[480,640,3]` | 右腕 RGB | | `timestamp` | `float32` | `[1]` | episode 内相对时间，单位秒 | | `frame_index` | `int64` | `[1]` | 当前 episode 内帧序号 | | `episode_index` | `int64` | `[1]` | 当前帧所属 episode | | `index` | `int64` | `[1]` | section 数据集内全局帧序号 | | `task_index` | `int64` | `[1]` | 对应 `meta/tasks.parquet` 的任务索引 | 所有 section 当前均为 30 Hz。episode 允许提前结束，因此不同 episode 的帧数可以不同。 ## 6. `observation.state`：实际关节状态 Shape 为 `[14]`，顺序固定为： ```text 0 left.joint1.angle_rad 1 left.joint2.angle_rad 2 left.joint3.angle_rad 3 left.joint4.angle_rad 4 left.joint5.angle_rad 5 left.joint6.angle_rad 6 left.gripper.pos 7 right.joint1.angle_rad 8 right.joint2.angle_rad 9 right.joint3.angle_rad 10 right.joint4.angle_rad 11 right.joint5.angle_rad 12 right.joint6.angle_rad 13 right.gripper.pos ``` 语义与单位： - `joint*.angle_rad`：PiperX 实际反馈的关节角，单位 rad； - `gripper.pos`：实际夹爪开合反馈，归一化量，约 `0.0～1.0`； - `0.0` 约表示闭合，`1.0` 约表示最大张开； - 左右臂各有 6 个旋转关节和 1 个夹爪反馈。 训练代码应读取 `meta/info.json` 中的 `names`，不要只依赖硬编码下标。 ## 7. `observation.state.endpose`：实际末端位姿 Shape 为 `[12]`，顺序为： ```text 0 left.pose.x 1 left.pose.y 2 left.pose.z 3 left.pose.rx 4 left.pose.ry 5 left.pose.rz 6 right.pose.x 7 right.pose.y 8 right.pose.z 9 right.pose.rx 10 right.pose.ry 11 right.pose.rz ``` 语义与单位： - `pose.x/y/z`：实际末端位置，单位 mm； - 左、右末端位置分别位于各自 PiperX 的机器人基座坐标系； - `pose.rx/ry/rz`：轴角向量（rotation vector），单位 rad； - 这三个旋转量不是相互独立的 roll、pitch、yaw 欧拉角； - 该 feature 不包含夹爪，夹爪反馈位于 `observation.state`。 若模型统一使用 SI 单位，可在训练预处理阶段执行 `xyz_m = xyz_mm / 1000.0`，但不要覆盖原始数据。 ## 8. `action`：实际发送的关节目标 Shape 为 `[14]`，名称和顺序与 `observation.state` 相同： ```text left joint1..6 target (rad) left gripper target right joint1..6 target (rad) right gripper target ``` 该 action 的准确语义是： - Pika 先产生末端目标； - 目标经过坐标变换、工作空间限制和 official IK； - 控制程序向 PiperX 发送关节命令； - 数据集保存本周期实际发送路径返回的最终 `sent_joints`； - 夹爪项保存本周期实际目标； - 它是绝对目标，不是 `action - state` 差值； - 它不是用下一帧 `state[t+1]` 代替的代理 action。 因此，默认行为克隆可以使用： ```text 三路 RGB + observation.state[t] → action[t] ``` ## 9. `action.endpose`：有效末端目标 Shape 为 `[12]`，名称和顺序与 `observation.state.endpose` 相同，不重复夹爪。 它保存经过坐标变换、工作空间限制以及 IK 控制路径接受后的双臂末端目标。若某一周期 IK 无解并保持上一条有效控制命令，该 feature 保存相应的保持目标，而不是不可执行的原始 Pika 输入。 该 feature 可用于： - EEF 辅助监督； - 运动学一致性损失； - 末端轨迹可视化； - 3D 空间建模； - 数据质量检查。 ## 10. Observation 与 Action 的时间关系 每行数据对应同一个控制周期： ```text 1. 读取实际机器人反馈 ├── observation.state[t] └── observation.state.endpose[t] 2. 读取双 Pika，生成末端目标 3. 执行安全限制和 official IK，并发送命令 ├── action[t] └── action.endpose[t] 4. 三路 RGB 与以上低维数据写入 frame[t] ``` 即： ```text frame[t] = {observation[t], action[t], RGB[t]} ``` 原始数据没有人为把 action 移动到下一行，也没有转换成 delta。动作的物理结果通常出现在 `observation[t+1]` 或更后面的帧，因为机器人、CAN、IK 和机械结构均存在动态延迟。 ## 11. 三路视觉数据 | Feature | 视角 | 分辨率 | 帧率 | |---|---|---:|---:| | `observation.images.left.third_view` | 第三人称全局视角 | 640×480 RGB | 30 FPS | | `observation.images.left.wrist` | 左机械臂腕部视角 | 640×480 RGB | 30 FPS | | `observation.images.right.wrist` | 右机械臂腕部视角 | 640×480 RGB | 30 FPS | 说明： - 当前数据只保存 RGB； - 不保存深度图、点云或 IMU； - 三路图像与双臂状态在同一 observation 周期内读取，属于软件层面的近同步； - 当前数据没有声明相机之间为硬件触发同步； - `left.third_view` 中的 `left` 是软件挂载命名，不表示该相机是左腕相机； - 训练时应通过 LeRobot loader 按 frame 读取视频，不要按 MP4 文件名手工对齐。 ## 12. Episode 的含义 每个已保存 episode 表示对应 section 的一次人工示范。 采集程序中的准备和审核阶段不属于正式轨迹： ```text PREP：恢复到该 section 的起始状态，不记录 RECORD：执行当前 section，正式记录 REVIEW：选择保存、丢弃重录或退出，不记录 ``` 因此，episode 中不包含： - 人为恢复场景和机器人起始位姿的过程； - section 之间的等待； - REVIEW 阶段； - 被操作者丢弃的失败轨迹； - 退出时尚未确认保存的当前轨迹。 不同 episode 可以具有不同长度。训练序列和 action chunk 不能跨越 episode 边界。 ## 13. Metadata 文件 ### `meta/info.json` 数据集的权威 schema，包含： - LeRobot 版本； - robot type； - FPS； - episode 和 frame 总数； - 每个 feature 的 dtype、shape 和 names； - 数据和视频分块模板。 若本文与实际数据不一致，以对应 section 的 `meta/info.json` 为准。 ### `meta/episodes/chunk-*/file-*.parquet` 保存 episode 级索引、长度、物理数据/视频分块位置和 episode 统计信息。 ### `meta/stats.json` 保存各 feature 的统计量，可用于归一化和数据检查。训练/验证拆分后，应避免使用验证集统计量拟合训练预处理。 ### `meta/tasks.parquet` 保存 `task_index` 对应的任务文字描述。 ## 14. 当前数据未包含的内容 本数据集不直接提供： - 深度图和点云； - D435i IMU； - 原始 Vive/Pika 世界坐标； - 关节速度和关节力矩； - 末端六维力/力矩； - 多相机硬件同步时间戳； - 左右机器人基座之间的统一世界外参； - section 之间未记录的场景恢复过程； - 完整长任务的单条连续轨迹。 模型若依赖这些信息，需要明确增加采集或离线派生流程，不能仅根据现有字段名推断。 ## 15. 训练使用建议 ### 分 section 训练 最直接的方式是为每个 section 训练独立策略： ```text policy_S1: S1 observation → S1 action policy_S2: S2 observation → S2 action ... ``` 执行完整任务时，由上层状态机或任务规划器按照 `S1 → S2 → ...` 切换策略。 ### 联合训练 也可以联合加载多个 sections，但必须保留 section/task 标识，并保证： - 不把不同 sections 的相邻物理文件误认为连续轨迹； - 序列采样不跨 section 或 episode 边界； - 模型能够区分当前执行的是哪个 section； - 训练集与验证集按 episode 划分； - 各 section 在采样和损失中的权重得到明确控制。 ### 推荐模型输入与目标 默认推荐： ```text 输入：三路 RGB + observation.state 目标：action 辅助输入/监督：observation.state.endpose、action.endpose ``` 若需要 delta action，应在训练预处理阶段可复现地派生，不要修改原始数据集。 ## 16. 使用注意事项 - 必须复制和交付完整 section 目录，不能只复制 `data/` 或 `videos/`； - 不要手工合并 `file-*.parquet` 或 `file-*.mp4`； - 不要依据物理文件数推断 episode 数； - 每次训练前读取实际 `meta/info.json`； - 所有关节角和旋转量均使用 rad； - 所有 EEF XYZ 均使用 mm； - 左右 EEF XYZ 分别处于各自机器人基座坐标系； - 夹爪是归一化开合量； - 图像的 loader 输出可能为 channel-first tensor，具体以 LeRobot loader 为准； - `S1`、`S2` 的数据不能在没有 section 标签的情况下混为一条连续轨迹。 ## 17. 训练前检查清单 - [ ] 每个 section 的 `meta/info.json` 可以解析； - [ ] `observation.state` 为 `[14]`； - [ ] `observation.state.endpose` 为 `[12]`； - [ ] `action` 为 `[14]`； - [ ] `action.endpose` 为 `[12]`； - [ ] 四个低维 feature 不包含 NaN 或 Inf； - [ ] 三路 RGB 均可正常解码； - [ ] 随机检查左腕、右腕和第三视角没有串台； - [ ] 每个 episode 的 `frame_index` 从 0 递增； - [ ] 每个 episode 的 timestamp 单调递增； - [ ] 序列窗口和 action chunk 不跨 episode； - [ ] 训练/验证按 episode 划分； - [ ] 联合训练时保留 section/task 标识； - [ ] 训练配置明确记录 mm、rad、轴角和夹爪单位。 ## 18. 当前数据快照 ### `S1_turn_off_lamp` ```text LeRobot codebase: v3.0 Robot type: dual_piper_follower Episodes: 50 Frames: 21,615 FPS: 30 平均 episode: 432.3 frames / 14.41 s ``` ### `S2_pick_up_tube` ```text LeRobot codebase: v3.0 Robot type: dual_piper_follower Episodes: 50 Frames: 29,950 FPS: 30 平均 episode: 599.0 frames / 19.97 s ```