ykcheungab
249 lines
14 KiB
Markdown
249 lines
14 KiB
Markdown
# 统一力标定模型契约
|
||
|
||
Purpose: reference. Scope: SDK 标定文件选择、SN 绑定和推断接口。
|
||
状态：2026-10-18 已实现 schema 3 的空间/全局增益；ML 后端仅保留契约，尚未实现。
|
||
保持 `cal_path` 与现有单点文件；新增空间模型和机器学习模型使用同一入口。
|
||
|
||
## 现状与边界
|
||
|
||
现有实现见 [calibration.py](../src/orisys/calibration.py)、
|
||
[Sensor](../src/orisys/sensor.py)、[profile resolver](../src/orisys/sensors/calibration.py)。
|
||
当前读 schema 1/2，按 SN 加载要求三个通道，转换只接收三个力标量。
|
||
`ForceReadout.apply` 会分别转换滤波前后数据，不能直接挂接带状态的空间或 ML 模型。
|
||
|
||
| 所有者 | 责任 |
|
||
|---|---|
|
||
| 离线实验 / AutoCal | 采集、训练、验证、导出模型；将实验坐标转换为契约坐标 |
|
||
| SDK | 选文件、校验身份与输入、准备特征、推断、输出逐轴有效性 |
|
||
| 应用 | 提供 SN 与文件选择，展示状态；不自己套用第二次增益 |
|
||
| 设计资产 | 几何与坐标定义；不提供每台设备的实测标定值 |
|
||
|
||
SDK 不训练模型、不导入应用代码、不读取训练 CSV，不运行文件内指定的 Python。
|
||
实验 `finger_multical.experiment_model/1` 必须显式导出，不能直接当 SDK 文件加载。
|
||
|
||
## 文件选择：保留路径，文件决定模型
|
||
|
||
不增加 `model_type` 构造参数或全局活动模型。`Sensor`、`FingerRuntime.open` 和
|
||
profile 创建处理器统一复用内部选择器；现有入口参数只映射为选择请求。
|
||
|
||
| 请求 | 文件与行为 |
|
||
|---|---|
|
||
| 非空 `cal_path` | 精确加载该文件；缺失、错误或不兼容时报错，不换文件 |
|
||
| `calibration_dir` + `device_id` | 保持 `<dir>/<sensor_type>/<device_id>.json`；缺文件保持 raw 并报告 missing，不回退产品模板 |
|
||
| 两者都未提供 | 保持产品包默认解析；有 descriptor 时用 `default_calibration`，旧包保留既有候选顺序 |
|
||
| profile 的 `CalibrationSelection.NONE` | 明确不标定；不赋予 `cal_path="none"` 新语义 |
|
||
|
||
`cal_path` 与 `calibration_dir` 仍互斥。构造入口 `device_id` 对应文件 `identity.sn`，
|
||
不新造另一个 SN 字段。未指定设备的录像可显式选文件，但实际 SN 一致性标记为 unknown。
|
||
有 `device_id` 时严格匹配 `sensor_type`、`sn`；不根据相机编号猜 SN。
|
||
保留 `device_id` 单独传入时的参数错误；目录本身不存在也报错，不能当成 SN 文件缺失。
|
||
|
||
```python
|
||
# 沿用现有调用参数；cal_path 可以选择 schema 1/2/3 文件。
|
||
runtime = FingerRuntime.open(
|
||
config="finger", video="test.mp4",
|
||
device_id="DD02-GL-001",
|
||
cal_path="calibrations/finger/DD02-GL-001.json",
|
||
)
|
||
# 归零值来自本次无载窗口，不是模型内固定常量。
|
||
runtime.set_calibration_reference({"fn": measured_zero_raw}, reference_id="unloaded-1")
|
||
# 自动按 SN 选择仍使用 calibration_dir="calibrations"，不同时传 cal_path。
|
||
```
|
||
|
||
同一 SN 比较不同模型时，显式指定不同 JSON；默认 SN 文件只代表一个选定版本。
|
||
不扫描目录选“最新模型”，不在每帧重新加载。
|
||
|
||
## 最小文件：schema 3
|
||
|
||
复用 `force_calibration.json` 文件角色，增加 schema 3；文件名不参与模型类型判断。
|
||
以下是三点结构示例，数值和 SHA 占位值不是设备标定结果。
|
||
|
||
```json
|
||
{
|
||
"schema_version": 3,
|
||
"unit": "N",
|
||
"identity": {"sensor_type": "finger", "sn": "DD02-GL-001"},
|
||
"pipeline": {
|
||
"stitch_resolution": [700, 750],
|
||
"dis_mode": 4,
|
||
"hhd_downsample": 3,
|
||
"source_scale": 0.42,
|
||
"filters": {"measurement": {"flow_ema_alpha": 1.0}},
|
||
"feature_signature_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||
"geometry_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||
"coordinates": {
|
||
"frame": "autocal_flat",
|
||
"unit": "px",
|
||
"origin_xy": [511, 1021],
|
||
"map_sha256": "0000000000000000000000000000000000000000000000000000000000000000"
|
||
}
|
||
},
|
||
"model": {
|
||
"type": "spatial_gain/1",
|
||
"input_profile": "fn_delta_autocal_uv/1",
|
||
"output_frame": "sdk_force/1",
|
||
"outputs": ["fn"],
|
||
"params": {
|
||
"points_uv": [[-145, 604], [145, 604], [5, 430]],
|
||
"gains_N_per_raw": [0.00015, 0.00020, 0.00025],
|
||
"triangles": [[0, 1, 2]],
|
||
"valid_force_range_N": [0.0, 3.0]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 规则 |
|
||
|---|---|
|
||
| `schema_version` | 整数 3；未知版本拒绝 |
|
||
| `unit` | 固定 `N` |
|
||
| `identity` | `sensor_type`、非空 `sn` 必填；文件位置不能替代身份 |
|
||
| `pipeline` | 输入 profile 要求的实际处理参数、几何和坐标身份；缺少必需项或不匹配则拒绝 |
|
||
| `model.type` | SDK 已注册的版本化标识；决定参数解析和推断，不是模块路径 |
|
||
| `input_profile` | SDK 已实现的特征、单位、形状、预处理和时序契约 |
|
||
| `output_frame` | `sdk_force/1` 延续对应处理 profile 的 FN/FX/FY 符号和基方向；不是世界坐标合力模长 |
|
||
| `outputs` | 非空、无重复的 `fn/fx/fy` 子集；支持 FN-only，不冒充三轴标定 |
|
||
| `params` | 模型类型私有参数；通用加载器不解释点数或网络层 |
|
||
|
||
`provenance` 可选，保存数据摘要、训练版本和验证指标；不作为运行时输入。
|
||
其余未知语义字段拒绝，不能靠忽略字段误读新模型。新增模型类型不必升级外层 schema；
|
||
修改输入或算法语义必须升级相应 `/1` 标识。
|
||
|
||
`geometry_sha256` 是所用计算 mesh 文件字节的 SHA-256；`map_sha256` 是 SDK 坐标映射定义的
|
||
附件字节摘要，包含坐标转换结果，不能只比较图幅。pipeline 的必需键由输入 profile 固定，
|
||
覆盖该 backend 所有影响测量的设置；只检查示例中的部分配置不算兼容校验。
|
||
|
||
新增 profile 必须定义闭合的签名字段表。首个 profile 的 `feature_signature_sha256` 摘要
|
||
对象包含 `feature_version`、`processing_backend`、有效的图像预处理/光流/HHD 配置和计算资产哈希；
|
||
不含文件绝对路径、SN、显示资源或力读数滤波。以 UTF-8、键排序、无多余空格的 JSON 计算 SHA-256。
|
||
特征定义或单位改变须升级 `feature_version`，配置覆盖后重新计算，不能用配置文件名代替。
|
||
实现由 `calibration_context.build_context` 统一生成，特征版本为 `orisys_hhd_raw/1`。
|
||
|
||
## 空间增益模型
|
||
|
||
`spatial_gain/1` 固定输出 `fn`，使用 `fn_delta_autocal_uv/1`：
|
||
|
||
- 输入为同一帧的未经过力读数滤波的 FN raw、有效会话零点及接触 U/V。
|
||
上游光流滤波属于 pipeline 身份；不得混用不同特征链。
|
||
`delta_raw`、U、V 为有限浮点标量，前者单位 raw，后两者为上述有符号像素。
|
||
- SDK 会话准备 `delta_raw = fn_raw - zero_raw`，模型不再次扣零。
|
||
零点必须来自明确的归零操作或已标注窗口；模型文件不保存某段录像的启动零点。
|
||
- U 向右、V 向上，`x=origin_x+U`、`y=origin_y-V`。
|
||
SDK 提供并校验坐标转换；不能让模型偷偷按比例换算，不能运行时依赖 AutoCal。
|
||
- `points_uv` 为 N×2，`gains_N_per_raw` 长度 N；N≥3 且非共线、坐标唯一、增益有限且为正。
|
||
`triangles` 为任意数量的三索引，必须构成支持点凸包内完整、无重叠的非退化三角网。
|
||
保存连接关系以避免重新剖分引入变化；点数由数组决定，不固定为 9/15。
|
||
- 对三角形内查询，`g=Σw_i*g_i`，`fn_N=g*delta_raw`；不插值倒数，不外推。
|
||
未覆盖、位置失败、归零无效均返回无效，不能偷偷改用 M0。
|
||
- `valid_force_range_N` 必填。估计超范围时保留数值并标记 `out_of_range`，不截断。
|
||
|
||
FingerRuntime 使用 `artifacts` 中 `role="coordinate_map"` 的只读 NPZ：
|
||
`uv_by_output_px` 为 H×W×2 有符号 UV，`valid_mask` 为 H×W bool；可附 `origin_xy` 与
|
||
`flat_mapping_sha256`。`pipeline.output_domain_sha256` 绑定实际展开的 remap、mask 和 world_xyz；
|
||
形状、几何或特征身份不同则在打开视频前拒绝。离线直接提供 UV 的模型可以没有映射附件。
|
||
|
||
单点/两点数据不自动切换算法；可导出独立的 `global_gain/1`，参数为各输出轴的增益和有效范围，
|
||
输入 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。
|
||
附件间依赖也须逐项声明和校验，未声明的外部权重不可加载。
|
||
|
||
## 每帧推断与有效性
|
||
|
||
内部统一生命周期如下，`calibration.load` 分流到旧曲线或新模型：
|
||
|
||
```text
|
||
load(selected_file, device_identity, pipeline) -> CalibrationModel
|
||
model.predict(frame_id, timestamp_s, profile_features, reference_id) -> CalibrationResult
|
||
model.reset(reference_id)
|
||
|
||
CalibrationResult:
|
||
values_N: {axis: finite_float | null}
|
||
status: {axis: ok | no_contact | invalid_input | zero_unavailable |
|
||
coordinate_unmapped | outside_coverage | out_of_range}
|
||
```
|
||
|
||
FN 空间模型输入仅允许单一接触；当前定位器只返回一个中心，无法证明不存在多接触，
|
||
不能宣称已标定总力。全局 `force_delta/1` 不要求定位，未提供接触状态不等同于无接触。
|
||
无接触、失败帧的校准输出为空，raw 另行保留；缺失值不是 0 N。
|
||
`out_of_range` 有数值但不在验证范围，其余失败状态无数值；未声明轴不可用、单位仍为 raw。
|
||
不把某轴 raw 填进 `values_N`，也不只靠全局 `force_unit` 判断三轴单位。
|
||
schema 3 的旧数值读数接口以 NaN 表示已声明轴的无效输出，并同步暴露上述状态；
|
||
`force_calibrated` 表示已加载模型能力，不表示当前帧有效。
|
||
|
||
一个模型实例属于一个流；按帧顺序每帧推断一次，读数和录像复用结果。
|
||
清零、重连、倒播或更换模型时重置状态；不同 SN 不共享可变状态。
|
||
schema 3 先做上游测量与归零、模型推断，再做有效 N 读数的显示滤波；失败帧不进滤波历史。
|
||
schema 1/2 仍保留旧滤波/转换顺序。状态模型不能塞入会调用两次的旧 `convert` 回调。
|
||
|
||
加载诊断至少包含路径、来源、SN 校验状态、模型/输入 profile、轴集合、内容指纹和失败原因。
|
||
加载不匹配失败与逐帧暂时无效分开；替换时先完成加载校验，失败不得破坏原活动模型。
|
||
Sensor 提供 `bind_calibration_context`、`set_calibration_reference`、`apply_calibration_frame`；
|
||
FingerRuntime 自动绑定真实上下文，并转发归零。`FrameSnapshot.force_units` 和
|
||
`calibration_status` 随帧保存，不能用稍后读取的 Sensor 状态解释旧帧。
|
||
归零与换模型须在计算线程或暂停处理时调用，不承诺并发修改安全。
|
||
|
||
## 兼容、实现位置与验收
|
||
|
||
新读取器并存支持 schema 1/2/3；旧文件不重写，SN 校验的旧三通道要求保持。
|
||
schema 3 按声明轴校验，允许 FN-only；旧 SDK 遇 schema 3 必须拒绝，不能降级猜读。
|
||
回退通过恢复旧文件的 `cal_path`；SN 默认文件切换前保留旧副本，不覆盖唯一证据。
|
||
|
||
| 修改位置 | 最小工作 |
|
||
|---|---|
|
||
| `calibration.py` | schema 分流、身份和附件校验；旧曲线适配器 |
|
||
| `sensors/calibration.py` | 统一选择器与指纹；支持 SN 请求 |
|
||
| 新 `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.json` 与同名 `.coordinates.npz` 是本次实验交付，
|
||
`identity.sn="dd02-gl"` 为实验标识，未从硬件读取；原三边缘点与非单调点警告保留于 provenance。
|
||
它不是生产包默认文件，需显式 `cal_path` 选择。
|
||
|
||
实现验收必须覆盖：旧结果与单位不变；显式路径/SN/默认/关闭选择；错误 SN 不串用；
|
||
3/14/更多点、退化网格与凸包外；节点和插值预测；零点不重复扣除；缺坐标/无接触；
|
||
FN-only 的 FX/FY 不冒充 N；未知模型、附件损坏和依赖缺失；状态模型每帧只调用一次及 reset。
|
||
另以独立录像验证物理准确度，契约或单元测试通过不代表标定合格。
|