openwam-robotwin-gt

OpenWAM Robotwin Ground Truth

在 RoboTwin 2.0 里按官方轨迹做物理回放，导出每个 episode 前 132 帧 head_camera 的 ground-truth，供 OpenWAM 等表征的下游 probing 使用。

状态：已完成。 Agilex 2500 个 episode、Franka 2300 个 episode，共 4800 个 HDF5，全部通过结构检查，上传后都用 sha256 与 Hub 上的文件核对过。

建议用本仓库里的 RGB 重新提取 feature。 回放的物理过程和官方原始数据不完全一致，越往后物体位置偏差越大（见与官方数据的差异）。如果 feature 仍然用官方 mp4 提取，后半段帧的 depth、分割、点云和 feature 看到的画面就可能对不上。改用本仓库 HDF5 里的 RGB 重新提取，图像和 GT 来自同一次渲染，逐帧严格对应。做法见用 GT 的 RGB 重新提取 feature。读取 RGB 时要特别注意颜色通道顺序。

目录结构

agilex/<task>/gt_export/data/episode<N>.hdf5        # 50 个 task × 50 个 episode
agilex/<task>/gt_export/data/episode<N>_extra.hdf5  # 补充 GT：位姿、分割 ID、手腕相机
agilex/<task>/gt_export/scene_info.json
franka/<task>/gt_export/data/episode<N>.hdf5        # 46 个 task × 50 个 episode
franka/<task>/gt_export/data/episode<N>_extra.hdf5
franka/<task>/gt_export/scene_info.json
reports/export_summary.json                    # 数量、帧数统计和各仓库版本
reports/agilex_status.json                     # 每个 episode 的帧数、sha256、对齐帧下标
reports/franka_status.json
reports/replay_success_check_failed.json       # 54 个回放未复现任务成功的 Franka episode
reports/drift/<embodiment>__<task>.json        # 每个 episode 相对官方 RGB 的偏差
reports/provenance.json                        # 版本号和所有本地改动
reports/robotwin-local.patch                   # 相对上游 RoboTwin 的完整 diff
tools/robotwin_gt_frames.py                    # 读帧和读 GT 的辅助函数（推荐使用）
tools/robotwin_gt_extra.py                     # 读 _extra 文件、计算任意像素 3D flow 和 2D 轨迹
tools/compute_drift.py                         # 生成 reports/drift 的脚本
reports/extra/<embodiment>__<task>.json        # _extra 文件的逐 episode 校验结果
reports/extra_summary.json                     # _extra 文件的完成数量和目标物体匹配统计

episode 的范围就是 OpenWAM 仓库里 agilex_robotwin10s_manifest.jsonl 和 franka_robotwin10s_manifest.jsonl 列出的全部 episode，按 (task, episode) 对应。

数据内容

episode<N>.hdf5 里的数据都只来自 head_camera，没有 wrist、front 等其他相机，也没有视频和语言指令。手腕相机画面和其他补充数据在 episode<N>_extra.hdf5 里，见补充 GT。T 是该 episode 的帧数（不超过 132）。

补充说明：

• 分割：存的是调色板颜色，不是物体 ID，也没有颜色和物体名的对照表。颜色只在同一个 episode 里稳定，可以用来区分实例。上游 RoboTwin 的调色板只有 139 种颜色，遇到 label ID 更大的资产（例如 open_laptop）会报错，所以我们把调色板扩展到 256 种，前 139 种颜色保持原样。
• 几何检查：cam2world_gl 转成 OpenCV 约定后与 extrinsic_cv 的差不超过 2e-7。把点云投影到同一帧的 depth 上，误差中位数是 0 mm；投影到相隔 4 帧的 depth 上，误差是几十毫米。这说明各模态来自同一帧。

补充 GT：位姿、分割 ID、手腕相机

每个 episode<N>.hdf5 旁边都有一个 episode<N>_extra.hdf5，供任意像素的 3D scene flow、点跟踪（TAPVid 指标）和多物体分割 probe 使用。

生成方式：用同样的代码和配置把每个 episode 重新回放一遍，额外记录下面这些数据。每个 episode 回放后，新生成的 episode<N>.hdf5 都和本仓库已发布的版本做了 sha256 比对，逐字节相同才接受。所以 _extra 文件和已有 GT 来自完全相同的仿真过程，逐帧对应。

