chenlin
f5d84e26f6
新增专家轨迹诊断、原视频估计相机入口和状态参考ACT数据门禁/训练链路；更新版本与进度文档。 验证：120项CPU/USD回归和4步synthetic CPU smoke通过；1333帧默认GUI历史回放PASS。原视频相机完整回放超时124，策略GPU E2E未执行，完整pre-commit工具缺失。 兼容性：HDF5、Cartpole、USD和控制阈值保持不变。本提交为实验进度快照，不宣称完整发布验收通过；数据、视频和权重不纳入。
255 lines
15 KiB
Markdown
255 lines
15 KiB
Markdown
# L20 左手专家轨迹 HDF5 交付要求
|
||
|
||
**接口版本：`l20_tracking_v1`**
|
||
|
||
**交付对象：视频重定向/示教数据同事**
|
||
|
||
**当前用途：浮动腕部与全部手指参考关节的轨迹回放，后续用于学习策略。**
|
||
|
||
本文第1–9节保持左手交付约定；右手接入差异见第10节，不得直接使用左手哈希、限位或拇指联动。
|
||
本文是可独立分享的数据交付说明，与当前仓库校验器一致。它不是通用 HDF5 标准，也不是完整 DexSchema。
|
||
请先交付 **1 条短样例**，确认坐标、尺度、关节映射后再批量导出。
|
||
|
||
## 1. 要交什么
|
||
|
||
交付重定向后的 **L20 左手机器人参考状态轨迹**：
|
||
|
||
- 腕部/手根的三维位置与姿态。
|
||
- 约定模型的全部手指关节角，包括从动关节。
|
||
- 同步时间戳与逐帧有效标记。
|
||
- 模型身份、坐标变换、尺度和数据来源说明。
|
||
|
||
不是原始人手关键点、MANO 参数或电机实测指令。关节状态不能直接等同于执行器控制命令。
|
||
本阶段不要求图像、物体位姿、奖励、接触标签、速度、加速度、电流或力矩；缺少这些内容不需要补零伪造。
|
||
|
||
## 2. 文件结构（必填）
|
||
|
||
文件扩展名建议使用 `.hdf5`；HDF5 根属性通过 `file.attrs` 保存，**不要创建名为 `attrs` 的 group**。
|
||
|
||
```text
|
||
demonstrations.hdf5
|
||
├── 根属性：schema_version、embodiment、hand_side、asset_sha256、root_link、
|
||
│ provenance、source_description、metric_scale_provenance、scale_to_meters
|
||
├── metadata/
|
||
│ ├── joint_names UTF-8 [J]
|
||
│ └── world_from_source float64 [4, 4]
|
||
└── episodes/
|
||
├── demo_000000/
|
||
│ ├── time float64 [T]
|
||
│ ├── wrist_position float32 [T, 3]
|
||
│ ├── wrist_quaternion float32 [T, 4]
|
||
│ ├── joint_position float32 [T, J]
|
||
│ └── valid bool [T]
|
||
└── demo_000001/
|
||
└── 同样结构，可以有不同帧数 T
|
||
```
|
||
|
||
- 至少一个 episode；名称必须为 `demo_` 加六位数字，如 `demo_000012`。
|
||
- 每条 episode 至少两帧；各字段的 T 必须相同。
|
||
- 一个文件共享模型、关节顺序及源世界标定；标定、模型或关节布局改变时另建文件。
|
||
- 当前约定资产的 **J=21**，不是从“L20”名称推断出的自由度。21 个状态关节不代表 21 个独立执行器。
|
||
|
||
## 3. 根属性
|
||
|
||
除 `scale_to_meters` 外，下列属性均为非空 UTF-8 字符串。
|
||
|
||
| 属性 | 内容与要求 |
|
||
| --- | --- |
|
||
| `schema_version` | 固定为 `l20_tracking_v1` |
|
||
| `embodiment` | 固定为 `L20` |
|
||
| `hand_side` | 固定为 `left` |
|
||
| `asset_sha256` | 双方约定的原始模型依赖包哈希，64 位小写十六进制；见第 6 节 |
|
||
| `root_link` | 固定为当前模型的 `hand_base_link` |
|
||
| `provenance` | 实际专家重定向数据填 `expert_retargeted`；程序生成的测试数据填 `synthetic` |
|
||
| `source_description` | 视频/轨迹标识、重定向工具及版本、世界原点与 X/Y 朝向、源坐标约定、腕点到机器人根部的映射依据、质量限制 |
|
||
| `metric_scale_provenance` | 米制尺度如何获得，标定方法/版本或估算方法、可信程度与已知误差；不得把估算写成实测 |
|
||
| `scale_to_meters` | **有限正浮点标量**，记录已应用的源位置尺度系数；不是要求读取方再缩放 |
|
||
|
||
例：源位置以毫米表示，则 `scale_to_meters=0.001`；输出位置仍须已经是米。
|
||
源数据已经是米时可填 `1.0`，但必须有实际依据，不能仅为通过校验填写。
|
||
|
||
## 4. 字段与坐标语义
|
||
|
||
| 路径 | 类型 / shape | 单位及语义 |
|
||
| --- | --- | --- |
|
||
| `metadata/joint_names` | HDF5 UTF-8 string `[J]` | `joint_position` 每列对应的模型关节名称，严格使用第 5 节顺序 |
|
||
| `metadata/world_from_source` | `float64 [4,4]` | 已应用的源世界系到交付世界系刚体变换；矩阵平移部分单位 m |
|
||
| `episodes/.../time` | `float64 [T]` | 秒；每条轨迹从 0 开始，严格递增 |
|
||
| `episodes/.../wrist_position` | `float32 [T,3]` | `hand_base_link` 的 **link 原点**在交付世界系中的 `[x,y,z]`，单位 m |
|
||
| `episodes/.../wrist_quaternion` | `float32 [T,4]` | **`[w,x,y,z]`**；将根 link 局部向量主动旋转到交付世界系 |
|
||
| `episodes/.../joint_position` | `float32 [T,J]` | 参考关节角，单位 rad；零位和正方向与约定模型一致 |
|
||
| `episodes/.../valid` | `bool [T]` | 整帧是否有效；不是每关节标记，不使用 0/1 整数数组代替 bool |
|
||
|
||
### 坐标与姿态
|
||
|
||
1. 交付世界系采用 **右手系、Z 向上**，在一个 episode 内固定，不随腕部移动。
|
||
2. 根部位姿不是人手腕点、机器人质心或 USD default prim 位姿。重定向端必须先完成到
|
||
`hand_base_link` 坐标系的映射，并说明映射依据。
|
||
3. 记录的尺度和刚体变换满足：
|
||
|
||
```text
|
||
p_world = R_world_from_source @ (scale_to_meters * p_source) + t_world_from_source
|
||
```
|
||
|
||
此式用于源位置点；人手腕点到机器人根部的额外映射仍须由重定向端完成。
|
||
导出的 `wrist_position` 和 `wrist_quaternion` **已经在交付世界系**。
|
||
接收端不会再次应用该矩阵或尺度。
|
||
4. `world_from_source` 最后一行为 `[0,0,0,1]`，旋转部分正交且行列式为 +1，不能混入尺度或镜像。
|
||
已统一世界系时可以使用单位矩阵，但不能用单位矩阵掩盖未知标定。
|
||
5. 有效四元数必须单位化，范数容差 `1e-4`；相邻两帧都有效时，四元数点积必须非负。
|
||
`q` 与 `-q` 表示同一旋转，导出时应统一相邻符号；不能混用 `xyzw` 或欧拉角。
|
||
6. 不要为了适配当前合成测试而把真实轨迹自动平移到 `z=0.4`，或把起始姿态强制设为单位四元数。
|
||
场景对齐必须有明确、可追溯的坐标约定。
|
||
|
||
## 5. 关节顺序与联动
|
||
|
||
当前 `joint_names` 必须严格等于下列列表；这是数据清单顺序，**不是仿真运行时 DOF 顺序**。
|
||
|
||
```python
|
||
joint_names = [
|
||
"index_dip", "index_mcp_pitch", "index_mcp_roll", "index_pip",
|
||
"middle_dip", "middle_mcp_pitch", "middle_mcp_roll", "middle_pip",
|
||
"pinky_dip", "pinky_mcp_pitch", "pinky_mcp_roll", "pinky_pip",
|
||
"ring_dip", "ring_mcp_pitch", "ring_mcp_roll", "ring_pip",
|
||
"thumb_cmc_pitch", "thumb_cmc_roll", "thumb_cmc_yaw", "thumb_ip", "thumb_mcp",
|
||
]
|
||
```
|
||
|
||
- 不允许重名、缺列、多列、静默重排或用其他手型的关节代替。
|
||
- 每个有效帧必须满足清单 `joints[].lower_rad/upper_rad`，校验容差为 `1e-6 rad`。
|
||
精确限位以随交付约定的 JSON 清单为准，避免使用文档四舍五入值作为限位。
|
||
- 当前源模型定义以下联动；数据中仍须包含这些从动关节列：
|
||
|
||
```text
|
||
thumb_ip = 1.02 * thumb_mcp
|
||
index_dip = 0.89 * index_pip
|
||
middle_dip = 0.89 * middle_pip
|
||
ring_dip = 0.89 * ring_pip
|
||
pinky_dip = 0.89 * pinky_pip
|
||
```
|
||
|
||
偏置均为 0 rad，有效帧等式残差绝对值不得超过 `1e-3 rad`。
|
||
- 联动关系和各关节限位必须同时满足；不能单独裁剪从动关节而破坏联动。
|
||
- 这些是约定模型的约束，不是已经核实的硬件电机协议。重定向映射有疑问时先确认，不要擅自独立控制从动关节。
|
||
|
||
## 6. 模型身份与随附清单
|
||
|
||
本仓库当前清单：
|
||
|
||
[`assets/robots/dex_hand/linkerhand_g20_left/tracking_manifest.json`](assets/robots/dex_hand/linkerhand_g20_left/tracking_manifest.json)
|
||
|
||
当前原始模型依赖包 `asset_sha256`：
|
||
|
||
```text
|
||
6c8f35358f481cf604ee802588017f30c1661c0f38e1187c49e5340db3830538
|
||
```
|
||
|
||
这是**当前版本快照**。请由仿真方提供同版 `tracking_manifest.json` 与约定模型，数据方确认使用该模型后填写哈希。
|
||
不得把上述哈希复制到实际使用了其他模型的数据中。
|
||
|
||
- 哈希不是 HDF5 文件自身哈希，不是仅入口 USD 的哈希，也不是浮动控制覆盖层的哈希。
|
||
- 它由完整解析资源包的相对路径与各文件 SHA-256 汇总生成，使用仓库工具获取，不自行猜测算法。
|
||
- 模型依赖内容或名称变化时必须重新对齐。分享本文给同事时，**请同时附上同版清单**，不要只发送失效的仓库相对链接。
|
||
|
||
## 7. 时间同步、无效帧与缺失数据
|
||
|
||
- `time[0]` 必须精确等于 `0.0`，之后严格递增；不得有重复、倒序时间戳。
|
||
- 允许非均匀采样，不强制视频帧率等于仿真控制频率。保留实际时间间隔，不通过伪造时间戳“拉齐”数据。
|
||
- 同一帧腕部、姿态和关节角必须已经同步；异步数据须由交付方先明确对齐方式。
|
||
- 任一必需部分缺失或不可信，整帧 `valid=false`。至少一帧有效；全部无效的 episode 会被拒绝。
|
||
- **所有数值都必须有限，包括无效帧，不能出现 NaN/Inf。** 无效帧可以用明确的有限占位值，
|
||
但必须保留 `valid=false`，并在来源说明中解释。无效帧四元数不要求单位化。
|
||
- 必填 dataset 不能省略；禁止把缺失帧补零后标成有效，或把插值/估算值冒充测量。
|
||
- 当前重采样 CLI 只接受全有效 episode，不跨无效片段插值。建议交付方将连续有效片段显式切成
|
||
独立 episode，并为每段重新设置从 0 开始的时间；原片段来源需可追溯。
|
||
|
||
## 8. 导出注意事项
|
||
|
||
使用 `h5py` 时，字符串必须显式声明 UTF-8，数值类型按契约转换：
|
||
|
||
```python
|
||
# 仅展示 dtype 写法；不是完整数据生成器，不包含真实轨迹。
|
||
import h5py
|
||
import numpy as np
|
||
|
||
utf8 = h5py.string_dtype(encoding="utf-8")
|
||
# metadata.create_dataset("joint_names", data=joint_names, dtype=utf8)
|
||
# group.create_dataset("time", data=np.asarray(time, dtype=np.float64))
|
||
# group.create_dataset("wrist_position", data=np.asarray(position, dtype=np.float32))
|
||
# group.create_dataset("wrist_quaternion", data=np.asarray(quaternion_wxyz, dtype=np.float32))
|
||
# group.create_dataset("joint_position", data=np.asarray(q, dtype=np.float32))
|
||
# group.create_dataset("valid", data=np.asarray(valid, dtype=np.bool_))
|
||
```
|
||
|
||
不要用 `dtype="S"` 或普通 ASCII bytes 数组写 `joint_names`。不要用 float64 替代契约中的 float32，
|
||
也不要用整数时间戳或整数 `valid` 代替约定类型。
|
||
|
||
## 9. 交付及验收流程
|
||
|
||
### 数据方交付
|
||
|
||
1. 一份包含一条短轨迹的 `.hdf5` 样例，优先选择连续、全有效、缓慢运动的片段。
|
||
2. 对应模型清单/版本确认。
|
||
3. 明确的标定与重定向说明；写入根属性，也可附独立说明文件。
|
||
4. 可选：对应原视频片段或可视化，便于人工核对方向、尺度与动作，不是本格式必填字段。
|
||
|
||
### 仿真方校验
|
||
|
||
从仓库根目录运行：
|
||
|
||
```bash
|
||
export PYTHONPATH="$PWD/source/dex_workbench${PYTHONPATH:+:$PYTHONPATH}"
|
||
~/isaacsim/python.sh -m dex_workbench_tracking.cli validate /path/to/demonstrations.hdf5 \
|
||
--manifest assets/robots/dex_hand/linkerhand_g20_left/tracking_manifest.json
|
||
```
|
||
|
||
该校验不启动仿真。仿真方本地的 `python.sh` 路径不是数据文件的依赖；具备项目模块、NumPy、h5py
|
||
的普通 Python 环境也可执行同一 `-m` 命令。
|
||
|
||
- **PASS**：schema、模型身份、关节顺序、限位和已记录联动一致。
|
||
- **FAIL**：修正具体报错后重新交付，不绕过校验器或放宽断言。
|
||
- 不加 `--manifest` 只检查格式，不能证明模型/关节兼容。
|
||
- 校验通过后仍需人工核对坐标和标定，再做受限动力学回放。格式通过不等于重定向正确、动力学可执行、
|
||
策略已经可训练或真机可运行。
|
||
|
||
**注意：** 当前诊断脚本要求腕部及全部五组联动都有足够运动，用于发现失效约束；这是诊断用例要求，
|
||
不是 HDF5 格式要求。合法的静止或局部手指轨迹不应为了满足诊断而添加伪造动作。
|
||
|
||
仿真实现与已有验证结果另见 [`L20_TRACKING.md`](L20_TRACKING.md)。本文只约定数据交付，不要求数据方运行 Isaac Sim。
|
||
|
||
## 10. 右手扩展：显式身份，不是左手镜像
|
||
|
||
本次校验器在 `l20_tracking_v1` 中接受 `hand_side="right"`；其余shape、dtype、坐标和有效帧语义不变。
|
||
旧版本校验器仅接受left，读取右数据必须升级本次代码。一个文件不能混合左右手episode。
|
||
|
||
右手必须使用 [`右手 tracking_manifest.json`](assets/robots/dex_hand/linkerhand_g20_right/tracking_manifest.json)，
|
||
该清单明确 `hand_side=right`，绑定已检查的右URDF身份。旧无side的左清单仍可读，右清单不得省略side。
|
||
左右文件对另一侧清单均拒绝；即使只篡改数据hash/root以匹配另一侧，仍会被side校验拒绝。
|
||
|
||
- `embodiment="L20"`、`root_link="hand_base_link"` 不变；**hand_side改为right**。
|
||
- 右原始转换USD依赖包 `asset_sha256`：
|
||
`d38dc5e4d473119b237b86bdd36087788f726abd9f486b1678f4e719d5513098`。
|
||
不是右prepared覆盖层哈希，不得复制到不同模型数据。
|
||
- 右当前也是21个状态关节；逐项名称与第5节列表一致，但必须仍按**右清单**排序核对，不能假设所有手型如此。
|
||
- 右拇指 `thumb_ip=1.03*thumb_mcp`，不是左手1.02；四指 `dip=.89*pip`，offset均0。
|
||
- 右 `thumb_cmc_pitch/roll/mcp` 上限分别 `.83/1.39/1.25 rad`，四指pip为`1.75 rad`。
|
||
其他值及浮点精确值按右清单 `lower_rad/upper_rad`；不使用文档舍入值放宽限位。
|
||
- 右URDF `thumb_cmc_yaw`轴为负Z，USD通过局部关节旋转表达。零位/方向必须按右模型重定向，
|
||
不能直接把左轨迹换hand_side/哈希当作右轨迹，也不能简单给全部角度取负。
|
||
- 数据样例仍应来自同版右模型。右手初次接入仅验证合成HDF5；后续一个独立绑定的专家参考
|
||
已完成80倍慢放回放，见 `L20_TRACKING.md` 第5节；不证明原速或任意专家数据可回放。
|
||
|
||
给右手数据同事发送本文时，附上同版**右清单**与右模型坐标/映射说明。模型来源、转换设置、
|
||
本地使用及发布限制见 [`右手资产说明`](assets/robots/dex_hand/linkerhand_g20_right/README.md)。
|
||
|
||
## 11. 状态输入ACT训练的额外准备（不改变HDF5 schema）
|
||
|
||
路线A的训练入口与详细契约见 [`L20_IMITATION.md`](L20_IMITATION.md)。
|
||
除本文的HDF5与模型清单，还需要仓库外的episode/capture-group划分JSON及绑定HDF5哈希的数据审查JSON。
|
||
至少两个独立来源组用于训练/验证，建议另留test组；同一录制的切片、慢放、重采样副本必须同组同分区。
|
||
单条样例不足以构造无泄漏训练/验证集，不能通过改名复制来补齐。
|
||
|
||
审查需明确坐标/尺度与同步依据、组来源，以及同意将未来参考状态作为实验目标代理。
|
||
不必为此伪造实测动作、速度、力矩或物体数据。初版ACT只做参考轨迹模仿，不证明已学会抓取。
|
||
示例模板默认不具备批准状态；收到独立核验材料前不得自动改为已审核。
|