# Autocal 标定操作与数据格式草稿

状态：待评审，2026-10-11。用途：方案及操作指南。阶段一只针对 finger，由操作员手动完成选点、设档、加载、记录和逐点灵敏度可视化；下列流程尚非全部可执行的软件说明。

## 范围与软件现状

| 项目 | 当前约定 |
|---|---|
| 标定范围 | 多测点法向力，暂定 0–30 N；剪切及组合载荷后续再做 |
| 传感器 | 首版固定为 finger；其余类型须另行验证几何、采集和处理契约 |
| 压头 | 直径 6 mm、球面半径 3 mm 的半球压头 |
| 参考 | 砝码或 50 N／2 N·m FT sensor，首版先接通一种 |
| 图像 | 一个完整测试事件一个连续视频，档位间不切段 |
| 调试输入 | 已有视频与实时相机编号共用 finger worker 和 `SdkPacket`；相机实机尚未验收 |
| 交付 | 单个 session 能重新打开、追溯参考载荷，计算并显示不同测点的灵敏度 |

[LF606 规格书](references/lf606-d40-h18-4x-spec.pdf)量程表包含 50 N／2 N·m 档位，但图签为 200 N／8 N·m；实机以铭牌及标定证书核对。

现有模块与待接工作见[实施计划](implementation-plan.zh.md)；旧 `.oryseq` 格式见 [sequence-format.md](sequence-format.md)，其本身不包含下文的载荷循环。

## 操作员逐步流程

设备操作沿用 [workflow.md](workflow.md) 的准备、运动边界及停机流程。以下不新增自动运动授权；尚未接通的步骤不能靠占位按钮完成。

| 步骤 | 操作员动作 | 软件记录／通过条件 |
|---|---|---|
| 1. 建立会话 | 填写传感器 SN、gel ID、实验台、压头和参考设备；选保存位置 | 创建唯一 `session_id`；保存身份和配置快照 |
| 2. 检查设备 | 完成设备设置、回零及既定检查，核对相机和参考输入 | 状态可读；运动边界按既定流程确认 |
| 3. 确认测点 | 在有效 UV 区域选点，核对三维位置和姿态 | 分配 `site_id`，UV→3D 映射有效 |
| 4. 设置循环 | 定义加载范围、档位、保持时间和重复数，选择手动模式 | 保存计划；自动加载留到下一阶段 |
| 5. 建立基准 | 无接触时检查零载荷，保存参考图像和必要历史 | 保存归零／基准事件及 `baseline_id` |
| 6. 开始事件 | 到达确认的测点姿态后，在加载前启动记录 | 新建 `trial_id` 和视频；确认视频与参考记录正常后加载 |
| 7. 逐级加载 | 用现有手动控制或砝码到目标档位，确认实际到达并保持 | 每档有 `step_id`、目标及有效参考力、分支和时间范围 |
| 8. 逐级卸载 | 按相同档位下降到零，保留恢复过程 | 连续记录卸载分支；循环内不重新归零或重置图像基准 |
| 9. 结束／重复 | 检查恢复与记录状态，停止事件；重复或移到下一点 | 完成写入后标记状态；每次重复使用新 trial 和视频 |
| 10. 计算与复核 | 重新打开会话，选择有效保持窗口，查看每点曲线及 UV 灵敏度图 | 显示加载／卸载差异、误差、无效原因；留完整 trial 独立验证 |

推荐路径为 `0 → F1 → F2 → Fmax → F2 → F1 → 0`，具体档位待定。逐级卸载提供与加载分支相同载荷的对照；各档采用相同保持规则。保持时间先支持 10–30 s 配置，人工选择分析窗口并记录原因；到时不自动等于稳定。异常时按既定流程停止，保留未完成记录，重测用新 trial。

## 坐标与关联

| 对象 | 保存内容 | 约定 |
|---|---|---|
| 测点 | `uv_xy`、`position_sensor_mm` | UV 单位 pixel，可为亚像素值；直接映射到 mesh 的 mm 位置 |
| UV 定义 | `uv_origin_px`、图像尺寸、轴正方向 | 原点在有效 mask 内底部中间；允许负 Y |
| 几何 | `geometry_id`、mesh／mask／映射文件及哈希 | 固定映射版本，二维与三维值可相互核对 |
| 姿态 | `T_platform_from_sensor`、`pose_source`、激励方向 | 记录传感器→平台变换，区分实测和指令；normal 不必单独保存 |
| 关联层级 | `session → site → trial → step → samples` | trial 是完整循环，step 是循环内档位；帧与参考流按时间关联 |

## 文件及内部参数

以下为新格式建议，不是现有共享记录器文件的原样清单。`sites`、`trials` 和 `steps` 先内嵌于 `session.json`。

