Blame for collector/docs/data.md

# data/ —— 配置文件与数据存储结构

本文档描述 `data/` 目录下的配置文件格式、SQLite 表结构与录制数据的目录布局。
所有结构均从代码（`config/settings.py`、`core/task_record.py`、
`core/egodata_writer.py`、`core/database.py`、`core/recording_record.py`、
`core/helpers.py`）与仓库内模板文件归纳得出。

## 1. 总览：仓库提供什么，本地生成什么

| 文件/目录 | 归属 | 说明 |
|---|---|---|
| `server_config.example.json` | 仓库模板 | 服务器连接配置模板；本地真实配置写在 `server_config.json`（gitignore） |
| `device_names.example.json` | 仓库模板 | 设备命名表模板（空 `{}`）；本地真实配置写在 `device_names.json`（gitignore） |
| `tasks.example.json` | 仓库模板 | 任务列表模板（`{"tasks": []}`）；本地真实数据写在 `tasks.json`（gitignore） |
| `device_params.json` | 仓库内默认文件 | 每设备相机参数（曝光），出厂为空对象 `{}`；key 用设备稳定标识，增长后可能含设备标识，勿提交本地改动 |
| `recordings/` | 本地生成（gitignore） | 录制会话输出根目录 |
| `app.db`、`pipeline.db` | 本地生成（gitignore） | SQLite 数据库；当前代码使用 `pipeline.db`（`settings.DB_PATH`），`app.db` 未被现有代码引用，属历史遗留 |

本地真实文件可能包含服务器地址、凭据、MAC 等敏感信息，**永不提交**；
新环境首次运行由程序按需创建，结构见下文。

## 2. 配置文件

### 2.1 `server_config.json`（模板 `server_config.example.json`）

服务器连接与上传行为配置。字段由 `config/settings.py` 中的读写函数定义：

| 键 | 类型 | 含义 | 默认/回退 |
|---|---|---|---|
| `server_url` | string | 服务器地址；为空时回退出厂默认 `http://127.0.0.1:8000`（`settings.SERVER_URL`） | 空 |
| `username` | string | 上传登录用户名 | 空 |
| `password` | string | 上传登录密码 | 空 |
| `upload_auto_sync` | bool | 录制完成后是否自动上传 | `true` |
| `upload_delete_after` | bool | 上传成功后是否自动删除本地文件 | `false` |

写入采用合并式（merge-write）：`_save_server_config` 只更新传入键，保留其余字段。

### 2.2 `device_names.json`（模板 `device_names.example.json`）

设备命名表。顶层为 JSON 对象：

```json
{
  "<DeviceInfo.stable_key>": { "name": "<用户命名>", "sensor": "<parquet 列名>" }
}
```

- **key**：设备稳定标识 `DeviceInfo.stable_key`，形式如 `uvc:{by-id 前缀}`（同型号同序列号两台并存时 udev 的 by-id 链接名相撞、只有一台拿得到链接，**且谁拿到取决于注册顺序、重枚举时会翻转** ⇒ 两台都退到 `uvc:usb-<USB 拓扑路径>` 如 `uvc:usb-1-5`，同样跨重启稳定）、
  `d435:{serial}`、`ble:{MAC}` 等（含设备序列号/MAC，属本地敏感信息，不入库）。
- **value**：规范形式为 `{"name": str, "sensor"?: str}`；旧版本可能是纯字符串，
  读取时自动兼容升级。
  - `name`：用户在界面中给设备的命名（槽名随 GUI 用户命名）。
  - `sensor`：仅 BLE 数据手套使用，把设备绑定到 parquet 列名
    （`right_glove` / `left_glove`）。按 MAC 持久化，重连保持；首次连接的未知手套
    由 `assign_glove_sensor_role` 按广播名偏好（`L` → `left_glove`、
    `R` → `right_glove`）自动分配一个空闲列名并写回。

### 2.3 `tasks.json`（模板 `tasks.example.json`）

采集任务列表，是任务进度的事实来源（single source of truth）。顶层结构：

```json
{
  "tasks": [ { <任务条目> }, ... ],
  "updated_at": "<ISO 时间戳>"
}
```

任务条目字段（由 `core/task_record.py` 归纳）：

