 ykcheungab
|
c2293d4d41
|
界面：三维可选「深度响应 / 光流幅值」上色（默认深度），并加一个「诊断信息」开关收拾面板脚下的文字
- What（颜色来源）: `DisplaySettings` 增 `field`（`"depth"` 默认 / `"flow"`），随显示设置持久化
（`scene3d/prefs.py`：新增 `FIELD_CHOICES`/`DEFAULT_FIELD`，手改文件里的非法值修回默认）。
`FingerFrameAdapter` 按所选字段先试、失败再用另一个，并把"换了量"这件事记在
`last_substitution`（新诊断码 `field_substituted`，info 级）；两个字段都拿不到时，
`last_diagnostic` 取**信息量最大**的那条（域不符/过期/未声明 > 没这个字段），而不是"所选字段"的
那条空话。设置对话框新增「颜色来源」下拉，下面一行 `field_note` 直接写"这一帧画的是 X，不是所选的 Y"；
图例（`legend_label`）永远标注**实际**画出来的量，所以设定与画面不一致时两处都能看出来。
深度响应 `[1]`、光流幅值 `[px]`，两者都是 `approximate`——代码与文案都不把它们说成毫米。
- What（诊断信息开关）: 视图菜单新增 `诊断信息`（可勾选、持久化 `show_diagnostics`、**默认关**，
由 `DisplayPrefsController` 持有并推给两个面板）。关掉后：2D 面板只留"画面 + 计划说明 + 深度色标"，
三条解释流水线的标签（箭头按位移放大、原始图像 → 算法输出、全部帧）隐藏；3D 面板只留
色条 + 一行图例 + 来源，info 级诊断隐藏。**永不隐藏**：warning/error 级诊断（测量是否过期、
字段是否本帧的、是否与设备核对过——`geometry_unverified` 虽然是 info 也白名单保留）与
深度色标。3D 图例改成 `ShrinkableLabel`（一行、裁切 + tooltip，不再折行），色标数值从 4 位有效数字
收到 3 位（"0.0334 – 0.899"）。设置对话框控件宽度 88 → 108 px（不再需要迁就 240 px 面板）。
- What（取景脚本）: `tools/ui_snapshot.py --scene flow3d` 现在同时给 flow 与 depth（各带 provenance），
所以「颜色来源」开关有东西可切；再加 `.repro/shot_variants.py` 一次出四张图
（深度版 / 光流版 / 诊断开 / 设置对话框）。
- What（测试）: `test_scene3d_adapters.py` 增 3 项（默认深度、换量时给出 `field_substituted` 并在恢复后
清掉、depth 不在场景栅格时按 `field_domain_mismatch` 拒绝而不是缩放）；`test_scene3d_view.py` 增
1 项（field 的持久化与修复，并把 `field in FIELD_CHOICES` 加进"手改文件会被修复"的参数化）；
`test_scene3d_pane_ui.py` 增 3 项（两种量可选 + 说明行 + 恢复的偏好会移动下拉；诊断开关只隐藏 info、
保留 warning 与"未核对"；2D 脚注三标签的显隐与窗口开关一致）；`test_display_prefs.py` 增 1 项
（开关推到两个面板、写偏好）。`test_ui_smoke.py` 与 `tools/ui_check.py` 里"箭头图例可见"的四条断言
改为按新规则检查（默认隐藏、开诊断后可见、关掉再隐藏）。
- Why: ①"深度"比"光流"更贴近操作员口中的"压得多深"，但两者都只是近似量，所以做成开关而不是替换——
并且换量必须说出来（否则画面会被读成所选的量）。②面板脚下的解释文字是"内部管线"而不是"画面是什么"，
拍视频与日常看都只需要后者；用一个开关收起，比做一个滚动日志面板诚实（这些是每帧状态，不是事件）。
- Verification: pytest shared/tests apps/studio/tests（offscreen）658 passed / 0 failed / 15 skipped；
真 GL 组（gl_smoke + view + pane_ui）70 passed / 0 failed / 1 skipped；
`tools/ui_check.py` 590 项检查 0 失败；`.repro/locale_check.py` 0 缺失（新增 7 个 key 双语齐备）。
目视验收：同一批合成数据渲染的四张图（深色主题）——深度版（默认）、光流版、诊断打开、设置对话框。
- Not in this change: 不改采集/记录/契约之外的三维渲染；不做页签容器与窄窗口回退；曲线量程仍是出厂 ±20 N。
真机待验证：手指路径上 `packet.depth` 的栅格是否就是场景的 300×280（若不是，面板会写明并回退到光流）。
|
2026-09-15 21:23:18 +08:00 |
|
|
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 |
|
|
ykcheungab
|
ac4dcd643f
|
feat(studio): 三维视图接入产品（阶段 4：界面、生命周期与记录隔离）
- What: `Scene3DView` 装配（widget/相机/渲染器/合成器/协调器/适配器），`asset_source`
只查找并后台加载已编译的 `.oryscene` 包，`scene3d/prefs` 持久化并**修复**显示设置，
`ui/mesh3d_panel` 用真实容器替换占位标签（无 GL/无包/包被拒/传感器不匹配各显示一行原因），
`main.py` 在 `QApplication` 之前选定 GL profile，`app_window` 接线：3D 作为采集线程上的
第二个 sink、`_on_run_tick` 驱动 `tick()`、视图切换与 `closeEvent` 释放、preferences 落盘。
- Why: 阶段 4 的验收要求"三维开关不影响采集/记录/力曲线"，并把阶段 1 留下的
"开/关三维 CSV 一致"这条补上；同时把"没有 context"从"看起来像在工作"变成可显示的终态。
- Verification: app 侧 test_scene3d_view 28 项、test_scene3d_gl_smoke 14 项（真实 GPU）、
adapters 17 项、skeleton 4 项、stage1 24 项、coordinator 13 项、ui_smoke 86 项；
shared 侧 contract 26 / assets 33 / package 19 / live 25；`ui_check.py` 566 项检查 0 失败
（新增 "3D pane" 段 12 项）；`locale_check.py` 302 个字面 key 0 缺失、中英各 377 key 对齐；
记录隔离：同一 96 帧会话挂/不挂 3D 消费者，`forces.csv` 逐字节相同、有效样本数与记录问题数相同；
生产者预算：合成器放慢到 50 ms 时 `submit_packet` p99 < 1 ms。
- Not in this change: 示意位移（`displacement_sensor_m`）仍未接入（需 SDK lift 与已确认尺度）；
ARM 板卡适配（按用户要求暂缓）；包签名/AES-GCM 与长时性能报告（阶段 5）；
仓库中仍未提供 `.oryscene` 包（发布产物，且其单位与变换必须由人声明）。
|
2026-09-14 15:47:32 +08:00 |
|
|
ykcheungab
|
ea1027e5a6
|
阶段 3：实时数据 —— 采样、合成、最新帧调度与适配器 - What: sampling.py 实现 SurfaceSampler（向量化四点双线性：无效 tap 不计入也不致无效、任一**正权** tap 无效即整顶点无效且值为 NaN、域/形状不符先拒；采样表只在加载时构建）与 remap_to_domain（按 unroll 映射 gather，空洞保持 NaN 且 valid=False，保留尾随轴以支持矢量场）。composer.py 实现 SceneComposer.compose（域校验 → 采样 → 位移 → **从形变后位置重算法线**；scalar 绝不成以 display_gain；approximate 位移产生 display_illustrative(info) 诊断、calibrated 不产生、无位移则着色并报 field_unavailable）与 build_rest_frame（参考帧：scalar 全 NaN、valid 全假、descriptor=unavailable/display_only），gl_backend.rest_surface 改为委托它，避免两处定义。coordinator.py 实现完整调度：容量 1 双 mailbox、generation/来源/会话三重过期拒绝并计数、**最多一次合成在飞行**、可见性挂起/恢复、设置变更（倍率变化重合成**屏幕上那一帧**）、close 幂等；submit 只做身份与形状的廉价校验，绝不等显示。adapters.py 实现 Finger/Box 适配器：|flow| 或 depth 响应、可选经 unroll 映射 remap、设备 valid_mask 优先、域不符时**发布空**并报出所见的两个形状；一律不造位移（未标定的毫米不如没有），并新增 display_illustrative 到诊断码表（info）。assets.py 从"桩类堆"改成门面：re-export 真正实现 + SceneCompiler.compile（外壳 GLB 与预算检查；加密请求明确拒绝并指向阶段 5）。测试：shared/tests/test_scene3d_live.py 25 项（采样/无效语义/倍率只影响位置/示意形变标注/法线重算/remap 空洞/参考帧/只读数组）、apps/studio/tests/test_scene3d_coordinator.py 13 项（状态机、过期、替换计数、单飞行、submit p99<1ms、切换场景丢弃在飞结果、隐藏挂起、倍率重合成、close 幂等）、test_scene3d_adapters.py 13 项；并把三处"桩仍未实现"的过时断言改成对已实现行为的断言。docs/architecture/studio-3d-stages.md 阶段 3 记为完成。 - Why: 阶段 3 决定"屏幕上的颜色和力值到底对应什么"。三条最容易错且肉眼看不出来的规则必须由代码而不是约定来保证：无效点不是 0（NaN 与 valid 分离，否则缺口会被画成一个测量值）、显示倍率只动位置不动测量（否则色标悄悄变了含义）、以及显示永远不能给采集施加背压（容量 1 mailbox + 单飞行合成 + 廉价 submit）。 - Verification: shared 全量通过（scene3d 相关 103 项：contracts 26、assets 33、package 19、live 25）；studio 全量通过（scene3d 相关 54 项：stage1 24、skeleton 4、coordinator 13、adapters 13；GL 冒烟 10 项在真实 context 下另行通过）；ui_check 554 项 0 失败。过程中修掉 3 个真实缺陷：倍率变化时用 incoming.peek() 取不到"屏幕上那一帧"（已被消费）导致改了倍率画面不动——改为保留 _last_field_frame；display_illustrative 不在码表里被默认成 error；assets.py 里与 package/legacy 同名的重复桩类（会误导集成者，已改为门面）。另修正两处我自己的错误断言（对称凸起顶点法线本就竖直；pytest.approx 不能直接 .all()）。 - Not in this change: 手势与面板（阶段 4）；示意位移的真实来源（需要 SDK lift + 已确认尺度，现阶段 adapter 一��� displacement=None）；app_window 接线与记录隔离（阶段 4）。
|
2026-09-14 15:21:39 +08:00 |
|