rollout_data/README.md

# 中文 / English

[中文](#zh) · [English](#en)

<a id="zh"></a>

# 机器人执行数据

本次提供 OpenPI π0.5 与 FLUX 各 1 条 Flexiv 双臂衣物折叠执行记录，采用 LeRobot v3 格式。两套数据均保留左右两路 ego 相机（960×960、30 Hz）、逐帧状态与动作、双侧 IMU、相机标定和机器人侧 H5 记录。音频与 rear 相机不包含在 rollout 交付中。

| 模型 | 目录 | Episode | 帧数 | 时长 |
| --- | --- | ---: | ---: | --- |
| OpenPI π0.5 | `openpi_pi05/` | 1 | 6,540 | 218 秒 |
| FLUX | `flux/` | 1 | 30,619 | 1,020.633 秒（约 17 分钟） |

两条 rollout 合计 37,159 帧、约 20 分 38.6 秒。本模型仓库提供执行样例；人工演示数据不包含在此目录中。

## 文件与读取方式

以下路径相对于各模型目录。请分别将 `openpi_pi05/` 和 `flux/` 作为独立的 LeRobot 数据集根目录读取；两套数据各自从 episode 0 开始，不能直接拼接其索引文件。

| 路径 | 内容 |
| --- | --- |
| `data/chunk-000/file-000.parquet` | 逐帧状态、动作、关节信息与时间戳 |
| `videos/observation.images.left_ego/` | 左侧 ego 视频 |
| `videos/observation.images.right_ego/` | 右侧 ego 视频 |
| `meta/info.json`、`meta/stats.json` | 交付版本的特征定义与统计 |
| `meta/episodes/`、`meta/tasks.parquet` | Episode 索引、视频引用与任务 |
| `meta/calibration.json` | 保留相机的内参与数值外参 |
| `imu/` | 左右侧 IMU，保留原始采样频率 |
| `robot/episode_0000.h5` | 视频对齐前的机器人采样与控制记录 |
| `insta360_export.json` | 导出配置、同步信息及源转换检查记录 |
| `checksums.sha256` | 本目录交付文件的 SHA-256 校验值 |

状态与动作均为 16 维，左手在前、右手在后，每手顺序为 `[x, y, z, qw, qx, qy, qz, gripper]`。位置单位为米，四元数采用 `wxyz`，夹爪单位为度。导出配置为 `action_mode=next_state`，`action[t]` 对应下一帧状态（末帧除外），不是原始模型动作块；控制器侧记录另见 H5。H5 采样范围与 LeRobot 对齐后的帧数不同，需结合各侧同步参数读取，不能按行号直接拼接。两套数据的主机时钟原点不统一，请使用各自的同步信息。

`meta/info.json` 中 `data_files_size_in_mb` 和 `video_files_size_in_mb` 是 LeRobot 分片配置，并非交付目录实际大小。

## 标定与机器人模型

保留相机的标定位于各模型目录的 `meta/calibration.json`。双臂名义结构参考为 [`robot_model/flexiv_rizon4_dual_umi.urdf`](robot_model/flexiv_rizon4_dual_umi.urdf)；集成时需核对实际设备版本与标定。

## 检查范围

本次检查覆盖视频文件完整性、帧数与分辨率、音频轨是否缺失、Parquet 行数及索引、时间戳单调性、状态与动作有限性、下一帧状态关系，以及元数据对保留视频的引用。源转换器记录的重复取帧计数仍保留：OpenPI 左/右为 7/6，FLUX 左/右为 30/31；跳帧计数均为 0。这些是源转换器计数，不等同于本次重复帧质检结论。

人工演示的质检报告不覆盖这两条 rollout。本次未运行完整 rollout 运动质检，也未评估任务成功率。本次发布检查见 [rollout 验证](../docs/ROLLOUT_VALIDATION.md)。这些样例不构成任务成功率评测。

---

<a id="en"></a>

# Robot Rollout Data

One Flexiv bimanual garment-folding rollout is provided for each of OpenPI π0.5 and FLUX in LeRobot v3 format. Both datasets retain two ego camera views (left/right, 960×960, 30 Hz), per-frame states/actions, bilateral IMU, calibration and robot H5 records. Audio and rear-camera views are excluded from the rollout delivery.

| Model | Directory | Episodes | Frames | Duration |
| --- | --- | ---: | ---: | --- |
| OpenPI π0.5 | `openpi_pi05/` | 1 | 6,540 | 218 seconds |
| FLUX | `flux/` | 1 | 30,619 | 1,020.633 seconds (about 17 minutes) |

Together they contain 37,159 frames / 20 min 38.6 sec. This directory contains execution examples; human demonstration data is not included here.

## Files and reading

Treat `openpi_pi05/` and `flux/` as separate LeRobot dataset roots. Each starts at episode 0; their index files cannot be concatenated directly. Paths below are relative to the respective root.

| Path | Content |
| --- | --- |
| `data/chunk-000/file-000.parquet` | Per-frame states, actions, joint data and timestamps |
| `videos/observation.images.left_ego/` | Left ego video |
| `videos/observation.images.right_ego/` | Right ego video |
| `meta/info.json`, `meta/stats.json` | Delivered feature schema and statistics |
| `meta/episodes/`, `meta/tasks.parquet` | Episode index, video references and task |
| `meta/calibration.json` | Retained camera intrinsics and numerical extrinsics |
| `imu/` | Left/right IMU at the original sample rates |
| `robot/episode_0000.h5` | Robot samples and control records before video alignment |
| `insta360_export.json` | Export configuration, synchronization and source converter checks |
| `checksums.sha256` | SHA-256 checksums of the delivered files |

State and action vectors have 16 dimensions: left hand followed by right hand, each as `[x, y, z, qw, qx, qy, qz, gripper]`. Positions are in metres, quaternions use `wxyz`, and gripper values are in degrees. Export mode is `action_mode=next_state`: `action[t]` is the next-frame state, excluding the last frame, not a raw model action chunk. Controller records are in H5. Its sample span differs from the aligned LeRobot data; use per-side synchronization parameters rather than joining by row number. The two releases use different host-clock origins; consult each dataset's own synchronization information.

`data_files_size_in_mb` and `video_files_size_in_mb` in `meta/info.json` are LeRobot sharding settings, not actual delivery sizes.

## Calibration and robot model

Calibration is in each dataset's `meta/calibration.json`. The nominal dual-arm structure reference is [`robot_model/flexiv_rizon4_dual_umi.urdf`](robot_model/flexiv_rizon4_dual_umi.urdf); confirm the actual hardware version and calibration before integration.

## Validation scope

Checks cover video completeness, frame counts/resolution, absence of audio streams, Parquet row counts and indices, increasing timestamps, finite states/actions, next-state consistency and metadata references to retained videos. Source converter repeated-frame selection counts remain recorded: OpenPI left/right 7/6, FLUX left/right 30/31, with zero skipped frames. These source counts are not a new duplicate-frame QC result.

The human demonstration QC report does not cover these rollouts. Complete rollout motion QC and task success evaluation were not performed. See the [release validation](../docs/ROLLOUT_VALIDATION.md). These examples do not constitute a task-success evaluation.

## 下载与最小读取 / Download and minimal inspection

这些样例位于 **model repo**，不是独立 dataset repo。下载保留目录结构后，用下列方法检查 Parquet；LeRobot 加载器请分别指向各自的数据集根目录。元数据中的 `train: 0:1` 是导出索引，不代表独立训练/测试划分。

These samples live in a **model repo**, not a separate dataset repo. Preserve the directory structure when downloading. Inspect Parquet as below, and point LeRobot loaders to each dataset root separately. The exported `train: 0:1` split is an index convention, not an independent train/test protocol.

```bash
pip install -U huggingface_hub pyarrow
hf download Crobotia/iUMI_Inference --local-dir iUMI_Inference --include "rollout_data/*"
```

```python
from pathlib import Path
import json
import pyarrow.parquet as pq

root = Path("iUMI_Inference/rollout_data/openpi_pi05")  # or: flux
info = json.loads((root / "meta/info.json").read_text())
frames = pq.read_table(root / "data/chunk-000/file-000.parquet")
assert frames.num_rows == info["total_frames"]
print(frames.select(["timestamp", "observation.state", "action"]).slice(0, 2).to_pylist())
```

从单个数据集根目录运行 `shasum -a 256 -c checksums.sha256` 可检查其 13 个文件。整个仓库的校验清单另位于根目录。现有校验清单均保留文件原始字节；本次未重采样或重新编码视频。

Run `shasum -a 256 -c checksums.sha256` inside either dataset root to verify its 13 listed files. The repository root has a separate combined manifest. Source data bytes and per-dataset manifests are preserved; videos were not resampled or re-encoded for this upload.

## 使用条款 / Terms

本次样例未附独立媒体/数据许可；源码 Apache-2.0 标签不自动覆盖这些文件。适用条款见 [LICENSES.md](../LICENSES.md)，使用或再分发前请向 Crobotia 确认。

No separate media/data license declaration accompanies these samples. The source-code Apache-2.0 tag does not automatically cover them. See [LICENSES.md](../LICENSES.md) and confirm applicable terms with Crobotia before use or redistribution.