| 键 | 类型 | 含义 |
|---|---|---|
| `id` | string | 任务唯一 ID（读取时也兼容 `task_id` 键名） |
| `name` | string | 任务名；录制时输入的 `task_name` 按 `name` 精确匹配来累计进度，同时是录制目录名的来源 |
| `description` | string | 任务描述 |
| `total_required` | int | 要求完成的录制总次数（`>0` 才视为有效任务） |
| `assigned_at` | string | 任务分配时间（ISO 8601，用于列表排序，新→旧；空/非法排最后） |
| `params` | object | 任务自定义参数（如对象、用手等） |
| `completed_count` | int | 录制完成次数（持久化权威值，每次录制完成 +1，与本地文件是否被删除无关） |
| `status` | string | `pending` / `in_progress` / `completed`，每次加载时由 `completed_count` 与 `total_required` 重新推算 |
| `source` | string | `"local"` = 采集端自建任务（任务页「＋ 新建任务」创建，id 前缀 `local-`）；缺失 = 服务端任务/历史任务 |
| `created_by` | string | 本机任务的创建身份（`"guest"` 或用户名）；**仅创建者可见**。缺失视为「无主」，对所有身份可见（兼容手工写的数据） |
| `hidden` | bool | 删除墓碑：用户删除过的**服务端任务**标 `true`，防止后端再次推送时“复活”（任务页删除同时会真删本地录制目录与录制记录，这里只留墓碑；进度 `local_count` 不回退）。本机任务删除时**整条移除**，不留墓碑 |

行为要点（均来自代码）：

- 首次运行若文件缺失或解析失败，写入内置示例种子任务（`task_001` 起 3 条）后重读。
- `load_tasks` 除旧数据回填外不写回文件；后端推送经 `merge_backend_tasks`
  按 `id` 合并，本地保留 `total_required`/`params` 覆盖字段与
  `completed_count` 权威值；同名多可见任务只保留 `assigned_at` 最新的一条，
  其余标 `hidden`。
- 旧数据缺少 `completed_count` 时，一次性按 `data/recordings/<name>/` 下含
  `meta/info.json` 的会话目录数回填初值并写回，此后以持久化值为准。
- 任务页「🗑 删除」= 真删除：先按 `<RECORDING_DIR>/<task_tag>/` 校验删净
  （删不掉则弹窗报错且任务不删除），再删除该目录下的录制记录行，最后只在本
  文件写 `hidden` 墓碑。`completed_count` 等进度计数按「持久化权威值」处理，
  不随删除回退。
- **采集端自建任务**（`source="local"`，任务页「＋ 新建任务」）：
  - 名称只允许字母/数字/汉字/下划线/连字符（拒绝空格、点、斜杠等），
    去首尾空白后 ≤64 字符，大小写不敏感查重（含 `hidden` 与种子任务），
    拒绝 Windows 保留名（CON/PRN/AUX/NUL/COM1-9/LPT1-9）。规则保证
    `name == task_tag(name)`，即任务名 = 录制目录名 = 上传会话/项目名。
  - `id` 形如 `local-YYYYmmdd-HHMMSS-<4hex>`；`assigned_user` 恒为 `null`
    （不算指派任务），可见性由 `created_by` 决定：**仅创建者可见**，游客建的
    只对游客可见。后端轮询不会删除本机任务（`merge_backend_tasks` 账号撤销
    清除显式豁免本机任务）。
  - 进度只在本机累计（`local_count`，`synced_count`/`backend_count` 恒 0）；
    `pending_sync_tasks` 跳过本机任务，**不向服务器上报任务进度**。录制数据
    仍按任务名正常上传，服务器按名称匹配/自动创建项目。
  - 删除 = 真删本地目录 + 录制记录行 + 从本文件**整条移除**（后端永远不会
    推送它，不需要 `hidden` 墓碑；同名任务可以重建）。
  - 改名只对本机任务开放，且**本机已有录制目录时拒绝**（改名不迁移数据，
    避免旧目录失去归属、上传队列路径脱节）；新名字目录已存在也拒绝。
  - 服务端后来推送同名任务时走既有同名去重（`(name, assigned_user)`，按
    `assigned_at` 新者胜出）：本机任务可能被隐藏，录制目录由同名服务端任务
    继续使用，进度以服务端任务为准 —— 创建时会拒绝与现有任务重名，正常操作
    不会主动制造这种情况。

### 2.4 `device_params.json`

每设备相机参数（当前为曝光设置）持久化。顶层为 JSON 对象，key 与
`device_names.json` 同为 `DeviceInfo.stable_key`：

```json
{
  "<stable_key>": {
    "exposure": { "auto": true, "value": 0.0 },
    "original": { "auto": true, "value": 0.0 }
  }
}
```

- `exposure`：当前曝光（`auto=true` 时 `value` 被忽略）。
- `original`：设备首次开启时读回的原厂曝光基线，只写一次、永不覆盖，
  供“恢复默认”按钮使用。

仓库内默认文件为空对象 `{}`，随使用增长。注意：key 与 `device_names.json` 同为
`DeviceInfo.stable_key`，增长后可能含设备序列号/MAC 等标识，本地修改过的文件请勿提交。

## 3. SQLite 数据库（`data/pipeline.db`）

`core/database.py` 定义建表 SQL（`CREATE TABLE IF NOT EXISTS`），
连接为线程本地单例，启用 `journal_mode=WAL` 与 `foreign_keys=ON`。

