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

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

状态：2026-10-11 修订，仅 finger，待实机验收。手动采集、记录总览及稳定段检查已接通；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 定义和 uv_outline、sites、trials、状态；开始、保持结束、trial 结束和整场关闭时更新
trial session.json	共享录像元数据；另有 calibration_session_id、trial_id、site_id、repeat_index、site、plan、来源、配置、trial_status、trial_reason、capture_status、capture_reason、capture_report、steps；采集 session_id 是独立的整数编号
raw_0001.mp4	保存每个已交付图像帧；容器帧率仅供播放，实际时序用 frames.csv；不等于来源视频
frames.csv	帧身份、电脑采集时间、视频位置及丢帧状态；每帧写入
forces.csv	图像算法原始及处理后输出；不是独立真实力
reference.csv	每个实际开始的保持窗口一行；完整窗口在计时终点关闭，中断窗口在停止时关闭
derived/review_<时间>_<标识>/review.json	另存初步分析，包含窗口均值、标准差、拟合和质量说明；不覆盖采集数据
同目录 overview.json	总览版本、session_id、计划 CSV 内容及来源哈希、测点覆盖和拟合摘要；载入时按原始数据及复核窗口重算
derived/summary_*/、summary-latest.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

参考窗口起点包含、终点不包含；换档无恒定力标签，视频与算法输出照常保存。最终状态以排空后的 manifest 为准；保存失败不算成功，重试不覆盖原文件。

录像完整性由 capture_guard.capture_verdict() 统一判定：写入帧数、录像帧数、单分段、队列丢帧、 视频可解码、未中止、采集中途来源会话未变，全部通过才写 complete，否则 incomplete 并保留原因码 （如 zero_frames、video_undecodable、source_restarted、closing_timeout）；排空期间界面 轮询 poll() 而不阻塞。汇总见多点格式的汇总一节：同一套 summary_export 写 derived/summary_*/ 与 summary-latest.json，按 hold_id（reference.csv 数据行序号）区分重测，不自动标记稳定，不把 raw 与 N 混用。

多点会话格式

多点标定按测点组织（sites/<site_id>/repeat-00N/），复核输入见多点标定会话格式。

软件数据流及后续

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

主时间是电脑取得该帧时绑定的单调时间，UTC 仅供追溯，处理完成时间不能代替采集时间。FT／ECAT 后续按同一接收时间关联，不按行号配对。host_replay 只是本次解码时间，不能恢复原实验同步。

“标定记录”页打开会话，核对型号／SN、来源和采集状态；选点及单次试验先看时间曲线，再“检查保持段…”，最后保存分析结果。采集页“查看标定数据…”也跳转至此。

总览	规则
计划对照	导入模拟页 CSV；核对映射、原点、轴向、尺寸及三维位置，按 U/V 匹配；标记漏采和计划外点，同点重复序号合并
状态	采集完整性与稳定段检查分别展示；未完成 trial 可查看曲线、结束原因及缺失文件，不参与拟合
UV 轮廓	新采集的 uv_outline 保存映射身份及传感面／彩色 patch 外轮廓；旧记录仅恢复映射验证一致的几何轮廓，缺失或不匹配时提示；显示保持像素等比例
时间曲线	FN_raw 及人工保持参考力；显示有效样本、无效／未关联数、录像丢帧、最大帧间隔；各 trial 独立时间原点，不代表 FT 同步
法向响应	横轴实际参考 N，纵轴 FN_raw 均值；区分加载／卸载及候选／已确认，可筛选 trial；拟合仍基于本点全部合格加载窗口
灵敏度图	仅已确认拟合按 raw/N 着色，其余灰色；不插值，表中另列拟合范围及 trial 数
保存恢复	保存计划及窗口快照；载入 review.json 恢复总览，无 overview.json 时仅恢复窗口；未保存修改有提示

拟合使用初始零载及加载窗口均值，各窗口等权；卸载仅作对照。缺样本、档位或信号变化时不生成系数。拟合 RMSE 不是独立验证误差。

采集页显示 FN／FX／FY raw 及最近 60 秒曲线，已标定轴另显示 N；无效帧断开，停止或超过 1 秒无新帧时提示。人工参考力不是实时 FT。

实时 UV 图可切换真实背景、位移箭头与深度；深度按当前帧有效范围自适应，单位不是毫米；跨帧同色不代表同值，缺失或过期字段不绘制。显示不改变录像及坐标。

检查保持段曲线、样本数、标准差和漂移；起止以保持开始为零，只能在原段内调整。勾选“已检查稳定”后重算并保存。至少两个不同载荷的已确认零载／加载窗口才有确认拟合；确认稳定不代表精度合格。

分析保存 selections、拟合、样本轨迹、输入 SHA256 与版本；确认的初始零载段另存基准图像、帧身份与哈希。输入变化时拒绝载入与保存，结果不改 reference.csv。

“重复性与验证…”使用已确认窗口，site.quality 保存跨 trial 同参考力的极差与标准差、卸载减加载差及最终减初始零载；参考力须完全相同，不插值，不足两次不算重复性。

验证逐次留出完整 trial，用其余 trial 拟合预测留出窗口，报告 RMSE／MAE／最大误差及超出训练范围数量，训练不足时说明原因。交叉验证不能代替独立实验或正式系数。

跟踪器基准与算法历史尚未完整快照，录像不能保证从全新进程精确复算。相机、FT、实际平台反馈和容量／延迟须实机联调；自动加载、剪切、空间外推及实时部署留待后续。见实施计划。