ykcheungab
24 KiB
记录通道与数据可靠性
本文记录 Studio 在"完整记录、数据可靠优先"这轮改动中的架构决定，以及针对架构评审 第 8 节所列缺陷的修法与验证方式。
核心结论是：标定采样、全程历史、无效样本隔离之所以会出问题，根因是同一处架构缺口 —— 采集数据只有一个出口，就是 16 ms 的 UI 定时器。
1. 改动前的问题链
worker 线程 ──> self._latest（单槽，后写覆盖）
│
UI 定时器 _on_run_tick（16 ms）──┬──> 曲线历史（只保留窗口内样本）
├──> 标定采样（且被 if self._show_cal 守卫）
└──> 箭头/深度渲染
由此派生出评审指出的多个缺陷，它们不是彼此独立的问题：
| 现象 | 机制 |
|---|---|
| 标定依赖面板可见 | app_window.py 中 push_raw 被 if self._show_cal: 守卫，而它是唯一检查录制截止时间的地方 |
| 标定录制中无法停止 | push_raw 永不执行 → _finish_recording 永不调用 → _recording 恒为真 → 而 _recording 又让录制按钮禁用。两次点击都无法脱困 |
| 历史被窗口裁掉 | MetricHistory._prune() 主动丢弃 t < t_end - window_sec 的样本 |
| 面板未刷新时丢数据 | 单槽 _latest 后写覆盖，UI 降帧即丢样本 |
2. 现在的结构
worker 线程 ──> self._latest（显示，可有损）
│
└──> _emit(packet) ──> 记录 sink（记录，不可丢）
│
app_window._on_packet_recorded（运行在采集线程，不碰 Qt）
├──> SessionStore 全程存储
└──> CalibrationRecorder.feed() 标定采样缓冲
UI 线程 _on_run_tick ──> 曲线显示（仍可降帧）
└──> CalibrationRecorder.tick() 到点后结算（Qt 回调留在 UI 线程）
分工原则：
feed()在采集线程调用，只往线程安全的缓冲里追加，绝不触碰 Qt 控件。因此 隐藏标定面板、曲线重绘变慢、窗口后台化都不会中断记录。tick()在 UI 线程调用，负责判定截止时间、计算统计量并触发回调 —— Qt 信号与 控件更新必须留在 UI 线程。- sink 是普通 callable 列表，某个 sink 抛异常会被记录并只影响该 packet，不会杀掉采集。
关键文件
| 文件 | 职责 |
|---|---|
shared/.../acquisition/sinks.py |
RecordSinkMixin：sink 注册与扇出，两个 worker 共用 |
shared/.../force/session.py |
SessionStore：全程存储，内存有界，双单位 + 有效性 + 帧号 |
shared/.../force/calibration_recorder.py |
标定采样状态机，与 Qt 无关 |
3. SessionStore 的三条保证
- 不是"把窗口调大"：按定长 numpy 块追加，O(1) 写入；达到
max_samples时释放最旧 的整块并累加dropped。dropped由界面显式提示（status.samples_dropped）， 不允许静默丢数据。 - 同时保存 raw 与标定后数值：每个样本存
(fn,fx,fy)_raw与(fn,fx,fy)_N两套。 切换显示单位时曲线从 store 重建，而不是把新单位的值追加到旧缓冲上。 - 无效样本标记而不是归零：读取失败时存 NaN 且
valid=False；iter_valid()只产出 有效样本，因此标定统计不可能把一个失败读数当作 0 平均进去。
4. 针对评审第 8 节的修法
| # | 问题 | 修法 |
|---|---|---|
| 1 | 标定中无法点击停止 | _refresh_enabled 改为 can_record = self._running，录制中按钮保持可用并显示「停止」 |
| 2 | 切换 raw/N 后历史混用单位 | 新增 ForcePlotsPanel.set_units(unit, store)：清空缓冲并从 SessionStore 按目标单位重建；时间原点保留，X 轴不会跳回 0 |
| 3 | 异常被当成正常数据 | read_forces_from_sensor 不再吞异常：返回 valid=False + invalid_reason + NaN；SdkPacket 新增 valid / invalid_reason / raw_available；无效样本不进曲线、不进标定 |
| 4 | 标定依赖面板可见 | 采样改由 worker sink 驱动；_show_cal 只影响可见性，不再作为采样入口 |
| 5 | 历史 FN 被截断 | 去掉写入前的 max(0.0, fn) 夹值与显示前的 np.maximum；负值原样保留，越界由坐标轴范围裁剪（只影响绘制，不影响数据） |
| 6 | 导出覆盖并自动应用标定 | 导出只写用户标定目录（local_bundle_dir=None），不再改写 config/sensors/<type>/；应用前弹窗显示目标设备类型与配置，且只下发给匹配的 worker |
| 7 | 深度显示误导 | depth_map_to_bgr 支持 value_range 固定色标与 invalid_mask；色标在会话内锁定到首个有效深度帧并在面板头部显示数值范围；无深度时显示明确提示，不再回退成普通形变图 |
| 8 | 历史只保留窗口内样本 | 见 §3；SessionStore 与显示用的 MetricHistory 分离 |
另外修正了评审未列出的一处：RAW 通道不可用时，原代码把标定后的 N 值复制进 raw 字段
（fn_raw = fn）。现改为 raw_available=False 且 raw 保持 NaN，避免"原始值"实际上是
标定值。
5. 验证
$py = "D:\orisys_ws\orisys-app\.venv-build\Scripts\python.exe"
$env:PYTHONPATH = "D:\orisys_ws\orisys-app\shared\src;D:\orisys_ws\orisys-app\apps\studio\src"
cd D:\orisys_ws\orisys-app\apps\studio
& $py tools/ui_check.py # 含 "record channel" 段落
shared/tests/test_record_channel.py：11 项，覆盖内存上界、双单位、无效隔离、 跨线程 feed、截止时间结算、取消语义。shared/tests/test_experiment_recorder.py：12 项，覆盖目录结构、CSV 列序与空值规则、 帧号/时间基准一致、分段滚动与帧索引、仅数据模式、无损序列、队列溢出计数与报警、 编码失败上报并停止录制、元数据字段、崩溃后仍留有元数据、on_packet不阻塞。shared/tests/test_worker_cancellation.py：4 项，覆盖非阻塞 stop、线程所有权、 会话交接。tools/ui_check.py：新增record channel与experiment record两段，断言记录通道 在完全没有 UI 定时器触发的情况下仍收满样本、隐藏标定面板仍能采样、录制按钮是可用 取消入口、深度缺失不回退、色标锁帧，以及通过界面录制的目录结构与事件序列。apps/studio/tests/test_ui_smoke.py：上述不变量各有对应 pytest 用例，复用ui_check._StuckWorker与ui_check._fake_packet，保持单一来源。
已知环境限制
本机未安装 pytest，且沙箱拒绝写入工作区之外的路径，conftest.py 的 tmp_path 因此
写 prefs 失败。上述 pytest 用例是用等价驱动脚本执行的（参数化用例除外）；ui_check.py
覆盖同样的不变量且可完整运行。
6. 实验录制（第一阶段剩余部分）
shared/src/orisys_app_shared/record/experiment.py 的 ExperimentRecorder 落盘格式：
outputs/recordings/<UTC 时间戳>_session<NNNN>/
session.json 元数据 + 事件 + 结束统计
forces.csv 每帧一行
frames.csv 帧索引映射（帧号 ↔ 视频分段）
events.csv 带时间戳的操作事件
raw_0001.mp4 处理前相机图像，按需分段
frames/ 可选无损 PNG 序列
forces.csv 列序固定为
session_id, frame_id, t_rel_s, FN_raw, FX_raw, FY_raw, FN_N, FX_N, FY_N, valid, calibration_id。
几条硬性约束：
- 一次实验一个目录，
session.json在开始时先写一次，因此即使进程崩溃也留有可识别 的元数据；停止时再写一次并补上ended_at、事件与统计。 - 不静默丢数据：
on_packet只把标量（以及开启视频时的一帧拷贝）放进有界队列， 队列满则计数并报警，绝不阻塞采集；连续写失败达到MAX_CONSECUTIVE_ERRORS就停止录制 并把failed置位，而不是假装录完了。 - 帧号与时间统一：
forces.csv与frames.csv共用 packet 的frame_id，t_rel_s同源于首帧；frames.csv额外记录采集墙钟时间、落在哪个分段、以及是否进过视频， 这就是丢帧/分段场景下的重建依据。 - 未标定或读取失败的单元格留空，不写 0：
FN_N等列在无标定时为空，valid=0的行 所有数值列都为空。精度用repr(float)（最短往返表示），界面小数位不影响落盘。 - MP4 是有损封装：
session.json的video.lossy_note明确记录这一点，需要算法复现时 可开启lossless_frames输出 PNG 序列。 raw_frame在入队时必须拷贝：packet 里的帧可能复用 SDK 的采集缓冲，直接持有引用 会让录制内容随后续帧改变。
6.1 录制速率与时长（视频 30 fps、时长实时递增）
session.json 的 video.fps 是容器速率，必须等于传感器的采集速率，取自传感器配置
（config/sensors/<type>/sensor.json 的 fps，box 为 30），不是 packet 里那个
fps 字段 —— 后者是"管线每秒完成多少帧"的计数器，开流瞬间的缓冲突发或视频文件源会让
它读到 48，用它写 30 fps 的容器就等于把回放播成了快进。这是"传感器 30 fps、录制结果
48 fps"的直接原因。
StudioMainWindow._video_fps()：实时相机 → 传感器配置的fps；视频文件源 → 实测值； 实时相机的实测值另存video.measured_fps，两者都进session.json，对不上时看得见。- 视频按速率节流，CSV 一行不少（
ExperimentRecorder._video_frame_due）：比1/fps提前超过VIDEO_PACING_TOLERANCE（0.5 个周期）到达的帧只进frames.csv/forces.csv，不进视频，并计入stats.resampled_video；报告里会写成 "N frame(s) were delivered faster than the 30 fps recording rate, so they are in frames.csv but not in the video"。这不是丢数据，是显式记账。 - 节流表的调度基准取"上一帧排定时刻 + 周期"与"当前时间戳"的较晚者，所以卡顿之后不会 用一串补帧追进度。
stats()的duration_s在录制进行中就返回_last_t - _t0（此前只有_finalise才写，界面上的录制时长因此整场停在 00:00.0）；forces.csv的行数与时间轴不受影响。
已知环境限制
本机未安装 pytest，且沙箱拒绝写入工作区之外的路径，conftest.py 的 tmp_path 因此
写 prefs 失败。上述 pytest 用例是用等价驱动脚本执行的（参数化用例除外）；ui_check.py
覆盖同样的不变量且可完整运行。录制相关的测试把临时目录放在
shared/tests/_scratch/（已加入 .gitignore）以避开该限制。
7. 第一、二阶段评审 P1/P2 的整改（数据语义、终态、标定身份、深度重算）
评审脚本 D:/orisys_ws/_review_phase12/reproduce.py 的十条复现条件已全部翻转，改后
输出见同目录 reproduce_after.log。以下按发现逐条说明改法。
7.1 记录语义（P1-1）
唯一转换入口 shared/.../record/sample.py::to_record_sample。规则：
- 计算链失败（
valid=False或stale_forces=True）的帧，六个力值全部记为不可用。 SDK 的info.FNORMAL在计算失败时仍返回上一帧的数值，记录它等于伪造测量值。 - 只有该轴确实加载了标定曲线才写 N 值（
calibrated_axes按轴判断，而不是force_calibrated这个传感器级标志）。未标定的轴留空。 mono_t是排序基准，墙钟只进元数据。SdkPacket.mono_t/wall_t默认None而不是0.0：默认 0 会让所有帧的时间相同。- 每行
calibration_id取 packet 自带版本（采集线程在采集瞬间盖的哈希）， 会话级版本只作回退；一份 CSV 中途换标定也说得清。
7.2 记录终态与队列损失（P1-5、P1-6）
- 生命周期显式化为
starting/recording/stopping/stopped/failed；写线程拥有终态与最终 报告，文件打开、写入、flush、close 全在异常边界内。连续写失败会立刻停止接收 （rejected_after_failure计数），is_recording随之变假 —— 不会出现 failed=True 却 仍在录制。starting也算“录制中”，否则开始录制后立刻点停止会失效。 stop(wait=True, timeout=…)超时返回completed=False的报告，不写ended_at、 不丢弃线程引用；未结束的 recorder 不允许再次start()。- 队列按字节预算（
max_queue_bytes，默认 512 MiB）而不是仅按条数：1920×1080 BGR 排 2048 条副本约 11.9 GiB。预算用尽时丢视频保数据行；连条目队列都满时把数据行放进 独立的_row_backlog（默认 8192 行），因此视频溢出不再连带丢掉 CSV。 - 真的丢掉的数据行会在
frames.csv留下dropped=1的索引行，回放据此显示“该帧未录制”， 而不是拿上一帧冒充。统计区分dropped_data、dropped_video、dropped_gaps（已标记的缺口）与unrecorded_gaps（连标记都放不下的）。
7.3 标定身份与生效确认（P1-7）
- 标定身份是内容哈希（
calibration_digest，sha256），不是路径：同一路径可以重新导出 不同系数。Sensor打开时自带 bundle 标定，因此采集线程在第一帧之前就把实际加载的 标定哈希报出来（on_calibration_applied(path, version, frame_id)），事件与每行版本都 来自这次确认，而不是“已下发”的意图。 - 事件在发生时打时间戳（
log_event(..., mono_t=…, frame_id=…)），不再在写线程出队时 重新计时。 - 面板拆成三个独立动作：保存标定记录 / 导出系数 / 应用到设备。导出只写文件，
应用需要再次确认并等设备确认后才记
calibration_applied。
7.4 标定诊断与实验明细（P1-2、P1-8）
CalibrationRecorder.fit用将要导出的那个模型（build_export_model+ SDK 的Calibration.convert）计算残差与验证误差。分段线性模型会精确穿过它自己的标定点， 所以训练残差恒为 0 —— 真正有意义的诊断是留出验证点的偏差。界面按“导出模型：分段线性 （N 点 / M 个折点，最大残差）…”显示。- 验证点不进入构建（
CalPanel._rebuild_store跳过is_validation），重复参考载荷按 n 加权合并（merge_samples），不再“最后一个覆盖前面的”。 CalibrationPoint.samples保存该点全部三轴采样（帧号、相对时间、三轴 raw、三轴 N、 valid），连同排除/验证状态、方向、备注与实际时长一起写入独立的标定会话文件 （calibration_session_*.json，force/calibration_session.py），并可用「打开标定记录」 重新载入检查。界面上的降采样 trace 只是预览，不是审计数据。
7.5 深度重算与游标同步（P1-3、P1-4）
- 不再重开回放位置：
DepthRecomputer记录当前已读到的段内帧号，请求第 2 帧再请求第 3 帧只多读 1 帧（旧实现每次都从头读，2 和 3 会落到 5）；往回退才重开视频。 - 每帧都执行实时同一条链路：盒子
compute_deformation + compute_contact，手指再加上FingerRuntime的展开与有效区域（_BoxReplay/_FingerReplay）。 config_name用完整解析后的配置路径（load_fixed_mode），不再缩减成父目录名或 stem —— 那可能加载同名但不同的配置，而哈希校验还在比对原路径。- 算法参考状态：SDK 的跟踪器/滤波是有状态的，离线复现需要历史。两条可用依据：
- 操作归零（
zeroing事件，带帧号）会清空跟踪器，因此从该帧重放是精确的； - 录制开始前采集线程保留
PREROLL_FRAMES（30 帧，且不超过 192 MiB）的预处理帧， 录制开始时写入preroll_0001.mp4，session.json记preroll_frames/preroll_segment，回放先把它们喂给 SDK 再进入首帧。 都不满足时（跨分段、无归零、无预卷）仍然重算，但结果带state_approximate/state_across_segment提示，不假装与当时一致。
- 操作归零（
- 回放游标与深度结果按请求序号 + 帧号绑定：等待期间移动游标会作废旧请求，结果回来 只渲染属于当前帧的那一张；否则面板显示「当前游标位置尚未重算深度」，绝不复用旧图。
7. 同步回放与深度重算
决定：不保存深度。 回放时按录像与配置离线重算。
理由是体积：30 Hz、320×240 的 float32 深度每帧约 300 KB，一小时就是 ~16 GB；
即使降频到 1 Hz 也要百兆级。所以 session.json 里明确写：
"depth": {
"stored": false,
"replay": "recompute",
"quantity": "relative deformation / algorithm response, not a calibrated length",
"method": "re-run the SDK over raw_*.mp4 with this config_ref",
"config_sha256": "...",
"sdk_version": "..."
}
代价是重算要 SDK 能复现同样结果，因此 RecordingReader.replay_warnings() 会主动
比对当前配置文件哈希与录制时的哈希、以及 SDK 版本，回放窗口顶部把这些提示出来：
| 提示 | 含义 |
|---|---|
depth_recomputed |
深度来自离线重算，不是当时保存的数据（始终提示） |
config_changed |
配置文件已变，重算结果可能与当时不同 |
sdk_changed |
SDK 版本已变，重算结果可能不同 |
config_missing |
缺少配置哈希，无法校验一致性 |
rows_skipped |
有无法解析的 CSV 行被跳过 |
回放界面
回放不再是一个独立窗口：ui/playback_dialog.py 已删除，拆成
replay.py::ReplayController（读盘 + 游标 + 深度重算）与 ui/replay_bar.py::ReplayBar
（录制选择 + 进度条 + 单位 + 提示），入口在「文件 → 打开录制目录…／回放最近一次录制」
与品牌轨的「历史回放」。布局与关闭流程见 docs/shell-lifecycle.md §2。
- 一个游标驱动三处：移动位置同时更新视频帧、深度面板与三张曲线的游标线；
并且通过
cursor_moved信号同步到主界面的曲线面板。 - 单位可切换（raw/N），数据直接来自录制目录的
forces.csv。 - 回放按录制实际有的单位打开：录制里
FN_N等列全空（没有标定）时退回 raw， 否则选 N 会画出三张空图；raw一定存在（那是设备测到的值）。 单位由ReplayController.set_unit一处决定，回放条、曲线与设置区下拉同时改。 - 数值卡读的是游标处的那一帧（
ForcePlotsPanel._readout_at_cursor）：浏览历史或回放 时，三个大数字是播放头所指的样本，而不是实时采集的最后一个样本 —— 否则一张 7.5e5 原始计数的曲线旁边会写着实时的0.0，看起来就像"回放根本没打开"。 实时视图仍是"最新样本就是游标"，所以跟随状态下不额外读盘。 - 帧未被写入视频时（记录队列曾溢出）明确提示，而不是显示上一帧冒充当前帧。
- 深度重算在守护线程上执行，UI 线程立即返回。实测
_on_recompute_depth返回耗时 0.001 s，而 SDK 调用仍在后台跑。
两个必须知晓的边界：
- SDK 打开视频逐帧步进可能长时间阻塞，且无法取消。因此用守护线程：窗口能关、 进程能退，但那个线程会一直挂到进程结束。用线程池（非守护）会让整个进程无法退出， 这是实测踩到的。
- 重算失败一律显示原因（SDK 不可用／未记录配置／配置路径不存在／无视频分段／ 帧不在视频中），绝不用其它图像顶替。
8. 长历史浏览：按需读盘而不是整段载入
record/index.py 的 RecordingIndex 是回放的数据源索引：
- 流式扫一遍
forces.csv，只把小东西留在内存：每行一个时间（float64）、一个 valid 标志、一个帧号，以及每CHECKPOINT_ROWS（4096）行的字节偏移。500k 行约 6.5 MB（SessionStore的默认上限正好对应 30 Hz 下约 4.6 小时）。 row_range(t0, t1)用二分定位行区间，read_rows(start, stop)先seek到最近的 检查点再向前扫描——读一个 10 秒区间就是 10 秒的解析量，不是整段。 区间会额外带上t0之前的那一行，绘制时才能画出跨过左边界的线段。overview(buckets)在同一次流式扫描里把每行折进所属桶，得到每桶每轴的 min/max/count。全程色带因此不会漏掉某桶里的尖峰（按行抽样会漏）。
ReadingReader 相应变化：
| 方法 | 作用 |
|---|---|
info() |
行数超过 max_rows（默认 200k）时给出降采样视图，并置 decimated=True；duration_s 始终取自帧索引，不取自视图 |
window(t0, t1, max_points=…) |
区间精确读取（可再降采样），尖峰按轴保留 |
overview(unit, buckets) |
全程包络，按 (unit, buckets) 缓存 |
statistics(t0, t1, unit) |
只算该区间的统计量 |
force/source.py 把两种来源统一成同一接口：StoreCurveSource（实时内存块）与
RecordingCurveSource（磁盘区间 + 缓存包络），都提供
extent() / window() / envelope() / statistics() / duration_s()；ForcePlotsPanel
只认这个接口，因此同一套浏览逻辑既能看内存会话也能看磁盘录制。
回放窗口在曲线被降采样时会明确写出「显示 N / 共 M 行」，而不是让操作员自己数点。
未做的验收项：真实分辨率与目标 ARM 板上的最大 RSS、积压与丢失测试（需要硬件）， 以及选中时间段的 CSV 导出。
9. 界面上的记录状态条
录制过程对操作员可见的部分，集中在顶栏状态行右侧的一个记录状态条
（apps/studio/src/orisys_studio/ui/record_status.py）。它回答按钮本身答不了的四个问题：
| 显示 | 判据 | 颜色令牌 |
|---|---|---|
尚未记录 |
本会话从未开始记录（recording.is_recording 与 last_report 都为空） |
status_idle |
记录中 mm:ss.d |
recording.is_recording；时长取自 recorder.stats().duration_s |
status_running |
正在写入… |
recording.report_pending：写入线程还没关完文件（不当成已完成） |
status_connecting |
上次记录 N 帧 |
已拿到终态报告且 failed/write_errors 为 0 |
status_idle |
写入异常（N） |
stats.failed 或 stats.write_errors > 0 |
status_error |
丢帧不是单独一行，而是追加在状态后面（丢帧 N），并把整条状态提到 warning 色；
N 是 dropped_data + dropped_video + dropped_gaps + unrecorded_gaps —— 只报前两个
队列溢出计数会低估真实损失。tooltip 里分项列出帧数、分段、时长、四类丢帧、写入错误、
最近一次错误与输出目录，因此状态条本身可以保持一行。
读数入口是 StudioMainWindow._record_stats()：它在 UI 线程上返回
(state, stats, directory)，是唯一读记录通道的地方。ExperimentRecorder.stats()
返回加锁快照，不会被写入线程阻塞；tools/ui_snapshot.py --scene recording 就是替换这
一个接缝来渲染「记录中」画面，既不写文件也不开设备。
刷新时机：_on_run_tick（16 ms 定时器）与每次状态跃迁（开始/停止记录、拿到终态报告、
阶段变化）。控件只在文本或颜色令牌真的变化时才 setText/setStyleSheet，因此 60 Hz
下不会反复重排顶栏。
10. 尚未完成（第三阶段及以后）
- PyOpenGL 三维显示（
mesh3d_panel.py目前仍是占位符，不是已有实现）。 - CSV 的「导出选中时间段」（整段导出已随录制落盘；区间导出待做）。
- 标定的稳定后采样（当前按固定时长采样，稳定性以 σ 呈现）。
- 在目标 ARM 板上用真实分辨率测长时录制的最大 RSS、队列积压与丢失。