# UMI转LeRobotV3数据集
UMI转LeRobotV3算子用于将UMI（Universal Manipulation Interface）兼容的机器人示教数据集转换为LeRobot V3格式。算子通过适配器注册表机制支持多种平台，无需修改代码即可接入新平台，转换结果可直接用于后续模型训练。
- **核心能力：**
  - 多平台支持：内置Pika双臂鱼眼平台适配器（默认），同时提供通用YAML Manifest适配器，新平台只需在数据集根目录编写manifest.yaml即可零代码接入。
  
  - 平铺输出：data/、meta/、videos/直接输出到结果目录顶层。
  
  - 批量处理：支持一次提交多个数据集并行转换，单个失败不影响其他。
  
  - 视频编码：图像解码后统一编码为AV1视频。
  
  - Ray分布式：支持Ray集群并行转换。
   
- **输入：** 包含UMI数据集目录（含episode{N}/子目录，N为非负整数）与可选挂载配置文件（manifest.yaml），挂载配置文件优先级高于输入数据集根目录配置文件。
- **输出：** LeRobot V3格式数据集目录。
#### 参数配置
当预置算法选择"UMI转LeRobotV3算子"后，需填写以下环境变量：
| 参数名             | 是否必填 | 默认值   | 可选值             | 说明                                                                                                                                                                                                                                    |
|:---|:---|:---|:---|:---|
| UMI_PLATFORM | 是    | manifest | pika、manifest | - pika：内置平台适配器。  - manifest：通用YAML manifest，需在挂载目录或者数据集根目录预置manifest.yaml。   |
| UMI_FPS       | 是    | 0      | 整数            | 帧率覆盖。填正整数强制使用该帧率；填0或空值时由真实采样率动态计算。                                                                                                                                                                                                     |
   
#### 输入说明
支持UMI兼容格式数据集，episode目录命名episode{N}（N为非负整数，按数字顺序处理），每个episode包含相机、位姿、夹爪等示教数据流。同一episode内各数据流帧数需保持一致；目录下存在sync.txt时以该文件对齐帧数，缺失时算子以相机时间戳为基准对位姿/夹爪流做最近邻时间戳匹配（文件名须为数字时间戳）。
#### 输入数据集目录结构
输入须为UMI兼容格式（以Pika双臂为例）：
```
dataset_root/                          # SOURCE_DATASET_PATH 指向此目录
├── instructions.json                  # 可选，根级任务指令
├── episode0/
│   ├── instructions.json              # 可选，episode级指令（优先于根级）
│   ├── camera/color/pikaFisheyeCamera_l/   # sync.txt（可选）+ 时间戳命名 .jpg
│   ├── camera/color/pikaFisheyeCamera_r/
│   ├── localization/pose/pika_l/           # sync.txt（可选）+ 时间戳命名 .json（x/y/z/roll/pitch/yaw）
│   ├── localization/pose/pika_r/
│   ├── gripper/encoder/pika_l/             # sync.txt（可选）+ .json（distance 字段）
│   └── gripper/encoder/pika_r/
└── episode1/
    └── ...
```
任务描述支持两级instructions.json配置：优先读取episode目录下的instructions.json（值非null时直接使用）；否则回退到数据集根目录的instructions.json（1条prompt时所有episode共用，多条时按episode序号严格匹配）；两者均无则使用空串。
#### 输出说明
根据输入数据集生成LeRobot V3格式数据集，转换完成后自动执行验证，验证结果写入conversion_summary.json。
#### 输出目录结构
输出为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.left_fisheye/chunk-000/file-000.mp4
    └── observation.images.right_fisheye/chunk-000/file-000.mp4
```
