orisys-app

Files

T

ykcheungab 7d1fca4c93 fix(studio-3d): 字段级来源与失效状态 —— 旧光流/算法失败不再冒充实时测量

- What:
  1. **采集侧声明每个派生数组的归属**（`acquisition/models.py`）：`SdkPacket` 新增
     `flow_valid/flow_frame_id/depth_valid/depth_frame_id/forces_valid`（`None` = 未声明）。两个真实
     生产者都填写：`finger_worker`/`sdk_worker` 逐帧记录"该数组实际算出来的 frame_id"，链失败时
     `*_valid=False` 并把上一次成功帧号带出来。光流与形变链分开判定（力读取失败不等于光流失败），
     但算法链失败时本帧的一切派生量都不可声明。
  2. **adapter 按声明收数据**（`scene3d/adapters.py`）：`_field_validity()` 三态——未声明 → 拒绝并报
     `field_unverified`（没声明就不算数）；声明为假 → `field_stale`（把 `invalid_reason` 带进诊断）；
    声明帧号不是本帧 → `field_stale`（两个帧号都写进 details）。`_intersect_device_mask` 换成
     `_device_mask`：设备 mask 形状不符**拒绝该帧**（`field_domain_mismatch`，两个形状都写进诊断），
     既不拉伸也不静默忽略。发布的帧带 `computed_frame_id`，身份一路带到显示侧。
  3. **契约**（`scene3d/contracts.py`）：`SceneState` 加 `"stale"`；诊断码加 `field_stale`/`field_unverified`
     （warning）；`SurfaceFieldFrame.computed_frame_id` 与 `RenderFrame.computed_frame_id`（由 composer
     原样透传）；`validate_surface_frame` 校验帧号非负且不晚于所属帧。新增 locale：
     `scene3d.state_stale`（中英各一条）。
  4. **协调器不再"边失败边报 live"**（`scene3d/coordinator.py`）：新增 `_stale_since` 宽限状态机与
     `note_field_failure()`——字段被拒、帧被判 invalid、compose 抛错、或合成结果的 `computed_frame_id`
     落后于本帧，都立即把状态改为 `stale` 并保留最后一帧；宽限（`stale_grace_s`，默认 1.0 s）到期后
     回参考模型并转 `no_data`；收到好帧即回 `live` 并清掉宽限。顺带修掉"等待首帧时每个 tick 都把参考
     模型重新 present 一次"（`_rest_presented`，16 ms 一次的无谓上传）。
  5. **诊断真正到达界面**（`scene3d/view.py`）：`submit_packet()` 在 adapter 拒绝时把
     `adapter.last_diagnostic` 交给 `note_field_failure()`；`tick()` 把协调器诊断的变化经已有
     `diagnosticRaised` 冒泡（协调器自身仍然零 Qt 依赖）。新增 `_snapshot_diagnostic()` 与 `_adapter`
     引用（后续"按能力禁用控件"也要问它）。
- Why: 审查报告 P1/R2：`FingerFrameAdapter.snapshot()` 从不读 `valid`/`stale_forces`/`invalid_reason`，
  只看到有限的 `flow` 就当作新数据上色（复现：`valid=False, stale_forces=True` + 有限 flow → 仍有有效
  着色点、diagnostic=None）；compose 抛错只写 `last_diagnostic`，画面与 `state` 保持不变；
  `snapshot()` 返回 None 时诊断无人读取；mask 域不符时静默忽略会扩大可信范围。力读数失败不该机械地
  判死三维，但算法失败也不能因为旧数组是有限值就当成新数据——所以按**字段级来源**处理，并让失效有
  明确的、可见的状态而不是继续保持 live。
- Verification:
  · `test_scene3d_adapters.py` 23 通过（+6 新增）：stale flow 被拒且带原因、未声明 flow → `field_unverified`、
  帧号不符 → `field_stale`（details 两个帧号）、新帧记录 `computed_frame_id`、box 侧"形变链失败仍用光流"、
  box 全部字段不可声明时拒绝；mask 域不符由"被忽略"改为"拒绝该帧"（原断言已改）。
  · `test_scene3d_coordinator.py` 30 通过（+6 新增）：落后帧号的合成结果永不上屏且状态 stale、
  字段被拒 → 宽限内保留画面/宽限后回参考模型/好帧回 live、compose 抛错不再保持 live、invalid 帧也计入
  宽限。
  · `test_scene3d_view.py`（+3 新增，offscreen 可跑）：adapter 拒绝 → 协调器 stale 且诊断经
  `diagnosticRaised` 回到面板、`scene3d.state_stale` 不是裸键；未声明字段 → `field_unverified`；
  新鲜字段照常上屏回到 live。
  · 全量：apps/studio 228 项 0 失败 14 跳过；shared 301 项 0 失败 1 跳过（`--junitxml` 计数）。
