Autocal 标定操作与数据格式草稿
状态：待评审，2026-10-10。用途：方案及操作指南。近期目标是跑通多测点法向采集、保存和离线重算；下列操作是首版目标流程，尚非全部可执行的软件说明。
范围与软件现状
| 项目 |
当前约定 |
| 标定范围 |
多测点法向力，暂定 0–30 N；剪切及组合载荷后续再做 |
| 压头 |
直径 6 mm、球面半径 3 mm 的半球压头 |
| 参考 |
砝码或 50 N／2 N·m FT sensor，首版先接通一种 |
| 图像 |
一个完整测试事件一个连续视频，档位间不切段 |
| 交付 |
单个 session 能重新打开、追溯参考载荷并离线重算 |
LF606 规格书量程表包含 50 N／2 N·m 档位，但图签为 200 N／8 N·m；实机以铭牌及标定证书核对。
| 功能 |
源码现状 |
首版需要补齐 |
| 设备设置、轴操作、测点姿态预览 |
Autocal 已有对应模块 |
与采集事件关联 |
.oryseq 导入导出 |
已有；见 sequence-format.md |
载荷循环由 trial 的 steps 表达，不假定旧序列已支持 |
| 自动执行、传感器及标定点页面 |
运行入口提示未实现，相关页面占位 |
最小事件控制和采集入口 |
| 图像、读数、事件记录 |
Studio／shared 已有记录链 |
接入 Autocal，增加 trial／step、参考流及独立事件视频 |
| 新格式回放、拟合及导出 |
本文定义目标契约 |
关联校验与最小离线处理 |
操作员逐步流程
设备操作沿用 workflow.md 的准备、运动边界及停机流程。以下不新增自动运动授权；尚未接通的步骤不能靠占位按钮完成。
| 步骤 |
操作员动作 |
软件记录／通过条件 |
| 1. 建立会话 |
填写传感器 SN、gel ID、实验台、压头和参考设备；选保存位置 |
创建唯一 session_id；保存身份和配置快照 |
| 2. 检查设备 |
完成设备设置、回零及既定检查，核对相机和参考输入 |
状态可读；运动边界按既定流程确认 |
| 3. 确认测点 |
在有效 UV 区域选点，核对三维位置和姿态 |
分配 site_id，UV→3D 映射有效 |
| 4. 设置循环 |
选择载荷档位、保持时间及重复数；预览正反路径 |
保存 load_levels_n、hold_s、repeats；档位不超本次确认范围 |
| 5. 建立基准 |
无接触时检查零载荷，保存参考图像和必要历史 |
保存归零／基准事件及 baseline_id |
| 6. 开始事件 |
到达确认的测点姿态后，在加载前启动记录 |
新建 trial_id 和视频；确认视频与参考记录正常后加载 |
| 7. 逐级加载 |
按路径到各目标档位并保持，标记实际到达时间 |
每档有 step_id、目标及实际参考力、分支和时间范围 |
| 8. 逐级卸载 |
按相同档位下降到零，保留恢复过程 |
连续记录卸载分支；循环内不重新归零或重置图像基准 |
| 9. 结束／重复 |
检查恢复与记录状态，停止事件；重复或移到下一点 |
完成写入后标记状态；每次重复使用新 trial 和视频 |
| 10. 复核会话 |
重新打开文件，回放至少一个完整事件，检查档位对应关系 |
缺失、丢帧和中断可见；保留完整 trial 作独立验证 |
推荐路径为 0 → F1 → F2 → Fmax → F2 → F1 → 0，具体档位待定。逐级卸载提供与加载分支相同载荷的对照；各档采用相同保持规则。保持时间先支持 10–30 s 配置，人工选择分析窗口并记录原因；到时不自动等于稳定。异常时按既定流程停止，保留未完成记录，重测用新 trial。
坐标与关联
| 对象 |
保存内容 |
约定 |
| 测点 |
uv_xy、position_sensor_mm |
UV 单位 pixel，可为亚像素值；直接映射到 mesh 的 mm 位置 |
| UV 定义 |
uv_origin_px、图像尺寸、轴正方向 |
原点在有效 mask 内底部中间；允许负 Y |
| 几何 |
geometry_id、mesh／mask／映射文件及哈希 |
固定映射版本，二维与三维值可相互核对 |
| 姿态 |
T_platform_from_sensor、pose_source、激励方向 |
记录传感器→平台变换，区分实测和指令；normal 不必单独保存 |
| 关联层级 |
session → site → trial → step → samples |
trial 是完整循环，step 是循环内档位；帧与参考流按时间关联 |
文件及内部参数
以下为新格式建议，不是现有共享记录器文件的原样清单。sites、trials 和 steps 先内嵌于 session.json。
| 文件 |
主要字段／数据 |
写入时机 |
session.json |
format_version、session_id、身份、配置快照、坐标定义、文件清单、sites、trials、状态 |
会话建立、事件完成及结束时 |
sequence.oryseq |
实际使用的测点计划；遵循现有格式 |
开始采集前保存快照 |
video/<trial_id>.<ext> |
算法入口图像、完整循环及恢复 |
每 trial 开始至结束 |
frames.csv |
session_id、trial_id、frame_id、t_rel_s、视频路径、段内帧号、丢帧标记 |
每帧 |
baseline/ |
基准图像、初始状态或预录引用、baseline_id |
建立／重置基准时 |
reference.csv |
trial_id、t_rel_s、clock_id、实测力分量、有效性 |
FT 自身采样频率；砝码方式可不生成此流 |
motion.csv |
时间、目标／反馈位姿、有效性 |
有实际反馈时保存；缺少反馈须注明 |
events.csv |
时间、trial／step、事件类型、原因 |
到档、阶段切换、归零、异常及中断 |
derived/<processing_id>/ |
对齐样本、特征、拟合结果、验证指标和处理配置 |
离线处理；不覆盖原始文件 |
| 参数归属 |
主要参数 |
单位／填写来源 |
| session 身份 |
sensor_sn、gel_id、bench_id、indenter_id、reference_source |
操作员填写或设备读取 |
| session 采集 |
分辨率、像素格式、编码、版本、滤波与归零配置 |
软件快照；编码待实测确认 |
| session 时间 |
各流 clock_id、时间戳含义、偏移及同步误差 |
软件记录；不能按行号配对 |
| site |
site_id、UV、三维位置、几何关联 |
pixel／mm；软件映射 |
| trial |
trial_id、site_id、重复编号、姿态、baseline_id、视频、起止时间、状态 |
软件分配并记录实际执行 |
| trial 计划 |
load_levels_n、hold_s、repeats |
N／s／次数；操作员设置 |
| step |
step_id、target_load_n、branch、起止时间、analysis_window_s |
N／会话相对秒；branch 为 load／unload／zero |
| step 砝码参考 |
质量、重力加速度、传力方向、有效时段及 reference_load_n |
kg／m/s²／N；仅在传力条件成立时使用 m×g |
| 质量 |
valid、invalid_reason、丢帧／中断状态 |
未知不补零；算法失败不等于图像不可用 |
软件数据流与责任
当前实际链路
| 链路 |
代码位置／输出 |
对 Autocal 的含义 |
| 运行请求 → 未实现提示 |
window.py 的 _on_run_requested |
尚无自动采集循环 |
| 页面装配 → 占位页面 |
workspace.py |
传感器、表面和标定点页尚未接通 |
| Studio 采集包 → 记录通道 |
recording.py 的 RecordingChannel.on_packet |
将采集包分发给会话存储、标定采样器及文件记录器 |
| 采集包 → 有界队列 → 写入线程 |
experiment.py |
当前写 session、forces、frames、events、分段 MP4 或 PNG；不能直接视为新格式已完成 |
首版待接通链路
| 顺序 |
输入 → 处理 → 输出 |
负责模块 |
| 1 |
操作员设置 + .oryseq → sites／载荷路径 → session 快照 |
Autocal 会话与事件控制 |
| 2 |
UV + 固定映射 → mesh 位置 + 平台姿态 → site／trial |
几何及现有姿态计算能力 |
| 3 |
相机 → SDK 采集包 → 视频、帧索引 |
复用 shared 采集与记录能力 |
| 4 |
FT／砝码 + 平台反馈 + 档位事件 → 带时间的数据流 |
Autocal 参考输入及事件控制；与图像并行 |
| 5 |
事件结束 → 完成写入 + 完整性检查 → trial 状态 |
文件记录器及会话控制 |
| 6 |
视频解码 + 基准／配置 → SDK 特征重算；时间对齐参考 → 拟合／验证 |
离线处理，结果存 derived |
保留现有算法通道值时可沿用 forces.csv，但它不是独立参考力。业务层组织试验，SDK 负责图像算法，共享记录器负责文件写入；不让 SDK 依赖 Autocal UI。
首版验收与待定事项
| 验收 |
通过条件 |
| 数据关联 |
每个视频可追溯到测点、姿态、基准、加载／卸载档位及参考力 |
| 可回放 |
重新打开后能解码完整 trial，恢复处理状态并重算选定窗口 |
| 有效性 |
丢帧、参考缺失、中断及失败显式可见；原始记录不被重处理覆盖 |
| 最小验证 |
至少留出完整 trial，分别比较加载／卸载的法向误差；阈值待定 |
开跑前仍须确定载荷档位、轴方向及精确原点、参考采集与同步、视频编码和恢复窗口。先实测单 trial 的容量及丢帧，再估算整场存储。视频空档不承诺连续回放。空间模型、实时集成及长期可靠性验证后续再做；本流程不证明剪切或多接触精度。
ykcheungab