Scheduled Commit

TREX_LEROBOT_V2_FORMAT_SUMMARY.md

@@ -0,0 +1,74 @@
+# T-Rex LeRobot v2（含 force）格式 · 一页总结
+
+详细规范：`docs/TREX_LEROBOT_V2_FORMAT.md`（7 节，含 modality.json 模板与 track 升级路径）。
+参考实现：`data/trex_mini_force`。就绪校验：
+`python scripts/data/check_trex_dataset_ready.py --dataset-root <root> --require-force`
+
+## 骨架
+
+标准 LeRobot v2.1 三件套：
+
+```
+<root>/
+├── data/chunk-{chunk:03d}/episode_{index:06d}.parquet     # 逐帧表
+├── videos/chunk-{chunk:03d}/{video_key}/episode_{index:06d}.mp4   # 每路一目录
+└── meta/  info.json · stats.json · episodes.jsonl · tasks.jsonl · modality.json · embodiment.json
+```
+
+`info.json` 的 `fps=30` 是 mp4 源率。20 Hz 动作 / 5 Hz 触觉 / 10 Hz 视频的逻辑网格
+由训练 loader 按 `timestamp` 重采，采集端不做任何降采样。
+
+## 每帧一行，七类列
+
+| 类别 | 列 | 形状 / 内容 |
+|---|---|---|
+| 关节 | `observation.state` / `action` | `[58]` = 左臂 7 + 左手 22 + 右臂 7 + 右手 22 |
+| 末端 | `observation.state_eef62`（测量） / `action.eef62_absolute`（指令目标） | `[62]` = 每臂 [3 平移, 6D 旋转(旋转矩阵前两列)] + 22 手关节，**全绝对值** |
+| 力 | `observation.tactile_force` | `[60]` = 10 指 × 6 维 wrench，指主序（左 thumb→pinky，再右手同序），**原始连续物理值** |
+| 时间 | `timestamp` | 秒，**严格递增**——整个格式最重要的不变量 |
+| 索引 | `frame_index` `episode_index` `index` `task_index` | LeRobot 标准 |
+| 语言 | `annotation.task` | 每集一条指令 |
+| 视频 | 3 路 RGB `[180,320,3]` · 10 路触觉 raw `[240,320,3]` · 10 路 deform `[240,240,3]` | 共 23 路 `observation.images.*`，手指顺序与力列一致 |
+
+## meta 关键约定
+
+- `modality.json`：`state.eef62 → observation.state_eef62`，`action.eef62 → action.eef62_absolute`，
+  23 路 video key → original_key。
+- `stats.json`：必含 `observation.tactile_force`（60 维展平）与 `observation.state_eef62` 的 q01/q99。
+- `embodiment.json`：本体标签（如 `dexmate_vega1_and_sharpa_wave`）。
+
+> **eef62 列可由构建脚本生成**：`scripts/data/build_trex_track_force_v2.py` 会用 T-Rex FK（`assets/trex_camera_calib.json` + `T_REX_ROOT` 运动学）从 58 维关节列算出 `observation.state_eef62` / `action.eef62_absolute`。采集端**最低只需 58 维关节 state/action**；若采集端已有可靠的 eef62 也可直接存。
+
+## 五条铁律
+
+1. 只存绝对值、只存物理单位——归一化 / delta-base / 降采样全部在训练侧。
+2. `timestamp` 严格递增；episode ≥ 6 s（推荐 8–15 s）。
+3. 指令与测量分开：`action.*` = teleop 下发目标，`observation.*` = 回读。
+4. 力列与触觉视频的手指顺序全局一致。
+5. 缺帧不丢行：值置零，timestamp 连续。
+
+## 后处理才追加（采集端不管）
+
+`tracks_trex_track_force_v2/*.npz`（SAM2 + CoTracker 250 点）→ parquet 追加
+`observation.track_xy [250,2]`、`observation.track_visibility [250]` →
+`meta/trex_track_force_manifest.json`、`relative_stats_dreamzero.json`（delta-base 统计）、
+`dataset_ready.json`。
+
+## 微调 joint force-action 模型的额外要求
+
+- 力必须连续无量化，逐帧写原始传感器值；力时间戳对齐"执行该动作后测到"。
+- 训练用 `scripts/train/trex_fullmodel_full_training_wan22.sh`，
+  加 `action_head_cfg.config.force_future_loss_weight=0.5`。
+
+## 采集格式 → 可训练格式（一条命令）
+
+```bash
+SOURCE_TREX_DATA_ROOT=<采集数据集> TREX_DATA_ROOT=<输出目录> GPUS=6,7 \
+  bash scripts/data/prepare_trex_track_force_training.sh          # 加 --run-training 可直接接训练
+```
+
+它按序：硬链接克隆源数据（视频不占第二份空间）→ SAM2+CoTracker 提取 250 点 track
+→ 追加 track/visibility/eef62 parquet 列 → 校验 60 维力列 → 写 stats / relative_stats /
+manifest / dataset_ready → 逐 episode 验证。之后即可用
+`scripts/train/trex_fullmodel_full_training_wan22.sh`（joint 模型）或
+`trex_track_force_training_wan22.sh`（原模型）训练。

docs/TREX_LEROBOT_V2_FORMAT.md

@@ -70,6 +70,8 @@ chunk 规则：LeRobot 标准，`chunks_size=1000`，episode_index // 1000 决
 }
 ```
 
+> **eef62 列可由构建脚本生成**：`scripts/data/build_trex_track_force_v2.py` 会用 T-Rex FK（`assets/trex_camera_calib.json` + `T_REX_ROOT` 运动学）从 58 维关节列算出 `observation.state_eef62` / `action.eef62_absolute`。采集端**最低只需 58 维关节 state/action**；若采集端已有可靠的 eef62 也可直接存。
+
 ## 5. 硬性规范
 
 1. **只存绝对值、只存物理单位**。q99 归一化、delta-base、5 Hz 触觉降采样都是训练时的事；统计换了不必重建数据。
@@ -113,3 +115,16 @@ chunk 规则：LeRobot 标准，`chunks_size=1000`，episode_index // 1000 决
 
 **微调建议**：用 `scripts/train/trex_fullmodel_full_training_wan22.sh`，并加
 `action_head_cfg.config.force_future_loss_weight=0.5`（小规模消融验证：λ_f=0.5 手指速度误差 −46%、位置无偏差；λ_f=1.0 会引入手部姿态偏差）。
+
+## 采集格式 → 可训练格式（一条命令）
+
+```bash
+SOURCE_TREX_DATA_ROOT=<采集数据集> TREX_DATA_ROOT=<输出目录> GPUS=6,7 \
+  bash scripts/data/prepare_trex_track_force_training.sh          # 加 --run-training 可直接接训练
+```
+
+它按序：硬链接克隆源数据（视频不占第二份空间）→ SAM2+CoTracker 提取 250 点 track
+→ 追加 track/visibility/eef62 parquet 列 → 校验 60 维力列 → 写 stats / relative_stats /
+manifest / dataset_ready → 逐 episode 验证。之后即可用
+`scripts/train/trex_fullmodel_full_training_wan22.sh`（joint 模型）或
+`trex_track_force_training_wan22.sh`（原模型）训练。