- Not in this change: `docs/architecture/studio-3d-contracts.pyi` 与新契约的同步放在阶段 6 的文档提交里
  一起做（本阶段契约改动较多，避免每提交改一次文档）；设备几何身份（R3）、资产加载请求号（R7）、
  二维后端统一、限速与真实统计均未动；真机上"链失败时 VRAW 是否也过期"这一条仍需实测（若证明链失败
  不影响 VRAW，`flow_valid` 放宽为只看读取结果是一行改动，已写进计划的风险项）。

2026-09-14 21:03:07 +08:00

config

fix(studio-3d): 字段级来源与失效状态 —— 旧光流/算法失败不再冒充实时测量

2026-09-14 21:03:07 +08:00

docs

删除深度重算引擎；修好回放视频每帧重开文件导致的无法播放，运输控制改到状态轨主按钮 - What: 1) 彻底删除深度重算引擎：shared/.../record/depth.py（DepthRecomputer/DepthResult）与 depth_backends.py（BoxReplay/FingerReplay）、其专属测试 test_depth_replay.py，record/__init__ 不再导出，playback.py::replay_warnings 不再报 depth_recomputed；apps/studio/replay.py 由 515 行瘦身为只做读盘+游标+视频帧+提示，回放视图的 2D 面板只提供「原始图像」；session.json 的 depth.replay 由 recompute 改为 none；删除 31 个只剩深度使用的文案键（depth_*/warn_state_*/warn_reset_*），warn_config_changed 与 warn_sdk_changed 改为描述"由视频重算"；ui_check 深度段、studio 两个深度用例、test_playback 三例、drive_shared 的 test_depth_replay 与 reproduce.py 的深度段一并清理（shared 套件 150→134 项）。2) 无法播放的根因是 RecordingReader.video_frame_at 每帧都 cv2.VideoCapture 重开并 seek：小片段已 ~10 ms/帧，1080p H.264 每次 seek 需从关键帧解码（上百 ms），而播放每 33 ms 要一帧且全在 UI 线程上，视频因此看着不动；改为按分段缓存解码器、顺序帧用 read() 步进（实测 10 ms → 0.5 ms/帧）、跳转才 seek，新增 RecordingReader.close() 释放。运输控制按用户建议上移到状态轨主按钮：toolbar.set_run_role("playback") 使回放视图的主按钮变成「▶ 回放」/「⏸ 暂停」（实时视图仍是「▶ 运行」），点按以 1× 推进游标（墙钟计时，漏拍不变慢）、到末尾自动停，拖动游标/框选/滚轮/拖总览条经 ForcePlotsPanel.timeline_taken_over 自动暂停，空格键同效；曲线表头不再放第二个播放按钮；按钮样式在回放角色下不再套用"停止"的红色语义。 - Why: 用户要求先清掉深度重算引擎、并反馈"现在无法播放视频"，建议把上方播放按钮在历史回放形式下改为回放。 - Verification: ui_check.py 554 项 0 失败（新增 seek<250ms/步进<60ms 的解码预算、回放按钮文字随播放/暂停切换、手动拖游标即暂停、切回实时视图按钮恢复运行、按深度视图已移除）；test_ui_smoke.py 71 项 0 失败；drive_shared.py 134 项 0 失败（深度引擎用例随代码删除）；locale_studio.py 262 键齐全、zh==en；reproduce.py 退出 0；.repro/probe_play.py 实测按「回放」后 0.75 s 内游标推进 0.689 s、面板 12/12 帧都在更新；两张复核图（回放视图的「▶ 回放」、实时视图的「▶ 运行」）。 - Not in this change: 录制文件格式与 CSV 列序不变（raw_*.mp4 与 forces.csv 继续一起写）；「由视频重算」复核模式保留（它复用实时管线，是有状态、只能顺序前进的一遍）。

2026-09-14 09:31:21 +08:00

src/orisys_studio

fix(studio-3d): 字段级来源与失效状态 —— 旧光流/算法失败不再冒充实时测量

2026-09-14 21:03:07 +08:00

tests

fix(studio-3d): 字段级来源与失效状态 —— 旧光流/算法失败不再冒充实时测量