### 表 `recording` —— 录制历史记录

| 列 | 类型 | 含义 |
|---|---|---|
| `id` | TEXT PK | 记录 ID |
| `camera_index` | INTEGER | 触发录制的摄像机槽位索引 |
| `camera_name` | TEXT | 摄像机名 |
| `file_path` | TEXT | 会话目录路径 |
| `file_size_mb` | REAL | 文件大小（MB） |
| `duration_sec` | REAL | 录制时长（秒） |
| `resolution_w` / `resolution_h` | INTEGER | 分辨率 |
| `status` | TEXT | `completed` / `uploaded`（已上传、本地保留）/ `aborted` / `deleted` / `uploaded_deleted`（已上传、本地已删，行保留供历史可查） |
| `started_at` / `finished_at` | TEXT | 起止时间 |

索引：`idx_recording_camera(camera_index)`、`idx_recording_date(started_at)`。
读写封装在 `core/recording_repository.py`（`RecordingRepo`）、数据类在
`core/recording_record.py`（`RecordingRecord`）。

### 表 `upload_task` —— 上传任务记录

| 列 | 类型 | 含义 |
|---|---|---|
| `id` | TEXT PK | 上传任务 ID |
| `session_path` | TEXT | 会话目录路径 |
| `session_name` | TEXT | 会话名 |
| `episode_index` | INTEGER | 池化 episode 全局序号（v1.1.0 起） |
| `status` | TEXT | `pending` / `uploading` / `completed` / `failed` / `skipped`；`uploading` 在 POST 发起前写入，其 `updated_at` 即"POST 开始时刻"（启动续传的时间窗判定依赖它，程序被杀时该行会停在 `uploading`） |
| `progress` | REAL | 进度（0.0–1.0） |
| `retry_count` | INTEGER | 重试次数 |
| `server_url` | TEXT | 目标服务器 |
| `server_session_id` | TEXT | 服务器返回的会话 ID |
| `error_message` | TEXT | 错误信息 |
| `created_at` / `updated_at` | TEXT | 创建/更新时间 |

索引：`idx_upload_status(status)`、`idx_upload_session(session_path)`。

## 4. 录制目录结构（`data/recordings/`）

录制由 `core/pipeline.py` 驱动 `core/egodata_writer.py`（`EgoDataWriter`）
写入。目录布局为 EgoData 标准，并兼容 LeRobot v3 格式消费方。

### 4.1 目录树

```
data/recordings/                          # 录制根目录（settings.RECORDING_DIR）
└── <task_tag>/                           # 任务目录：清洗后的任务名（task_name 为空时叫 "session"）
    └── <task_tag>_000001/                # 会话（episode）目录：任务名 + 6 位序号
                                          #   旧格式兼容：episode_000001/
        ├── metadata.json                 # EgoData 根级元数据（见 4.3）
        ├── timestamps.json               # 逐帧时间戳（见 4.4）
        ├── videos/                       # RGB 视频（每台相机一路 MP4）
        │   └── <camera_name>/            #   槽名，如 head_left_rgb；_aux 后缀相机归入主相机目录
        │       └── chunk-0000/
        │           └── <camera_name>.mp4 #   编码自适应（v1.0.9：HEVC CRF30 直出，性能不足回退 H.264 CRF23；实际见 metadata.video_codec）
        ├── depth/                        # 深度（仅启用深度时创建）
        │   └── <深度槽名>/               #   如 head_depth（S80M 兜底）/ d435_depth（D435）/ stereo_depth（S80C）
        │       ├── <深度槽名>.mp4        #   深度热力图视频（JET 伪彩，可视化用途）
        │       └── 000001.png …          #   原始 uint16 毫米 PNG（16-bit grayscale，
        │                                 #   raw_depth 槽位；v1.0.11 曾改 raw16 bin，
        │                                 #   体积过大且上传失败，v1.0.12 回退 PNG16）
        ├── calibration/                  # 标定（StereoCalibration）
        │   ├── head_stereo.json          #   首台双目型设备标定（服务器/回放/三角化依赖此路径）
        │   └── <槽名前缀>_calibration.json  # 其余设备的标定（槽名前缀去掉 "_N" 消歧编号）
        ├── data/                         # 传感器数据（LeRobot v3 兼容 Parquet）
        │   ├── <sensor>/                 #   每传感器一个目录，如 right_glove / left_glove
        │   │   └── chunk-0000/
        │   │       └── chunk_000000.parquet   # zstd 压缩，schema 见 4.5
        │   └── imu/                      #   双目 IMU（仅双目会话，每帧一行）
        │       └── chunk-0000/
        │           └── chunk_000000.parquet
        └── meta/                         # LeRobot v3 兼容元数据
            ├── info.json                 # 上传服务器严格依赖的字段（见 4.6）
            ├── stats.json                # 各特征 mean/std/min/max（归一化统计）
            ├── tasks.jsonl               # {"task_index": 0, "task": "<任务名，空时 'default recording'>"}，单行 JSON
            └── episodes/
                ├── chunk-000/
                │   └── file-000.parquet  # 每会话一行的 episode 表
                └── chunk_000000.parquet  # 前者的兼容旧路径副本
```

