当前基线：2026-08-11。入口为 Dashboard /umi-dataset；标准归档格式为 自动识别 UMI 夹爪或 Ego 手姿的 LeRobot v3，UMI Zarr 仅用于旧训练栈兼容。

1. 在 Bags 或数据集页面选择已经停止录制、完成合并的 rosbag。
2. 选择 LeRobot 或 Legacy UMI，并填写任务名；episode、布局和图像模式用于夹爪路线。
3. LeRobot 先抽样腕部图像检测 UMI ArUco ID 1/0。重复检测到双标记时，把图像、TCP pose 和夹爪宽度对齐到 20 Hz；均无双标记时，走 30 Hz 三视角 Ego 手姿推理。
4. 查看任务日志，并抽查视频、Parquet/Zarr 元数据、episode 边界与有效性掩码。

每个源 rosbag 生成一个独立目录：

outputs/lerobot_datasets/<bag>_lerobot/
outputs/umi_datasets/<bag>_umi/

导出器不会把多条选中 bag 静默拼成同一数据集。

单臂状态为 10 维，双臂状态为 20 维：

single_arm_10d = xyz + rot6d + width
bimanual_20d = [left_10d, right_10d]

• 位置是米制绝对 EE 位置；rot6d 为旋转矩阵前两行；夹爪是米制物理开口宽度。
• 双臂布局的左右 pose 来自 /insight_global/.../pose，转换 camera center → TCP 后保存在 insight9_map 全局坐标系；单臂布局使用所选 Insight3 自身的 VIO 坐标系。
• 手别由相机配置中的 teleop_role 决定，不依赖设备名称后缀。
• TCP 坐标系由 tcp_frame_id 明确指定，左右手使用相同右手坐标系，不镜像左手。
• 所有 state/action 数值必须有限；缺失值写有限占位，并用逐维 validity 标为 false。
• 官方 LeRobot 键为 action，同时保存数值相同的 OpenPI 默认键 actions；对应有效性 分别为 action_valid 和 actions_valid。
• action[t] = T[t+1]，末帧复用当前 state 作占位且两套 action validity 全 false。
• 训练 adapter 在 normalization 前，以当前 T0 为统一参考计算每个未来绝对目标 inv(T0) @ T[k+1]；不得使用相邻未来帧之间的 sequential delta。夹爪保持未来绝对宽度。

TCP 定义和 Jetson NX 外参见主仓库 docs/UMI_TCP_FRAMES.md。

• Auto-split 在约 1 秒停顿处切分 episode。
• One rosbag 保持一条 bag 对应一个 episode。
• 网页当前默认 Original，保留各路原始分辨率。
• 显式选择 224×224 或 384×384 时，先取水平居中、底部对齐的最大正方形操作区， 再等比缩放，避免 portrait 画面被拉伸。640×544 输入对应 ROI [0,96,544,544]。
• 单臂视频键为 right_wrist_0_rgb；双臂键固定为 base_0_rgb、 left_wrist_0_rgb、right_wrist_0_rgb。NV12 腕部图必须保留 Y/UV 色度并完整解码为 三通道 RGB，不能复用夹爪检测的亮度快速路径。
• Parquet 保存统一 state 时间戳、各相机真实 rosbag 时间戳和逐路 validity。超出同步 容差的图像保留占位但标为无效，不能作为有效观测。

修改默认图像模式前应确认训练 adapter、存储预算和模型输入要求，不能只因为 “分辨率更高”就改变标准归档。

连续采集双夹爪夹起一次性纸杯并放入纸箱时，在 Dataset 页面选择 Production cup grasps · filter, label, verify。该模式固定使用双臂三相机布局和原始分辨率，后端会拒绝 224/384 请求，避免正式数据被误降采样。

生产模式执行以下质量链路：

1. 先按至少 0.8 秒停顿切候选小节，并沿用位置步长 + 局部速度创新、姿态和 pose 间隔门；
2. 只保留夹爪宽度至少变化 3 cm、以张开开始并以张开结束的完整开—闭—开循环；
3. 在主闭合前保留 2 秒、释放后保留 2.5 秒，排除人工复位纸杯和冗余空闲；
4. 对超过 30 mm/frame 的夹爪宽度跳变保留原始有限值，但把对应宽度维度标为无效；
5. 写入 approach_cup、grasp_and_transport_cup_to_box、open_grippers、 retreat_from_cup 四类逐帧标签和 meta/segments.parquet，每段至少 10 帧；
6. 完整解码三路输出视频，并验证 episode、时间戳、状态/action、任务索引及动作段覆盖；
7. 将通过的数据集计入 outputs/lerobot_datasets/cup_catalog.json，显示距离 500 条还差多少。

