# Autocal 最小标定流程实施计划

状态：P0 契约和离线验证完成，2026-10-11；P1–P5 待实施。用途：方案。后续完整实施建议两个子代理；当前不启动代理或设备动作。需求以[操作与数据格式草稿](calibration-data-format.zh.md)为准。

## 首版边界

| 交付 | 首版选择 |
|---|---|
| 采集对象 | 固定为 finger；先以视频文件输入验证，再用实时相机输入验证同一路径 |
| 测点 | 复用现有选择和姿态能力；UV pixel→3D mm，保存映射身份 |
| 参考输入 | 人工确认砝码档位，记录质量、传力条件及有效时段；FT 自动采集另估 |
| 载荷循环 | 操作员逐级加载卸载，软件记录到档、保持及恢复；暂不做闭环力控制 |
| 视频 | 输入视频用于无设备调试；每 trial 的输出视频独立连续，含必要预录／基准；编码必须通过本机回放验证 |
| 复核 | 重新打开 session，按 step 选择窗口，重算特征并对照参考载荷 |
| 验证 | 独立 trial 的法向拟合误差及加载卸载差异；不承诺未经验证的实时精度 |

人工砝码方案依赖现有装夹能够实现有效法向传力；若实际只能用 FT，自动接口须提前纳入关键路径。0–30 N 是需求范围，不是已批准的设备动作上限。自动测点遍历、自动压入、复杂空间模型、实时部署及新安装包均不在首版。

## 现有基础及缺口

基线为 app `c98390ff4a09233d838be2c5698fa8b42e3c3eb6`。以下是源码审阅结论，尚未进行设备或吞吐测试。

| 位置 | 可复用 | 尚缺 |
|---|---|---|
| `apps/autocal/src/orisys_autocal/sequence_io.py` | `.oryseq` 校验与保存 | trial／step 载荷路径 |
| `sensor/export_bundle.py`、`sensor/uv_flat.py`、`motion/kinematics.py` | 几何、UV 与姿态能力；bundle 已有物理尺度处理 | 验证计算管线 UV 与预览映射、坐标尺度一致 |
| `shared/src/orisys_app_shared/acquisition/` | `FingerAcquisitionWorker.start` 接受视频路径或相机整数编号，两者经同一 finger 处理链输出 `SdkPacket` | Autocal 生命周期与最小预览接入；视频与相机分别验证时间基准 |
| `shared/.../record/experiment.py`、`video_writer.py` | 有界队列、后台写入、丢帧及错误处理 | 当前为滚动 MP4；事件视频、编码和新 manifest 不可直接视作已支持 |
| `apps/studio/src/orisys_studio/recording.py`、`replay_analysis.py` | 已有记录组织和回放经验 | Autocal 不应直接依赖 Studio 私有模块；需要时仅提取共同核心到 shared |
| Autocal `ui/window.py`、`ui/workspace.py` | 设备和页面装配 | 运行入口未实现，采集及标定点页占位 |

原始 mesh 不应直接当作 mm；沿用 `SensorBundle.vertices_mm` 等经过验证的物理输出。SDK 只负责图像算法，Autocal 组织试验，shared 提供实际共用的采集／存储能力。

## 传感器控制复用与迁移

Studio 从 `app_window._start_run` 读取选择、解析 config、设置滤波并调用 worker `start`；`SessionController` 注册采集 sink，按首帧、错误和停止更新状态；`RecordingCoordinator.on_packet` 把包送往内存会话、标定采样器和文件记录器。Autocal 首版只需其中的设备采集与保存路径。

