Initial snapshot: hand motion pipeline (Dyn-HaMR + dex-retargeting + SPIDER)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-15 14:13:49 +08:00
commit 7e4ef6f98b
7002 changed files with 1452249 additions and 0 deletions
@@ -0,0 +1,217 @@
+# L20 左手专家轨迹 HDF5 交付要求
+
+**接口版本：`l20_tracking_v1`**
+
+**交付对象：视频重定向/示教数据同事**
+
+**当前用途：浮动腕部与全部手指参考关节的轨迹回放，后续用于学习策略。**
+
+本文是可独立分享的数据交付说明，与当前仓库校验器一致。它不是通用 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。