ykcheungab
06e06126ca
选点、对准、加载与录像分散在两个面板，状态靠隐藏相位判断。现改由不依赖 Qt 的采集控制器驱动，并加入录像选项、汇总平铺副本、保持到时自动结束、会话结束回到空闲，以及无设备时的模拟采集。已运行 Autocal 非 Qt 测试并通过范围内门禁；界面测试待 Windows 复核，未做实机验收。
152 lines
13 KiB
Markdown
152 lines
13 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 保持 | 展示完整加载与卸载路径，顺序即记录顺序 |
|
||
| 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 手动复现，不自动执行。缺 UV、缺已记录姿态，或三维位置与原像素不一致时拒绝导出，须重新选点。
|
||
|
||
| 操作表字段 | 含义 |
|
||
|---|---|
|
||
| `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`、`raster_width_px`／`raster_height_px`、`u_positive`／`v_positive`、`mapping_sha256` | 像素坐标复现所需的映射身份 |
|
||
|
||
列定义只有 `ui/site_export.py` 一处。序列页的 [`.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 定义和 uv_outline、sites、trials、状态、`recording` 块（`video`／`codec`／`lossless_frames`，建立时写一次，旧会话缺块按 `video=true` 读）；开始、保持结束、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` | 汇总四件文件与最后成功发布的指针；字段见[多点格式](multipoint-data-format.zh.md) |
|
||
| `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()` 而不阻塞。汇总见[多点格式的汇总一节](multipoint-data-format.zh.md)：同一套
|
||
`summary_export` 写 `derived/summary_*/` 与 `summary-latest.json`，按 `hold_id`（`reference.csv`
|
||
数据行序号）区分重测，不自动标记稳定，不把 raw 与 N 混用。
|
||
|
||
见[录像工作流](recording-workflow.zh.md)。
|
||
|
||
### 多点会话格式
|
||
|
||
多点标定按测点组织（`sites/<site_id>/repeat-00N/`），复核输入见[多点标定会话格式](multipoint-data-format.zh.md)。
|
||
|
||
## 软件数据流及后续
|
||
|
||
| 输入 → 处理 → 输出 | 所有者 |
|
||
|---|---|
|
||
| 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、实际平台反馈和容量／延迟须实机联调；自动加载、剪切、空间外推及实时部署留待后续。见[实施计划](implementation-plan.zh.md)。
|