和已有数据的关系： - 用原来的调色板映射 actor_id 和 mesh_id，得到的颜色和 episode<N>.hdf5 里的 actor_segmentation、mesh_segmentation 逐像素相同。 - 分割图里出现的每个 actor id，在 entities 里都有对应的条目。

目标物体（targets）：把 scene_info 里的占位符（{A}、{B}……）对应到 entity id。每个占位符带一个 status： - unique：值是 模型名/baseK，且场景里只有一个同名物体。 - mapped：值是颜色或尺寸描述（如 red block），或者多个物体同名（如两个 001_bottle）。这种情况按任务代码里的赋值关系，对应到具体的任务属性（如 block1、bottle2、bread[0]），同时在 task_attr 字段里写明用的是哪个属性。 - ambiguous：仍有多个候选，全部列在 candidates 里。例如 stack_bowls_two 和 stack_bowls_three 的占位符都是同一个碗模型，代码里也没有指明对应哪只碗。 - not_found、descriptive：没能对应到实体。

每个任务各种 status 的数量统计见 reports/extra_summary.json 的 target_status。 - handover_block 的 scene_info 本身是空的，它的两个物体可以从 task_objects 里的 box、target_box 取得。

验证结果： - 抽查 8 个 episode（Agilex 和 Franka 各 4 个，包括 open_laptop）： - 用位姿把运动物体（含机械臂各 link）的像素从第 t 帧推到第 t+4 帧，结果和那一帧深度的误差中位数是 0.16–0.43 mm。 - 手腕相机的内外参和官方数据逐帧完全相同；RGB 误差 0.1–0.75/255，与 head 相机同一水平。

计算任意像素的 3D flow 和 2D 轨迹：

from robotwin_gt_extra import load_extra, dense_flow
ex = load_extra(".../episode0_extra.hdf5")
f = dense_flow(".../episode0.hdf5", ex, t=0, t2=4)
# f["p1"], f["p2"]: (240, 320, 3) 世界坐标，3D scene flow = p2 - p1
# f["u2"], f["v2"]: 第 t2 帧的 2D 位置；f["visible"]: 在视野内、没被遮挡、且仍属于同一实体
# f["entity_id"]: 每个像素所属实体，可以和 ex["is_robot"]、ex["targets"] 组合，按机器人、物体、背景分组

dense_flow 的做法是：先用深度把像素反投影到 3D，再乘上该像素所属实体的 pose_{t2} · pose_t⁻¹，最后投影回图像。遮挡判断用第 t2 帧的深度（默认容差 1 cm），并要求像素仍落在同一实体上。所以如果一个点被同一物体的其他部分挡住，也会被判为不可见。

帧数与对齐帧

• 帧数：每个 episode 的帧数 = min(132, 官方视频帧数)，4800 个 episode 全部核对过。Agilex 有 1963 个 episode 满 132 帧、537 个不足；Franka 分别是 957 个和 1343 个。
• 对齐帧：请全程只用下面这一条规则，feature 提取和 GT 提取都一样（tools/robotwin_gt_frames.py 里的 feature_indices 就是它）：

python ids = np.arange(33) * 4 # 0, 4, ..., 128 if ids[-1] >= T: # 即 T < 129 ids = np.linspace(0, T - 1, 33, dtype=np.int64)

• 与旧脚本的差异：旧的 feature 提取脚本在这里不统一。extract_openwam_features.py 在 T ≥ 129 时用 arange，而 extract_robotwin_dinov2.py 等脚本在视频帧数 ≤ 132 时就改用 linspace。官方视频帧数在 129–132 之间的 44 个 episode（Agilex 30 个、Franka 14 个）因此选到了不同的帧。重新提取时统一用上面的规则，就不会再有这个问题。

用 GT 的 RGB 重新提取 feature

1. 读帧：用 tools/robotwin_gt_frames.py 读帧，不要再读 manifest 里 video 字段指向的 mp4：

python from robotwin_gt_frames import load_rgb_frames, load_gt ids, frames = load_rgb_frames(".../franka/adjust_bottle/gt_export/data/episode0.hdf5") # frames 是 33 张 RGB 格式的 PIL.Image，大小 320×240；ids 是对应的帧下标 gt = load_gt(".../episode0.hdf5") # depth、分割、点云、位姿等，按同一组 ids 取出

