整理 Autocal 操作步骤与数据流表格

汇总文件与参数，区分现有软件链路和待实现流程。文档门禁通过。

apps/autocal/docs/calibration-data-format.zh.md

@@ -1,101 +1,115 @@
-# Autocal 标定数据格式草稿
+# Autocal 标定操作与数据格式草稿
 
-状态：待评审。日期：2026-10-10。用途：方案。近期目标是在几天内跑通多测点法向标定的最小数据流程；字段和目录均为建议，尚未实现。
+状态：待评审，2026-10-10。用途：方案及操作指南。近期目标是跑通多测点法向采集、保存和离线重算；下列操作是首版目标流程，尚非全部可执行的软件说明。
 
-## 目标与现状
+## 范围与软件现状
 
-数据应支持从原始图像重新计算标定，并用于提高实时力读数的可靠性。首阶段聚焦多测点法向力，暂定 0–30 N，使用砝码或 FT sensor 作为参考。保存完整激励过程，用于分析位置差异、滞后和漂移；剪切及组合载荷留待后续。
-
-现有 [sequence-format.md](sequence-format.md) 定义 `.oryseq` 测试计划；[workflow.md](workflow.md) 定义采集、原始存储、处理及验证流程。共享记录器已有帧索引、读数、事件和可选无损图像。本方案在此基础上补充测点、激励、独立参考测量及关联关系。
-
-## 数据组织
-
-首版以单个 session 为交付单位：建立测点及试验记录 → 采集图像和参考载荷 → 保存并重新打开 → 离线重算并检查对应关系。先支持一种实际可用的参考输入方式，不要求砝码和 FT 自动接入同时完成。多 session 数据集管理、剪切、复杂模型及自动稳定判定后续再做。
-
-测试计划、原始记录与标定模型分别保存。计划描述要做什么；原始记录描述实际发生什么；模型保存实时使用的参数及适用范围。后处理结果引用原始记录，不能覆盖它。
-
-层级为 `session → site → trial → steps/samples`。`site` 指表面测点；一次测试事件是同一测点的一次完整加载卸载循环，对应一个 `trial_id` 和一个独立视频。循环内的载荷档位使用 `step_id`，重复循环使用新的 `trial_id`。多 session 数据集管理后续再做。
-
-| 层级 | 建议保存的内容 |
+| 项目 | 当前约定 |
 |---|---|
-| `session` | 传感器 SN、gel ID、相机和实验台身份、探头形状尺寸、几何版本、装夹配置、软件版本及配置快照 |
-| `site` | 测点 ID、UV 坐标、mesh 三维位置及几何关联 |
-| `trial` | 测点 ID、载荷路径、姿态、重复编号、视频路径、开始结束时间、执行状态 |
-| `steps` | 档位 ID、目标载荷、加载／卸载分支、实际时间范围及分析窗口 |
-| `samples` | 图像、参考力和运动流，以及时间、阶段和质量信息 |
+| 标定范围 | 多测点法向力，暂定 0–30 N；剪切及组合载荷后续再做 |
+| 压头 | 直径 6 mm、球面半径 3 mm 的半球压头 |
+| 参考 | 砝码或 50 N／2 N·m FT sensor，首版先接通一种 |
+| 图像 | 一个完整测试事件一个连续视频，档位间不切段 |
+| 交付 | 单个 session 能重新打开、追溯参考载荷并离线重算 |
 
-## 测点与坐标
+[LF606 规格书](references/lf606-d40-h18-4x-spec.pdf)量程表包含 50 N／2 N·m 档位，但图签为 200 N／8 N·m；实机以铭牌及标定证书核对。
 
-UV 使用像素，直接通过固定版本的 UV→3D 映射取得 mesh 位置，同时保存二维与三维值用于核对。平台将测点法向对齐 Z；`normal` 不设为必填字段。
+| 功能 | 源码现状 | 首版需要补齐 |
+|---|---|---|
+| 设备设置、轴操作、测点姿态预览 | Autocal 已有对应模块 | 与采集事件关联 |
+| `.oryseq` 导入导出 | 已有；见 [sequence-format.md](sequence-format.md) | 载荷循环由 trial 的 steps 表达，不假定旧序列已支持 |
+| 自动执行、传感器及标定点页面 | 运行入口提示未实现，相关页面占位 | 最小事件控制和采集入口 |
+| 图像、读数、事件记录 | Studio／shared 已有记录链 | 接入 Autocal，增加 trial／step、参考流及独立事件视频 |
+| 新格式回放、拟合及导出 | 本文定义目标契约 | 关联校验与最小离线处理 |
 