要点：

- **序号**：episode 序号 = `max(任务进度 batch_index, 目录扫描最大序号 + 1)`；
  `batch_index` 是“录制完成次数 + 1”（`core/task_record.py` 持久化），
  上传后自动删除本地文件也不会使序号回退。
- **视频/深度/标定**：深度槽位（`depth_slots`）不建视频目录也不走 MP4 合成；
  `start_episode` 中 `_aux` 后缀摄像头归入主摄像头目录。
- **旧格式兼容**：会话目录也可能以 `<tag>_YYYYMMDD_HHMMSS`（`session_dirname`）
  命名且内含 `meta/info.json`（LeRobot v3 旧会话）；`core/helpers.py` 的
  `list_all_sessions` / `detect_session_format` 通过 `metadata.json`（egodata）
  或 `meta/info.json`（lerobot_v3）识别会话，回放支持两种格式。
- **中止录制**：`abort_episode` 直接 `rmtree` 丢弃整个会话目录。
- **关键点数据不写在本目录**：手部关键点输出镜像到仓库根的
  `keypoints_output/<task>/<session>/`（见第 5 节）。

### 4.2 深度通道说明

- **S80M 传统路径**（无显式注册深度槽）：单槽兜底 `head_depth`，
  由 `write_depth_frame` 惰性创建目录并合成热力图 MP4，受
  `settings.DEPTH_ENABLED` 门控（默认关闭，遗留开关勿启用）。
- **D435/D405**（`core/pipeline.py` 经 `set_depth_camera` 显式注册槽位）：
  打开即录深度；槽位配置了 `raw_depth=True` 时额外写原始 uint16 PNG16
  （`egodata_depth_path`：`depth/<槽名>/000001.png`，文件名从 1 起 6 位，
  压缩级 `settings.D435_PNG_COMPRESSION`）。
  热力图支持固定色标（`near_mm`/`far_mm`）、3×3 中值与 EMA 时域平滑
  （仅作用于可视化通道，原始 PNG16 不经过）。
- **S80C**（v1.0.11）：`set_depth_camera(settings.S80M_DEPTH_SLOT,
  raw_depth=True)` 显式注册槽位 `stereo_depth`，深度由 `read_stereo_rgb.py`
  子进程内 SDK 深度引擎计算（~20fps），经管道深度块 → `depth_ready` 信号
  回主程序；录制时热力图 MP4 + PNG16 与 D435 同口径落盘。深度源低于
  录制帧率时热力图 MP4 重复最近帧补拍（时长与 RGB 对齐），PNG16 仅
  记新帧不重复。
- **读取**：PNG16 直接 `cv2.imread(path, cv2.IMREAD_UNCHANGED)`；
  v1.0.11 窗口会话存的是 raw16 bin（`np.fromfile(dtype=np.uint16)
  .reshape(h, w)`，`(h, w)` 取 `metadata.json` `cameras.<槽名>.height/width`），
  读取方已做扩展名回退兼容（`depth_align.load_depth_frame`）。

### 4.3 `metadata.json` 字段概览（EgoData 根级元数据）

| 键 | 含义 |
|---|---|
| `format` / `format_version` | 固定 `"egodata"` / `"1.0"` |
| `episode_index` | episode 序号 |
| `fps` | 默认录制帧率 |
| `task_name` | 任务名（可为空） |
| `cameras` | `{槽名: {height, width, ...}}`；深度槽带 `type:"depth"`、`unit:"mm"`、`format:"png16"`（v1.0.11 窗口会话为 `"raw16"`）；RGB 槽带独立帧率 `fps`（与默认不同时）；挂设备归属时带 `device_key`/`device` |
| `devices` | 设备段数组：`{key, kind, name, slots, serial?, sensor_column?, resolution, fps, calibration}`；`serial` 仅在设备提供时写入 |
| `sensors` | 传感器名列表（如 `["right_glove", "left_glove"]`） |
| `sensor_dim` | 传感器维度（256 = 16×16 触觉矩阵展平） |
| `created_at` | 创建时间（Unix 时间） |
| `codebase_version` | 程序版本（`config.__version__`） |
| `video_codec` | v1.0.9：本会话视频编码信息 `{encoder, codec, crf, ffmpeg, selected_by, probe}`；`selected_by` = `"auto"` 或显式指定名，`probe` = 录前速度探针结果（x265 路径） |
| `drop_stats` | v1.0.9：录制丢帧统计 `{队列键: 丢弃帧数}` + `imu_overflow`（IMU 防丢缓冲溢出次数）；无丢帧时全为 0。v1.3.10 起另有**带后缀**的键：`*_ms`（时长）/ `*_count`（次数）——夹爪 RGB 的帧空洞与采集侧仪表（`<槽>_gap_ms`、`_readfail_ms`、`_overwrite_count`、`_emit_lag_max_ms`、`_dispatch_lag_max_ms` 等）。**`_ms`/`_count` 后缀的键不是帧数**，加总帧数前必须过 `core.pipeline.is_frame_drop_key`（见 [file_format](file_format.md) §7.3、[postmortem](postmortem_trajectory_and_rgb.md) §4.6） |