建议每个 rosbag 录 10～20 次，不要把 500 次放进一个包。每次动作结束后停稳至少 1 秒， 人工复位时不要移动夹爪。每个包独立输出为 <bag>_cup_lerobot/，便于失败重试、质量隔离和 分批训练。每个输出包含 meta/quality_report.json、meta/verification.json 和 review/atomic_action_contact_sheet.jpg；只有 verification 为 PASS 的 episode 才计入 累计 catalog。

当前三份生产验收共生成 25 条、4011 帧、200.55 秒。两路腕部保持 544×640，头部保持 1088×1920，均为 20 Hz；三路视频完整解码且图像 validity 无无效帧。夹爪宽度共检测到 319 个超过 30 mm/frame 的边，合并孤立尖峰后标记 269 个无效宽度帧；100 个动作段均不少于 10 帧。官方 lerobot==0.4.4 的 LeRobotDataset 已实际加载 12 条分片、跨 episode 取样、 以 PyAV 解码三路视频并运行 batch size 2 的 DataLoader。

TCP 平移连续性门分两步判断：先找超过 5 cm 的候选步长，再检查该步相对前后局部速度 的位移创新量是否也超过 5 cm。连续高速运动因前后速度一致而保留；VIO 重置或重定位 坐标跳变产生的孤立速度脉冲仍会拒绝。姿态 45° 和 pose 间隔 100 ms 门限保持不变。

只有导出器明确判定为质量不合格的 bag 才会重命名为 fail_<原名>；若同名目录已存在， 使用 fail_2_<原名> 等递增名称避免覆盖。fail_ 包仍保留在 rosbags/ 并显示于 Bags 页面，但从 Dataset 页面隐藏，直接提交导出 API 也会拒绝。以下失败必须保留原名：

• camera/profile 配置错误；
• TCP 或夹爪宽度标定缺失；
• pose/topic 缺失等现场系统问题；
• 导出器崩溃、磁盘或编码错误。

这是为了避免把可修复的环境问题误判成坏数据，同时确保质量拒绝不会自动删除原始录制。 需要永久清理时仍应在 Bags 页核对目录和体积后手工删除。

Dataset 页面会在未检测到夹爪双标记时自动调用 scripts/ego_lerobot_export.py。自动模式 使用整条 rosbag、页面任务文本和单动作段；需要精细裁剪或多段语义标注时仍使用下述命令与 版本化 spec。它交付头部、左腕、右腕三路图像，但仅在头部 RGB 上运行 WiLoR；腕部流只作为同步 上下文和高精度相机中心位置约束，不生成腕部手势检测。动作裁剪和多段标注保存在 config/dataset_schemas/*.json。

docker exec insight-dashboard python3 scripts/ego_lerobot_export.py \
  rosbags/<bag> outputs/lerobot_datasets/ego_hand/<name> \
  --spec config/dataset_schemas/<annotation>.json

相机左右角色只读取 teleop_role。当前物理映射为 insight3_b → left_hand、 insight3_a → right_hand；/tf_static 中父子 frame 含 tcp 的变换不会进入交付。 WiLoR 原始 handedness 保留，腕部相机中心投影仅用于拒绝明显离群伪标，之后再以保守的 单帧轨迹连续性规则修正明显左右身份误标，所有剔除和纠正写入 keyframes/manifest。

缓存按 rosbag 指纹、裁剪、相机配置、模型文件和质量阈值确定。相同输入复用最终缓存； 任务文本或动作段变化时复用基础视觉/手姿缓存，只重写标注和 overlay。首次转换仍需实际 推理和 H.264 编码。--hand-backend module:factory 可接入其他模型，factory 输出统一的 2D/3D 关键点、手腕姿态、MANO 参数、置信度与 handedness，后续处理无需修改。

• 两路手持相机的 teleop_role、tcp_frame_id、全局 pose 和 gripper width 必须与物理设备一致。
• Jetson NX 已配置 camera center 到左右 TCP 的静态平移；其他 profile 不能复用 其机械尺寸，必须现场标定。
• 当前 insight3_a 与 insight3_b 使用同一组实测夹爪像素/米制宽度标定；任一路 标定缺失或无效时，双臂 LeRobot 导出仍会安全失败。
• 导出成功不等于数据可训练；仍需抽查时序、episode 切分、图像方向、TCP 轴、 夹爪宽度范围、逐维 state/action mask 和逐路图像 mask。