| Studio 入口／现有位置 | Autocal 处理 | 原因及验证 |
|---|---|---|
| `shared/sensors` 的 `scan_sensor_catalog`、`CatalogEntry` | 直接调用，保存选择的 config 路径及身份 | 目录解析本来由 shared 拥有；拒绝不可运行的条目 |
| `shared/acquisition` 的 `FingerAcquisitionWorker`、`SdkPacket`、`RecordSinkMixin` | 首版只实例化 finger worker；视频路径或相机整数编号均调用公开 `start/stop/latest/add_sink/remove_sink` | 同一采集算法、帧号和基准预录；验证各自时间基准、首帧、断流、停止后 sink 解绑 |
| `Studio/ui/sensor_picker.py` | 首版在 Autocal 用简短选择控件调用 shared catalog；不搬 Studio widget | widget 用 Studio 文案和状态栏布局；只有界面行为真正一致时再迁入共享 UI |
| `Studio/ui/sensor_dialog.py` | 留在 Studio | 绑定 Studio window、校准文件热应用和面板；Autocal 只需本次原始采集的配置 |
| `Studio/session_controller.py` | 留在 Studio；Autocal 写仅管理所选 worker 的薄协调器 | 类内有 `QTimer`、Studio 状态、双 worker、记录计数；整类移动会改变现有生命周期 |
| `Studio/recording.py` | 复用底层 `shared/record`，新建 Autocal trial 协调；不移动整个类 | 现有类含 Studio session store、力阈值和标定采样器，语义不同 |
| `Studio/session_metadata.py` 中 `capture_metadata`、`filter_metadata`、`video_fps` | 两端都需要时提取到 shared；Studio 保留兼容导入并验证输出相同 | 通用的设备事实可共享；Studio 偏好设置、显示和文案仍留本地 |

接线顺序：先用视频路径和 finger config 打开 worker；再接一个只入队的 packet sink，UI 从 `latest()` 取预览。相机接入时只替换输入值，不另建处理或记录分支。获得首帧后允许创建 trial，开始输出视频前取预录；结束时先停试验写入并等待完成报告，再停采集，关闭窗口前解绑 sink。若输入打开失败或写入失败，状态为失败，不能产生“已完成” trial。运动服务继续独立管理平台，采集协调器不下达运动命令。

只有当 Autocal 和 Studio 实际出现相同的 worker 生命周期代码时，才将这部分无 widget 逻辑抽到 `shared/acquisition`，两端改为调用同一实现；不为本次仅一个调用方预建框架。抽取须保留 Studio 的非阻塞停止、首帧才进入 running、reset 生效事件和 capture drop 计数。配对运行 Studio session／sensor catalog／recording 测试与 Autocal 生命周期测试。

## 工作包与估算

单位为工程人时，包含针对性测试和代码审查，不是代理运行时承诺。按现有环境可用、无设备通信等待、首版采用人工档位估算；各行不重复计算集成工作。

| 包 | 内容及可观察交付 | 负责人／写入范围 | 依赖 | 人时 |
|---|---|---|---|---:|
| P0 | 固定 finger schema、视频／相机共用 worker 契约、事件 API、时间原点、状态及示例 session；验证输入路径并检查输出编码 | 主代理：契约及现有 worker 的针对性验证 | 无 | 4–6 |
| P1 | 视频输入先接通单 worker 生命周期、来源帧率核对、基准／预录、trial 输出视频、CSV／manifest 写入、排空与失败状态；再以相机输入跑同一路径；必要时迁移元数据辅助函数 | A：shared acquisition／record、Autocal `sensor/` 采集服务、Studio 兼容导入及测试；不改 UI | P0 | 13–19 |
| P2 | session／site／trial／step 控制、人工载荷确认、阶段时间及状态约束 | B：Autocal 无 Qt 的标定控制及测试 | P0 | 8–12 |
| P3 | 最小会话表单、测点表、预览、开始／到档／结束／中止、状态显示 | 主代理：Autocal UI、配置及集成入口 | P0 后可用桩；实接 P1/P2 | 8–12 |
| P4 | 新格式读取、逐事件回放、基准恢复、窗口特征重算、最小拟合与误差表 | B：离线处理及测试；共享提取先协调 | P2；集成依赖 P1 样本 | 6–10 |
| P5 | 故障、旧消费者回归、GUI 流程、实际采集样本验收与交接 | 主代理集成，A/B 修复各自模块 | P1–P4 | 5–8 |
| 合计 | 最小可采集、可回放并离线复核 | 主代理 + A + B | 按下表排程 | 44–67 |

## 并行安排与代理数量

| 配置 | 预期软件交付窗口 | 取舍 |
|---|---|---|
| 主代理单独执行 | 约 6–9 个工作日 | 所有开发串行 |
| 主代理 + 1 子代理 | 约 5–7 个工作日 | 主代理承担控制、UI 和回放 |
| 主代理 + 2 子代理 | 约 4–5 个工作日，建议预留第 6 天联调 | 推荐；采集存储与事件控制并行 |
| 主代理 + 3 子代理 | 通常仍约 4–5 个工作日 | 第三个仅在后期做独立审查／故障验证 |