### 4.4 `timestamps.json`

```json
{
  "timestamps": [ { "frame_index": 0, "timestamp": 0.0, "wall_time": 1.7e9 }, ... ],
  "total_frames": 1234
}
```

- `timestamp`：会话相对时间（秒，与 parquet 的 `timestamp` 列同源）；`wall_time`：写入时刻的墙上时间。
- `hardware_ns`：仅双目相机帧携带（SDK 硬件纳秒时钟，与 IMU 同源）；含硬件
  时间戳的行在写出时按 `hardware_ns` 稳定排序，保证时间线单调。

### 4.5 Parquet schema（`data/` 与 `meta/episodes/`）

- `data/<sensor>/chunk-0000/chunk_000000.parquet`（每帧一行，zstd 压缩）：

  | 列 | 类型 | 含义 |
  |---|---|---|
  | `episode_index` | int64 | episode 序号 |
  | `frame_index` | int64 | 帧序号 |
  | `timestamp` | float32 | 会话时间（秒） |
  | `task_index` | int64 | 任务序号（当前固定 0） |
  | `observation.<sensor>` | list<float32, 256> | 传感器读数（16×16 展平；缺帧补零）。**手套压力矩阵落盘的是固件原始通道号**，不做任何手型重排 —— 右手帧恰好等于规范系，左手帧是规范系的 `[::-1, ::-1].T`（转置 + 180°）。任何把矩阵当"手"来读的消费方（分区显示、掌区映射、跨模态对齐）**必须先过 `core.render_engine.canonical_pressure_matrix(m, side)`**，否则左手会整体转 90°（2026-09-21 修的就是这个；契约见该函数 docstring） |
  | `observation.left_hand_pose` / `observation.right_hand_pose` | list<float32, 63> | 手部关键点（21 关节 × xyz，**米**，腕部相对系；USB 手套录制时由 IMU 实时解算回填，无手套或未解算时为零占位）。**全链无平滑**：写的是 SDK 的 `KeypointFrame.joints_m` 原始解算输出，不含 `sdk/glove.py` 那层 35ms EMA（改用它会引入不可逆相位滞后，见 `core/glove_keypoint_solver.py` 的 `joints_m` 注释） |
  | `action` | list<float32, 1> | 动作（当前固定 `[0.0]`） |
  | `status.<device_id>` | string | 该设备在本帧的连接状态（默认 `"connected"`） |

- `data/imu/chunk-0000/chunk_000000.parquet`（双目 IMU，每帧一行）：

  | 列 | 类型 | 含义 |
  |---|---|---|
  | `episode_index` / `frame_index` / `timestamp` / `task_index` | 同上 | 同上 |
  | `hardware_ns` | int64 | 帧的 SDK 硬件纳秒时间戳 |
  | `imu_ts_ns` | list<int64> | 本帧窗口内 IMU 样本时间戳，与样本一一对应 |
  | `observation.imu` | list<list<float32, 6>> | 样本序列，每样本 `[gx, gy, gz, ax, ay, az]` |

- `meta/episodes/chunk-000/file-000.parquet`（每会话一行）：
  `episode_index`、`task_index`、`start_frame_index`、`end_frame_index`、
  `length`（均为 int64）。

### 4.5.1 UMI 夹爪列与跨模态时间对齐

启用夹爪时 episode parquet 增加下列稀疏列。**无样本的行**：`*_ns` 时刻列填
`0`、3 向量力填 `[0,0,0]`、力矩阵填空 list —— 这个 0 是**哨兵不是时刻**
（`features[...].missing_sentinel = 0` 已声明），读数时先滤掉再当时间轴用
（实测 7%~15% 的行是这种：力按 30Hz 采、行也是 30Hz，相位不同步时必然有空窗）：