-| 字段 | 约定 |
+## 操作员逐步流程
+
+设备操作沿用 [workflow.md](workflow.md) 的准备、运动边界及停机流程。以下不新增自动运动授权；尚未接通的步骤不能靠占位按钮完成。
+
+| 步骤 | 操作员动作 | 软件记录／通过条件 |
+|---|---|---|
+| 1. 建立会话 | 填写传感器 SN、gel ID、实验台、压头和参考设备；选保存位置 | 创建唯一 `session_id`；保存身份和配置快照 |
+| 2. 检查设备 | 完成设备设置、回零及既定检查，核对相机和参考输入 | 状态可读；运动边界按既定流程确认 |
+| 3. 确认测点 | 在有效 UV 区域选点，核对三维位置和姿态 | 分配 `site_id`，UV→3D 映射有效 |
+| 4. 设置循环 | 选择载荷档位、保持时间及重复数；预览正反路径 | 保存 `load_levels_n`、`hold_s`、`repeats`；档位不超本次确认范围 |
+| 5. 建立基准 | 无接触时检查零载荷，保存参考图像和必要历史 | 保存归零／基准事件及 `baseline_id` |
+| 6. 开始事件 | 到达确认的测点姿态后，在加载前启动记录 | 新建 `trial_id` 和视频；确认视频与参考记录正常后加载 |
+| 7. 逐级加载 | 按路径到各目标档位并保持，标记实际到达时间 | 每档有 `step_id`、目标及实际参考力、分支和时间范围 |
+| 8. 逐级卸载 | 按相同档位下降到零，保留恢复过程 | 连续记录卸载分支；循环内不重新归零或重置图像基准 |
+| 9. 结束／重复 | 检查恢复与记录状态，停止事件；重复或移到下一点 | 完成写入后标记状态；每次重复使用新 trial 和视频 |
+| 10. 复核会话 | 重新打开文件，回放至少一个完整事件，检查档位对应关系 | 缺失、丢帧和中断可见；保留完整 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`、身份、配置快照、坐标定义、文件清单、sites、trials、状态 | 会话建立、事件完成及结束时 |
+| `sequence.oryseq` | 实际使用的测点计划；遵循现有格式 | 开始采集前保存快照 |
+| `video/<trial_id>.<ext>` | 算法入口图像、完整循环及恢复 | 每 trial 开始至结束 |
+| `frames.csv` | `session_id`、`trial_id`、`frame_id`、`t_rel_s`、视频路径、段内帧号、丢帧标记 | 每帧 |
+| `baseline/` | 基准图像、初始状态或预录引用、`baseline_id` | 建立／重置基准时 |
+| `reference.csv` | `trial_id`、`t_rel_s`、`clock_id`、实测力分量、有效性 | FT 自身采样频率；砝码方式可不生成此流 |
+| `motion.csv` | 时间、目标／反馈位姿、有效性 | 有实际反馈时保存；缺少反馈须注明 |
+| `events.csv` | 时间、trial／step、事件类型、原因 | 到档、阶段切换、归零、异常及中断 |
+| `derived/<processing_id>/` | 对齐样本、特征、拟合结果、验证指标和处理配置 | 离线处理；不覆盖原始文件 |
+
+| 参数归属 | 主要参数 | 单位／填写来源 |
+|---|---|---|
+| session 身份 | `sensor_sn`、`gel_id`、`bench_id`、`indenter_id`、`reference_source` | 操作员填写或设备读取 |
+| session 采集 | 分辨率、像素格式、编码、版本、滤波与归零配置 | 软件快照；编码待实测确认 |
+| session 时间 | 各流 `clock_id`、时间戳含义、偏移及同步误差 | 软件记录；不能按行号配对 |
+| 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`、丢帧／中断状态 | 未知不补零；算法失败不等于图像不可用 |
+
+## 软件数据流与责任
+
+### 当前实际链路
+
+| 链路 | 代码位置／输出 | 对 Autocal 的含义 |
+|---|---|---|
+| 运行请求 → 未实现提示 | [window.py](../src/orisys_autocal/ui/window.py) 的 `_on_run_requested` | 尚无自动采集循环 |
+| 页面装配 → 占位页面 | [workspace.py](../src/orisys_autocal/ui/workspace.py) | 传感器、表面和标定点页尚未接通 |
+| Studio 采集包 → 记录通道 | [recording.py](../../studio/src/orisys_studio/recording.py) 的 `RecordingChannel.on_packet` | 将采集包分发给会话存储、标定采样器及文件记录器 |
+| 采集包 → 有界队列 → 写入线程 | [experiment.py](../../../shared/src/orisys_app_shared/record/experiment.py) | 当前写 session、forces、frames、events、分段 MP4 或 PNG；不能直接视为新格式已完成 |
+
+### 首版待接通链路
+
+| 顺序 | 输入 → 处理 → 输出 | 负责模块 |
+|---|---|---|
+| 1 | 操作员设置 + `.oryseq` → sites／载荷路径 → session 快照 | Autocal 会话与事件控制 |
+| 2 | UV + 固定映射 → mesh 位置 + 平台姿态 → site／trial | 几何及现有姿态计算能力 |
+| 3 | 相机 → SDK 采集包 → 视频、帧索引 | 复用 shared 采集与记录能力 |
+| 4 | FT／砝码 + 平台反馈 + 档位事件 → 带时间的数据流 | Autocal 参考输入及事件控制；与图像并行 |
+| 5 | 事件结束 → 完成写入 + 完整性检查 → trial 状态 | 文件记录器及会话控制 |
+| 6 | 视频解码 + 基准／配置 → SDK 特征重算；时间对齐参考 → 拟合／验证 | 离线处理，结果存 derived |
+
+保留现有算法通道值时可沿用 `forces.csv`，但它不是独立参考力。业务层组织试验，SDK 负责图像算法，共享记录器负责文件写入；不让 SDK 依赖 Autocal UI。
+
+## 首版验收与待定事项
+
+| 验收 | 通过条件 |
 |---|---|
