补充 Autocal 最小标定数据流程草稿

明确像素到三维映射、逐级加载卸载及每事件独立视频，压缩坐标说明。文档门禁通过，流程尚未实现。
2026-10-10 13:10:45 +08:00
parent b827c5ffee
commit b15842ec00
2 changed files with 101 additions and 0 deletions
@@ -0,0 +1,101 @@
+# Autocal 标定数据格式草稿
+
+状态：待评审。日期：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` | 图像、参考力和运动流，以及时间、阶段和质量信息 |
+
+## 测点与坐标
+
+UV 使用像素，直接通过固定版本的 UV→3D 映射取得 mesh 位置，同时保存二维与三维值用于核对。平台将测点法向对齐 Z；`normal` 不设为必填字段。
+
+| 字段 | 约定 |
+|---|---|
+| `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` | 平台坐标中的激励单位向量，明确正负号及运动方向与作用力方向的关系 |
+
+原点位于有效 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. 选定事件视频编码，实测容量及回放误差，确认初始化方式后冻结格式。