ykcheungab
121 lines
12 KiB
Markdown
121 lines
12 KiB
Markdown
# 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 规格书](references/lf606-d40-h18-4x-spec.pdf)量程表包含 50 N／2 N·m 档位，但图签为 200 N／8 N·m；实机以铭牌及标定证书核对。设备准备、运动边界和停机沿用 [workflow.md](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`](sequence-format.md)仍为平台毫米坐标的几何／运动计划；它与模拟页操作表分别导出，不代表已接通载荷执行。
|
||
|
||
## 目录与文件
|
||
|
||
本场目录名为 `<产品型号>_<SN>_<UTC时间>_<唯一标识>`，完整身份保存在 manifest。每个 trial 是一个测点的一次完整循环，档位用编号及时间窗口区分，不按力值拆原始视频目录。
|
||
|
||
```text
|
||
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 图有“真实背景”“位移箭头”“深度”三个独立开关；取消真实背景显示纯色画布，深度颜色可叠加在两种背景上。深度色阶按当前帧有效 UV 区域内的有限值最小／最大值自动调整，并显示范围；同一颜色在不同帧不代表相同数值，算法单位不代表毫米。缺失或过期字段不绘制，显示原因。显示切换不改变数据和录像，也不旋转 UV 坐标。
|
||
|
||
复核时选中表格中的保持段，检查下方原始样本图；起点、终点以该段保持开始为 0 秒，只能在原保持段内调整。勾选“已检查此段稳定”，点击“应用窗口并重算”，最后“另存分析结果”。至少有两个不同载荷的已确认加载／零载窗口时，显示已确认窗口拟合；不足时明确显示候选拟合。人工确认只表示看过稳定性，不证明参考力准确或物理同步。
|
||
|
||
分析结果保存 selections、候选与已确认拟合、原始样本轨迹、输入 CSV／manifest 的 SHA256、配置快照及分析包版本；每个已确认初始零载段保存基准图像及帧身份、图像哈希。点击“载入已保存复核…”选 review.json 恢复窗口并重算；输入身份或哈希改变时拒绝载入及保存。新增结果另存为独立目录，不修改 reference.csv 的采集声明。
|
||
|
||
正式分析拟合 `F_ref = gain_n_per_raw × raw + offset_n`，保存有效档位、范围、误差及加载／卸载差异，并保留独立 trial 验证。基准图像与算法历史尚未完整快照，因此当前录像不承诺从全新进程精确复算同样信号。FT、实际平台反馈、视频容量与驱动延迟仍须联调；自动加载、剪切、空间外推及实时部署留到后续。实施顺序见[实施计划](implementation-plan.zh.md)。
|