| 列 | 类型 | 含义 |
|---|---|---|
| `observation.gripper_{left,right}_force` | list<float32, 3> | 3 向量力 `[fx,fy,fz]` mN |
| `observation.gripper_{left,right}_force_ns` | int64 | 该力样本的采集时刻（宿主单调钟 ns；0 = 本行无样本） |
| `observation.gripper_{left,right}_force_matrix` | list<int16> / list<float32> | 250×250×3 力矩阵（档位见下） |
| `observation.gripper_{left,right}_force_matrix_ns` | int64 | 该力矩阵样本的采集时刻（0 = 本行无样本） |
| `observation.slam_trajectory` | list<double> | 轨迹点 `[t,x,y,z,qx,qy,qz,qw]`×N，变长（坐标帧见下） |
| `observation.slam_trajectory_ns` | list<int64> | 每个轨迹点对应取样帧的**宿主时刻**，与 `slam_trajectory` 同序等长 |
| `observation.gripper_state` | list<float32, 3> | `[open_pct, gripped, fz_mn]` |

力矩阵档位记在**每段一份**的 `meta/episodes` 行（`force_matrix_specs` 列），
不按面值猜——同一任务换档时前一段的倍率不会被后一段顶掉。

#### SLAM 轨迹的坐标帧

`x,y,z,qx,qy,qz,qw` 在现实中指向哪，由 `meta/info.json` 里的帧标注给出：

| 键 | 值 |
|---|---|
| `observation.{prefix}slam_trajectory.frame` | 帧 id，如 `down_left_forward` |
| `observation.{prefix}slam_trajectory.frame_axes` | `{"+X":"down","+Y":"left","+Z":"forward"}` |
| `gripper_slam_frame`（顶层，仅真有 SLAM 轨迹的任务） | 同上帧 id，一眼可查 |

- **v1.3.13 起**默认 `down_left_forward`：**+X=下 / +Y=左 / +Z=前**，右手系，
  单位米，原点为按下 ENTER 那一刻的夹爪位置，姿态相对该帧首帧。
- **v1.3.12 及更早**录的 episode（`data/recordings/UMIGripper_Action_AI` 里
  那 153 段）是 `right_forward_up`：+X=右 / +Y=正对 / +Z=上。数值本身总是能
  正常解算，**只是含义不同**，读端必须按帧标注解释，不能假设一种。
- ⚠ 分界是**发布版本**，不是日历日：v1.3.13（2026-09-28）起才是新帧；
  此前的版本**不写** `frame` 键 —— 所以旧 episode 里这两个键**不存在**，
  「键不在」就等于旧帧，不要当成"缺省 = 新帧"。（2026-09-22..09-27 用
  v1.3.12 录的也在旧帧那侧：没有键。老数据最新一段录于 2026-09-21 21:01；
  新帧那边已有 `UMI_9_29`（2026-09-29 录、204 段、`app_version` 1.3.13）——
  这条线**已经跨过去了**，同一份 `data/recordings` 里两种帧并存。）
- ⚠ 帧标注是**任务级**的（`meta/info.json` 的 `features` 按并集/后写覆盖合并）：
  一个任务目录若跨了这次改帧，它只能记住最后写入的帧，该任务早期 episode
  会被标错。按 episode 精确区分需要 `meta/episodes` 加列（v1.3.13 未加）——
  跨改帧的任务目录请按录制日期切分，切点取"那天升到了 v1.3.13"。
- 环境变量 `KSQ_GRIPPER_SLAM_FRAME=right_forward_up` 可让新录制回落到旧帧
  （做 A/B 对比用）；未设/空串走新帧，认不出的取值会向 stderr 出声后回落
  新帧，不静默。该变量**每次会话解析一次**，录制中途改它不生效。

**为什么需要 `_ns` 列。** 同一行里的 RGB 帧和力样本**不是同时刻采集的**，
两条支路各走各的路：RGB 走外部帧源队列，写线程每 tick 取**队头最旧帧**；
力/矩阵走 latest-wins 单槽，写线程取到的是**当下最新**样本。于是「行号相同」
≠「时刻相同」——力恒领先 RGB，领先量等于那张 RGB 帧在队列里的滞留时间，
且随录制时长增长（RGB 源实测 30.84 fps vs 写线程 30 fps，约每秒多积 1 帧）。
力矩阵还走独立泵线程，与 3 向量力之间也各记各的时刻，所以两者不共用一列。

v1.3.3 起每行落盘两条支路各自的采集时刻（宿主单调钟纳秒，与 `hardware_ns`
同一时基），下游按时间取最近邻即可还原真实配对：

```bash
venv/bin/python scripts/align_modalities.py <episode.parquet> --residual
```

```python
from align_modalities import align_episode
mapping, residual_ns = align_episode("episode-000.parquet", side="left")
# mapping[k] = 视频第 k 帧应对应的 parquet 行号
```

- 对齐精度上界是**半个力样本间隔**，不是半个行周期。`force_ns == 0` 表示
  「本行窗口内没有新样本」（**不是**时刻为 0，取最近邻时必须排除，否则会把
  一批帧吸到第 0 行）。样本每 k 行才有一个时上界放宽到 k/2 个行周期。