| 文件 | 主要字段／数据 | 写入时机 |
|---|---|---|
| `session.json` | `format_version`、`session_id`、`sensor_type`、`input_source`、身份、配置快照、坐标定义、文件清单、sites、trials、状态 | 会话建立、事件完成及结束时 |
| `sequence.oryseq` | 实际使用的测点计划；遵循现有格式 | 开始采集前保存快照 |
| `video/<trial_id>.<ext>` | 算法入口图像、完整循环及恢复 | 每 trial 开始至结束 |
| `frames.csv` | `session_id`、`trial_id`、`frame_id`、`t_host_mono_ns`、`t_host_utc_ns`、`time_basis`、视频路径、帧号、丢帧标记 | 每帧，时间与帧身份同时绑定 |
| `baseline/` | 基准图像、初始状态或预录引用、`baseline_id` | 建立／重置基准时 |
| `reference.csv` | `trial_id`、`sample_id`、`t_host_mono_ns`、`clock_id`、力、有效性、来源及延迟估计 | FT／ECAT 每个样本；砝码用事件和有效时段 |
| `motion.csv` | 时间、目标／反馈位姿、有效性 | 有实际反馈时保存；缺少反馈须注明 |
| `events.csv` | `t_host_mono_ns`、trial／step、事件类型、参考有效时段、原因 | 到档确认、阶段切换、归零、异常及中断 |
| `derived/<processing_id>/` | 逐点灵敏度表、加载／卸载曲线、误差、分析窗口和处理配置 | 分析时另存；不覆盖原始文件 |

| 参数归属 | 主要参数 | 单位／填写来源 |
|---|---|---|
| session 身份 | `sensor_sn`、`gel_id`、`bench_id`、`indenter_id`、`reference_source` | 操作员填写或设备读取 |
| session 采集 | 分辨率、像素格式、编码、版本、滤波与归零配置 | 软件快照；编码待实测确认 |
| 输入来源 | `input_source.kind` 为 `video` 或 `camera`；`value` 分别为视频路径或相机整数编号；视频另存文件哈希 | 传给同一 `FingerAcquisitionWorker.start`；来源文件与 trial 输出视频不可混淆 |
| session 时间 | 同进程 `clock_id`、单调时钟原点、UTC 对照、时间来源、延迟及同步误差 | 电脑采集／接收时记录；不能按行号配对 |
| site | `site_id`、UV、三维位置、几何关联 | pixel／mm；软件映射 |
| trial | `trial_id`、`site_id`、重复编号、姿态、`baseline_id`、视频、起止时间、状态 | 软件分配并记录实际执行 |
| trial 计划 | `load_levels_n`、`hold_s`、`repeats` | N／s／次数；操作员设置 |
| step | `step_id`、`target_load_n`、`branch`、实际起止时刻、`analysis_window_s` | N／电脑单调时间；branch 为 load／unload／zero |
| step 砝码参考 | 质量、重力加速度、传力方向、有效时段及 `reference_load_n` | kg／m/s²／N；仅在传力条件成立时使用 m×g |
| 质量 | `valid`、`invalid_reason`、丢帧／中断状态 | 未知不补零；算法失败不等于图像不可用 |
| 逐点结果 | `site_id`、`gain_n_per_raw`、`sensitivity_raw_per_n`、有效档位数、误差及滞后 | 仅对有效独立参考与原始法向信号拟合；缺数据标无效 |

实时采集以电脑收到**该帧**时的单调时间为主时间。采集线程需把 `t_host_mono_ns` 与帧序号、图像原子配对；记录器再保存 UTC 对照，处理结束时间不能代替采集时间。FT／ECAT 样本也在电脑收到时打同源时间戳，按时间关联，并记录可测得的延迟与失同步；低延迟不等于零延迟。砝码的人工到档时刻只定义有效区间，稳定窗口仍需检查。

旧视频没有原始逐帧电脑时间时，重放取得的是本次解码时间，`time_basis=host_replay`；它可验证处理链，不能还原原实验与 FT 的同步。若视频附有原始帧时间则保留 `time_basis=original_recorded` 和原时钟身份。finger worker 已停止按配置帧率推算 `mono_t`，并在包中保留主机采集时间、源帧编号及可用的媒体时间；正式记录器仍须将这些字段写入 `frames.csv`。manifest 保留来源路径、哈希、配置、媒体帧率及各时间基准。

事件边界如下。`events.csv` 每行至少保存 `event_id`、`trial_id`、可为空的 `step_id`、`event_type`、`t_host_mono_ns`、`clock_id` 和 `reason`。操作员的确认时间和设备反馈时间分别标明来源；不得把按钮时刻冒充设备实际到档。所有流用 `trial_id` 与同源单调时间关联。

