feat: ForceStreamSession 覆盖 field 与 FN-only 标定(T06b)

新增 measurement_requirements,告知调用方 field 模型需要同帧场数据。补充标量、field、FN-only 三类标定与旧 ForceSession 的数值等价测试,以及标定与帧不匹配的情况:field 缺 context 时构造失败,基线帧缺 field 时零点失败,ready 后缺 field 的帧单独标为 invalid_input。与改动前的旧会话基线逐位一致。回归 381 项、lint 通过。
This commit is contained in:
ykcheungab
2026-10-21 15:46:01 +08:00
parent 14e73d743c
commit 11f8dc93e5
3 changed files with 279 additions and 10 deletions
+17 -9
View File
@@ -1,14 +1,18 @@
# 新力侧会话(T06a)
# 新力侧会话(T06a/T06b)
本文件是单路 SensorStream 计划 T06a 的 SDK 合同:新的力侧会话直接消费 T05 的
本文件是单路 SensorStream 计划 T06a/T06b 的 SDK 合同:新的力侧会话直接消费 T05 的
`ImageMeasurement`(T03 `MeasurementFrame` 头 + 同帧 raw/field),参考版本取帧上的
`reference_generation`。旧 `ForceSession` 仍为 App 保留到 T09/T10 迁移,本会话不提供
`process_measurement`、`request_zero_external_reset`、`tracker_reset_seq` 等旧外部复位接口。
## 接口
- `ForceStreamSession(sensor_family=..., calibration=None, settings=None)`:构造;T06a 支持
无标定与 schema2 标量曲线,`settings` 为 `OutputSettings`(None 用旧默认)。
- `ForceStreamSession(sensor_family=..., calibration=None, settings=None)`:构造。T06a 支持
无标定与 schema2 标量曲线;T06b 补充 schema3 field 模型(`hhd_normal_l1_field/1`,需要
`context` 与同帧 field)和 FN-only 全局增益模型(`outputs=["fn"]`);`settings` 为
`OutputSettings`(None 用旧默认)。
- `measurement_requirements`:`(want_field, want_contact)`,告诉 T05 调用方是否需要把
`field` include 进 `ImageMeasurement`(field 模型为 `(True, False)`,标量/FN-only 为 `(False, False)`)。
- `request_zero(reference_id=..., declared_unloaded=True, expected_reference_generation=版本, max_gap_s=None, max_window_s=None)`:
为指定参考版本确认无载归零;可选窗口上限。
- `process(measurement) -> ForceStreamOutput`:消费一个 T05 `ImageMeasurement`,返回逐帧结果
@@ -34,11 +38,15 @@
`reference_generation`;`quality` 为 `ok` / `uncalibrated` / `zero_pending` / `duplicate` /
`late` / `session_changed` / `version_changed` / `window_failed` / `invalid`。
迟到、无效和带质量标记的结果不会被丢弃;拒绝帧仍保留 raw 特征。
- **数值等价与滤波。** T06a 的零点/标定换算/读数滤波复用已发布算法;同一输入、无复位、
同一标定时与旧 `ForceSession` 逐帧相等(测试覆盖标量曲线、无标定、median+lowpass 滤波器)。
- **数值等价与滤波。** 零点/标定换算/读数滤波复用已发布算法;同一输入、无复位、同一标定时
与旧 `ForceSession` 逐帧相等(T06a 覆盖标量曲线、无标定、median+lowpass 滤波器;T06b 覆盖
`context` 与同帧 field)和 FN-only 全局增益模型(`outputs=["fn"]`);`settings` 为
固定设计帧率与显式滤波切换属于 T07,不在本会话实现。
- **三类标定与不匹配。** 标量曲线、field、FN-only 各有有效测试;无标定会话保持 raw 与
`uncalibrated` 状态;field 模型缺 `context` 时构造报 `CalibrationError`,基线帧缺 field 或
模型拒绝帧时零点失败并给出 `invalid_input`/原因;FN-only 的 FX/FY 永远保持 NaN +
`uncalibrated`,不冒充三轴标定。
- **线程与只读。** 一个实例只属于一个力侧线程;输入数组只读,输出只含标量/状态/不可变进度。
T06b 在本合同上补充 field 模型、FN-only 全局增益模型与三类标定的完整等价测试。
## 示例
@@ -64,8 +72,8 @@ assert row.zero.phase in ("resetting", "collecting")
## 后续
T06b:field(`hhd_normal_l1_field/1`)与 FN-only(schema3 `outputs=["fn"]`)标定、标定不匹配、
field 加权基线与标量力域基线的分离,以及对照旧 ForceSession 的完整五场景数值等价。
T06b 已交付标量/field/FN-only 三类标定与旧 ForceSession 的完整数值等价;spatial_gain/接触
映射模型不在 T06b 验收范围,需要时另立任务。
T07 才改变输出滤波的帧率与切换语义;T09/T10 迁移 App 后删除旧 `ForceSession`。
另一项后续任务:删除旧 `ForceSession` 之前,先把零点、标定、读数引擎从旧类中抽出来,
避免新会话依赖待删除的类型(T06b 或 T09 之前)。