# H5转LeRobotV3数据集
H5转LeRobotV3算子用于将HDF5格式（每个.h5文件代表一个episode）的机器人示教数据集转换为LeRobot V3格式。算子通过manifest配置驱动，内置智元A2D双臂人形机器人配置，其他h5数据机器人可在数据集目录编写 manifest.yaml 接入。
- **核心能力：**
  - manifest 驱动：通过h5 manifest 配置描述state/action字段向量、相机话题映射、任务文本等，配置可放置在数据集目录或使用平台内置。
  
  - 多机器人支持：内置智元A2D双臂人形机器人配置（4路相机：3 RGB + 1 深度），其他机器人可通过自定义 manifest 接入。
  
  - 批量处理：支持一次提交多个数据集并行转换，单个失败不影响其他。
  
  - Ray 分布式：支持Ray集群并行转换（可选开启）。
   
- **当前支持机型：** 智元A2D（a2d）。
- **输入：** 输入数据集目录包含.h5文件（一个文件对应一个episode），也可包含task.txt / prompt.json与可选挂载配置文件（manifest.yaml）。挂载配置文件的优先级高于输入数据集根目录配置文件。
- **输出：** LeRobot V3格式数据集目录。如果用户输出选的OBS路径，预置算法会判断是否有冲突目录，如果有冲突目录，则创建一个新目录并将结果放在新目录下。
#### 参数配置
平台内置智元A2D双臂人形机器人 manifest。
表1参数说明 
| 参数名   | 是否必填 | 默认值     | 可选值             | 说明                                                                                                                                                                                                                           |
|:---|:---|:---|:---|:---|
| robot | 否      | manifest | a2d、manifest | - a2d：智元机器人类型。  - manifest：通用YAML manifest，需在挂载目录或者数据集根目录预置manifest.yaml。   |
   
#### 输入说明
输入数据须包含h5格式数据，每个 .h5 文件代表一个 episode。输入数据集可配置manifest.yaml或任务描述文件 task.txt。
**输入数据集目录结构** **：**
```
<dataset_dir>/                           # SOURCE_DATASET_PATH 指向此目录  
├── episode_0.h5                         # episode 0 数据（state/action/cameras）  
├── episode_1.h5                         # episode 1 数据  
├── ...  
├── manifest.yaml                        # 可选，h5 manifest 配置（推荐）   
└── task.txt                             # 可选，统一任务描述
```
**manifest 2.0 配置文件** **：**
h5 manifest 是 h5tolerobotv3 算子的配置格式，以 schema_version: "2.0" + source_type: h5 标识。配置顶层描述 state/action 字段向量（每项通过 locator 定位 h5 dataset 路径）、相机话题映射、任务文本等。配置文件可放置在数据集一级目录（推荐 manifest.yaml，也接受任意 \*.yaml）。
- 智元 A2D（a2d）
```
schema_version: "2.0"
source_type: h5
repo_id: converted
robot_type: a2d
fps: 30
state:
  # arm 14 维（双臂 7 关节 × 2），names_from: embedded 从 h5 group attrs['name'] 读关节名
  - {locator: joints/state/arm/position, names_from: embedded}
  # effector 2 维（双夹爪），标 role: gripper 自动推导 gripper 索引写入清洗 sidecar
  - {locator: joints/state/effector/position, names_from: embedded, role: gripper}
  # head 2 维（头部俯仰/偏航）
  - {locator: joints/state/head/position, names_from: embedded}
  # waist 2 维（腰部俯仰/偏航）
  - {locator: joints/state/waist/position, names_from: embedded}
  # robot base position 3 维（底盘 x/y/z）
  - {locator: joints/state/robot/position, names: [base_pos_x, base_pos_y, base_pos_z]}
  # robot base orientation 4 维（底盘四元数 qw/qx/qy/qz）
  - {locator: joints/state/robot/orientation, names: [base_ori_x, base_ori_y, base_ori_z, base_ori_w]}
  # state 总维度 = 14 + 2 + 2 + 2 + 3 + 4 = 27
action:
  strategy: stored
  fields:
    # arm 14 维（双臂 7 关节 × 2，与 state.arm 对齐）
    - {locator: joints/action/arm/position, names_from: embedded}
    # effector 2 维（双夹爪，gripper）
    - {locator: joints/action/effector/position, names_from: embedded, role: gripper}
    # head 2 维
    - {locator: joints/action/head/position, names_from: embedded}
    # waist 2 维
    - {locator: joints/action/waist/position, names_from: embedded}
    # robot base position 3 维（底盘目标位置 x/y/z）
    - {locator: joints/action/robot/position, names: [base_cmd_pos_x, base_cmd_pos_y, base_cmd_pos_z]}
    # robot base velocity 2 维（底盘目标速度 x/y，与 state.orientation 不对齐 — A2D 设计）
    - {locator: joints/action/robot/velocity, names: [base_cmd_vel_x, base_cmd_vel_y]}
    # action 总维度 = 14 + 2 + 2 + 2 + 3 + 2 = 25
cameras:
  hand_left:  {locator: cameras/hand_left/color/data, depth: false}    # 左手相机 RGB
  hand_right: {locator: cameras/hand_right/color/data, depth: false}  # 右手相机 RGB
  head:       {locator: cameras/head/color/data, depth: false}        # 头部相机 RGB
  head_depth: {locator: cameras/head/depth/data, depth: true}         # 头部深度相机（16-bit PNG，编码为 8-bit gray mp4）
task:
  mode: const
  text: ""
output:
  chunk_size: 1000
  data_file_size_mb: 100
  video_file_size_mb: 200
  video_codec: auto
source:
  timestamp_path: timestamp   # h5 dataset 路径，int64 纳秒 → float32 秒
  file_glob: "*.h5"
  per_file: episode            # 一个 .h5 文件 = 一个 episode
```
#### 输出说明
生成 LeRobot V3 格式数据集。
```
<output_dir>/  
├── data/  
│   └── chunk-000/  
│       └── file-000.parquet            # state/action 轨迹数据  
├── meta/  
│   ├── info.json                       # 数据集基本信息（codebase_version 为 v3.0）  
│   ├── stats.json                      # 统计信息  
│   ├── tasks.parquet                   # 任务（prompt）元数据  
│   └── episodes/                       # episode 元数据  
└── videos/      
├── observation.images.hand_left/chunk-000/file-000.mp4      
├── observation.images.hand_right/chunk-000/file-000.mp4      
├── observation.images.head/chunk-000/file-000.mp4      
└── observation.images.head_depth/chunk-000/file-000.mp4
```