| 事件 | 触发与状态 |
|---|---|
| `trial_started` | 首帧可用且输出已打开后，trial 进入 `recording` |
| `step_reached` | 操作员确认到档或有效反馈确认；记录实际时刻和参考有效性 |
| `step_ended` | 本档保持及分析窗口结束，保留实际持续时间 |
| `trial_finished` | 视频与索引排空并通过完整性检查后，trial 进入 `complete` |
| `trial_aborted` | 输入、写入或操作异常；trial 进入 `incomplete`，保留已写数据及原因 |

`session` 在所有 trial 完成并检查文件后才进入 `complete`；任何缺失必须保留 `incomplete` 与原因。每次重试使用新的 `trial_id`，不覆盖旧视频。

逐点灵敏度先用有效保持窗口中的 `normal_force_raw` 和独立参考力拟合 `F_ref = gain_n_per_raw × raw + offset_n`；`sensitivity_raw_per_n` 为非零斜率的倒数。每个测点单独保存拟合范围、有效档位数、误差和加载／卸载差异。原始通道缺失、参考无效或载荷档位不足时不生成看似有效的系数。界面显示各点散点／拟合曲线，并在 UV 测点图着色；阶段一不从稀疏点外推整面精度。

以下是目标 `session.json` 的最小示意，供记录与分析模块共用字段；`video/` 是本次 trial 的输出，不是 `input_source` 原文件。例子不代表写入器已经实现。

```json
{
  "format_version": "0.1-draft",
  "session_id": "session-001",
  "sensor_type": "finger",
  "input_source": {
    "kind": "video",
    "value": "D:/samples/finger-input.mp4",
    "sha256": "<待采集时计算>",
    "clock_id": "host_replay",
    "time_basis": "host_replay",
    "configured_fps": 30.0,
    "source_fps": 30.0
  },
  "config_ref": "config/sensors/finger/sensor.json",
  "status": "incomplete",
  "sites": [{"site_id": "site-001", "uv_xy": [120.5, -4.0], "position_sensor_mm": [1.2, 0.8, 3.4]}],
  "trials": [{
    "trial_id": "trial-001",
    "site_id": "site-001",
    "baseline_id": "baseline-001",
    "video": "video/trial-001.mp4",
    "status": "incomplete",
    "steps": [
      {"step_id": "step-001", "branch": "load", "target_load_n": 5.0},
      {"step_id": "step-002", "branch": "unload", "target_load_n": 0.0}
    ]
  }]
}
```

## 软件数据流与责任

### 阶段一待接通链路

| 顺序 | 输入 → 处理 → 输出 | 负责模块 |
|---|---|---|
| 1 | 操作员设测点／载荷路径，可选导入 `.oryseq` → session 快照 | Autocal 会话与事件控制 |
| 2 | UV + 固定映射 → mesh 位置 + 平台姿态 → site／trial | 几何及现有姿态计算能力 |
| 3 | 视频路径先调试、相机随后 → 同一 finger 处理链；电脑采集时刻与帧绑定 → `SdkPacket`、trial 视频和索引 | SDK capture + shared worker；Autocal 不导入 Studio 的 UI 或控制器 |
| 4 | FT／ECAT 样本或砝码有效时段 + 手动控制反馈／确认 → 同源电脑时间流 | Autocal 参考输入及事件控制；与图像并行 |
| 5 | 事件结束 → 完成写入 + 完整性检查 → trial 状态 | 文件记录器及会话控制 |
| 6 | 视频解码 + 基准／配置 → 原始信号；时间对齐参考 → 逐点拟合、误差和 UV 着色 | Autocal 分析与可视化；结果存 derived |

保留现有算法通道值时可沿用 `forces.csv`，但它不是独立参考力。业务层组织试验，SDK 负责图像算法，共享记录器负责文件写入；不让 SDK 依赖 Autocal UI。

## 首版验收与待定事项

| 验收 | 通过条件 |
|---|---|
| 数据关联 | 每个视频可追溯到测点、姿态、基准、加载／卸载档位及参考力 |
| 可回放 | 重新打开后能解码完整 trial，恢复处理状态并重算选定窗口 |
| 有效性 | 丢帧、参考缺失、中断及失败显式可见；原始记录不被重处理覆盖 |
| 最小验证 | 至少留出完整 trial，分别比较加载／卸载的法向误差；阈值待定 |
| 逐点呈现 | 多测点各有灵敏度、有效性、参考力—原始信号曲线；UV 图能定位差异 |

开跑前仍须确定载荷档位、轴方向及精确原点、参考采集与同步、视频编码和恢复窗口。先实测单 trial 的容量及丢帧，再估算整场存储。视频空档不承诺连续回放。自动加载、空间模型及长期可靠性验证后续再做；本流程不证明剪切或多接触精度。