5 个提取脚本只需要换掉读取视频的那部分，后面的 resize 和预处理保持不变： - extract_openwam_features.py 的 frames()、extract_robotwin_dinov2.py 的 read_frames()、extract_robotwin_depth_features.py 的 read_frames()：换成 load_rgb_frames。这些函数原来返回的是 numpy 数组还是 PIL 图像各不相同，按需要用 np.asarray(img) 转换。 - extract_robotwin_d4rt_encoder.py：没有单独的读帧函数，是在 main() 里直接用 cv2.VideoCapture(row['video']) 读的，替换那一段即可。 - extract_robotwin_videomaev2_features.py：它的 read_frames() 读完帧后，还会再用 linspace 抽成 --frames 帧。只替换 read_frames()，后面这次抽帧保持原样。

1. 颜色通道（最容易出错的一步）：RoboTwin 把 RGB 数组直接交给 cv2.imencode 编码，而 OpenCV 默认输入是 BGR，所以存下来的 JPEG 字节里 R 和 B 是反的。 - 正确做法：用 cv2.imdecode(buf, cv2.IMREAD_COLOR) 解码，结果已经是 RGB，不要再做 BGR2RGB 转换。 - 错误做法：用 PIL、torchvision、ffmpeg 等解码，得到的会是 BGR。 - 验证：load_rgb_frames 已经按正确方式处理。我们用点云自带的 rgb 颜色和官方 mp4 分别验证过：franka/adjust_bottle/episode0 按正确方式解码，与官方 mp4 的 MAE 是 1.46/255；把通道弄反则是 2.82/255。 - 这个问题只影响 observation/head_camera/rgb。pointcloud 里的颜色顺序是正确的。

2. 编码格式：原来的输入是 H.264 编码的 mp4，现在是 JPEG。两者画质都很高，对 feature 的影响应该很小。如果希望和旧 feature 的输入完全同分布，可以先把帧按原参数重新编码成 mp4 再读。

3. 下游分析：换成新 feature 后，CKA、mKNN 等结果最好全部基于新 feature 重算，不要和旧 feature 的结果混用。

与官方数据的差异

回放时用的是和官方完全相同的轨迹文件（源 pkl 与官方 sha256 一致），joint_action 与官方逐帧相同，误差为 0，相机内外参也完全一致。差异只出在物体的物理状态上：回放越往后，物体位置和官方原始数据的偏差越大。

• 量化方法：reports/drift/ 里是每个 episode 在 33 个对齐帧上相对官方 *_clean_50 HDF5 中 RGB 的偏差，由 tools/compute_drift.py 生成。两个指标：
• mae：像素平均绝对误差，单位 /255。
• changed_frac：任一通道差超过 30 的像素所占比例，适合反映物体被挪动了多少。
• 例子：Franka place_bread_skillet 的正常 episode，末帧 MAE 在 1–12 之间；回放没复现任务成功的 episode 最高达到约 25，changed_frac 约 0.19。
• 如果继续用旧 feature（从官方 mp4 提取），可以按这两个指标设阈值，筛掉偏差大的 episode 或帧。
• 如果按上文重新提取 feature，图像和 GT 逐帧一致，这部分差异就不影响对齐了。

回放未复现任务成功的 episode

reports/replay_success_check_failed.json 列出 54 个 Franka episode，都是短 episode（70–124 帧）。它们回放完整条轨迹后，check_success() 没有通过：机器人动作和原始数据完全相同，但物体最终没到达目标位置。

• 重试无效：重跑了 3 次，结果逐字节相同，属于确定性的偏差，重试解决不了。
• 数据本身没问题：这些 episode 的 GT 与回放画面仍然一一对应，也通过了全部结构检查。
• 需要排除的情况：如果下游用到"任务成功"之类的语义，请把它们排除掉。

按 task 统计：

版本与复现

采集配置：只开 head_camera，max_gt_frames: 132，stop_after_gt_frames: true，关闭 domain randomization，数值数据用 gzip level 1 加 shuffle 无损压缩。

本地改动：相对上游 RoboTwin 的改动完整列在 reports/provenance.json 的 local_changes 里，diff 见 reports/robotwin-local.patch。其中两处会影响复现：

• front camera 的随机数：Agilex 关掉 front camera 后，仍然保留它原本会消耗的随机数抽取。否则物体初始位置和选用的机械臂都会和源数据不同。
• 调色板：扩展到 256 色，原因见上文"补充说明"。