Spaces:
Running
Running
File size: 57,035 Bytes
ddb63ef | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 | # 多设备采集存储结构接口文档
> 适用版本:collector v1.3.x 起的任务级池化布局(`format = "pooled_episodes_v1"`)
> 文档定位:本文是 [`docs/file_format.md`](file_format.md)(规范性契约)的**多设备补充**,
> 回答三件事——**不同设备的数据存哪、叫什么名字、在 meta 里怎么声明**。
> 布局/编号/原子写/上传契约以 `file_format.md` 为准;本文与它冲突时以它为准。
>
> 图例:
> **【现状】** = v1.3.x 已在代码中实现、磁盘上已有数据;
> **【提案】** = 为「双夹爪 + ego 相机三条 SLAM 轨迹」新增的约定,需改代码后才生效。
---
## 1. 存储布局
### 1.1 目录树(一条 episode 的全部文件)
```
data/recordings/<任务名>/
├── data/
│ └── chunk-{c:03d}/
│ └── episode-{f:03d}.parquet # 本段所有非视频观测(每帧一行)
├── videos/
│ └── chunk-{c:03d}/
│ ├── <image_key_1>/episode-{f:03d}.mp4
│ ├── <image_key_2>/episode-{f:03d}.mp4
│ └── <depth_key>/episode-{f:03d}.mp4 # 深度流(12-bit 灰度;回落 .mkv)
└── meta/
├── info.json # 任务级 schema/声明(读端入口)
├── stats.json # 任务级统计(定长列)
├── tasks.jsonl
└── episodes/
└── chunk-{c:03d}/
└── episode-{f:03d}.parquet # 本段一行元数据(含每段权威规格)
```
### 1.2 三条铁律
1. **一条 episode = 一个 `(c, f)` 编号 = 1 个 data parquet + 每路录制流 1 个视频 + 1 个 episodes 行文件。**
2. **所有非视频观测都进那一个 data parquet**:压力矩阵、手套 IMU、手部关键点、双目
IMU、夹爪力/力矩阵/状态、**所有 SLAM 轨迹**,全部是这张表的列,**没有按设备
拆分的子目录或轨迹侧车文件**(2026-09-10 定案废除轨迹 txt)。
3. **视频每流一个文件**,按 `<image_key>` 分目录;同一任务的视频槽允许跨 episode
改名,读端必须按 episodes 行/每段实际文件枚举,不能假设任务级固定集合。
### 1.3 编号规则(磁盘段号 0 基,parquet 列 1 基)
磁盘上的 episode 段号**从 0 开始**:`episode-000` 就是第 1 段。设 `k` 为任务内的
**全局 0 基段号**(0, 1, 2, …),则路径固定为:
```
c = k // 1000 # chunk 号;chunk-000 装 k=0..999
f = k % 1000 # chunk 内文件号,三位零起
data/chunk-{c:03d}/episode-{f:03d}.parquet
```
| 第几段 | `k`(0 基段号) | 文件 | parquet `episode_index` 列 |
|---|---|---|---|
| 1 | 0 | `chunk-000/episode-000` | 1 |
| 2 | 1 | `chunk-000/episode-001` | 2 |
| 1000 | 999 | `chunk-000/episode-999` | 1000 |
| 1001 | 1000 | `chunk-001/episode-000` | 1001 |
- **两套编号不要混**:
- **文件/段号 `f`(0 基)**:磁盘上的段标识,也是上传表单 `episode_index` 的值
(`core/uploader.py:581` 用 `episode_file_suffix()` = `k % 1000`)。
- **parquet `episode_index` 列(1 基)** = `k + 1`;`list_task_episodes()` 按
`chunk*1000 + f + 1` 还原。实测 `UMI_9_29/data/chunk-000/episode-000.parquet`
该列为 **1**,不是 0。
- `next_pooled_episode_index()` 对空目录返回 **1**(即 k=0),生产路径不会取到 0;
`episode_chunk_file(0)` 会被钳到 `(0,0)`,所以测试里把 `_episode_index=0` 也落到
`episode-000` —— 这是代码里唯一出现 0 的地方,**别据此认为列也是 0 基**。
- `chunks_size = 1000` 由 `info.json` 声明,读端不得写死。
- 同一 episode 的 data / videos / meta-episodes 三处**共用同一个 `(c, f)`**。
- 跨 chunk 时 `f` 会回绕(第 1001 段是 `chunk-001/episode-000`),**不要**拿
「最大 `f` + 1」当段号;统一走 `core.helpers.list_task_episodes()`。
- 异常终止不占号(`meta/recycled_episode.json` 标记复用);正常完成/删除的号永不复用。
### 1.4 这里**不放**什么
| 内容 | 实际位置 | 说明 |
|---|---|---|
| 手部关键点后处理结果 | `keypoints_output/<task>/episode_{episode_index:06d}/`(parquet 列值,1 基;第 1 段是 `episode_000001`) | 不写回录制目录 |
| 标定文件 | `meta/info.json` 的 `calibration` + 每段 episodes 行 | 没有 `calibration/` 目录 |
| 设备命名/曝光配置 | `data/device_names.json` / `data/device_params.json` | 本地配置,不进录制目录 |
| 上传临时切片、锁、回收标记 | 见 `file_format.md` §11 | 读端一律忽略 dotfiles 与临时件 |
---
## 2. 命名规范
### 2.1 三个命名空间,不要混用
| 命名空间 | 形态 | 出现位置 | 谁生成 |
|---|---|---|---|
| **设备 key** | `<kind>:<稳定标识>`,如 `d435:213622075531`、`gripper:CC:BA:97:25:B4:44` | `info.json` 的 `devices[].key`、`data/device_names.json` / `device_params.json` | `core/device_detector.py` |
| **视频槽 image_key** | `<前缀>_rgb` / `<前缀>_depth` / `stereo_left` … | `videos/<image_key>/`、`cameras`、`video_extensions`、`device_names` | UI 打开设备时分配(§2.3) |
| **parquet 列名** | `observation.<...>` / `status.<...>` / 顶层键列 | data parquet schema、`info.json.features` | pipeline + writer |
设备 key 与列名**没有派生关系**:`d435:213622075531` 对应哪一列,只能通过
`devices[].slots` + `features` 查,不能从 key 字符串拼。
### 2.2 列名语法
```
observation.<namespace><signal> # 观测列(数值/序列/轨迹)
status.<UVC槽|传感器名|夹爪非视频槽> # 连接状态列(string)
<key_column> # 帧键列:episode_index / frame_index / timestamp / …
```
`<namespace>` 取值表:
| namespace | 归属 | 示例 | 现状 |
|---|---|---|---|
| `""`(空) | 第 1 台 UMI 夹爪(历史契约) | `observation.slam_trajectory`、`observation.gripper_state` | 【现状】 |
| `gripper_2_` | 第 2 台 UMI 夹爪 | `observation.gripper_2_slam_trajectory`、`observation.gripper_2_gripper_state` | 【现状】 |
| `ego_` | ego 相机(角色名) | `observation.ego_slam_trajectory` | 【提案】 |
| 传感器名本身(`left_glove` / `right_glove`) | 数据手套(BLE/USB) | `observation.left_glove`、`observation.left_glove_imu_quat` | 【现状】 |
| 无 | 手部关键点(恒写列) | `observation.left_hand_pose` | 【现状】 |
**注意**:夹爪的力/状态列在写入时是「前缀 + 完整旧键」,所以第 2 台是
`observation.gripper_2_gripper_left_force`(两个 `gripper` 不是笔误),而轨迹列因为
信号名本身不含 `gripper`,才是 `observation.gripper_2_slam_trajectory`。写读两侧
都按**前缀拼接**处理,不要手写名字时想当然。
### 2.3 多实例编号规则
| 规则 | 说明 |
|---|---|
| **首台不编号** | 夹爪 rig1 必须是空串前缀(现有 357 段数据依赖),**禁止**改名为 `gripper_1_` |
| **第二台起加 `_2`** | 槽名 `d435_rgb_2`、`gripper_2_rgb`;列前缀 `gripper_2_` |
| **新命名空间首台用角色名** | ego 首台就是 `ego_`(没有历史包袱);第二台 `ego_2_` |
| **编号 = 打开顺序(夹爪)** | `ui/main_window.py:1625`:先开的是 rig1。落盘 `devices[].key` 含序列号,事后可核对;但「哪条轨迹属于哪只手」只存在于打开顺序里(见 §5.2 建议) |
### 2.4 字符集与保留词
- 列名点分段只允许 `[a-z0-9_]+`;**全小写、纯 ASCII**。
- 视频槽名由 `core/device_naming.slot_base()` 清洗(非法字符 → `_`,可含中文);
列名**不走**清洗,必须由写入方自己守规则。
- 保留后缀(writer 按后缀定类型,`core/egodata_writer.py:808-830`):
`slam_trajectory`、`slam_trajectory_ns`、`_force`、`_force_matrix`、`_force_ns`、
`_force_matrix_ns`、`_state`、`_imu_quat`、`_imu_valid`、`_hand_pose`。
新增信号名不得以这些后缀结尾,除非语义就是它们。
- 禁用名:`slam_pose`(已废除,writer 静默忽略)、`gripper_1_*`、
`observation.images.*`(本仓库视频不进 features)。
- 同一任务的列名**不得跨 episode 改名**(`features` 是任务级并集,改名会留下
两个键,且旧键永久残留)。
---
## 3. 每段都有的公共列
| 列 | 类型 | 语义 |
|---|---|---|
| `episode_index` | int64 | parquet 全局 1 基序号 = 磁盘段号 `k` + 1(§1.3;`episode-000` 里是 1) |
| `frame_index` | int64 | 段内帧号,0 起递增、无空洞 |
| `timestamp` | float32 | 会话相对秒(该帧的写入时间) |
| `task_index` | int64 | 任务号,现恒 0 |
| `wall_time` | float64 | 本段起始墙钟 + 行相对时刻(v1.3.17 起):采集时刻的绝对 Unix 秒,段内严格递增 |
| `hardware_ns` | int64 | 该视频帧的采集时刻(v1.3.11 起为「锚点 + 序号 × T」的归一序列) |
| `raw_hw_ns` | int64 | **条件列**:归一前的原始设备戳(v1.3.11);本段至少一帧带原始戳时才写,其余行 0 |
| `action` | list\<float32,1\> | 恒写占位(当前 `[0.0]`) |
| `status.<id>` | string | 该槽位/传感器在本帧的连接状态(`connected` / `disconnected`) |
`status.<id>` 的 `<id>` 范围 = **`CameraWorker` 视频槽**(只有 UVC 走 `add_camera`,
进 `_slots`)+ 传感器列名(`left_glove`/`right_glove`)+ 夹爪非视频槽
(`gripper_pose`、`gripper_force_left/right` 及其 `gripper_2_*`)。**不含**设备 key,
也**不含外部帧源**(D435/S80M/夹爪 RGB 走 `register_external_source`,不在 `_slots`
里,因此没有 `status.<slot>` 列)。
### 3.1 七种时间语义,不能混
| 时间 | 盖戳方 | 时钟 | 用途 |
|---|---|---|---|
| `wall_time` | 写线程 | 宿主墙钟(Unix 秒) | 行落盘时刻,跨设备粗对齐 |
| `timestamp` | 写线程 | 会话相对秒(f32) | 段内相对时间 |
| `hardware_ns` | 采集侧 | 宿主钟链路=采集时刻(原样);设备钟链路(D435)归一后均匀递增 | 帧的主时间锚;跨模态对齐优先用 `timestamp` |
| `raw_hw_ns` | 采集侧 | 原始设备钟 | 审计真实到达/采集节奏 |
| `*_ns`(力/矩阵/轨迹) | 采集侧回调 | 宿主单调钟 ns | 样本级精确配对 |
| `slam_trajectory[i][0]` | SLAM 进程 | **相机传感器钟**(秒,ENTER 为原点) | 轨迹内部时间,**与 `hardware_ns` 不同源** |
| `imu_ts_ns` | SDK | 设备钟 ns | IMU 样本时刻 |
⚠ `slam_trajectory` 的 `t` 与 `hardware_ns` 之间只差一个「近似常量但带抖动」的
偏移(实测三个反推估计散布 ~104 ms,已超一帧)。**只能靠同序并行的
`slam_trajectory_ns` 配帧,不许拟合偏移,更不许把 `t` 当宿主时间用。**
---
## 4. 设备类型 → 数据落点
### 4.1 总表
| 设备 kind | 设备 key 示例 | 视频槽(videos/) | parquet 数据列 | info 声明 |
|---|---|---|---|---|
| `uvc` | `uvc:usb-DECXIN_…` | `head_left_rgb`(索引0)、`head_right_rgb`(1)、`head_right_rgb_N`(N≥2) | 仅 `status.<slot>` | `cameras`、`video_extensions`、`devices`、`device_names` |
| `d435`(D435/D405) | `d435:<serial>` | `<base>_rgb`、`<base>_depth`(同前缀多台 `_2`) | `hardware_ns`、`raw_hw_ns`、`depth_ns`、`rgb_dup`、`rgb_gap`、`depth_dup`、`depth_gap`、`ts_src`、`host_ns` | `cameras`(仅 RGB)、`video_extensions`(含深度)、`devices`、`calibration` |
| `s80m`(S80M/S80C) | `s80m:<sn>@<usb路径>` 或 `s80m:ftdi` | `stereo_left`、`stereo_right`、`stereo_depth` | `hardware_ns`、`raw_hw_ns`、`imu_ts_ns`、`observation.imu` | `cameras`、`video_extensions`、`devices`、`calibration.head_stereo` |
| `data_ble`(BLE 手套,主程序录制 kind) | `ble:<MAC>` / `usbglove:<serial>` | 无 | `observation.<sensor>`(16×16)、`status.<sensor>` | `sensors`、`sensor_dim`、`devices`、`features` |
| `ble`(其它 BLE,检测兜底) | `ble:<MAC>` | 无 | 主程序占位、不产数据;lite 的「BLE 手套」入口可按手套录制(数据同 `data_ble`) | 主程序不进 `devices`;lite 以 `ble_glove` 进 `devices` |
| `usb_glove`(USB 手套) | `usbglove:<serial>` | 无 | `observation.<sensor>`、`observation.<sensor>_imu_quat`、`…_imu_valid`、`observation.left/right_hand_pose` | `sensors`、`sensor_dim`、`devices`、`features` |
| `gripper`(UMI 夹爪) | `gripper:<MAC>` | `gripper_rgb`(rig1)/ `gripper_2_rgb`(rig2);`*_stereo_left` **只显示不录制** | 力/力矩阵/状态/轨迹(§4.6);RGB 行带 `raw_hw_ns` | `cameras`(仅 RGB)、`video_extensions`、`devices`、`features`、`gripper_slam_frame` |
| ego 相机 | 实际是 `d435`/`s80m`/`uvc` 之一 | 该设备的 RGB 槽 | 该设备已有列 + `observation.ego_slam_trajectory(_ns)`【提案】 | 上述 + `slam_frames`【提案】 |
> 「ego 相机」不是独立 kind,而是一个**角色**:本仓库里通常是头戴 S80C/S80M 双目
> 或 D435。角色与轨迹的绑定写在声明里(§6.6),不靠槽名字符串猜。
### 4.2 UVC 相机
- **落点**:`videos/chunk-{c:03d}/<slot>/episode-{f:03d}.mp4`;data parquet 只有
`status.<slot>`,**没有观测数值列**。
- **槽名**:`settings._camera_slot_name(index)`:0→`head_left_rgb`,1→`head_right_rgb`,
N≥2→`head_right_rgb_N`。
- **声明**:`cameras[slot] = {height, width, fps?}`、`video_extensions[slot]="mp4"`;
设备段 `{key, kind:"uvc", name, slots:[slot]}`。
- 多路 UVC:每路独立槽名,互不覆盖;设计上限 `settings.MAX_CAMERAS = 8`。
### 4.3 D435 / D405(RGB + 深度)
- **视频**:RGB 写 `videos/<rgb_slot>/…`;深度**不建 cameras 条目**,但写
`videos/<depth_slot>/…`(12-bit 灰度 MP4,x265 无能力时回落 FFV1 MKV)。
- **槽名**:`core/device_naming.allocate_slot_names()` 分配。用户命名为 `D405_head`
→ `D405_head_rgb` / `D405_head_depth`;未命名回落 `d435_rgb` / `d435_depth`;
同前缀多台追加 `_2`(`d435_rgb_2` / `d435_depth_2`)。
- **数据列**:D435 链路独有取证列(`extra` 非空才写):
`depth_ns`(int64)、`host_ns`(int64)、`rgb_dup`/`depth_dup`/`ts_src`(int8)、
`rgb_gap`/`depth_gap`(int32)。其它设备链路**没有**这些列。
- **深度节拍**:深度帧随主槽(`master_slot = <rgb_slot>`)每拍落一帧;深度源缺帧
时重复最近帧,保证深度第 i 帧与 RGB 第 i 帧对齐。
- **声明**:`cameras` 只列 RGB 槽;`video_extensions` 列 RGB + 深度两个 key;
`devices[].slots` 列两个槽。
### 4.4 S80M / S80C 双目
- **视频**:`stereo_left`、`stereo_right`(每路一个 MP4);`stereo_depth`(12-bit
灰度,S80C 深度引擎可用时)。
- **数据列**:
- `hardware_ns`:SDK 硬件戳(与 IMU 同源);
- `imu_ts_ns`(list\<int64\>) + `observation.imu`(list\<list\<float32,6\>\>):
**只挂在 `stereo_left` 主槽**(左右目共享同一份,避免重复行);
- `raw_hw_ns`:归一前原始戳。
- **限制**:`stereo_left/right` 是全局槽名,**同一时刻只支持一台 S80M**;
与 D435/D405 冲突(共用 `video0/video2`)。
- **声明**:`cameras` 含左右目;`video_extensions` 再加 `stereo_depth`;
`calibration.head_stereo`(首个注册了标定的设备,即 §6.5 的 `head_stereo`);
`devices` 含 `serial`(紧凑段里**不写** serial,见 §6.4)。
### 4.5 数据手套(BLE `data_ble` / `ble`,USB `usb_glove`)
BLE **不是「无数据」通道**:BLE 手套就是常规数据源,16×16 压力帧照常录进
`observation.<sensor>`(`core/ble_engine.py` 的 `SensorBLEEngine.data_ready` →
pipeline `write_sensor`)。「检测成 `ble`」只说明广播名不像手套、且还没绑定
sensor 列,不等于设备没有数据。
- **无视频**,全部进 data parquet:
| 列 | 类型 | 说明 |
|---|---|---|
| `observation.<sensor>` | list\<float32,256\> | 16×16 压力矩阵展平(`sensor_dim=256`);**固件原始通道号**,左手需 `core.render_engine.canonical_pressure_matrix()` 还原 |
| `observation.<sensor>_imu_quat` | list\<float32,64\> | 16×4 XYZW 四元数(USB 手套) |
| `observation.<sensor>_imu_valid` | list\<float32,16\> | 逐传感器有效掩码 |
| `observation.left_hand_pose` / `right_hand_pose` | list\<float32,63\> | 21 关节 × xyz,**恒写列**,无解算时全零占位 |
| `status.<sensor>` | string | 连接状态 |
- **检测态 vs 录制态**:
- `data_ble`:广播名含 `Matrix`/`L`/`R`,或 `device_names.json` 里已绑定
`sensor` 列 → **主程序**直接按手套打开并录制(`_open_glove`)。曾用 lite
绑过一次的 MAC,之后在主程序也会被判成 `data_ble`。
- `ble`:名字不像手套且未绑定 → 主程序只开占位画面(`_open_ble_placeholder`,
显示「该设备无可视化数据」);**lite 的「BLE 手套」入口会把它当手套打开**
(`ui/lite_window.py:_open_ble_glove`),分配 sensor 列并录制,和 `data_ble`
落盘内容一致。绑定后该 MAC 再被检测就是 `data_ble`。
- `usb_glove`:USB-C 手套(串口引擎),主程序与 lite 都录。
- **`devices[].kind` 随程序不同**(读端别只认一个值):
- 主程序:BLE 与 USB 手套统一写 `kind: "data_ble"`(`glove_entry` 硬编码);
- lite:BLE 写 `"ble_glove"`、USB 写 `"usb_glove"`,且 `slots` 放 sensor 列名
(`["left_glove"]`),因此 lite 的 `device_names` 里有手套列 → 设备绑定。
- **传感器列名**:`left_glove` / `right_glove`,由 `settings.assign_glove_sensor_role()`
按 MAC/序列号持久化到 `data/device_names.json`;**第 3 只手套拿不到空闲列名,
拒绝连接**(历史上曾静默映射成 `left_glove` 导致两路互相覆盖)。
- **声明**:`sensors = ["left_glove","right_glove"]`、`sensor_dim=256`、
`features` 逐列声明;设备段 `{key, kind, name, slots}`(kind/slots 见上)。
⚠ **主程序**的紧凑设备段丢掉了 `sensor_column`、`slots` 为空,所以「哪只手套
对应哪一列」在磁盘上只能靠 `name` 与列名的约定推断;lite 用 `slots=[sensor]`
补上了这个绑定(§6.4)。
### 4.6 UMI 夹爪(单台 / 双台)
**视频**:`gripper_rgb`(rig1)/ `gripper_2_rgb`(rig2)是唯一录制的流;
`gripper_stereo_left` / `gripper_2_stereo_left` **只用于 SLAM 与显示,不落视频**
(从未注册外部帧源)。
**数据列**(rig1;rig2 全身加 `gripper_2_` 前缀):
| 列 | 类型 | 说明 |
|---|---|---|
| `observation.gripper_{left,right}_force` | list\<float32,3\> | `[fx,fy,fz]` mN |
| `observation.gripper_{left,right}_force_ns` | int64 标量 | 该力样本采集时刻(宿主单调钟;无样本填 0) |
| `observation.gripper_{left,right}_force_matrix` | list\<int16\> 或 list\<float32\> | 250×250×3 力矩阵,`250×750` 展平;编码见 info `features.encoding` |
| `observation.gripper_{left,right}_force_matrix_ns` | int64 标量 | 力矩阵样本采集时刻(独立泵线程,与力值各记各的) |
| `observation.gripper_state` | list\<float32,3\> | `[open_pct, gripped, fz_mn]` |
| `observation.slam_trajectory` | list\<float64\> | 轨迹点 `[t,x,y,z,qx,qy,qz,qw]`×N,变长 |
| `observation.slam_trajectory_ns` | list\<int64\> | 与轨迹点**同序等长**的宿主时刻 |
| `status.gripper_pose` / `status.gripper_force_left` / `status.gripper_force_right` | string | 非视频槽的连接状态 |
rig2 的实际列名(易错,照抄):
```
observation.gripper_2_gripper_left_force
observation.gripper_2_gripper_left_force_ns
observation.gripper_2_gripper_left_force_matrix
observation.gripper_2_gripper_left_force_matrix_ns
observation.gripper_2_gripper_state
observation.gripper_2_slam_trajectory
observation.gripper_2_slam_trajectory_ns
```
**稀疏语义**:列级稀疏(本段真的出现过该列才建);行级无样本时,定长列填 `[0.0]*3`,
变长轨迹填 `[]`。
**声明**:`features` 逐列(力矩阵必须带 `encoding` + `scale`);有 SLAM 的任务写
`gripper_slam_frame`,并逐列写 `features[...].frame/frame_axes`;设备段 slots 列
全部 5 个槽(含只显示不录制的双目槽与 pose/force 槽)。
### 4.7 ego 相机与 ego SLAM【提案】
ego 相机的**视频/深度/IMU**沿用其宿主设备(§4.2–4.4)的规则,不新增存储位置。
它独有的是**自己的一条 SLAM 轨迹**:
| 列 | 类型 | 说明 |
|---|---|---|
| `observation.ego_slam_trajectory` | list\<float64\> | 点 `[t,x,y,z,qx,qy,qz,qw]`×N,`[]` = 本行无新点 |
| `observation.ego_slam_trajectory_ns` | list\<int64\> | 与点同序等长的**取样帧宿主时刻** |
- 命名用**角色前缀 `ego_`**,不用槽位名(`d435_rgb_` / `stereo_left_`)——换机时角色
不变、槽名会变;第二台 ego 用 `ego_2_slam_trajectory`。
- 若 ego SLAM 是**离线后处理**产物:允许事后往同一 episode parquet 补这两列,但
`_ns` 必须是**取样帧的宿主时刻**(与 `hardware_ns` 同时基),不能写处理时刻。
- ego 轨迹的 `frame`/时基/原点与夹爪**大概率不同**,必须逐列声明(§6.6)。
### 4.8 深度通道规则(所有深度设备统一)
- 深度槽**不建 `cameras` 条目**,但必须有 `video_extensions[<depth_key>]`(`mp4` 或 `mkv`)。
- 存储为**单流**:12-bit 灰度 HEVC(`gray12le`,对数深度码)或 FFV1 `gray16le` 无损 MKV;
解码走 `core/depth_codec.py` / `core/depth_reader.py`。
- 一个深度槽跟随一个主槽(`master_slot`)同步落盘;多深度设备各自独立槽名。
- 深度**不是** parquet 列,读端要靠视频文件 + `video_extensions` 判断。
---
## 5. 同时接入多个设备
### 5.1 能力与冲突矩阵
| 组合 | 可否同时 | 依据 / 限制 |
|---|---|---|
| UVC × N | ✅ | 每路独立槽名(设计上限 8) |
| D435/D405 × N | ✅ | 槽名按前缀编号;每台独立 RGB + 深度槽 |
| D435 + S80M/S80C | ❌ | 共用 `video0/video2`,后开者被拒绝 |
| S80M × S80M | ❌ | 全局槽名 `stereo_left/right`,只支持单台 |
| UMI 夹爪 + 独立 S80M | ❌ | 夹爪 ORB 桥接独占双目 |
| UMI 夹爪 + D435 | ✅(资源需实测) | 代码只拦 S80M;SLAM 与 RGB 争 CPU |
| UMI 夹爪 × 2 | ✅ | 第二台 `gripper_2_` 前缀;rig 号按打开顺序 |
| 数据手套 × 2 | ✅ | BLE/USB 都录;列名按 MAC/序列号绑定(16×16 压力 + USB 的 IMU/骨架) |
| 数据手套 × 3+ | ❌ | 无空闲列名,拒绝连接 |
| 其它 BLE 设备(`ble`,未识别为手套) | ⚠️ | **BLE 本身有数据**:`ble` 只是检测兜底。主程序开占位、不产数据且不进 `devices`;lite 的「BLE 手套」入口可当手套打开并录制(`observation.<sensor>`,devices kind=`ble_glove`) |
### 5.2 多设备隔离的四条规则
1. **视频槽名唯一**:同一会话内两个设备不能共用一个 image_key(会互相覆盖
`videos/<key>/episode-NNN.mp4`)。夹爪 rig2 靠 `gripper_2_`,D435 第二台靠 `_2`。
2. **列前缀唯一**:夹爪 rig1 空串 / rig2 `gripper_2_`;手套用传感器名;ego `ego_`。
同一个 `observation.<x>` 不允许两个写入方(历史上第 3 只手套被映射到
`left_glove` 就是这种静默坏)。
3. **设备 key 写进 `devices`**:`key` 含序列号/MAC,是事后判断「哪台设备写的哪条
轨迹」的唯一硬件依据。
4. **rig 号与物理手的绑定**:当前 rig 号 = 打开顺序(先开 = rig1)。建议【提案】
- 把 rig 号绑定到 `gripper:<MAC>` 并持久化(`data/device_names.json` 加 `rig` 字段),
- 在轨迹 feature 的 `owner` 里写 `device_key` + `hand`(`left`/`right`),
- 这样同一个任务目录跨人、跨天采集时,rig1 的物理意义不会漂。
### 5.3 一行一帧的对齐模型(MUST 理解)
写线程以 30 fps tick 建行;每个 tick 对每个视频槽取**队列里最旧的一帧**。因此:
- **行号相同 ≠ 物理时刻相同**。不同设备的画面差一个队列滞留(力样本恒领先 RGB,
滞留量随段内时长变化)。精确配对一律用 `hardware_ns` / `*_ns`,不要用行号。
- **深度随主槽**:深度第 i 帧与主槽第 i 帧对齐(缺帧重复最近帧)。
- **传感器/力/状态是 latest-wins 快照**:每行取「当下最新」样本,所以必须靠
`*_ns` 才知道它到底采于何时。
- **SLAM 轨迹是「本行窗口内累积的点列表」**:一行可以有 0 个、1 个或多个轨迹点;
`slam_trajectory_ns` 与点列表锁步,下标即配对。
- **行数 ≠ 点数**:写线程落后超过一帧会跳 tick,轨迹侧也可能丢点;按时间戳配对后
剩余的未配对点/帧是正常现象。
### 5.4 多设备时间基速查
| 数据 | 用哪个时间配帧 |
|---|---|
| 视频帧 | `hardware_ns`(归一后) |
| 力 / 力矩阵 | 各自 `*_ns`(宿主单调钟) |
| SLAM 轨迹点 | `slam_trajectory_ns`(宿主单调钟)↔ `hardware_ns` |
| IMU | `imu_ts_ns`(设备钟) |
| 跨设备粗对齐 | `wall_time` |
`slam_trajectory[i][0]` 是**相机传感器钟**,只用于轨迹内部(速度/时间差),
不要拿它直接减 `hardware_ns`。
### 5.5 稀疏列与缺数据语义
| 情况 | 表现 | 读取方处理 |
|---|---|---|
| 本段从未出现某设备 | 该列不在 parquet schema | 按缺列处理(`info.features` 是任务级并集,**不代表本段有**) |
| 本段有列但本行无样本 | 定长 `[0.0]*d`;变长 `[]`;标量 `0` | `0`/`[]` = 本行无新样本,**不是**真实零值 |
| 轨迹点缺宿主戳 | `slam_trajectory_ns` 对应位置为 `0` | 该点不可按时间配帧 |
| 整段轨迹都无戳 | `*_slam_trajectory_ns` 列**不创建** | 只能退回行号粗对齐(不建议) |
| 设备中途断连 | 有 status 列的设备(UVC/手套/夹爪非视频槽)该列变 `disconnected`;D435/S80M/夹爪 RGB 没有状态列 | 外部帧源要看数据列是否停止更新,不能等 status |
### 5.6 典型组合:2 夹爪 + 1 ego(S80C)+ 2 手套
**视频文件**(每段):
```
videos/chunk-000/stereo_left/episode-000.mp4 # ego 左目(主槽,带 IMU 行)
videos/chunk-000/stereo_right/episode-000.mp4 # ego 右目
videos/chunk-000/stereo_depth/episode-000.mp4 # ego 深度(12-bit 灰度)
videos/chunk-000/gripper_rgb/episode-000.mp4 # 夹爪 rig1 RGB
videos/chunk-000/gripper_2_rgb/episode-000.mp4 # 夹爪 rig2 RGB
```
**data parquet 主要列**(列序以实现为准,此处按来源分组):
```
episode_index, frame_index, timestamp, task_index, wall_time,
hardware_ns, raw_hw_ns, action,
imu_ts_ns, observation.imu,
observation.left_glove, observation.right_glove,
observation.left_glove_imu_quat, observation.left_glove_imu_valid,
observation.right_glove_imu_quat, observation.right_glove_imu_valid,
observation.left_hand_pose, observation.right_hand_pose,
observation.gripper_state, observation.gripper_left_force, observation.gripper_right_force,
observation.gripper_left_force_ns, observation.gripper_right_force_ns,
observation.gripper_left_force_matrix, observation.gripper_right_force_matrix,
observation.gripper_left_force_matrix_ns, observation.gripper_right_force_matrix_ns,
observation.slam_trajectory, observation.slam_trajectory_ns,
observation.gripper_2_gripper_state, observation.gripper_2_gripper_left_force, …,
observation.gripper_2_slam_trajectory, observation.gripper_2_slam_trajectory_ns,
observation.ego_slam_trajectory, observation.ego_slam_trajectory_ns,
status.gripper_pose, status.gripper_force_left, status.gripper_force_right,
status.gripper_2_pose, status.gripper_2_force_left, status.gripper_2_force_right,
status.left_glove, status.right_glove
```
> 该组合**没有** D435 的取证列(`depth_ns` / `rgb_dup` / `ts_src` 等);也**没有**
> `status.stereo_left/right`、`status.gripper_rgb`——它们是外部帧源,不建状态列。
---
## 6. `meta/info.json` 声明规范
### 6.1 顶层键
| 键 | 必填 | 说明 |
|---|---|---|
| `format` | ✅ | 恒 `"pooled_episodes_v1"`(格式判别键) |
| `chunks_size` / `data_path` / `video_path` / `episodes_path` | ✅ | 路径模板 |
| `codebase_version` / `app_version` | ✅ | 数据基准版本 / 程序版本 |
| `fps` / `video` / `task_name` | ✅ | 默认帧率 / 是否含视频 / 任务名 |
| `features` | ✅ | **逐列声明**(§6.2):本任务出现过的所有 parquet 列 |
| `cameras` | ✅ | RGB 槽 → `{height, width, fps?}`;**深度槽不入此表** |
| `video_extensions` | ✅ | **每个 image_key**(含深度)→ `mp4`/`mkv` |
| `devices` | ✅ | 设备紧凑段 `{key,kind,name,slots}` |
| `device_names` | ✅ | `devices[].slots` 的**全部槽位** → 用户命名(含深度/不录制槽) |
| `sensors` / `sensor_dim` | ✅ | 传感器列名列表 / 维度(256) |
| `calibration` | ✅ | 任务级最新标定(§6.5) |
| `total_episodes` | ✅ | 当前段数(删除不回退) |
| `created_at` | ✅ | 任务创建 Unix 秒 |
| `gripper_slam_frame` | 条件 | 有**夹爪** SLAM 轨迹才写;单数,只为兼容 |
| `slam_frames` | 【提案】 | 轨迹列 → frame id 的映射(§6.6) |
**只加不改**:服务器上传严格依赖既有键名/类型/结构。新增信息一律用新键,
既有键的值可以更新,但不能删、不能改类型、不能改语义。
### 6.2 `features` 逐列声明规则
`features` 的键 = **完整列名**(含 `observation.` 前缀);值是该列的编码描述。
| 列形态 | 声明样板 |
|---|---|
| 定长数值序列 | `{"dtype":"float32","shape":[3]}` |
| 定长矩阵 | `{"dtype":"float32","shape":[16,16]}`(压力矩阵必须是 2D,不能是 `[256]`) |
| 手部关键点 | `{"dtype":"float32","shape":[21,3]}` |
| IMU 样本序列 | `{"dtype":"float32","shape":[6]}`(每样本 6 轴) |
| 手套 IMU | `{"dtype":"float32","shape":[16,4]}` / `{"dtype":"float32","shape":[16]}` |
| SLAM 点列 | `{"dtype":"float64","shape":[8],"encoding":"flat_points_8_txyz_qxyzw","frame":"…","frame_axes":{…}}` |
| SLAM 时刻列 | `{"dtype":"int64","shape":[1],"encoding":"flat_parallel_to_slam_trajectory","clock":"host_monotonic_ns"}` |
| 力矩阵 | `{"dtype":"int16","shape":[250,250,3],"encoding":"row_diff_quantized","scale":10}` |
| 力矩阵(原值档) | `{"dtype":"float32","shape":[250,250,3],"encoding":"row_flat_raw","scale":1}` |
| 力/状态 | `{"dtype":"float32","shape":[3]}` |
| 采集时刻标量 | `{"dtype":"int64","shape":[1],"encoding":"host_monotonic_ns","missing_sentinel":0}` |
| 动作占位 | `{"dtype":"float32","shape":[1]}` |
- `shape` 指**单个元素**的形状,不是每行总长;变长列(list)也写元素形状
(所以轨迹是 `[8]`、时刻是 `[1]`)。
- `encoding` 是读端解码依据,**不能省**(尤其力矩阵的 `scale`)。
- `frame` / `frame_axes` 逐列独立;**同一任务里不同轨迹可以不同帧**。
- 视频流**不进** `features`(用 `cameras` + `video_extensions`)。
### 6.3 `cameras` 与 `video_extensions`
```json
{
"cameras": {
"stereo_left": {"height": 800, "width": 1280},
"stereo_right": {"height": 800, "width": 1280, "fps": 25.0},
"gripper_rgb": {"height": 960, "width": 1280}
},
"video_extensions": {
"stereo_left": "mp4", "stereo_right": "mp4", "stereo_depth": "mp4",
"gripper_rgb": "mp4", "gripper_2_rgb": "mp4"
}
}
```
- `cameras` 只放**有 RGB 视频的槽**;深度槽只在 `video_extensions` 里出现。
- `fps` 仅在该流与默认 `fps` 不同时才写。
- 读端判断文件是否存在/是什么格式**一律先看 `video_extensions`**,不要按扩展名猜。
### 6.4 `devices` / `device_names` / `sensors`
```json
{
"devices": [
{"key":"s80m:000000000001@1-3.4.1","kind":"s80m","name":"S80C_head",
"slots":["stereo_left","stereo_right","stereo_depth"]},
{"key":"usbglove:364933593535","kind":"data_ble","name":"USB 手套_left","slots":[]},
{"key":"gripper:CC:BA:97:25:B4:44","kind":"gripper","name":"UMI 夹爪001",
"slots":["gripper_stereo_left","gripper_rgb","gripper_pose",
"gripper_force_left","gripper_force_right"]}
],
"device_names": {"stereo_left":"S80C_head","gripper_rgb":"UMI 夹爪001"}
}
```
(示例只列了部分键;实际写入 `devices[].slots` 的**全部**槽位,见附录 B。)
- 紧凑段**有意不写** `serial` / `fays_serial` / `sensor_column`(隐私与上传契约);
硬件身份在 `key` 里。
- `slots` 是**设备注册的槽位全集**,包含不录制视频的槽(夹爪双目/pose/force、
S80M 深度槽);「哪些真的录了」看 `cameras` + `video_extensions`。
- `device_names` 映射 `devices[].slots` 里的**全部槽位**(含深度槽与不录制的槽),
不只是视频槽。
- **手套的设备条目分两种写法**(`devices[].kind` 不再是单值):
- **主程序**:BLE 与 USB 手套统一 `kind:"data_ble"`、`slots:[]`;`sensor_column`
被紧凑化丢掉,所以 `observation.left_glove` 与设备 `key` 之间**没有机器可读
的绑定**,只能靠 `name` 与列名的约定推断。
- **lite**:`kind:"ble_glove"` / `"usb_glove"`,`slots:["left_glove"]`(放的是
sensor 列名),因此 `device_names["left_glove"]` 直接给出「哪只设备写哪一列」。
- 【提案】主程序也把手套的 `"sensor_column"`(`build_device_meta()` 已产出,
**单数**、字符串)保留进紧凑段;夹爪保留 `"sensor_columns"`(复数、列表)
并补 `"rig":1`。都是 additive,不破坏既有键。
- `sensors` 只列本任务出现过的传感器列名;`sensor_dim` 恒 256。
### 6.5 `calibration`
- 结构:`{标定键: StereoCalibration.to_dict()}`,内容含
`type/name/resolution/fps/baseline/left_camera/right_camera/depth_scale/cam_imu_timeshift`,
相机内参为 `{intrinsic:[fx,fy,cx,cy], distortion:[...]}`。
- 键分配(`core/egodata_writer._plan_calibration_dict`):
- **第一个**注册了标定的设备 → `head_stereo`(服务器/回放/stereo_triangulate 兼容路径);
- 其余 → `<首槽名去掉 _N 编号>_calibration`,如 `d435_rgb_calibration`。
- 每段 episodes 行的 `calibration` 列保存**该段**的同一份 dict(JSON 字符串),
任务级 `info.calibration` 是最新值。
- ⚠ `head_stereo` 归属取决于 `devices` 顺序(= 设备打开顺序,仅 D435/S80M 注册
标定)。两台 D435 时先开的拿 `head_stereo`;ego 双目必须保证排第一,否则
`head_stereo` 会指到别的设备。读端不要假设 `head_stereo` 一定是头戴相机。
### 6.6 多条 SLAM 轨迹的声明【提案】
三条轨迹共存时,**每列一条完整声明**,顶层再给一个便利映射。权威在 `features`。
```json
{
"features": {
"observation.slam_trajectory": {
"dtype": "float64", "shape": [8],
"encoding": "flat_points_8_txyz_qxyzw",
"frame": "down_left_forward",
"frame_axes": {"+X": "down", "+Y": "left", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "enter_press"},
"owner": {"role": "gripper", "rig": 1, "device_key": "gripper:CC:BA:97:25:B4:44"},
"source_slot": "gripper_stereo_left"
},
"observation.slam_trajectory_ns": {
"dtype": "int64", "shape": [1],
"encoding": "flat_parallel_to_slam_trajectory",
"clock": "host_monotonic_ns"
},
"observation.gripper_2_slam_trajectory": {
"dtype": "float64", "shape": [8],
"encoding": "flat_points_8_txyz_qxyzw",
"frame": "down_left_forward",
"frame_axes": {"+X": "down", "+Y": "left", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "enter_press"},
"owner": {"role": "gripper", "rig": 2, "device_key": "gripper:68:EE:8F:C6:0D:BC"},
"source_slot": "gripper_2_stereo_left"
},
"observation.gripper_2_slam_trajectory_ns": {
"dtype": "int64", "shape": [1],
"encoding": "flat_parallel_to_slam_trajectory",
"clock": "host_monotonic_ns"
},
"observation.ego_slam_trajectory": {
"dtype": "float64", "shape": [8],
"encoding": "flat_points_8_txyz_qxyzw",
"frame": "ego_cam_optical",
"frame_axes": {"+X": "right", "+Y": "down", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "first_frame"},
"owner": {"role": "ego", "device_key": "s80m:000000000001@1-3.4.1"},
"source_slot": "stereo_left"
},
"observation.ego_slam_trajectory_ns": {
"dtype": "int64", "shape": [1],
"encoding": "flat_parallel_to_slam_trajectory",
"clock": "host_monotonic_ns"
}
},
"gripper_slam_frame": "down_left_forward",
"slam_frames": {
"observation.slam_trajectory": "down_left_forward",
"observation.gripper_2_slam_trajectory": "down_left_forward",
"observation.ego_slam_trajectory": "ego_cam_optical"
}
}
```
字段含义:
| 字段 | 必填 | 说明 |
|---|---|---|
| `frame` | 条件 | 坐标帧 id。**键不在 = 旧帧**(≤v1.3.12),不是取默认值 |
| `frame_axes` | 条件 | 各轴在现实中指向哪;跨帧对齐**只看方向词**,不看轴字母 |
| `time.t` | 【提案】 | `t` 字段的单位(现有恒 `sensor_s`) |
| `time.clock` | 【提案】 | `camera_sensor`(相机传感器钟)或 `host_monotonic`(宿主单调钟) |
| `time.epoch` | 【提案】 | 原点:`enter_press` / `first_frame` / `device_boot` |
| `owner.role` | 【提案】 | `gripper` / `ego` |
| `owner.rig` | 【提案】 | 夹爪 rig 号(1 起) |
| `owner.hand` | 可选 | `left` / `right`,物理手绑定(见 §5.2 第 4 条) |
| `owner.device_key` | 【提案】 | 与 `devices[].key` 对应,用于溯源 |
| `source_slot` | 【提案】 | `_ns` 时刻对应的采样槽位;**可能不录制视频**(如夹爪双目槽),读端据此知道这条轨迹来自哪路画面/哪台设备 |
**为什么必须逐列 `frame`**:v1.3.x 的实现是**一个全局帧**套给所有
`*slam_trajectory` 列(`core/egodata_writer.py:1146`、`:1214`)。三条轨迹共存时,
ego 的坐标帧会被贴成夹爪的 `down_left_forward`——数值正常、语义全错,和
v1.3.13 那次坐标帧改版是同一类坑。落地前必须改成「按列取帧」。
**顶层 `slam_frames` 与 `features[...].frame` 必须由同一张表生成**,不要手写两遍;
`gripper_slam_frame` 保留(值 = rig1 的帧),只为老读端。
**三条轨迹默认不在同一坐标系**:各自的原点/朝向独立(夹爪是 ENTER 时刻,
ego 是首帧或上电)。要统一到某一坐标系属于**派生**(外参放 `calibration`),
不要改写原始轨迹列。
### 6.7 任务级合并语义(坑)
`info.json` 的 `features` / `cameras` / `video_extensions` 是**按并集合并、
值以最新 episode 为准**(`_write_info_json` 的 `merged_features.update(...)`):
- 某设备只在前几段出现 → 后面的段没有该列,但 `features` 仍声明它;
- 某段 ego SLAM 失败 → 该段没有轨迹列,`features` 仍有;
- 同一任务跨了坐标帧改版 → `frame` 只能记住最后一次写入的值,早期段被标错;
- 力矩阵换档 → 任务级 `scale` 被最后一段覆盖。
**读端 MUST 以「本段 parquet 的实际 schema」判断本段有哪些列**,
`info.json` 只用于解释列的含义与回退默认值。
### 6.8 声明与列的一致性(写入方 MUST)
1. `features` 的键集合 = 本任务出现过的列(可多于本段)。
2. 每一条 `observation.*` 列都有对应 feature;`status.*` 与顶层键列**不进** features。
3. 同一列在 `features` 与 `meta/episodes` 行中的描述不得矛盾(目前只有力矩阵有
双份声明,权威顺序见 §7.3)。
4. 不认识的键**不要**写进 info 让读端猜(例如已废除的 `slam_pose`)。
---
## 7. `meta/episodes` 每段声明
### 7.1 现有列(每段一行)
`episode_index`、`task_index`、`start_frame_index`、`end_frame_index`、`length`、
`created_at`、`duration_sec`、`drop_stats`、`video_codec`、`calibration`、
`force_matrix_specs`(后四列是 JSON 字符串,读取方须 `json.loads`)。
### 7.2 新增 `slam_specs`【提案】
为了让「每段到底有哪几条轨迹、各自什么帧/时基」可逐段判定,建议在
episodes 行加一列 `slam_specs`(string,JSON),结构与 §6.6 的单列声明同型:
```json
{
"observation.slam_trajectory": {
"frame": "down_left_forward",
"frame_axes": {"+X": "down", "+Y": "left", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "enter_press"},
"owner": {"role": "gripper", "rig": 1}
},
"observation.ego_slam_trajectory": {
"frame": "ego_cam_optical",
"frame_axes": {"+X": "right", "+Y": "down", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "first_frame"},
"owner": {"role": "ego"}
}
}
```
- 缺列 = 旧 episode,按 `info.json` 解释。
- 加列时旧行必须补默认值 `"{}"`(`_episode_rows_table` 已按 schema 补默认,
但新增列要同步进 `_EPISODE_COLUMNS`),否则新老行拼不成一张表。
### 7.3 每段级 vs 任务级:权威顺序
| 信息 | 权威 | 回退 |
|---|---|---|
| 力矩阵 `scale`/`encoding` | 本段 `force_matrix_specs` | `info.features[列]` → 1 |
| SLAM `frame`/`time` | 本段 `slam_specs`【提案】 | `info.features[列]` |
| 有无某列 | 本段 parquet schema | 无(不能看 info) |
| 视频扩展名 | `info.video_extensions` | 无 |
先例:力矩阵就是「每段一份」才没被后一段的档位覆盖(`file_format.md` §7.2.1)。
---
## 8. 校验清单
### 8.1 写入方(MUST)
1. 每台设备的视频落到唯一 image_key;深度槽不进 `cameras`、必须进 `video_extensions`。
2. 每台设备的观测列用唯一前缀;第 1 台夹爪保持空串前缀,第 2 台 `gripper_2_`。
3. 变长轨迹:无点写 `[]`;`_ns` 与点锁步(缺戳补 `0`,不跳过);全段无戳不建 `_ns` 列。
4. 力矩阵列整段只用一种 dtype;`scale` 同时写进 features 与 `force_matrix_specs`。
5. `features` 只声明真实出现过的列;每列带 `dtype`/`shape`,能变长的带 `encoding`。
6. **每条** SLAM 列独立写 `frame`/`frame_axes`(不要全局套一个);先把
`gripper_slam_frame` 的写入条件收紧到夹爪前缀,避免只有 ego 的段被贴上夹爪帧。
7. `devices[].slots` 写设备全部槽;`device_names` 写这些槽 → 用户命名;`sensors` 写
传感器列。手套的设备↔列绑定:主程序靠 `sensor_column`(当前紧凑化会丢,见 §6.4),
lite 靠 `slots=[sensor]`。
8. 新键只加不改;`episodes` 表加列时同步 `_EPISODE_COLUMNS`。
### 8.2 读取方(MUST)
1. `format == "pooled_episodes_v1"` 才按本文读;未知格式报错不猜。
2. 先读**本段 parquet schema** 判断列存在性,再读 `info.features` 解释含义。
3. 轨迹一律按 `observation.*slam_trajectory` 匹配,**别写死** `gripper_1_`
(那个键不存在)。
4. 配帧用同名列 + `_ns`,`searchsorted` 找最近邻;`0` 视为无戳。
力/矩阵的 `_ns` 是**标量**(该行那个样本的时刻),轨迹的 `_ns` 是**同行等长列表**。
5. `frame` 键不在 = 旧帧(`right_forward_up`);不同轨迹的 `frame` 可能不同,
按 `frame_axes` 的方向词解释,不按轴字母对齐。
6. 力矩阵先看本段 `force_matrix_specs`,再回退 `features.scale`,默认 1。
7. 视频扩展名看 `video_extensions`;深度走 gray12le/FFV1 专用解码。
8. 忽略 dotfiles、`.lock`、`recycled_episode.json`、临时件。
### 8.3 读三条轨迹的最小伪代码
```python
import json, pyarrow.parquet as pq
info = json.load(open(f"{task}/meta/info.json", encoding="utf-8"))
t = pq.read_table(f"{task}/data/chunk-000/episode-000.parquet")
cols = [c for c in t.column_names if c.endswith("slam_trajectory")]
for col in cols: # 排序稳定,便于逐条处理
spec = info["features"][col]
frame = spec.get("frame", "right_forward_up") # 键不在 = 旧帧
axes = spec.get("frame_axes")
pts = t.column(col).to_pylist() # 每行 list[8] 或 []
ns = (t.column(col + "_ns").to_pylist()
if col + "_ns" in t.column_names else None)
# ns 与 pts 逐行等长;点级配对:zip(每 8 个值为一点, ns 行内列表)
```
---
## 9. 兼容、迁移与落地改动
### 9.1 已有数据
- **不要重命名** `observation.slam_trajectory` / `gripper_*` 任何既有列,
也不要给 rig1 补 `gripper_1_` 前缀——`UMIGripper_Action_AI`(153 段)、
`UMI_9_29`(204 段)和全部读端都按旧名。
- `UMIGripper_Action_AI` 里还有历史 `observation.slam_pose` 列:读端可忽略,
新写入**不再产生**。
- 旧帧数据(无 `frame` 键)与 v1.3.13 左乘/1.3.14 右乘的差异见 `docs/data.md`
§4.5.1;不要按 `app_version` 猜乘侧。
### 9.2 新增「双夹爪 + ego 三轨迹」的改动点
| 位置 | 改动 |
|---|---|
| `core/pipeline.py:1045` `write_slam_trajectory(prefix=…)` | ego 产出端传 `prefix="ego_"`;rig2 已有 `"gripper_2_"` 通路 |
| `core/egodata_writer.py:1146` | 全局 `slam_frame` → 按列取帧的映射(从采集侧/产出端拿) |
| `core/egodata_writer.py:1289` | `gripper_slam_frame` 只在有**夹爪**轨迹时写 |
| `core/egodata_writer.py:1180-1216` | 每条轨迹补 `time`/`owner`/`source_slot`;新增 `slam_frames` |
| `config/settings.py` | 新增 ego 坐标帧注册(`ego_cam_optical` + 轴表),与夹爪帧表分开;`KSQ_GRIPPER_SLAM_FRAME` 只作用于夹爪 |
| `core/egodata_writer.py:_EPISODE_COLUMNS` | 加 `slam_specs`(JSON 字符串,默认 `"{}"`)【提案】 |
| `tools/tests/test_gripper_slam_columns.py` | 加 ego 用例:三列并存、各自 `frame` 不串、只有 ego 时不写 `gripper_slam_frame`、`_ns` 逐行等长 |
### 9.3 验证命令
```bash
QT_QPA_PLATFORM=offscreen venv/bin/python tools/tests/test_gripper_slam_columns.py
venv/bin/python tools/tests/lite_gripper_smoke_test.py
```
---
## 附录 A · 名称速查
| 设备 | 视频槽 | 关键列 | info 声明 |
|---|---|---|---|
| UVC | `head_left_rgb` / `head_right_rgb` / `head_right_rgb_N` | `status.<slot>` | cameras / video_extensions |
| D435/D405 | `<base>_rgb` / `<base>_depth` | `depth_ns`、`rgb_dup`、`rgb_gap`… | cameras / video_extensions / calibration |
| S80M/S80C | `stereo_left` / `stereo_right` / `stereo_depth` | `imu_ts_ns`、`observation.imu` | cameras / video_extensions / head_stereo |
| 手套(BLE/USB) | 无 | `observation.left_glove`、`…_imu_quat`、`…_imu_valid`、`left/right_hand_pose` | sensors / features / devices(kind 随程序:`data_ble` 或 `ble_glove`/`usb_glove`) |
| 夹爪 rig1 | `gripper_rgb`(双目槽不录) | `gripper_left/right_force(_ns)`、`_force_matrix(_ns)`、`gripper_state`、`slam_trajectory(_ns)` | features / gripper_slam_frame |
| 夹爪 rig2 | `gripper_2_rgb` | `gripper_2_gripper_*`、`gripper_2_slam_trajectory(_ns)` | features |
| ego | 宿主设备的 RGB 槽 | `ego_slam_trajectory(_ns)`【提案】 | features / slam_frames |
## 附录 B · 完整 `info.json` 示例(2 夹爪 + ego S80C + 2 手套)
```json
{
"format": "pooled_episodes_v1",
"chunks_size": 1000,
"data_path": "data/chunk-{c:03d}/episode-{f:03d}.parquet",
"video_path": "videos/chunk-{c:03d}/{image_key}/episode-{f:03d}.{ext}",
"episodes_path": "meta/episodes/chunk-{c:03d}/episode-{f:03d}.parquet",
"codebase_version": "v3.0",
"app_version": "1.4.0",
"fps": 30.0,
"video": true,
"task_name": "示例任务",
"features": {
"observation.left_glove": {"dtype": "float32", "shape": [16, 16]},
"observation.right_glove": {"dtype": "float32", "shape": [16, 16]},
"observation.left_glove_imu_quat": {"dtype": "float32", "shape": [16, 4]},
"observation.left_glove_imu_valid": {"dtype": "float32", "shape": [16]},
"observation.right_glove_imu_quat": {"dtype": "float32", "shape": [16, 4]},
"observation.right_glove_imu_valid": {"dtype": "float32", "shape": [16]},
"observation.left_hand_pose": {"dtype": "float32", "shape": [21, 3]},
"observation.right_hand_pose": {"dtype": "float32", "shape": [21, 3]},
"observation.imu": {"dtype": "float32", "shape": [6]},
"observation.gripper_state": {"dtype": "float32", "shape": [3]},
"observation.gripper_left_force": {"dtype": "float32", "shape": [3]},
"observation.gripper_right_force": {"dtype": "float32", "shape": [3]},
"observation.gripper_left_force_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.gripper_right_force_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.gripper_left_force_matrix": {"dtype": "int16", "shape": [250, 250, 3], "encoding": "row_diff_quantized", "scale": 10},
"observation.gripper_right_force_matrix": {"dtype": "int16", "shape": [250, 250, 3], "encoding": "row_diff_quantized", "scale": 10},
"observation.gripper_left_force_matrix_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.gripper_right_force_matrix_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.gripper_2_gripper_state": {"dtype": "float32", "shape": [3]},
"observation.gripper_2_gripper_left_force": {"dtype": "float32", "shape": [3]},
"observation.gripper_2_gripper_right_force": {"dtype": "float32", "shape": [3]},
"observation.gripper_2_gripper_left_force_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.gripper_2_gripper_right_force_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.gripper_2_gripper_left_force_matrix": {"dtype": "int16", "shape": [250, 250, 3], "encoding": "row_diff_quantized", "scale": 10},
"observation.gripper_2_gripper_right_force_matrix": {"dtype": "int16", "shape": [250, 250, 3], "encoding": "row_diff_quantized", "scale": 10},
"observation.gripper_2_gripper_left_force_matrix_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.gripper_2_gripper_right_force_matrix_ns": {"dtype": "int64", "shape": [1], "encoding": "host_monotonic_ns"},
"observation.slam_trajectory": {
"dtype": "float64", "shape": [8], "encoding": "flat_points_8_txyz_qxyzw",
"frame": "down_left_forward",
"frame_axes": {"+X": "down", "+Y": "left", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "enter_press"},
"owner": {"role": "gripper", "rig": 1, "device_key": "gripper:CC:BA:97:25:B4:44"},
"source_slot": "gripper_stereo_left"
},
"observation.slam_trajectory_ns": {"dtype": "int64", "shape": [1], "encoding": "flat_parallel_to_slam_trajectory", "clock": "host_monotonic_ns"},
"observation.gripper_2_slam_trajectory": {
"dtype": "float64", "shape": [8], "encoding": "flat_points_8_txyz_qxyzw",
"frame": "down_left_forward",
"frame_axes": {"+X": "down", "+Y": "left", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "enter_press"},
"owner": {"role": "gripper", "rig": 2, "device_key": "gripper:68:EE:8F:C6:0D:BC"},
"source_slot": "gripper_2_stereo_left"
},
"observation.gripper_2_slam_trajectory_ns": {"dtype": "int64", "shape": [1], "encoding": "flat_parallel_to_slam_trajectory", "clock": "host_monotonic_ns"},
"observation.ego_slam_trajectory": {
"dtype": "float64", "shape": [8], "encoding": "flat_points_8_txyz_qxyzw",
"frame": "ego_cam_optical",
"frame_axes": {"+X": "right", "+Y": "down", "+Z": "forward"},
"time": {"t": "sensor_s", "clock": "camera_sensor", "epoch": "first_frame"},
"owner": {"role": "ego", "device_key": "s80m:000000000001@1-3.4.1"},
"source_slot": "stereo_left"
},
"observation.ego_slam_trajectory_ns": {"dtype": "int64", "shape": [1], "encoding": "flat_parallel_to_slam_trajectory", "clock": "host_monotonic_ns"},
"action": {"dtype": "float32", "shape": [1]}
},
"cameras": {
"stereo_left": {"height": 800, "width": 1280},
"stereo_right": {"height": 800, "width": 1280},
"gripper_rgb": {"height": 960, "width": 1280},
"gripper_2_rgb": {"height": 960, "width": 1280}
},
"video_extensions": {
"stereo_left": "mp4", "stereo_right": "mp4", "stereo_depth": "mp4",
"gripper_rgb": "mp4", "gripper_2_rgb": "mp4"
},
"devices": [
{"key": "s80m:000000000001@1-3.4.1", "kind": "s80m", "name": "S80C_head",
"slots": ["stereo_left", "stereo_right", "stereo_depth"]},
{"key": "gripper:CC:BA:97:25:B4:44", "kind": "gripper", "name": "UMI 夹爪001",
"slots": ["gripper_stereo_left", "gripper_rgb", "gripper_pose",
"gripper_force_left", "gripper_force_right"]},
{"key": "gripper:68:EE:8F:C6:0D:BC", "kind": "gripper", "name": "UMI 夹爪002",
"slots": ["gripper_2_stereo_left", "gripper_2_rgb", "gripper_2_pose",
"gripper_2_force_left", "gripper_2_force_right"]},
{"key": "usbglove:364933593535", "kind": "data_ble", "name": "USB 手套_left", "slots": []},
{"key": "usbglove:364133593535", "kind": "data_ble", "name": "USB 手套_right", "slots": []}
],
"device_names": {
"stereo_left": "S80C_head", "stereo_right": "S80C_head", "stereo_depth": "S80C_head",
"gripper_stereo_left": "UMI 夹爪001", "gripper_rgb": "UMI 夹爪001",
"gripper_pose": "UMI 夹爪001", "gripper_force_left": "UMI 夹爪001",
"gripper_force_right": "UMI 夹爪001",
"gripper_2_stereo_left": "UMI 夹爪002", "gripper_2_rgb": "UMI 夹爪002",
"gripper_2_pose": "UMI 夹爪002", "gripper_2_force_left": "UMI 夹爪002",
"gripper_2_force_right": "UMI 夹爪002"
},
"sensors": ["left_glove", "right_glove"],
"sensor_dim": 256,
"created_at": 1790000000.0,
"calibration": {
"head_stereo": {
"type": "stereo_rgbd_camera",
"name": "head_stereo",
"resolution": [1280, 800],
"fps": 30.0,
"baseline": 0.095,
"left_camera": {"intrinsic": [600.0, 600.0, 640.0, 400.0], "distortion": [0.0, 0.0, 0.0, 0.0, 0.0]},
"right_camera": {"intrinsic": [600.0, 600.0, 640.0, 400.0], "distortion": [0.0, 0.0, 0.0, 0.0, 0.0]},
"depth_scale": 0.001,
"cam_imu_timeshift": 0.0
}
},
"total_episodes": 1,
"gripper_slam_frame": "down_left_forward",
"slam_frames": {
"observation.slam_trajectory": "down_left_forward",
"observation.gripper_2_slam_trajectory": "down_left_forward",
"observation.ego_slam_trajectory": "ego_cam_optical"
}
}
```
> 附录 B 的手套段是**主程序**写法(`kind:"data_ble"`、`slots:[]`)。lite 录同一套
> 硬件时会写 `kind:"ble_glove"` / `"usb_glove"`,并把 `slots` 写成 sensor 列名
> (`["left_glove"]`),读端两种都要认(§4.5 / §6.4)。
## 附录 C · data parquet 列与类型(同附录 B 组合)
| 列 | pyarrow 类型 | 产生条件 |
|---|---|---|
| `episode_index` / `frame_index` / `task_index` | int64 | 恒有 |
| `timestamp` | float32 | 恒有 |
| `wall_time` | float64 | 恒有 |
| `hardware_ns` | int64 | 恒有(无硬件戳的槽写 0) |
| `raw_hw_ns` | int64 | 本段至少一帧带原始设备戳时写 |
| `action` | list\<float32,1\> | 恒有 |
| `imu_ts_ns` | list\<int64\> | 有双目 IMU 样本 |
| `observation.imu` | list\<list\<float32,6\>\> | 同上 |
| `observation.left_glove` / `right_glove` | list\<float32,256\> | 该段有手套数据 |
| `observation.<sensor>_imu_quat` | list\<float32,64\> | USB 手套出现 |
| `observation.<sensor>_imu_valid` | list\<float32,16\> | 同上 |
| `observation.left_hand_pose` / `right_hand_pose` | list\<float32,63\> | **恒有**(全零占位) |
| `observation.gripper_*` / `gripper_2_gripper_*` | 见 §4.6 | 该段夹爪产生过对应样本 |
| `observation.slam_trajectory(_ns)` | list\<float64\> / list\<int64\> | 夹爪 SLAM 有点 |
| `observation.gripper_2_slam_trajectory(_ns)` | 同上 | rig2 SLAM 有点 |
| `observation.ego_slam_trajectory(_ns)` | 同上【提案】 | ego SLAM 有点 |
| `status.<id>` | string | UVC 槽 / 传感器列名 / 夹爪非视频槽注册过(外部帧源没有) |
> 列顺序由实现决定(按来源分组构造),**读端必须按列名取,不能按位置**。
|