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

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 规格书量程表包含 50 N／2 N·m 档位，但图签为 200 N／8 N·m；实机以铭牌及标定证书核对。

现有模块与待接工作见实施计划；旧 .oryseq 格式见 sequence-format.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，且已检查的 DD02 视频约 20 fps、配置为 30 fps；实施时须停止把该推算值当采集时刻。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 原文件。例子不代表写入器已经实现。

{
  "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 的容量及丢帧，再估算整场存储。视频空档不承诺连续回放。自动加载、空间模型及长期可靠性验证后续再做；本流程不证明剪切或多接触精度。