新增 HHD 场加权标定模型与加权空载基线
field_gain/1 用坐标增益图对无旋向量场做 L1 场加权，以连续 30 帧加权中位数替代旧 raw 零点，实时入口暂不支持。目标测试 102 项与 lint_gate 通过；契约见 orisys-sdk/docs/field-gain-model.zh.md。
This commit is contained in:
ykcheungab
@@ -1,7 +1,7 @@
|
||||
# 统一力标定模型契约
|
||||
|
||||
Purpose: reference. Scope: SDK 标定文件选择、SN 绑定和推断接口。
|
||||
状态：2026-10-18 已实现 schema 3 的空间/全局增益；ML 后端仅保留契约，尚未实现。
|
||||
状态：2026-10-19 已实现 schema 3 的空间、全局与场加权增益；ML 后端仅保留契约，尚未实现。
|
||||
保持 `cal_path` 与现有单点文件；新增空间模型和机器学习模型使用同一入口。
|
||||
运行中的 Finger 可调用 `runtime.set_calibration(file, device_id=sn)`；调用者须在处理线程的帧边界执行。
|
||||
该接口按实际几何、展开域及处理参数重新校验，成功切换后清除会话零点；校验失败保留原模型。
|
||||
@@ -154,46 +154,9 @@ FingerRuntime 使用 `artifacts` 中 `role="coordinate_map"` 的只读 NPZ：
|
||||
输入 profile 为 `force_delta/1`，由 SDK 按同一归零语义准备对应 raw 增量。
|
||||
这不同于旧曲线的绝对 raw 输入；兼容适配器不得替旧文件额外扣零。
|
||||
|
||||
## 机器学习扩展
|
||||
## 其他模型类型
|
||||
|
||||
同一 SN、路径和外层字段不变，只替换 `model`。下面只预留 `onnx/1` 示例，
|
||||
不表示 SDK 已支持 ONNX；后端实现和输入 profile 验证通过前必须拒绝加载。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "onnx/1",
|
||||
"input_profile": "fn_delta_autocal_uv/1",
|
||||
"output_frame": "sdk_force/1",
|
||||
"outputs": ["fn"],
|
||||
"params": {
|
||||
"input_tensor": "features",
|
||||
"output_tensor": "force_N",
|
||||
"feature_order": ["delta_raw", "u", "v"],
|
||||
"dtype": "float32",
|
||||
"shape": [1, 3],
|
||||
"valid_force_range_N": [0.0, 3.0]
|
||||
},
|
||||
"artifacts": [
|
||||
{
|
||||
"role": "weights",
|
||||
"path": "DD02-GL-001/model.onnx",
|
||||
"sha256": "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
此标量 profile 的规范输入即上述顺序、类型、形状；输出 float32 `[1, len(outputs)]`，
|
||||
轴序严格按 `outputs`。归一化及单位转换封装在已验证的模型图内，不由应用另做。
|
||||
`fn_delta_autocal_uv/1` 只允许 `outputs=["fn"]`，不能凭 FN 特征宣称三轴已标定。
|
||||
需要图像、完整光流或历史序列时新增输入 profile，明确 H/W、通道、掩码、单位和时间窗口；
|
||||
没有对应特征的处理器拒绝加载，不能用零张量凑齐输入。
|
||||
|
||||
`artifacts` 只在有外部文件时必填；路径相对所选 JSON 的父目录，禁止绝对路径、URL、
|
||||
`..` 或链接逃逸。校验 SHA-256、角色和文件完整性后才初始化受支持的后端。
|
||||
不加载 pickle、任意 Python 或模型自带扩展库；缺推断依赖须明确报错，不自动安装。
|
||||
文件与所有附件共同构成内容指纹，不能只哈希 JSON。
|
||||
附件间依赖也须逐项声明和校验，未声明的外部权重不可加载。
|
||||
场加权 FN 模型 `field_gain/1`（输入 profile `hhd_normal_l1_field/1`）的字段、映射、空载基线与诊断契约见[场加权模型契约](field-gain-model.zh.md)。ML 扩展（首个示例 `onnx/1`）仍是预留示例，见[机器学习模型契约](ml-model-contract.zh.md)；后端实现和输入 profile 验证通过前必须拒绝加载。
|
||||
|
||||
## 每帧推断与有效性
|
||||
|
||||
@@ -240,12 +203,14 @@ schema 3 按声明轴校验，允许 FN-only；旧 SDK 遇 schema 3 必须拒绝
|
||||
|---|---|
|
||||
| `calibration.py` | schema 分流、身份和附件校验；旧曲线适配器 |
|
||||
| `sensors/calibration.py` | 统一选择器与指纹；支持 SN 请求 |
|
||||
| 新 `calibration_models.py` | 受控类型表、空间增益与模型生命周期；ML 后端另行实现 |
|
||||
| 新 `calibration_models.py` | 受控类型表、空间/全局/场加权模型与生命周期；ML 后端另行实现 |
|
||||
| `sensor.py`、`finger/runtime.py`、处理器适配层 | 提供同帧位置/零点，缓存逐轴结果和状态 |
|
||||
| Sensor 与 `ForceReadout` | 复用读数滤波器；schema 3 在推断后逐轴滤波，旧路径不变 |
|
||||
| 离线导出器 | 实验模型到 schema 3；SDK 不依赖实验目录 |
|
||||
|
||||
当前导出入口为 workspace 的 `scripts/finger_multical/export_sdk.py`，输出已有文件时拒绝覆盖。
|
||||
场加权实验文件 `data/dd02-gl/force_calibration.v3.field.json` 由同目录 `export_field.py`
|
||||
从上述交付只读转换（不重训、不改排除点、不覆盖原件），契约见[场加权模型契约](field-gain-model.zh.md)。
|
||||
`data/dd02-gl/force_calibration.v3.json` 与同名 `.coordinates.npz` 是本次实验交付，
|
||||
`identity.sn="dd02-gl"` 为实验标识，未从硬件读取；原三边缘点与非单调点警告保留于 provenance。
|
||||
它不是生产包默认文件，需显式 `cal_path` 选择。
|
||||
@@ -253,4 +218,6 @@ schema 3 按声明轴校验，允许 FN-only；旧 SDK 遇 schema 3 必须拒绝
|
||||
实现验收必须覆盖：旧结果与单位不变；显式路径/SN/默认/关闭选择；错误 SN 不串用；
|
||||
3/14/更多点、退化网格与凸包外；节点和插值预测；零点不重复扣除；缺坐标/无接触；
|
||||
FN-only 的 FX/FY 不冒充 N；未知模型、附件损坏和依赖缺失；状态模型每帧只调用一次及 reset。
|
||||
场加权另需常增益等价、两区域贡献、边界投影、映射错误与 30 帧加权基线生命周期，
|
||||
见 `tests/test_field_calibration.py`。
|
||||
另以独立录像验证物理准确度，契约或单元测试通过不代表标定合格。
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
# 场加权力标定模型契约
|
||||
|
||||
用途：reference。范围：SDK schema 3 `field_gain/1` 的输入、映射、空载基线、诊断与兼容边界。
|
||||
[统一力标定模型契约](calibration-model-contract.zh.md)负责文件选择、身份与逐帧生命周期；
|
||||
本文只补充场加权模型特有语义。状态：2026-10-19 已实现并有回归测试，离线录像对照见
|
||||
[实施计划](../../docs/workflow/field-weighted-calibration-plan.zh.md)。
|
||||
|
||||
## 定位与边界
|
||||
|
||||
从现有多点增益生成空间图，对 HHD 无旋向量场做加权求和，作为 FN 的实验估计。
|
||||
不依赖深度、接触中心、最大光流点或单接触判定；实时入口尚未接入，必须显式拒绝。
|
||||
现有增益对应各加载位置的整场响应，不是已验证的局部系数。交付证明软件契约与可复现估计，
|
||||
不宣称局部压力、多接触力可加性或精度改善。负的基线差保留；显示阈值只由显示层决定。
|
||||
|
||||
## 文件字段
|
||||
|
||||
`model.type` 为 `field_gain/1`，`input_profile` 为 `hhd_normal_l1_field/1`，`outputs` 仅 `["fn"]`。
|
||||
`pipeline` 沿用 schema 3 的测量身份，并增加闭合的 `pipeline.field`（由 SDK
|
||||
`FIELD_IDENTITY` 生成）：`grid`、`shape`、`mask_shape`、`vector`、`reduction`、`dtype`、
|
||||
`unit`、`mask`、`lifecycle`、`area_compensation`。它们进入特征签名；改变任一值即需升级 profile。
|
||||
`params` 必需键：
|
||||
|
||||
| 键 | 规则 |
|
||||
|---|---|
|
||||
| `points_uv`、`gains_N_per_raw`、`triangles` | 沿用空间增益的完整凸包三角网校验；点数由数组决定 |
|
||||
| `valid_force_range_N` | 必填 `[low, high]`；超范围保留数值并标 `out_of_range` |
|
||||
| `mapping` | 固定 `{"inside": "barycentric", "outside": "boundary_projection", "tie_break": "boundary_edge_order"}` |
|
||||
| `baseline` | 固定 `{"frames": 30, "statistic": "median"}`，仅实现这一策略 |
|
||||
|
||||
`artifacts` 必须有且仅有一个 `role="coordinate_map"` 附件；`map_sha256` 必须等于附件字节摘要。
|
||||
附件提供输出分辨率 `uv_by_output_px` 与 `valid_mask`，SDK 打开模型时校验形状与有限性。
|
||||
|
||||
## 增益图与加权求和
|
||||
|
||||
先把支撑点增益映射到 HHD 向量场的计算网格，再逐帧归约；缓存身份包含模型指纹、坐标附件、
|
||||
HHD 网格形状与物理有效掩膜，任一变化都重建。映射规则：
|
||||
|
||||
- 三角网内按重心插值取增益；查询落在共享边时按文件中的三角顺序取第一个命中的三角形。
|
||||
- 凸包外投影到最近边界线段，再按投影参数插值两端增益；距离相同时取边界边排序中靠前者。
|
||||
- 输出网格内只在物理有效像素上统计；有效掩膜内缺坐标或增益是模型映射错误，报
|
||||
`coordinate_unmapped`，不当作零或域外增益。
|
||||
- 按块面积降采样到 HHD 网格：增益取覆盖有效像素的均值；`coverage` 是覆盖面积比，
|
||||
`inside` 是凸包内面积比；混合覆盖格点保留比例，不平均无效坐标。
|
||||
|
||||
逐帧对同一帧的 HHD 无旋向量场 `d` 计算
|
||||
`P = A * sum_{HHD 激活格点}(gain * (|d_x| + |d_y|))`。HHD raw 汇总正是
|
||||
`A * sum_{激活格点}(|d_x|+|d_y|)`，所以常增益必须精确等于 `gain * raw`；`coverage` 只用于
|
||||
外推比例与诊断，不得再乘进 `P`，否则掩膜边缘的部分覆盖格点会被重复折扣。
|
||||
|
||||
HHD 激活但 `coverage=0`（没有任何有效像素映射到该格点）是模型映射错误，报
|
||||
`coordinate_unmapped`，不得静默记零。`A` 取自 `hhd/api.py` 现有的
|
||||
参考网格面积补偿（参考网格像素数/当前网格像素数），调用方不得再乘一次或重复归一化。
|
||||
不得改变 FN raw、HHD 分解或剪切分量。空场时 `P=0` 且外推比例为 0；
|
||||
负的 `FN = P - B0` 保留为有效数值（可能超量程）。
|
||||
|
||||
## 空载基线与生命周期
|
||||
|
||||
用户先声明无载窗口，SDK 才对后续帧累计加权 `P`：
|
||||
|
||||
- `Sensor.declare_unloaded_reference(reference_id=...)`（`FingerRuntime` 同名转发）开始窗口；
|
||||
`reference_id` 必填并记录。窗口要求连续 30 个有效帧；任一无效输入或映射错误会中断连续计数，
|
||||
向前 30 帧零点未就绪。
|
||||
- `B0` 为这 30 个 `P` 的中位数；就绪前的帧状态为 `zero_unavailable`，不输出牛顿值。
|
||||
就绪后 `FN = P - B0`。
|
||||
- 空载确认不以接触定位为门槛，但要求输入有限；换模型、重置、倒播或新会话使基线失效。
|
||||
- 场模型拒绝旧标量零点：`Sensor.set_calibration_reference()` 对 `hhd_normal_l1_field/1`
|
||||
抛 `CalibrationError`，调用方必须使用加权窗口接口，不能把旧 FN raw 零点当作 `B0`。
|
||||
|
||||
## 结果诊断
|
||||
|
||||
`CalibrationResult.diagnostics` 逐帧携带版本化诊断；旧结果或缺字段时按未知处理，不得补零：
|
||||
|
||||
| 键 | 含义 |
|
||||
|---|---|
|
||||
| `model_fingerprint` | 模型文档与附件的内容指纹 |
|
||||
| `mapping` | 生效的边界策略 |
|
||||
| `baseline_N`、`reference_id` | 已就绪基线及其声明标识；未就绪为 `None` |
|
||||
| `pending_reference_frames` | 当前连续窗口已累计的有效帧数 |
|
||||
| `extrapolated_fraction`、`coverage_fraction` | 按 `q` 加权的凸包外比例与覆盖比例 |
|
||||
| `area_scale`、`frame_id` | 本帧面积补偿与帧标识 |
|
||||
|
||||
`extrapolated_fraction` 是估计质量，不是有效性：它不改变 `status`，也不得让上层丢弃牛顿值。
|
||||
零点缺失、输入错误仍无效；超量程沿用现有显式状态。
|
||||
|
||||
## 兼容与实现位置
|
||||
|
||||
旧 `spatial_gain/1`、`global_gain/1` 与旧文件语义不变；schema 3 按声明轴校验，旧 SDK 遇
|
||||
`field_gain/1` 必须拒绝。`hhd_downsample` 仍按既有兼容例外处理：只允许该键数值不同，
|
||||
其余处理参数、几何、展开域、SN 与传感器类型仍须匹配，不能借此跳过签名校验。
|
||||
|
||||
| 位置 | 责任 |
|
||||
|---|---|
|
||||
| `src/orisys/field_calibration.py` | profile/策略常量、增益图构建、加权归约 |
|
||||
| `src/orisys/calibration_models.py` | 类型注册、参数校验、基线状态与诊断 |
|
||||
| `src/orisys/hhd/api.py` | 同帧 `get_field()`：`d` 拷贝、物理掩膜、面积补偿 |
|
||||
| `src/orisys/sensor.py`、`src/orisys/finger/runtime.py` | 同帧场推断、加权零点声明、上下文绑定 |
|
||||
| 工作区 `scripts/finger_multical/export_field.py` | 现有空间模型只读导出为实验文件，不重训、不改排除点 |
|
||||
|
||||
回归证据：`tests/test_field_calibration.py` 覆盖常增益等价、两区域贡献、重叠向量先合成再 L1、
|
||||
边界投影、掩膜/NaN/空场、映射错误与 30 帧基线生命周期；`tests/test_model_runtime.py` 覆盖
|
||||
HHD 同帧场接线、加权零点声明与无接触推断。命令与 run_id 记录在实施计划的执行结果中。
|
||||
实验导出文件不覆盖原件，provenance 声明来源哈希、边界/基线策略和实验假设。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 机器学习力标定模型契约
|
||||
|
||||
用途：reference。范围：SDK schema 3 中预留的 ML 模型后端（首个示例 `onnx/1`）与输入 profile
|
||||
约束。文件选择、身份、逐帧生命周期与有效性状态由[统一力标定模型契约](calibration-model-contract.zh.md)
|
||||
负责。状态：仅保留契约，SDK 尚未实现 ONNX 后端；实现与验证通过前必须拒绝加载。
|
||||
|
||||
同一 SN、路径和外层字段不变，只替换 `model`。下面只预留 `onnx/1` 示例，
|
||||
不表示 SDK 已支持 ONNX。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "onnx/1",
|
||||
"input_profile": "fn_delta_autocal_uv/1",
|
||||
"output_frame": "sdk_force/1",
|
||||
"outputs": ["fn"],
|
||||
"params": {
|
||||
"input_tensor": "features",
|
||||
"output_tensor": "force_N",
|
||||
"feature_order": ["delta_raw", "u", "v"],
|
||||
"dtype": "float32",
|
||||
"shape": [1, 3],
|
||||
"valid_force_range_N": [0.0, 3.0]
|
||||
},
|
||||
"artifacts": [
|
||||
{
|
||||
"role": "weights",
|
||||
"path": "DD02-GL-001/model.onnx",
|
||||
"sha256": "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
此标量 profile 的规范输入即上述顺序、类型、形状；输出 float32 `[1, len(outputs)]`，
|
||||
轴序严格按 `outputs`。归一化及单位转换封装在已验证的模型图内，不由应用另做。
|
||||
`fn_delta_autocal_uv/1` 只允许 `outputs=["fn"]`，不能凭 FN 特征宣称三轴已标定。
|
||||
需要图像、完整光流或历史序列时新增输入 profile，明确 H/W、通道、掩码、单位和时间窗口；
|
||||
没有对应特征的处理器拒绝加载，不能用零张量凑齐输入。
|
||||
|
||||
`artifacts` 只在有外部文件时必填；路径相对所选 JSON 的父目录，禁止绝对路径、URL、
|
||||
`..` 或链接逃逸。校验 SHA-256、角色和文件完整性后才初始化受支持的后端。
|
||||
不加载 pickle、任意 Python 或模型自带扩展库；缺推断依赖须明确报错，不自动安装。
|
||||
文件与所有附件共同构成内容指纹，不能只哈希 JSON。
|
||||
附件间依赖也须逐项声明和校验，未声明的外部权重不可加载。
|
||||
Reference in New Issue
Block a user