orisys-tech/orisys-app
3
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

细化 Autocal 传感器控制实施计划

Browse Source 
核对 Studio 采集链并明确 shared 复用边界、回归检查和更新后的工作量。文档门禁通过。
This commit is contained in:
ykcheungab
2026-10-11 11:36:53 +08:00
parent c98390ff4a
commit 6923cbf40c
1 changed files with 31 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/autocal/docs/implementation-plan.zh.md
+31 -13
View File
@@ -1,6 +1,6 @@
# Autocal 最小标定流程实施计划
状态：待评审，2026-10-10。用途：方案。建议使用两个实施子代理，主代理负责接口、UI 和集成；本计划不启动代理、不实施设备动作。需求以[操作与数据格式草稿](calibration-data-format.zh.md)为准。
状态：待评审，2026-10-11。用途：方案。建议使用两个实施子代理，主代理负责接口、UI 和集成；本计划不启动代理、不实施设备动作。需求以[操作与数据格式草稿](calibration-data-format.zh.md)为准。
## 首版边界
@@ -18,7 +18,7 @@
## 现有基础及缺口
基线为 app `d2122e60e1ed2468fb72cb351a07b0182166a09f`。以下是源码审阅结论，尚未进行设备或吞吐测试。
基线为 app `c98390ff4a09233d838be2c5698fa8b42e3c3eb6`。以下是源码审阅结论，尚未进行设备或吞吐测试。
| 位置 | 可复用 | 尚缺 |
|---|---|---|
@@ -31,37 +31,55 @@
原始 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`、`SdkAcquisitionWorker`、`SdkPacket`、`RecordSinkMixin` | 首版只实例化所选类型的 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 偏好设置、显示和文案仍留本地 |
接线顺序：先确认选中 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 | 固定 schema、事件 API、时间原点、状态及示例 session；验证实际相机和编码可用性 | 主代理：契约、共享模型声明 | 无 | 3–4 |
| P1 | 相机开关、基准／预录、trial 视频、CSV／manifest 写入、排空与失败状态 | A：shared acquisition／record 及对应测试；不改 UI | P0 | 10–14 |
| P0 | 固定 schema、传感器选择／worker 接口、事件 API、时间原点、状态及示例 session；检查编码 | 主代理：契约、共享模型声明 | 无 | 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 | 按下表排程 | 40–60 |
| 合计 | 最小可采集、可回放并离线复核 | 主代理 + A + B | 按下表排程 | 44–67 |
## 并行安排与代理数量
| 配置 | 预期软件交付窗口 | 取舍 |
|---|---|---|
| 主代理单独执行 | 约 5–8 个工作日 | 接口协调少，所有开发串行 |
| 主代理 + 1 子代理 | 约 4–6 个工作日 | 主代理承担控制、UI 和回放，容易成为瓶颈 |
| 主代理 + 2 子代理 | 约 3–4 个工作日，建议预留到第 5 天联调 | 推荐；采集存储与事件控制并行，主代理保持集成连续 |
| 主代理 + 3 子代理 | 通常仍约 3–4 个工作日 | 第三个仅在后期做独立审查／故障验证；不建议再拆一条实施线 |
| 主代理单独执行 | 约 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 | G1：人工档位的多事件采集可用 |
| 第 3–4 天 | P5 操作流程及集成 | 修复记录与性能问题 | P4，留出 trial 验证 | G2：重新打开、重算及对照通过 |
| 预留第 5 天 | 实际设备联调和交接 | 定向修复 | 定向修复 | 关闭实机问题或明确未验证项 |
| 第 2 天 | P3 接通控制与记录 | P1 写入与错误路径 | P2 收尾，开始 P4 | 合成事件通过，界面能显示采集状态 |
| 第 3–5 天 | P5 操作流程及集成 | Studio 兼容回归与性能修复 | P4，留出 trial 验证 | 先达 G1 多事件采集，再达 G2 重算对照 |
| 预留第 6 天 | 实际设备联调和交接 | 定向修复 | 定向修复 | 关闭实机问题或明确未验证项 |
依赖为 `P0 → (P1 ∥ P2 ∥ P3骨架) → P3实接`，随后 P4/P5 完成闭环。具体设备可用时间会改变日程，不能把等待藏进人时。
@@ -76,7 +94,7 @@ P0 先提供一份被各包共用的模型和合成数据，避免三个代理
| 记录 → 回放 | manifest、视频逐帧索引、基准、配置快照及缺失标记 |
| UI → 控制 | 操作请求；控制检查状态后返回结果，UI 不直接改 manifest |
A 独占新格式的文件写入，B 产生业务事件；主代理独占 `window.py`、`workspace.py` 及契约公共声明。修改 shared 行为必须保持 Studio 默认格式和生命周期。原记录器若不能满足事件视频路径，通过兼容的公共入口扩展，不能以 UI 层移动录像文件来补救。
A 独占新格式文件写入与 Autocal `sensor/` 采集服务，B 独占 Autocal `calibration/` 业务控制并产生事件；主代理独占 `window.py`、`workspace.py` 及契约公共声明。修改 shared 行为必须保持 Studio 默认格式和生命周期。原记录器若不能满足事件视频路径，通过兼容的公共入口扩展，不能以 UI 层移动录像文件来补救。
## 风险、增量与验收