- 早于第一个力样本的帧（段首陈旧帧，见 `rgb-prestart-frames`）与晚于最后
  一个样本的帧在时间上没有对应样本，只能夹到端点——**这不是对齐结果**，
  脚本单列「越界帧」计数，下游应丢弃。
- **v1.3.3 之前录的 episode 无法这样对齐**：那时力侧完全没有时间戳，RGB 侧
  的 `hardware_ns` 还被 `pyqtSignal(int)` 截成 32 位（每 2.147 s 翻符号）。
  脚本对这类 episode 明确报「无法对齐」而不是拿行号或增长率去猜。

##### ⚠ 姿态相对化的语义改过一次 —— 新旧数据要分开看

上面说的「姿态相对该帧首帧」有个**乘在哪一侧**的区别，v1.3.14 之前一直是
左边那一侧：

- **正确（v1.3.14 起）＝右乘 `R · R0ᵀ`**——在世界系里表达的相对姿态
  （「相对锚点转了多大」）。
- **改前＝左乘 `R0ᵀ · R`**——在锚点体轴系里表达的相对转动（body delta）。
  两者数值上只差一个**常数共轭**，所以位置/幅度都「看着正常」，但读端按它解
  会让**表观旋转轴整体转错**（本机锚点下约等于绕发布帧 −Y 轴转了 90°：绕 X
  的表观变成绕 Z、绕 Z 的变成反向绕 X，只有绕 Y 正常）。修在 `0ab64d7c`
  （v1.3.14 那一笔），同一笔把 `process_controller` 里描述该语义的注释同步了。

**`frame` 与 `app_version` 都分不出这两者**：两个构建写的都是
`frame=down_left_forward`，`__version__` 从 `177ef0ef`（左乘）到 `0ab64d7c`
（右乘）**一直是 `"1.3.13"`**（版本号在下一笔才抬到 1.3.14）。⇒ **不能按版本
猜 1.3.13 的数据是哪一种**。

**三类数据要分开**（左乘那段代码换过位置，但乘的侧一直没变 —— 别以为
「≤1.3.12 是另一条路径所以不受影响」）：

| 数据 | 相对化 | 现况 |
|---|---|---|
| **新帧 + v1.3.14 起**（`frame=down_left_forward` 且 `__version__` ≥1.3.14） | 右乘 | 按右乘读，就是现状 |
| **新帧 + v1.3.13**（`frame=down_left_forward`，`app_version` 1.3.13） | **左乘** | 仓库内只有 `UMI_9_29`，**已回填成右乘**（见下） |
| **旧帧**（没有 `frame` 键，≤1.3.12） | **也是左乘** | 在 `process_controller._pose_rotation_zero` 里做的（注释原文「全部姿态左乘基准的逆」），v1.3.13 只是把它搬进 `protocol.finish_publish_pose` 而**没有改乘的侧**；**本次没动**，仓库里的旧帧库（`UMIGripper_Action_AI` 153 段等）原样留在左乘 |

⇒ 所以**「仓库内一律按右乘解释」只对新帧那一支成立**。**旧帧数据要不要也按
右乘重解释，需要单独判定**（左乘的差异是「绕锚点 R0 的常数共轭」，旧帧的 R0
与轴定义与旧帧文档是配套写的，不能想当然地照新帧的结论搬）——这一条**待办**，
不要按「旧数据没受影响」理解。

本机新帧那一支是**已经回填好了**：`data/recordings/UMI_9_29`（204 段，
`app_version` 1.3.13）已于 2026-10-12 按右乘语义整体回填（逐点
`q_new = A · q_old · A⁻¹`，A = 绕发布帧 −Y 轴 90°，即把左乘值换成右乘值）。
逐点核验（全部 53272 点）与**逐文件 sha256 前后值**记在
`data/recordings_rotfix_backup/UMI_9_29_rotfix_20261012/MIGRATION.json`，
回填前的原值就存在**同一个目录**下（`data/`、`meta/` 两棵子树，204 段都在）；
逐文件核对：204/204 现场文件 = 记录的 `sha256_after`、204/204 备份 = `sha256_before`。

拿到**仓库之外**的 1.3.13 数据时先按这条确认（`app_version` 不足以判定）。
`config/settings.py` 与 `config/__init__.py` 的帧注释块有同一提醒。

### 4.5.2 SLAM 点与视频帧的时间对齐

`slam_trajectory` 每点的第 0 个字段 `t` 是**相机传感器钟**上的时间（native
侧 `img->timestamp`，相对按下 ENTER 设原点那一刻）。它与 RGB 帧的
`hardware_ns`（宿主单调钟）**不同源**，两者之间只差一个近似常量但带抖动的
偏移——只能从数据反推、不能换算。实测同一段数据反推出的偏移有三个估计值
（`arrival_monotonic − t` 中位、行桶中位、逐点拟合最优），散布约 **104 ms**，
已超一个帧间隔（33.3 ms）。

