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

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

状态：2026-10-11 修订，待实机验收。阶段一仅针对 finger。多测点会话、手动加载／卸载保持、视频和相机输入、模拟页测点操作表导出已接通；已可重开会话查看保持窗口、加载／卸载曲线及 UV 测点初步灵敏度；FT 同步、图像基准快照及正式灵敏度结果仍待实现。软件检查不代表设备或标定精度通过。

范围与坐标

项目	约定
载荷	法向压缩 0–30 N；剪切及组合载荷后续再做
压头	直径 6 mm、球面半径 3 mm 的半球压头
参考	当前人工填写实际参考力；计划使用砝码或 50 N／2 N·m FT sensor
图像	每 trial 保存一个连续视频，保留初始零载、换档、加载、卸载及恢复
UV	整数 pixel；原点为最靠近图像中线的有效列底部像素；U 向右、V 向上，允许负 V
三维	传感器坐标用 mm；平台坐标经过安装和姿态转换，须明确区分
映射身份	保存原点、栅格尺寸和 mapping_sha256；哈希覆盖实际位置查找表及有效掩膜
层级	session → site → trial → step → samples；同点重复及中止重试均创建新 trial

LF606 规格书量程表包含 50 N／2 N·m 档位，但图签为 200 N／8 N·m；实机以铭牌及标定证书核对。设备准备、运动边界和停机沿用 workflow.md。本页不会自动移动平台。

操作员逐步流程

步骤	操作	软件行为
1. 准备	填型号、SN、保存位置，载入 finger 导出包和配置	首次开始试验时建立本场 session；型号、SN、配置和映射在本场固定
2. 预览	选视频或相机编号，启动输入并检查二维 UV 图像	两种来源共用 finger worker；输入预览可贯穿多个 trial
3. 选点	点击 UV 粗选，再修改 U/V 到精确像素	显示传感器三维位置；拒绝掩膜外点
4. 设循环	输入严格递增的正载荷档位及每档 10–30 s 保持	展示完整路径；如 0 → 5 → 10 → 20 → 30 → 20 → 10 → 5 → 0 N
5. 开始	无载时点击“开始本次试验”	新建 trial 并连续录像；先提示初始零载
6. 保持	到目标后输入实际参考力，点击“已到目标力，开始保持”	当前目标不变，倒计时期间禁止再次确认或完成试验
7. 换档	倒计时结束后按提示手动调整至下一档	自动结束本档窗口；换档继续录像，但不沿用上一档恒定参考力
8. 完成	最终卸载至零并完成保持，点击“完成本次试验”	停止本 trial 录像，排空写入并检查完整性；输入预览继续
9. 重复／换点	重复同点或选下一点，再开始试验	同场目录内新增 trial；自动关联 site 和重复编号
10. 结束整场	所有试验结束后点击“结束本场标定”	所有 trial 完整才标 complete；有中止或失败则保留 incomplete

“提前结束（保留未完成数据）”立即停止本次试验；不删除数据，不续录旧 trial。视频播放结束或写入停止会中止当前试验。关闭程序时结束当前试验并关闭会话；异常退出留下的 in_progress 不代表已完成。目前不能恢复旧会话继续采集。

保持倒计时只结束档位窗口，整段录像到完成或提前结束才停止。到时不等于稳定；stability_verified=0，正式分析仍须复核窗口。初始和最终零载当前使用相同保持时间，后续可根据恢复实测调整。

模拟页与操作表

模拟页和标定页共用 UV 映射。在模拟页选点、调整列表顺序后点击“导出测点操作表…”，得到 UTF-8 CSV。操作员按表中 U/V 手动复现；当前不提供序列导入。三维位置被手工改动而与原像素不一致时拒绝导出，须重新在图上选点。

操作表字段	含义
order、site_id	表内顺序及测点编号；采集会话按首次实测顺序另行分配 site_id，以 U/V 和映射身份核对
u_px、v_px	与标定页相同原点、方向和单位
x_sensor_mm／y_sensor_mm／z_sensor_mm	传感器三维位置
x_platform_mm／y_platform_mm／z_platform_mm、yaw_deg、pitch_deg	当前模拟安装设置下的平台目标及角度
origin_raster_x_px／origin_raster_y_px、栅格宽高、轴方向、mapping_sha256	像素坐标复现所需的映射身份

序列页的 .oryseq仍为平台毫米坐标的几何／运动计划；它与模拟页操作表分别导出，不代表已接通载荷执行。

目录与文件

本场目录名为 <产品型号>_<SN>_<UTC时间>_<唯一标识>，完整身份保存在 manifest。每个 trial 是一个测点的一次完整循环，档位用编号及时间窗口区分，不按力值拆原始视频目录。

finger_F001_<时间>_<标识>/
  session.json
  trials/
    trial-001/
      session.json
      raw_0001.mp4
      frames.csv
      forces.csv
      reference.csv
      events.csv
    trial-002/
      ...

10 个点、每点 3 次正常循环共 30 个 trial 目录；中止和重试各占一次，档位数不增加目录数。