-| `uv_xy` | UV 展开图的像素坐标，可为亚像素值；X 水平、Y 垂直，正方向随 session 保存 |
-| `position_sensor_mm` | mesh 所在传感器坐标系中的三维位置，单位 mm |
-| `geometry_id`、文件哈希 | 固定 mesh、UV→3D 映射及 mask 版本，并保留引用文件 |
-| `T_platform_from_sensor` | 本次 trial 的传感器→平台姿态及来源；实测与指令值区分保存 |
-| `excitation_direction_platform` | 平台坐标中的激励单位向量，明确正负号及运动方向与作用力方向的关系 |
+| 数据关联 | 每个视频可追溯到测点、姿态、基准、加载／卸载档位及参考力 |
+| 可回放 | 重新打开后能解码完整 trial，恢复处理状态并重算选定窗口 |
+| 有效性 | 丢帧、参考缺失、中断及失败显式可见；原始记录不被重处理覆盖 |
+| 最小验证 | 至少留出完整 trial，分别比较加载／卸载的法向误差；阈值待定 |
 
-原点位于有效 mask 内的底部中间，保存 `uv_origin_px` 及展开图尺寸；允许负 Y，有效性由 mask 判断。先还原原点偏移及轴方向，再查询 UV→3D 映射。三维单位为 mm，不需要把 UV 像素统一换算为 mm。
-
-## 激励条件
-
-每次 trial 记录参考来源 `reference_source`、法向方向、目标载荷、实际参考载荷、保持时间及重复编号。加载、保持、卸载通过阶段事件关联到时间流；零载荷也须实测记录。
-
-建议同一测点逐级加载，再按相同档位逐级卸载，最后恢复零载荷。例如 `0 → F1 → F2 → Fmax → F2 → F1 → 0`，档位仍待确定。每档采用相同的保持和取样规则，保留过渡过程，比较相同参考力下两个分支的响应；中途不重新归零或重置图像基准。[GelSight 研究](https://doi.org/10.3390/s17122762)指出黏弹性可造成加载卸载差异。
-
-每档都回零的独立接触适合检查重复接触与恢复，可在少量代表点补测；仅逐级加重后一次卸完，缺少中间档位的卸载窗口，不足以评估各档位滞后。数据格式保留实际载荷路径，不强制所有 trial 使用同一模式。
-
-砝码方式记录质量、重力加速度取值、加载方向及传力方式。`m × g` 表示沿重力方向的载荷，只有传力与对齐条件成立时才能作为法向参考；不能生成虚假的连续测力序列。FT sensor 方式保留实际测量流、坐标变换、归零和标定信息，未测得分量保持未知。
-
-首阶段使用直径 6 mm、球面半径 3 mm 的半球压头。记录 `indenter_id`、形状、尺寸定义及已知材料信息；接触面积随变形变化，不能把压头截面积当作实测接触面积。其他压头暂不纳入。
-
-首轮覆盖多测点、0–30 N 内多个载荷及重复加载卸载。FT sensor 采用用户确认的 50 N／2 N·m 档位，参考[LF606 规格书](references/lf606-d40-h18-4x-spec.pdf)。附件图签为 200 N／8 N·m，但量程表包含所选档位；实机身份仍以铭牌及标定证书核对。30 N 为暂定测试范围。
-
-保持时间先设为可配置的 10–30 s，记录请求值、实际值及分析窗口；首版允许人工选择窗口并注明原因，不把固定时长当作稳定证明。详细材料测试和接触协议暂不作为首版交付要求。
-
-## 原始数据与同步
-
-每个 trial 单独保存一段连续视频，覆盖预录、加载、保持、逐级卸载和恢复，档位间不切段。保存图像算法入口的像素格式、位深、分辨率和处理配置；另存实际基准图像及必要初始状态。首选无损编码，选定后验证解码像素一致性；有损编码须先验证其对标定误差的影响。
-
-帧索引包含 `session_id`、`trial_id`、`frame_id`、采集时间戳、视频路径和视频内帧号。参考流保留实测力及来源；未知分量不补零。`fn_raw/fx_raw/fy_raw` 是算法输出，不能替代图像或独立参考力。
-
-相机、测力计和平台分别保留自身完整采样流、时间戳及 `clock_id`。单调时钟用于排序，墙钟用于会话追溯；记录时间戳对应曝光、设备采样还是主机接收，以及时钟偏移、同步方法和误差。不同流不能按行号直接配对，对齐方法及时间差随派生结果保存。
-
-运动流分别记录目标位姿和实际反馈，不能把位移指令当作作用力。质量字段区分丢帧、图像饱和、参考测量无效、同步失败及接触异常；图像可用性与算法成功与否分开记录。无法判断的状态保持未知，失败原因保留。
-
-## 第一版存储建议
-
-首版复用共享记录器，以 JSON、CSV 和每个 trial 独立的视频跑通回放。`sites`、`trials` 及各自 `steps` 先放入 `session.json`，不另建文件；HDF5 后续再评估。
-
-| 文件或目录 | 内容 |
-|---|---|
-| `session.json` | 格式版本、身份、配置快照、测点及试验数组、坐标及同步约定、文件清单、完成或中断状态 |
-| `sequence.oryseq` | 本次实际使用的测试计划快照 |
-| `frames.csv`、`video/<trial_id>.<ext>` | 帧索引和独立事件视频；扩展名随实际编码确定 |
-| `baseline/` | 无接触基准图像及初始状态引用 |
-| `reference.csv` | FT 原始测量流；砝码方式将各档载荷、来源和有效时段存入 steps |
-| `motion.csv` | 有实际反馈时保存；没有反馈则在 trial 标明姿态来源 |
-| `events.csv` | 阶段切换、基准重置、异常及中断事件 |
-| `derived/<processing_id>/` | 对齐数据、特征、拟合与验证结果，附处理版本和配置 |
-
-每次重处理使用独立 `processing_id` 并引用输入身份。中断、丢失及主动不保存的时段分别标记。
-
-视频仅覆盖各测试事件，空闲移位不录像；参考、运动和事件可全程记录。先实测一个完整循环的容量、吞吐、丢帧和回放结果，再按 trial 数估算整场存储。每段视频保留自身初始化依据，不承诺跨空档连续回放；分段本身不降低有效画面的单位时间容量。
-
-## 首版验收与后续模型
-
-首版必须能重新打开一次多测点、多载荷采集，唯一关联测点、trial、图像、参考载荷及姿态，并从保留图像重算选定窗口。未知和失败数据不补零；至少留出完整 trial 检查法向力拟合。自动空间模型、实时集成和长期可靠性验证不阻塞首版数据采集，但首版不能据此宣称实时精度已验证。以下为后续产物要求。
-
-实时产物保存模型、预处理及基准要求、传感器与几何身份、训练数据来源、有效载荷和空间范围、验证结果。实时输出包含力值、坐标系、有效性及超范围原因。
-
-若模型依赖位置，实时阶段须从图像估计接触 UV／三维位置，或由外部提供位置，不能依赖只在标定时已知的 `site_id`。平台坐标用于解释施加的激励，实时读数转换到约定的传感器坐标。单接触标定不能直接证明多接触或分布载荷下的准确性。
-
-按完整 trial 或 session 划分训练与验证，避免相邻帧跨集合。另留未参与拟合的测点、幅值或采集日期；首阶段报告法向力误差、滞后、重复性、漂移和实时延迟。验收须证明保留窗口内可重算、结果可追溯、独立验证满足约定阈值；暂不声明剪切精度。
-
-## 待评审
-
-1. 固定 UV 轴正方向及底部中间原点的位置，核对像素→3D 映射。
-2. 核对 FT sensor 实机身份、采集器配置、载荷档位和验收阈值。
-3. 用先导试验确认保持与恢复时间、姿态来源和同步误差。
-4. 选定事件视频编码，实测容量及回放误差，确认初始化方式后冻结格式。
+开跑前仍须确定载荷档位、轴方向及精确原点、参考采集与同步、视频编码和恢复窗口。先实测单 trial 的容量及丢帧，再估算整场存储。视频空档不承诺连续回放。空间模型、实时集成及长期可靠性验证后续再做；本流程不证明剪切或多接触精度。