ykcheungab
136 lines
12 KiB
Markdown
136 lines
12 KiB
Markdown
# 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 规格书](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` | 另存初步分析，包含窗口均值、标准差、拟合和质量说明；不覆盖采集数据 |
|
||
| 同目录 `overview.json` | 总览版本、session_id、计划 CSV 内容及来源哈希、测点覆盖和拟合摘要；载入时按原始数据及复核窗口重算 |
|
||
| `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 + 帧身份／电脑时间 → 人工复核窗口 → 加载／卸载、重复性、trial 留出验证及 UV 着色 | Autocal 初步分析；实机验收后置 |
|
||
|
||
主时间是电脑取得该帧时绑定的单调时间，UTC 用于追溯；处理完成时间不能代替采集时间。FT／ECAT 后续接入同源接收时间，按时间关联，不按行号配对；低延迟不等于零延迟。旧视频的 `host_replay` 是本次解码时间，只能调试，不能恢复原实验与参考设备的物理同步。
|
||
|
||
“标定记录”页打开会话目录；采集页“查看标定数据…”也跳转至此。点击 UV 点或表格，联动响应及 trial 筛选，再“查看信号／复核窗口…”。
|
||
|
||
| 总览 | 规则 |
|
||
|---|---|
|
||
| 计划对照 | 导入模拟页 CSV；核对映射、原点、轴向、尺寸及三维位置，按 U/V 匹配；标记漏采和计划外点，同点重复序号合并 |
|
||
| 采集状态 | 未采、有未完成试验、待复核、已复核；完成次数及已确认窗口数分别列出，不把未完成 trial 用于拟合 |
|
||
| 法向响应 | 横轴实际参考 N，纵轴 FN_raw 均值；区分加载／卸载及候选／已确认，可筛选 trial；拟合仍基于本点全部合格加载窗口 |
|
||
| 灵敏度图 | 仅已确认拟合按 raw/N 着色，其余灰色；不插值，表中另列拟合范围及 trial 数 |
|
||
| 保存恢复 | “另存总览与复核”保存计划快照及窗口；载入 review.json 同时恢复总览，无 overview.json 时仅恢复复核 |
|
||
|
||
拟合使用初始零载及加载窗口均值，各窗口等权；卸载仅作对照。缺样本、档位或信号变化时不生成系数。拟合 RMSE 不是独立验证误差。
|
||
|
||
采集页显示 FN／FX／FY raw 及最近 60 秒曲线；已有标定的轴另显示 N。无效帧断开，停止或超过 1 秒无新帧时提示。人工参考力不是实时 FT。
|
||
|
||
实时 UV 图有真实背景、位移箭头、深度三个开关；关闭背景显示纯色画布。深度按当前帧有效 UV 有限值范围自适应，显示范围；跨帧同色不代表同值，算法单位不是毫米。缺失或过期字段不绘制并提示。显示不改变录像及坐标。
|
||
|
||
复核时选中表格中的保持段，检查下方原始样本图；起点、终点以该段保持开始为 0 秒，只能在原保持段内调整。勾选“已检查此段稳定”，点击“应用窗口并重算”，最后“另存分析结果”。至少有两个不同载荷的已确认加载／零载窗口时，显示已确认窗口拟合；不足时明确显示候选拟合。人工确认只表示看过稳定性，不证明参考力准确或物理同步。
|
||
|
||
分析结果保存 selections、候选与已确认拟合、原始样本轨迹、输入 CSV／manifest 的 SHA256、配置快照及分析包版本；每个已确认初始零载段保存基准图像及帧身份、图像哈希。点击“载入已保存复核…”选 review.json 恢复窗口并重算；输入身份或哈希改变时拒绝载入及保存。新增结果另存为独立目录，不修改 reference.csv 的采集声明。
|
||
|
||
“重复性与验证…”只用已确认窗口，结果保存在各 site 的 quality：同分支、相同人工参考力跨 trial 的极差／样本标准差；同 trial 同参考力的卸载减加载 raw 差；最终零载减初始零载。配对要求参考力完全相同，不插值；不足两次 trial 不计算重复性。
|
||
|
||
独立验证逐次留出一个完整 trial，用其余 trial 的零载／加载窗口拟合，再预测留出 trial 的全部已确认窗口。每窗口等权，报告 RMSE／MAE／最大绝对误差及超出训练 raw 范围的数量；训练档位不足时列明原因。交叉验证仍不能代替另一场独立实验，也不生成正式实时系数。
|
||
|
||
跟踪器基准与算法历史尚未完整快照，录像不能保证从全新进程精确复算。相机、FT、实际平台反馈和容量／延迟须实机联调；自动加载、剪切、空间外推及实时部署留待后续。见[实施计划](implementation-plan.zh.md)。
|