文件	内容及写入时机
根 session.json	format_version=autocal-session-1.0、字符串 session_id、型号／SN、配置快照及哈希、UV 定义、sites、trials、状态；首次开始、每档保持结束、trial 结束和整场关闭时更新
trial session.json	共享录像元数据；另有 calibration_session_id、trial_id、site_id、repeat_index、site、plan、来源、配置、trial_status、trial_reason、steps；采集 session_id 是独立的整数编号
raw_0001.mp4	保存每个已交付图像帧；容器帧率仅供播放，实际时序用 frames.csv；不等于来源视频
frames.csv	帧身份、电脑采集时间、视频位置及丢帧状态；每帧写入
forces.csv	图像算法原始及处理后输出；不是独立真实力
reference.csv	每个实际开始的保持窗口一行；完整窗口在计时终点关闭，中断窗口在停止时关闭
derived/review_<时间>_<标识>/review.json	另存初步分析，包含窗口均值、标准差、拟合和质量说明；不覆盖采集数据
derived/review_<时间>_<标识>/baseline_<trial>.png	已确认初始零载窗口的第一张有效录像帧；作为检查基准，不是跟踪器内部参考状态；无视频时在分析结果中标记 unavailable
events.csv	trial_started、step_reached、hold_started、hold_ended、trial_finished／trial_aborted；保存电脑事件时间及 step 信息

参数／字段	定义
site	site_id、uv_xy_px、position_sensor_mm、face_index、栅格像素、几何路径及哈希
trial 计划	levels_n、hold_s、有序 steps；step_index 从 0 开始，branch 为 zero／load／unload
trial 状态	先写 incomplete，排空录像并通过完整性检查才写 complete；根清单同时保存结果和原因
执行 steps	目标和实际参考力、保持起止单调时间、complete／incomplete、稳定验证标志
reference.csv	step_index、branch、target_load_n、t_start_host_mono_ns、t_end_host_mono_ns、F_ref_normal_N、预留 XYZ、force_frame、source、stability_verified、hold_complete
参考有效性	人工声明压缩为正；未测 XYZ 和坐标系留空，不补零，不直接把法向值当平台 Z；hold_complete=0 的窗口不能用于正式拟合
frames.csv	frame_id、source_frame_id、t_rel_s、t_host_mono_ns、t_host_utc_ns、acquired_at、time_basis、media_time_ms、segment、segment_frame、in_video、dropped、capture_dropped

参考窗口采用起点包含、终点不包含的时间范围。换档没有恒定力标签，视频和算法输出仍保存。trial_finished 表示请求正常结束；最终是否 complete 以排空后的 manifest 为准。保存失败不能当作成功；重试不覆盖原文件。

软件数据流及后续

输入 → 处理 → 输出	所有者
UV 像素 → 固定映射 → 传感器毫米坐标／模拟平台姿态 → 操作表或 site	Autocal sensor 几何与模拟界面
视频／相机 → 帧采集时间 → finger 处理 → SdkPacket	SDK capture、shared acquisition
手工参考 + 保持状态 → 有效候选窗口及事件	Autocal trial
session／site／trial 关联 → 根清单；数据包 → 视频及 CSV	Autocal 会话；shared recorder 负责文件写入
完整 trial + 帧身份／电脑时间 → 保持窗口原始均值 → 加载／卸载对照及 UV 测点着色	Autocal 初步分析；稳定性和正式验证仍后置

主时间是电脑取得该帧时绑定的单调时间，UTC 用于追溯；处理完成时间不能代替采集时间。FT／ECAT 后续接入同源接收时间，按时间关联，不按行号配对；低延迟不等于零延迟。旧视频的 host_replay 是本次解码时间，只能调试，不能恢复原实验与参考设备的物理同步。

点击“查看标定数据…”选择会话根目录；在独立窗口切换测点，检查每档有效样本、均值、标准差和质量说明。初步拟合仅使用初始零载及加载分支的窗口均值，各窗口等权；卸载点保留用于对照，不混入加载拟合。缺样本、档位或信号变化时不生成系数。UV 图仅显示已测点，不外推整面；拟合 RMSE 不是独立验证误差。

采集页持续显示 FN／FX／FY 原始信号及最近 60 秒曲线；已有标定的轴另显示 N，未标定的轴不将 raw 转称为 N。无效帧在曲线中断开；停止或超过 1 秒没有新帧时明确提示。此处没有实时 FT 参考力，人工填写的参考力仍是独立声明。

实时 UV 图有“真实背景”“位移箭头”“深度”三个独立开关；取消真实背景显示纯色画布，深度颜色可叠加在两种背景上。深度使用固定 0–1 算法单位色阶，超范围饱和，不代表毫米；缺失或过期字段不绘制，显示原因。显示切换不改变数据和录像，也不旋转 UV 坐标。

复核时选中表格中的保持段，检查下方原始样本图；起点、终点以该段保持开始为 0 秒，只能在原保持段内调整。勾选“已检查此段稳定”，点击“应用窗口并重算”，最后“另存分析结果”。至少有两个不同载荷的已确认加载／零载窗口时，显示已确认窗口拟合；不足时明确显示候选拟合。人工确认只表示看过稳定性，不证明参考力准确或物理同步。

分析结果保存 selections、候选与已确认拟合、原始样本轨迹、输入 CSV／manifest 的 SHA256、配置快照及分析包版本；每个已确认初始零载段保存基准图像及帧身份、图像哈希。点击“载入已保存复核…”选 review.json 恢复窗口并重算；输入身份或哈希改变时拒绝载入及保存。新增结果另存为独立目录，不修改 reference.csv 的采集声明。

正式分析拟合 F_ref = gain_n_per_raw × raw + offset_n，保存有效档位、范围、误差及加载／卸载差异，并保留独立 trial 验证。基准图像与算法历史尚未完整快照，因此当前录像不承诺从全新进程精确复算同样信号。FT、实际平台反馈、视频容量与驱动延迟仍须联调；自动加载、剪切、空间外推及实时部署留到后续。实施顺序见实施计划。