Spaces:
Running
Running
| # 数据文件架构接口契约（v1.1.2） | |
| > 本文是录制数据落盘格式的**规范性契约**，供一切读写该数据的程序严格对齐： | |
| > 服务器导入器、离线处理工具、第三方数据读取器。凡本文标注 **MUST** 的条目， | |
| > 写入方必须产出、读取方必须容忍；标注 SHOULD 为建议。歧义以 `core/helpers.py` | |
| > 与 `core/egodata_writer.py` 的实现为准。 | |
| > | |
| > 多设备并存（多相机 / 双夹爪 / ego 相机多轨迹）时的槽位与列名分配、`meta` | |
| > 声明细节见 [`multi_device_storage.md`](multi_device_storage.md)。 | |
| v1.1.0 起录制数据从「每会话一个子目录」改为**任务级池化布局**（LeRobot v3 | |
| 命名）。v1.1.1 起 `stats.json` 自含累加器（每块加 `count`），`.stats_state.json` | |
| 边车已废除。**v1.1.2 起每段文件名前缀 `file-` 改为 `episode-`**（编号不变： | |
| `file-011` → `episode-011`），应用内删除改为直接彻底删除（不再产生 `_trash/`）； | |
| **v1.1.2 起深度存储改单流 12-bit 灰度 HEVC MP4**（gray12le 对数深度码； | |
| x265 无 12-bit 灰度能力时回落 FFV1 gray16le MKV；旧双流 MKV / PNG16 仅 | |
| 读侧容忍，见 §8）。 | |
| 旧格式（v1.0 每会话目录）仅存在于历史数据，读侧工具内部处理， | |
| **本契约只定义新格式**。 | |
| --- | |
| ## 1. 顶层布局与格式判别 | |
| ``` | |
| data/recordings/<task>/ # <task> = 任务清洗名（可含中文） | |
| ├── videos/ | |
| │ └── chunk-{c:03d}/<image_key>/episode-{f:03d}.{ext} | |
| ├── data/ | |
| │ └── chunk-{c:03d}/episode-{f:03d}.parquet | |
| └── meta/ | |
| ├── info.json | |
| ├── stats.json | |
| ├── tasks.jsonl | |
| ├── recycled_episode.json # 异常终止回退标记，见 §7.5 | |
| └── episodes/ | |
| ├── .lock # 运行时锁锚点，见 §7.4 | |
| └── chunk-{c:03d}/episode-{f:03d}.parquet # 每 episode 一个文件（单行） | |
| ``` | |
| - **格式判别**：读 `meta/info.json` 的 `format` 字段，`"pooled_episodes_v1"` | |
| 即本契约；`format` 缺失且存在 `<task>_NNNNNN` 子目录者为 v1.0 旧格式。 | |
| - 任务目录内**没有** `calibration/`、`metadata.json`、`timestamps.json`、 | |
| 每会话子目录（v1.0 遗留物）。 | |
| - `<task>` 即任务名；上传/项目语义中「会话名」概念废除，任务名即项目名。 | |
| ## 2. 编号规则（MUST） | |
| 全局 episode 序号 **N 从 1 起递增**（跨该任务全部 episode；权威 = data/ | |
| videos 文件组扫描与 `tasks.json` 进度水位取 max）： | |
| ``` | |
| chunk = (N - 1) // 1000 # chunk-000 装 N=1..1000 | |
| fnum = (N - 1) % 1000 # 三位零起：episode-000 .. episode-999 | |
| ``` | |
| - `chunks_size = 1000`（info.json 声明，服务器/工具按此计算，勿写死）。 | |
| - 同一 episode 的**所有文件共用同一个 (chunk, fnum)**：视频各流、data | |
| parquet、episodes 每段文件（episode-005 = 第 6 个 episode，全部同名）。 | |
| - **界面/上传的任务名后缀 = episode 文件号（0 基）**：第 N 段显示 | |
| `_ep{(N-1)%1000:06d}`（即 `_ep000011` = 本地 `episode-011`）。回放/上传 | |
| 界面显示名、zip 内 arcname、上传表单 `episode_index` 值**三处同一号码** | |
| （= 本地文件后缀）；真实全局序号 N 只出现在 parquet 的 | |
| `episode_index` 列，不靠界面名反推。 | |
| - **异常终止不占号**：GUI「异常终止」丢弃的录制**不消耗序号**——中止时 | |
| 写下 `meta/recycled_episode.json` 标记（§7.5），下一次录制优先复用该号 | |
| （即使进度水位已跑在前面也不跳号）；正常完成即清标记。**删除（含上传后 | |
| 自动删除）不回退**：已完成的 episode 序号永不复用（服务器已持有该号）。 | |
| 删除即彻底删除（v1.1.2 起无 `_trash/` 回收区）；2026-10-12 起删完**校验** | |
| 三处（videos/data/meta 行）确实不在，并真删本地录制记录（`pipeline.db` | |
| 的 recording 行），删不净如实报错。 | |
| - **旧分片命名残留（读侧 MUST 容忍）**：v1.1.0 早期曾用「每 chunk 一个 | |
| 分片」，分片文件名 = chunk 自身编号（chunk-000 → file-000.parquet， | |
| 一个文件装该 chunk 内最多 1000 个 episode 的行）。该布局已废除，新写入 | |
| 一律每段一文件；读侧工具（`episode_row`/上传/迁移）对旧分片按 | |
| `episode_index` 列过滤做回退，**不靠文件名**。v1.1.2 起每段文件前缀 | |
| `episode-`、分片保留 `file-` 前缀，两者路径不再重名。 | |
| ## 3. meta/info.json（任务级，MUST 字段） | |
| 单 JSON 对象（可读缩进，无单行约束）： | |
| | 字段 | 类型 | 说明 | | |
| |---|---|---| | |
| | `format` | str | `"pooled_episodes_v1"`（格式判别键） | | |
| | `chunks_size` | int | `1000` | | |
| | `data_path` | str | 模板 `data/chunk-{c:03d}/episode-{f:03d}.parquet` | | |
| | `video_path` | str | 模板 `videos/chunk-{c:03d}/{image_key}/episode-{f:03d}.{ext}` | | |
| | `episodes_path` | str | 模板 `meta/episodes/chunk-{c:03d}/episode-{f:03d}.parquet` | | |
| | `codebase_version` | str | 数据代码基准版本（如 `"v3.0"`，沿用服务器侧语义） | | |
| | `app_version` | str | 主程序版本（如 `"1.1.0"`） | | |
| | `fps` | float | 录制帧率（如 `30.0`） | | |
| | `video` | bool | 是否含视频 | | |
| | `task_name` | str | 任务名（= 目录名） | | |
| | `features` | obj | **只声明实际存在的列**：`action` 恒在；`observation.<sn>` 每传感器一列；有 IMU 才有 `observation.imu`。形如 `{"action": {"dtype": "float32", "shape": [1]}, "observation.imu": {"dtype": "float32", "shape": [6]}, "observation.right_glove": {"dtype": "float32", "shape": [256]}}` | | |
| | `cameras` | obj | RGB 相机键 → `{height, width}`（深度槽不入 cameras，见 `video_extensions`） | | |
| | `devices` | list | 设备紧凑注册：`{key, kind, name, slots}`（kind: d435/s80m/uvc…；slots 为该设备的 image_key 列表） | | |
| | `device_names` | obj | image_key → 设备显示名 | | |
| | `sensors` | list | 任务级出现过的传感器名 | | |
| | `sensor_dim` | int | 传感器观测维度（如 `256`） | | |
| | `created_at` | float | 任务创建时间（Unix 秒） | | |
| | `calibration` | obj | **任务级最新标定**（每设备一键：如 `head_stereo`，内容为 `StereoCalibration.to_dict()` 规范化结构：`type/name/resolution/fps/baseline/left_camera/right_camera/depth_scale/cam_imu_timeshift`，相机内参为 `{intrinsic: [fx,fy,cx,cy], distortion: [...]}`）。多设备时以设备名/前缀消歧编号（`d435_rgb_calibration` 等） | | |
| | `total_episodes` | int | 当前 episode 数（上传删除不回退，见 §6） | | |
| | `video_extensions` | obj | **每个 image_key** → 扩展名（RGB=`mp4`；深度=`mp4`=12-bit 灰度 HEVC、`mkv`=FFV1 回落）；读侧必须按此判文件，勿按扩展名硬猜格式 | | |
| | `gripper_slam_frame` | str | **条件字段（v1.3.13 增）**：本任务 SLAM 位姿所用的坐标帧 id。**只在任务真有 SLAM 轨迹列时写**——没有 `observation.*slam_trajectory` 的任务不会出现这个键。取值见 §3.1 | | |
| ### 3.1 SLAM 位姿坐标帧（v1.3.13 增） | |
| 两处标注，作用不同： | |
| - **顶层 `gripper_slam_frame`**（上表）：整个任务的位姿帧，一眼可见。 | |
| - **`features["observation.<sn>_slam_trajectory"]` 里的 `frame` / `frame_axes`**： | |
| ```json | |
| "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"} | |
| } | |
| ``` | |
| ★键名带**夹爪前缀**：第 1 台夹爪前缀是空串（列就叫 `observation.slam_trajectory`， | |
| 上面的例子就是它），第 2 台起才是 `observation.gripper_2_slam_trajectory`。 | |
| 读端请按 `observation.*slam_trajectory` 配，别写死带 `gripper_1_` 的名字—— | |
| 那个键在磁盘上**不存在**。 | |
| `frame` 是帧 id，`frame_axes` 是各轴在现实中指向哪（中文名只在 GUI 上，不落盘）。 | |
| 两个已知 id： | |
| | `frame` | `frame_axes` | 叫法 | | |
| |---|---|---| | |
| | `down_left_forward` | `{"+X":"down","+Y":"left","+Z":"forward"}` | 新帧，**v1.3.13 起的默认** | | |
| | `right_forward_up` | `{"+X":"right","+Y":"forward","+Z":"up"}` | 旧帧（`X=右/Y=正对/Z=上`） | | |
| ★旧帧的 `+Y` 也叫 `forward`（中文写「正对」不是「前」），而它和新帧 `+Z` 的 | |
| `forward` **是同一个物理方向** —— M 恰好把中间帧 +Y 映到发布帧 +Z（实测映射： | |
| 旧+X 右→新−Y **右**、旧+Y 正对→新+Z 前、旧+Z 上→新−X **上**；后两项的方向词 | |
| 读的是**落点那个轴是什么方向**，不是新帧同名字母的含义）。所以： | |
| **`forward` 可以跨帧等同，轴字母不行**。旧 `+Y` 与新 `+Y` 差 90°（前者正对、 | |
| 后者左），读端别按轴字母把两个帧对齐，要按 `frame_axes` 里的方向词。 | |
| **读侧两条硬规则：** | |
| 1. **`frame` 键不在 = 旧帧**，不是"取默认值"。分界是**发布版本**不是日历日： | |
| v1.3.13（2026-09-28）起录的才写这个键，v1.3.12 及更早录的**根本不写**。 | |
| 所以对老 episode 忽略这个键、按 `right_forward_up` 解读。 | |
| 2. **标注是任务级的**，不是每 episode 一条：`features` 按并集 / 后写覆盖合并， | |
| 一个任务目录若跨了这次改帧，`info.json` 只能记住**最后写入**的那个帧， | |
| 该任务早期的 episode 会被标错。要逐 episode 精确区分得往 `meta/episodes` | |
| 加列（v1.3.13 未加）。跨线的任务目录请按录制日期切开。 | |
| 3. **帧是一回事、姿态相对化是另一回事**：相对化从 ≤1.3.12 起一直是**左乘** | |
| `R0ᵀ·R`（锚点体轴系里的 body delta；先在 `process_controller`，v1.3.13 起搬到 | |
| `protocol.finish_publish_pose`，乘的侧没变），v1.3.14 才改成正确的**右乘** | |
| `R·R0ᵀ`。两者只差一个常数共轭（位置/幅度看着都正常，但读端按错的那支解会让 | |
| **表观旋转轴整体转错**），而 `frame` 与 `app_version` **都分不出**（两个构建 | |
| 都是 `down_left_forward`、`__version__` 都写 `"1.3.13"`）。 | |
| **新帧**数据已按右乘回填（`data/recordings/UMI_9_29`，逐文件 sha256 记在其 | |
| rotfix 备份目录的 `MIGRATION.json`）；**旧帧**数据（无 `frame` 键）同样是左乘、 | |
| 本次**没动**，要不要重解释**待判定**。详见 `docs/data.md`。 | |
| 坐标约定本身（各轴在现实中指向哪、原点与首帧相对化、两套帧 id、回落开关） | |
| 见本仓库 `docs/data.md` 的「SLAM 轨迹的坐标帧」一节。发布侧那张换基矩阵 `M` | |
| （`core/gripper/slam/protocol.py` 的 `PUBLISH_RELABEL_QUAT` / `PUBLISH_RELABEL_MATRIX`） | |
| 是**实现细节**，`data.md` 里没有、读端也不需要：按 `frame_axes` 解释数值即可。 | |
| ## 4. meta/stats.json（任务级全局统计，v1.1.1 契约） | |
| 单 JSON 对象。**每块 {count, mean, std, min, max}，列表维度 = 列维度**： | |
| ```json | |
| { | |
| "observation.right_glove": {"count": 1196, "mean": [...256 个], "std": [...], | |
| "min": [...], "max": [...]}, | |
| "observation.imu": {"count": 9922, "mean": [...6 个], "std": [...], | |
| "min": [...], "max": [...]}, | |
| "action": {"count": 0, "mean": [0.0], "std": [1.0], "min": [0.0], "max": [0.0]} | |
| } | |
| ``` | |
| - **`count` 是累加器契约**：`sum = mean * count`、`sum_sq = (std² + mean²) * count`。 | |
| 写入方在每个 episode 结束后**读入现有 stats.json、按公式合并本 episode 统计、 | |
| 原子写回**；文件自身即持久累加器，**不存在任何边车**（`.stats_state.json` | |
| 已废除，读到即旧版残留，忽略即可）。 | |
| - **MUST**：`count` 恒存在。无 `count` 的块 = v1.1.0 旧格式，写入方须全量重扫 | |
| `data/` 重建一次再增量合并（参考 `core.helpers.recalc_stats`）。 | |
| - `action` 恒为占位块（`count:0`，仅声明列形状，不参与统计）。 | |
| - 只统计实际存在的列：帧级 `observation.<sn>`（逐行计数，含全零行）、样本级 | |
| `observation.imu`（按样本计数）；`observation.*hand_pose` 为恒写列（USB 手套 | |
| 录制时由 IMU 实时解算回填，无解算时为零占位），**不入统计**。 | |
| - 语义：删除 episode 不回退 stats（与任务进度水位一致）；stats.json 是全任务 | |
| 聚合快照，不是逐 episode 重建值。 | |
| ## 5. meta/tasks.jsonl（任务级，单行 JSONL 是格式契约） | |
| ```jsonl | |
| {"task_index": 0, "task": "D435-裸手_3D手部关键点识别_AI标注"} | |
| ``` | |
| - **MUST 每行一个完整 JSON 对象、且当前实现为单行**；读取方必须 | |
| `json.loads(f.readline())` 逐行解析。**禁止美化/多行重排**——多行会静默破坏 | |
| 首行读取器（task_index 变 0）。写入方只在文件不存在时创建。 | |
| ## 6. meta/episodes/（episode 元数据，每段一个文件） | |
| ### 6.1 文件与原子性 | |
| - **每 episode 一个文件** `chunk-{c:03d}/episode-{f:03d}.parquet`（与 data/videos | |
| 同编号：episode-000 = episode 1），**恒 1 行**（11 列，见 §6.2）。 | |
| - episode 结束时**单行原子写**：临时文件 + `os.replace` 原子替换；同号重录 = | |
| 覆盖该文件。读取方 MUST 容忍文件在任意时刻被原子替换（每次打开重新 | |
| 读取，勿缓存 fd）。 | |
| - 新布局写入**不需要 flock**（单文件原子替换即完整）；flock 锚点 `.lock` | |
| 仅剩旧分片回退的读-改-写路径使用（见 §7.4）。 | |
| - **旧分片回退（读侧 MUST 容忍）**：v1.1.0 早期目录可能存在「每 chunk 一个 | |
| 分片」（文件名 = chunk 编号的 file-{c:03d}.parquet，≤1000 行，行序按 | |
| `episode_index` 升序）。读侧定位行必须按 `episode_index` 列过滤、 | |
| **不靠文件名**（v1.1.2 起分片保留 file- 前缀、每段文件改 episode- | |
| 前缀，路径不再重名）。 | |
| `scripts/migrate_pooled_storage.py --split-episodes` 可把旧分片原地拆成 | |
| 每段文件（幂等）。 | |
| ### 6.2 列（11 列，MUST） | |
| | 列 | 类型 | 说明 | | |
| |---|---|---| | |
| | `episode_index` | int64 | 全局序号 N（1 起） | | |
| | `task_index` | int64 | 任务序号（现恒 0） | | |
| | `start_frame_index` | int64 | 首帧 frame_index | | |
| | `end_frame_index` | int64 | 末帧 frame_index | | |
| | `length` | int64 | 帧数 = data parquet 行数 | | |
| | `created_at` | float64 | episode 开始时间（Unix 秒） | | |
| | `duration_sec` | float64 | 时长（秒） | | |
| | `drop_stats` | str | **JSON 字符串**（如 `{"imu_overflow": 0}`），读取方须 `json.loads`。v1.3.10 起含**带后缀**的键：`*_ms`/`*_count` 是时长/次数（夹爪 RGB 帧空洞与采集侧仪表），**不是帧数**——加总帧数前须过 `core.pipeline.is_frame_drop_key`（见 §7.3） | | |
| | `video_codec` | str | **JSON 字符串**：本机原始编码信息（encoder/codec/crf/ffmpeg 路径/probe）；上传 zip 中的 mp4 可能已被再编码，见 §8 | | |
| | `calibration` | str | **JSON 字符串**：本 episode 标定（结构与 info.json 的 calibration 同型），保每 episode 标定保真 | | |
| | `force_matrix_specs` | str | **JSON 字符串**：本段力矩阵列规格（列名 → 描述），**倍率的权威来源**，见 §7.2.1。v1.3.x 新增；旧 episode 无此列（读侧按缺列容忍，退回 info.json） | | |
| **追加旧任务（写侧 MUST）**：向 v1.3.x 之前的任务继续录 episode 时，重写整表 | |
| 须对缺列补默认值（`force_matrix_specs` → `"{}"`，现由 `_episode_rows_table` | |
| 按 schema 填），否则新行与旧行拼不成一张表。读侧同理 **MUST 容忍该列缺失**。 | |
| ## 7. data/（每 episode 一个 parquet） | |
| `data/chunk-{c:03d}/episode-{f:03d}.parquet`，zstd 压缩，**稀疏列**（有数据才写该列）。 | |
| ### 7.1 键列（恒有） | |
| | 列 | 类型 | 说明 | | |
| |---|---|---| | |
| | `episode_index` | int64 | = N | | |
| | `frame_index` | int64 | 帧内序号，0 起递增，无空洞（abort 不落盘） | | |
| | `timestamp` | float32 | **墙钟相对秒**（episode 内相对，f32 精度够） | | |
| | `task_index` | int64 | 现恒 0 | | |
| | `wall_time` | float64 | **绝对 Unix 秒**（宿主时钟锚） | | |
| | `hardware_ns` | int64 | 设备时钟硬件时间戳（ns，可绕回）；IMU 挂靠基准。**D435（v1.3.11 起）取本行那一帧自己的戳**（RGB 行=彩色帧、深度=深度帧）；取不到设备钟时写 0（=未知），宿主时间另存 `host_ns` | | |
| | `depth_ns` | int64 | （D435）本行深度成员的设备钟 ns；深度轨对齐用，0=未知 | | |
| | `rgb_dup` / `rgb_gap` | int8 / int32 | （D435）彩色帧是否与上一行同一物理帧 / 中间跳过几帧（`frame_counter` 口径）| | |
| | `depth_dup` / `depth_gap` | int8 / int32 | （D435）同上，针对深度成员 | | |
| | `raw_hw_ns` | int64 | **归一前**的原始戳（v1.3.11，所有 RGB 槽位）。设备钟链路（D435）的 `hardware_ns` 在录制期被重写成「锚点 + 序号 × T」，原始值在这一列；**宿主钟链路（夹爪/S80M/裸手）两列相同**（v1.3.17 起不再重排） | | |
| | `ts_src` | int8 | （D435）时间戳来源：0=无设备钟 1=逐帧元数据 2=帧组戳(设备钟) 3=帧组戳(宿主钟) | | |
| | `host_ns` | int64 | （D435）仅 `ts_src=3` 时非 0：宿主单调钟 ns，不冒充设备钟 | | |
| ### 7.2 观测列（稀疏） | |
| | 列 | 类型 | 说明 | | |
| |---|---|---| | |
| | `observation.<sn>` | list<float32, 256> | 每帧一个传感器读数（维度 = info.json `sensor_dim`） | | |
| | `imu_ts_ns` | list<int64> | 与 `observation.imu` **一一对应**的样本时间戳 | | |
| | `observation.imu` | list<list<float32, 6>> | 挂在帧行上的**变长样本列表**（1000Hz/400Hz 只是 list 长短变化） | | |
| | `observation.left_hand_pose` | list<float32, 63> | **恒写列**：USB 手套录制时由 IMU 实时解算回填，无解算时为零占位；裸手 63 维 world landmarks 由后处理回填 | | |
| | `observation.right_hand_pose` | list<float32, 63> | 同上 | | |
| | `action` | list<float32, 1> | 恒写（现为 0） | | |
| | `status.<did>` | str | 稀疏设备状态列（`"connected"`/`"disconnected"` 等） | | |
| #### 7.2.1 力矩阵列（UMI 夹爪） | |
| `observation.[gripper_N_]gripper_{left,right}_force_matrix` —— 稀疏 `list` 列， | |
| 每个样本是一整帧 `(250,250,3)`（fx/fy/fz，单位 mN）的扁平编码，长度恒 | |
| `250 × 750 = 187500` 行差分按 `(250, 750)` 分块还原： | |
| | 编码 | 列类型 | 解码 | | |
| |---|---|---| | |
| | `row_flat_raw` | `list<float32>` | 原值直存（无差分无量化），`reshape(250,250,3)`；**不要 cumsum** | | |
| | `row_diff_quantized` | `list<int16>` | 先 `cumsum` 还原差分（int16 回绕，累加器用 int32），再 `reshape`，最后 ÷`scale` | | |
| **`scale` 是读取端的必需信息，不能从数据推断**：×10/×100/×1000 三档的列类型 | |
| 都是 `list<int16>`、元素也都是 int，只有 `scale` 能决定 ÷10 还是 ÷1000。 | |
| 漏读 = 数值整体放大 N 倍（图形形状仍对，故为静默错）。`row_flat_raw` 恒 1。 | |
| **权威顺序（读侧 MUST）**： | |
| 1. 同号 `meta/episodes/chunk-NNN/episode-NNN.parquet` 的 `force_matrix_specs` | |
| —— **每段一份，权威**； | |
| 2. `<task>/meta/info.json` 的 `features[列].scale` —— 任务级**回退**； | |
| 3. 都没有 → 1（未定标）。 | |
| **为什么必须有 (1)**：`info.json` 是任务级且「值以最新 episode 为准」， | |
| 同任务里换过力矩阵档位，早先几段的 `scale` 会被后一段覆盖（实测 ×10/×100/ | |
| ×1000 三段连录后再录一段 float32，三段全被顶成 1）。(1) 每段写一次、只增不改， | |
| 不受后续录制影响。 | |
| **自检判据**：同一帧 `Σ(fz 平面)` ≈ 同帧 `observation.*_gripper_*_force` 的 | |
| fz 分量（float32 档实测比值 1.000）。历史未定标 int16 档因逐点向零截断， | |
| 该比值明显小于 1（实测 0.04~0.55）——这是截断造成的，不是倍率。 | |
| `scripts/repair_force_matrix_scale.py` 用该判据给旧 episode 补写 (1)（只补 | |
| meta 行，不碰 data 字节）。 | |
| ### 7.3 时间对齐模型（MUST 理解） | |
| **表为帧行为主**：一行 = 一个 30fps 帧；视频帧/传感器读数/帧行共用同一 | |
| `frame_index`（写入线程同拍产出）。IMU 为变长 list 列挂在帧行上，录制时按 | |
| `hardware_ns` 设备时钟窗口挂靠。读取零重采样；宿主时间锚定靠 `timestamp` + | |
| `wall_time`。客户 9 列平表由导出工具展开插值合成，非本契约内容。 | |
| **两个时间戳分别是谁盖的（MUST 理解，v1.3.10 明确）**： | |
| | 列 | 盖戳者 | 语义 | | |
| |---|---|---| | |
| | `wall_time` | **写入线程**，`episode 起始墙钟 + timestamp`（v1.3.17 起） | 该行**采集时刻**的绝对 Unix 秒；`wall_time − timestamp` 恒为常数、段内严格递增。旧口径是落行那一刻的 `time.time()`，会带上写队列积压与掉拍（实测差整行 33ms） | | |
| | `hardware_ns` | **采集侧**，相机/传感器取到帧处 | 该帧**取到**的时刻。双目是 SDK 硬件戳（与 IMU 同源）；夹爪 RGB 是采集线程的宿主单调钟（≤078 段被截成有符号 32 位、每 4.295s 锯齿一次，读取方须按 2^32 解卷 —— `tools/audit_frame_gaps.py` 的 `trunc32`） | | |
| 两者之差 = 中间队列的滞留（+ 两钟固定偏移）。**空洞**（相邻行 `hardware_ns` 间隔 | |
| 超出标称帧间隔的部分）不等于画面丢了：夹爪 RGB 的空洞要走画面复核才能定性 | |
| （真丢 / 帧晚到 / 判不了），口径与全库基线见 | |
| [postmortem §4](postmortem_trajectory_and_rgb.md)。 | |
| ### 7.4 meta/episodes/.lock（运行时辅助文件，非数据） | |
| `meta/episodes/.lock` 是**空文件**，flock 锁锚点——旧分片回退的读-改-写用 | |
| `os.replace` 原子替换（inode 变化），锁必须挂在**路径不变的锚文件**上，故锚点 | |
| 为空文件、锁在 fd 上而非文件内容。新布局的每段文件写入是单文件原子替换， | |
| 不走该锁。**其他程序 MUST 忽略该文件**（不解析、不打包、不告警）；上传 zip | |
| 不含它（dotfiles 一律不进包）。 | |
| ### 7.5 meta/recycled_episode.json（异常终止回退标记，非数据） | |
| 内容为单 JSON 对象 `{"episode_index": <int>, "freed_at": "<ISO>"}`。录制被 | |
| 「异常终止」时由写入器**原子写入**（临时件 + `os.replace`），标记该序号 | |
| 可复用；下一次录制取号时若该号未被文件组占用则**优先复用**； | |
| 录制正常完成时清除，号已被占（跨机共享目录/遗留）时自动放弃。删除 | |
| （含上传后自动删除）**不写**该标记——已完成的序号永不复用（见 §2）。 | |
| **其他程序 MUST 忽略该文件**（不解析、不打包、不告警）；上传 zip 不含它。 | |
| ## 8. videos/（每 episode 每流一文件） | |
| - 路径 `videos/chunk-{c:03d}/<image_key>/episode-{f:03d}.{ext}`，`<image_key>` 为 | |
| 槽名（同任务内不同 episode 之间**允许槽改名**，如 ep1 用 `D435_depth_rgb`、 | |
| ep2 用 `D435_head_rgb`——读侧必须按 episodes 行的 image_key 枚举，勿假设 | |
| 任务级固定集合）。 | |
| - 扩展名以 info.json `video_extensions` 为准：RGB=`mp4`（HEVC/h264）， | |
| 深度=`mp4`（12-bit 灰度 HEVC）或 `mkv`（FFV1 回落，仅 x265 无 12-bit | |
| 灰度能力时产生）。 | |
| - **深度视频（v1.1.2 起，MUST）**：单流 12-bit 灰度 HEVC MP4——hevc Rext | |
| `gray12le` 单平面（对数深度码，qp=6、range=full、不带 profile；hvc1 | |
| 容器标记），解码后按对数码反量化回 uint16 毫米（实现口径在 | |
| `core/depth_codec.py` / `core/depth_reader.py`）。读侧注意：cv2 直读 | |
| gray12le 的 8-bit 转换不可靠，像素一律走 ffmpeg CLI 解 gray12le。 | |
| - **FFV1 回落（读侧 MUST 支持）**：x265 不可用时写 FFV1 `gray16le` 无损 | |
| MKV（uint16 毫米原值），`video_extensions` 记 `mkv`。 | |
| - **旧深度布局（读侧 MUST 容忍，仅历史数据）**： | |
| - v1.0.14 双流 MKV：流0 = 热力图 H.264（默认播放画面），流1 = FFV1 | |
| `gray16le` 无损 uint16 毫米深度（用 ffprobe/ffmpeg 的 stderr 探测 | |
| FFV1 流号）；v1.0.14 迁移合成的单流 MKV 同款； | |
| - PNG16：v1.0.12 及更早的单帧 PNG 序列。 | |
| - RGB 的 `_aux` 类辅助流归主 key 同一目录，非主键可忽略。 | |
| ## 9. 上传 zip 契约（给服务器导入器，端点不变） | |
| `POST /api/v1/session/upload`，`name` 语义 = **任务名**，form 字段 | |
| `episode_index`（字符串化的 **episode 文件号**——0 基，与本 episode 的 | |
| `episode-{f:03d}` 完全一致，见 §2「任务名后缀」；真实全局序号 N 以包内 | |
| parquet 的 `episode_index` 列为准；旧服务器忽略未知字段）。 | |
| zip = **单 episode 切片**，包内 arcname 与原池化目录完全一致（相对任务目录）： | |
| ``` | |
| videos/chunk-{c:03d}/<key>/episode-{f:03d}.{ext} # 仅本 episode 的各流文件 | |
| data/chunk-{c:03d}/episode-{f:03d}.parquet # 本 episode 数据 | |
| meta/episodes/chunk-{c:03d}/episode-{f:03d}.parquet# 本 episode 单行文件直传 | |
| meta/info.json # 任务级快照 | |
| meta/stats.json # 任务级快照（v1.1.1 含 count） | |
| meta/tasks.jsonl # 任务级 | |
| ``` | |
| - **MUST**：dotfiles（`.lock`、临时件）不进包；episodes 直传本 episode 的单行 | |
| 文件（旧分片回退时打成单行切片，arcname 同为新命名）。 | |
| - 导入器以 `info.json.format == "pooled_episodes_v1"` 识别新格式。 | |
| - **HEVC 预压缩**：zip 内 mp4 可能已被再编码为 HEVC（hvc1, CRF30）以缩小体积， | |
| 与 episodes 行 `video_codec`（描述本机原始编码）**不必一致**；mkv 深度永不再编码。 | |
| - 上传删除 = 删该 episode 文件组（videos/data 各 key 本 episode 文件 + 本段 | |
| episodes 行文件），删完**校验三处都真的没了**（`pooled_episode_leftovers`）， | |
| 没删净如实报错；stats、total_episodes **不回退**（total_episodes 由下次录制 | |
| 按 `list_task_episodes` 重算），episode 序号永不复用。 | |
| - **删除入口的编号口径**：`delete_pooled_episode`/`delete_local_session` 收的是 | |
| 全局号 **N（1 基）**，和上传器（`episode_chunk_file(N)`）、`UploadManager` 的 | |
| `(path, episode_index)` 防重键同一口径。文件名里的 `f` 是 **chunk 内 0 基** | |
| 文件号，**跨 chunk 后 `f + 1` 不再是 N**：chunk-000 满 1000 段就开 chunk-001 | |
| 并从 `episode-000` 重新计数，所以 | |
| ``` | |
| N = c * 1000 + f + 1 （c = chunk 号，1000 = POOLED_CHUNK_SIZE） | |
| ``` | |
| **统一由 `core.helpers.list_task_episodes(task_dir)` 还原**（它按 | |
| `chunk*POOLED_CHUNK_SIZE + int(f) + 1` 产出全局号，是权威枚举器），不要自己 | |
| 拿文件名拼 N。少 +1 删错段；多 +1 会指向不存在的 N+1（此时「没找到任何文件」 | |
| 被幂等判为已删净而返回 True，界面报成功、文件一个没动）。 | |
| **f 回绕尤其危险**：chunk-001 出现后再取「最大文件名 f + 1」，得到的是 | |
| chunk-000 里**真实存在**的前一段（f=0 → N=1），于是静默上传/删除到错的段。 | |
| lite 的取号口径历史上错过两次：先是**少 +1**（返回 0 基文件号 f 当 N 用）， | |
| 改成 `max(f) + 1` 后又在跨 chunk 时**回绕**；两处都已修成走 | |
| `list_task_episodes`（`tools/tests/lite_delete_test.py` 第 1/4/6 节分别钉 | |
| 「ep 是全局 N」「单段目录 ep=1 不是 0」「跨 chunk 的 ep=1001 不是 1」）。 | |
| `_delete_after_upload` 本身一直是原样透传（没有 +1 可去），变的一直是它上游 | |
| 的取号口径。旧格式（`data/` 下没有任何 `chunk-*/episode-*.parquet`）按整目录 | |
| 处理，取号返回 0。 | |
| ## 10. 关键点镜像布局（keypoints_output/） | |
| 后处理产物（手部关键点）按同一池化键镜像存放，与录制目录解耦： | |
| ``` | |
| keypoints_output/<task>/episode_{N:06d}/ | |
| ├── hand_pose/chunk-000.parquet # 2D 关键点（MediaPipe 后端） | |
| ├── auto_labels/auto_labels.parquet # 自动标注 | |
| └── hand_pose_3d/chunk-000.parquet # 3D 关键点（bare 63 维 world landmarks， | |
| # 回填 data parquet 两列的来源） | |
| ``` | |
| 镜像目录内文件名不含 episode 号（父目录已键控），按帧 `frame_index` 与 | |
| data parquet 对齐。 | |
| ## 11. 不属于架构的文件（其他程序须忽略/不得依赖） | |
| | 文件/目录 | 说明 | | |
| |---|---| | |
| | `meta/episodes/.lock` | 运行时 flock 锚点，恒空 | | |
| | `meta/recycled_episode.json` | 异常终止回退标记（§7.5），完成即删 | | |
| | `meta/.stats_state.json` | v1.1.0 边车残留，**已废除**，见即删 | | |
| | `_trash/` | v1.1.1 及更早应用内删除的回收区残留；v1.1.2 起删除即彻底删除，不再产生 | | |
| | `.{name}.tmp` | 原子写临时件（`os.replace` 前身） | | |
| | `_episodes_{task_id}_{N}.parquet` | 上传打包临时切片（仅旧分片回退路径产生），打完即删 | | |
| | `_migrate_backup_*` | 一次性迁移备份目录 | | |
| ## 12. 对齐检查清单（新程序接入逐项验证） | |
| 1. 读 `info.json` 判 `format=="pooled_episodes_v1"`，未知 format 报错不猜。 | |
| 2. 路径全部经模板 + (N→chunk,file) 计算，勿扫描拼接；`chunks_size` 读 info.json。 | |
| 3. episodes 每段一个文件（episode- 编号 = data/videos 同编号）；旧目录的多行 | |
| 分片（file- 前缀）按 `episode_index` 列过滤回退，勿按文件名对齐。 | |
| 4. stats.json 每块必有 `count`；无 count 的旧块触发全量重算或忽略并告警。 | |
| 5. tasks.jsonl 逐行 `json.loads`，写回保持单行。 | |
| 6. 深度文件按 `video_extensions` 判扩展名；12-bit 灰度 MP4 走 ffmpeg | |
| gray12le 解码 + 对数码反量化，FFV1 MKV 做流号探测（双流/单流都 | |
| 支持），旧 PNG16 按历史回退读取。 | |
| 7. 视频槽名按 episodes 行枚举，容忍跨 episode 槽改名。 | |
| 8. dotfiles 与临时件一律忽略；上传 zip arcname 与池化目录一致、episodes 带 | |
| 本 episode 单行文件、`name`=任务名 + form `episode_index`。 | |
| 9. IMU 是变长 list 列，读取端展开时按 `imu_ts_ns` 对齐，勿假设固定采样率行宽。 | |
| 10. 新布局 episodes 写入 = 单文件临时件 + os.replace 原子替换（无需 flock）； | |
| 旧分片回退的读-改-写必须走 flock（POSIX）+ 临时文件 + os.replace。 | |