因此 v1.3.6 起 native 在每个取样帧进进程时取一次 `CLOCK_MONOTONIC`
（`RawImageFrame.host_mono_ns`），随帧走完预处理/跟踪/排队全程，最终与位姿
一起打在 stdout 的 `Host:(<ns>)` 字段上，落成
`observation.{prefix}slam_trajectory_ns`。

> **改这段 native 代码要认准文件**：构建源是
> `core/gripper/orb_slam_src/ORB-SLAM/Examples/fays/fayssense_orb_slam.cc`，
> 由同树 `dist/fays_opencv48/CMakeLists.txt` 的 `FAYS_BRIDGE_SOURCE` 硬指向
> （该值缺省就是 `${KSQ_ROOT}/ORB-SLAM/Examples/fays/fayssense_orb_slam.cc`）。
> 2026-09-17 之前这两份源码只存在于 `online/`（不上传），现已随包入库，
> 可以直接改、有版本控制兜底；重建走 `core/gripper/orb_slam_src/build.sh`。
> `core/gripper/native/ORB-SLAM/Examples/fays/` 下那份是**陈旧副本，不是构建源**
> （只留一份 `SUPERSEDED.md`），改它不会进二进制——它连 2026-09-11 的崩溃修复
> 都没有。`online/` 里那份现在是**同一份源码的第二份拷贝**，不再是真源。

- **与 `slam_trajectory` 同序等长**，下标即配对，所以某帧有 N 个轨迹点就有 N
  个时刻。这要求时刻列表**锁步**累积：某个点没有戳时补 `0`（= 未知，与
  `*_force_ns` 的约定一致）而**不是跳过**，跳过会让后续点全部错位且无从察觉。
- 有了它，配 slam 点↔视频帧退化成一次 `searchsorted`：按 `hardware_ns` 找
  最近的 `slam_trajectory_ns`。**不需要拟合偏移，更不需要插值**——从实测点里
  取最近邻是合法的 1:1，不是造假数据。
- **全段无戳时不建该列**（例如 Python 侧已升级但 native 二进制未重编）。
  下游按列是否存在判断「本段能否按时间对齐」；列存在但个别值为 0 表示那
  一个点缺戳。
- **行数不等于点数。** 写线程在落后超过一帧时会重置时钟并**跳过**那些 tick
  （`core/pipeline.py` 的 `_write_loop`），实测一段 11.4 s 的录制因此少写
  11 行；slam 点侧则约丢 0.22%。所以「slam 点数 == 视频帧数」不成立，
  按时间戳配对后剩下未配对的点/帧是正常现象，不是数据损坏。

### 4.6 `meta/info.json` 字段概览（LeRobot v3 兼容，上传服务器严格依赖）

| 键 | 含义 |
|---|---|
| `codebase_version` | 固定字符串 `"v3.0"` |
| `fps` | 默认录制帧率 |
| `video` | bool：是否有视频 |
| `task_name` | 任务名（空时 `""`） |
| `features` | `{observation.<sensor>: {dtype:"float32", shape:[16,16]}, observation.imu: {dtype:"float32", shape:[6]}, action: {dtype:"float32", shape:[1]}}`；shape 必须是 2D `[16,16]` 而非 1D `[256]` |
| `cameras` | dict 格式 `{槽名: {height, width, fps?}}`（深度槽不在此列） |
| `devices` | 紧凑设备段：`[{key, kind, name, slots}]`（无 serial 等敏感字段） |
| `device_names` | 槽位 → 用户命名映射 |
| `sensors` | 传感器名列表 |
| `sensor_dim` | 传感器维度 |
| `created_at` | 创建时间（Unix 时间） |

`stats.json` 对应 `features` 各键给出 `mean`/`std`/`min`/`max`（IMU 为 6 轴
样本级统计，`action` 为占位值），供归一化使用。

## 5. 相邻输出目录 `keypoints_output/`（不在 `data/` 下）

录制后的手部关键点处理结果**不写回** `data/recordings/`，而是镜像输出到
仓库根的 `keypoints_output/`（`settings.KEYPOINTS_OUTPUT_DIR`，gitignore）：

```
keypoints_output/<task>/<session>/
├── videos/                             # 关键点可视化视频
├── hand_pose/chunk-000.parquet         # 2D 手部关键点
├── hand_pose_3d/chunk-000.parquet      # 3D 手部关键点
└── auto_labels/auto_labels.parquet     # 自动标注
```

读取时有三级回退路径（`core/helpers.py`）：先查 `keypoints_output/` 镜像，
再查会话目录内 `keypoints/`，最后查旧版 `annotations/`（含 `annotations/mmpose/`）。