按每日 8 小时有效工程时间估算；AI 编码可能更快，硬件、人工采样和联调不会按代理数等比加速。最短两三天可以优先完成采集里程碑，但不能把未完成的重算验收称为完整交付。

| 阶段 | 主代理 | A | B | 出口 |
|---|---|---|---|---|
| 第 1 天 | P0，随后做 UI 骨架 | P1 编码及采集验证 | P2 控制及合成事件 | 契约冻结，单 trial 合成数据能保存 |
| 第 2 天 | P3 接通控制与记录 | P1 写入与错误路径 | P2 收尾，开始 P4 | 合成事件通过，界面能显示采集状态 |
| 第 3–5 天 | P5 操作流程及集成 | Studio 兼容回归与性能修复 | P4，留出 trial 验证 | 先达 G1 多事件采集，再达 G2 重算对照 |
| 预留第 6 天 | 实际设备联调和交接 | 定向修复 | 定向修复 | 关闭实机问题或明确未验证项 |

依赖为 `P0 → (P1 ∥ P2 ∥ P3骨架) → P3实接`，随后 P4/P5 完成闭环。具体设备可用时间会改变日程，不能把等待藏进人时。

## 并行接口与文件所有权

P0 先提供一份被各包共用的模型和合成数据，避免三个代理自行定义不同 schema。函数名称在实施时确定，不为假想插件建立框架。

| 边界 | 必须固定的输入／输出 |
|---|---|
| 控制 → 记录 | session／trial／step 身份、阶段事件、姿态和参考有效时段；记录器返回写入状态 |
| 采集 → 记录 | `SdkPacket`、帧身份、采集时刻、图像及有效性；sink 不执行 UI 或阻塞磁盘写入 |
| 记录 → 回放 | manifest、视频逐帧索引、基准、配置快照及缺失标记 |
| UI → 控制 | 操作请求；控制检查状态后返回结果，UI 不直接改 manifest |

A 独占新格式文件写入与 Autocal `sensor/` 采集服务，B 独占 Autocal `calibration/` 业务控制并产生事件；主代理独占 `window.py`、`workspace.py` 及契约公共声明。修改 shared 行为必须保持 Studio 默认格式和生命周期。原记录器若不能满足事件视频路径，通过兼容的公共入口扩展，不能以 UI 层移动录像文件来补救。

## 风险、增量与验收

| 项目 | 处理及增量 |
|---|---|
| FT 自动输入 | 未找到现成 LF606 接口；规格书不含采集器协议。确认接口、样例和设备后暂估另加 8–20 人时；协议开发或采购等待须重估 |
| 编码不可用或有损 | P0/P1 做实际编码解码检查；不能悄悄用普通 MP4替代无损要求。可先交演示录像，但 G2 重算精度仍待验证 |
| 有状态算法回放 | P1 保存基准及初始化历史，P4 独立比较重算结果；失败时定位状态缺口，不只比较导出系数 |
| 自动加载／运动 | 暂不纳入；需要控制策略、传力验证和独立运动验收，不能只增加一个循环按钮 |

| 检查 | 通过条件 |
|---|---|
| G1 采集 | 至少两个测点、每点两个 trial；每 trial 包含正反载荷档位，视频连续且身份唯一 |
| G2 重算 | 全新进程读取文件，恢复基准／历史，重算窗口并对齐独立参考；完整 trial 留出验证 |
| 故障 | 中止、磁盘写失败、丢帧、参考缺失、相机关闭可见；未写完不标完成 |
| 回归 | Autocal 现有测试、shared 记录／生命周期／回放测试、Studio 相关消费者通过；GUI 与硬件证据分别报告 |
| 完成 | 文档和 lint 门禁通过；实际编码吞吐、容量及误差有证据；缺失设备不报通过 |

首版通过 G1/G2 后停止扩展。当前 `sensor_type` 固定为 finger。P0 已用假设备验证视频路径／相机编号经同一 worker 输出，并用现有 DD02 视频验证真实 SDK 处理链的首批帧；`mp4v` 在本机可写入及重新解码 30 帧。示例 session 与时间语义见数据格式草稿。该视频约 20 fps 而配置为 30 fps；P1 必须处理时间不一致，才可对齐参考力。尚未验证真实相机、长时写入及图像保真度；Autocal UI 与 trial 写入也尚未接通。参考方式及设备可用性决定是否把 FT 增量纳入后续关键路径。