 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
|
c9a28e7c3a
|
fix(studio-3d): 审计三维改动 —— 修「第一个会话之后画面永久冻结」，并把面板/视图接口显式化
- What:
1. **会话代际（真 bug）**：`ThreeDCoordinator.begin_session()` 新增——新采集会话开始时要显式宣告
（清掉已锁定的 session_id、generation+1、清空 mailbox、把参考模型放回屏幕）；`Scene3DView.begin_session()`、
`Mesh3dPanel.begin_session()` 转发，`app_window._start_run()` 在启动 worker 后调用。
另外 `submit()` 在"会话不符"时不再只计数，也给出 `stale_frame` 诊断（信息级），否则界面只是"不动"。
2. **接口显式化（可维护性）**：`Mesh3dPanel.attach_view()` 成为唯一装配入口（真实视图与测试替身都走它，
测试不再写 `_view`）；`_view` 类型改为 `Optional["Scene3DView"]`（TYPE_CHECKING 导入，保持 GL 惰性）；
容器里 7 处 `hasattr(...)` 鸭子调用改为直接调用（方法改名会立刻报错，而不是静默不生效）；
`Scene3DView.describe()`/`render_totals()` 与 `Mesh3dPanel.describe()`/`render_totals()` 让面板自己回答
"我是什么"——`app_window` 里那段走 5 个属性路径拼 `visualization3d` 的代码缩成一次调用 + 一个 try；
`scene3d/panel.py` 对 coordinator/widget 的导入移到 TYPE_CHECKING；`scene3d/__init__.py` 写上各模块职责图
（原文还写着"应用尚未导入本包"）。
- Why: 用户要求全面回顾三维改动并按"实时/回放/接口清晰/性能"四条检查 bug。审计确实抓到一个严重缺陷：
协调器记住第一个会话的 session_id 后，**之后每个会话的每一帧都被判为 stale 而拒绝**（实测 session 1 正常、
session 2 stale=3 且 0 帧上屏），而状态仍显示 live —— 表现为"第一次运行之后三维就再也不动了"。
这是"回放不太行"的直接原因之一（回放里的重算通道就是第二个会话）。顺带把"面板↔窗口"的隐式耦合收紧。
- Verification:
· 回归用例：`test_scene3d_coordinator.py` +2（新会话在宣告前 stale 且带诊断、宣告后接受并回到 live；
`begin_session` 在无场景/已关闭时安全）、`test_scene3d_view.py` +1（每次 _start_run 代际递增、第二个会话的帧被接受）。
· 实测（真 GPU，apps/studio 配置里那个包）：`audit_live_path.py` —— 三个连续会话 state=live、stale=0、
每次都有 26260 个非背景像素、descriptor=flow_magnitude；
`audit_replay_path.py` —— 回放时间轴正常（1.97 s 记录，播放 0.6 s 后位置 0.60 s，2D 有图，停止按钮生效，
面板标签"回放：录像不含三维场"），随后**真实重算通道**跑完（59 个样本、2.6 s、正常报"视频已结束"），
三维面板进入 state=live（62 帧上屏、2 帧显示丢弃、stale=0），标签切到"重算通道：由录像重算，非记录值"。
· 性能（真 GPU，shipped 包）：submit p50 0.26 / p95 0.38 ms，upload p50 0.18 ms，paint p50 0.90 ms，
latency p50 33.08 ms（= 30 fps 上限）；20k 顶点 CPU-only compose p50 5.97 ms（与已提交报告的 6.15 ms 一致）。
· apps/studio 全量通过；ui_check 583 项 0 失败（连跑两次）；locale_check 0 缺失。
· 修掉 ui_check 自身一处错误断言：场景已加载但本机无 GL context 时，面板显示"无法创建 context"是**正确**行为，
原断言却要求"不显示任何消息"（偶发失败的原因就是它，与产品无关）。
- Not in this change: 测试里仍直接读 `view._camera`/`widget._renderer`/`coordinator._composer` 等私有量（测试替身已收敛到
`attach_view`，其余留待需要时再抽）；`update_surface` 里每帧重算色标范围（`_valid_scalar_range`）可以做条件化，
实测开销很小故未动；SDK 对极小合成视频的解码问题（640×480 mp4v）——现在会 10 秒后明确报错而不是空转。
|
2026-09-14 19:58:33 +08:00 |
|
|
ykcheungab
|
981c250559
|
feat(studio-3d): 历史回放里的三维面板 —— 由「重算」通道喂它，并标注来源
- What: `VIEW_SHOWS_3D` 加入 `replay`；`app_window` 新增 `_shows_3d()`（可见性与布局共用一个判据）
与 `_splitter_sizes_for()`（预设表里的 3D 槽是"二维布局"的描述，面板打开时从最宽的面板借
`DEFAULT_3D_PANE_WIDTH=340`）；`ThreeDPanel` 新增第三个来源标签（实时采集 / 回放：录像不含三维场 /
重算通道：由录像重算，非记录值）与 `set_source_kind()`；`ThreeDCoordinator.show_rest()` 把参考模型
放回屏幕并停止主张测量值（重算停止时调用，否则最后一帧会留在屏幕上）；`Mesh3dPanel` 转发这两者，
并新增"加载中"状态的修正：切换传感器再切回来时若该包已加载，直接显示已就绪的画面而不是一条永远
不会被替换的"正在加载"。
- Why: 录像里没有三维场（raw_*.mp4 是原始相机图像，`depth.stored=false`，CSV 只有力值），所以纯回放只能
显示参考模型；但「从视频重算力值」本来就把同一个运行路径指向录像的原始视频，而采集线程上的三维 sink
早已注册——因此重算一开始面板就会收到真实的形变帧。这两件事必须由界面区分：一个是"没有测量"，
一个是"当前算法对这段录像会说什么"，把后者当成记录值展示就是另一种 `display_illustrative`。
- Verification: apps/studio 全量通过（test_scene3d_view.py 32 项，含"回放里面板可见且标注正确""重算时
标注切换""停止重算后清回参考模型""实时视图标为实时"；test_scene3d_coordinator.py 15 项，含 show_rest
与"停止时在飞的帧不会随后被显示"）；ui_check 570 项 0 失败（新增"已安装包必须被加载并标注来源"）；
locale_check 0 缺失；仓库内工程包经 validate_scene 全部 ok。
- Not in this change: 逐帧保存展开场/深度（记录格式变更，设计文档明确否掉）；重算通道本身（已存在，本次
只是把它的帧接到面板上）；示意位移（仍需 SDK lift + 已确认尺度）。
|
2026-09-14 17:13:37 +08:00 |
|
|
ykcheungab
|
5cd92254e1
|
feat(studio-3d): 阶段 5 —— 发布保护（签名/可选加密/平台锁定）与性能长时报告
- What: 新增 `scene3d/protect.py`（封套 v2：Ed25519 签名 + 可选 AES-256-GCM，nonce/salt 每包唯一、
元数据作 AAD、明文摘要进签名、KeyProvider 只问 get_content_key）与 `record/visualization3d.py`
（session.json 的 visualization3d 块：写入版本化、读取时缺块=不支持）；`package.py` 支持 v2
（payload=plain 仅签名 / aes-gcm 签名+加密）并继续读 v1，新增解压比上限与"写入后自读回"校验；
`contracts.py` 新增 PlatformLock/PlatformInfo/check_platform_lock、Sealing、platform_mismatch 诊断码；
`Scene3DView` 在装配前查 OS/架构、拿到 capabilities 后查图形半区，违反即撤下场景并在面板显示原因；
工具 `compile_scene.py` 新增 --sign-key/--write-verify-key/--encrypt-key-id/--key-file/--lock-from-probe，
`validate_scene.py` 新增 --key-file/--key-id/--verify-key/--require-signature（发布门禁），
新增 `bench_scene.py`（p50/p95 分阶段 + --cpu-only + --vertices N + --package）与
`soak_scene.py`（RSS 四分位速率 + 队列上界 + 抽稀采样）；两份报告落到 docs/architecture/。
- Why: 规格 §5.2 的保护目标是"提高复制成本"而不是"防提取"，所以要的是签名（来源）+ 可选认证加密（机密性）
+ 密钥隔离，而不是自制加密或把 ZIP 当加密；§12 的"包保护/性能/长时"三行需要可复现的数字与判定标准，
而不是一次性的观感。平台锁定还必须只降级三维：锁定不通过时二维照常。
- Verification: shared 全量通过（新增 test_scene3d_protect.py 35 项：封套往返/篡改/密钥/锁定/记录块/
compile→validate 端到端发布流程；test_scene3d_package.py 20 项含 v1↔v2 兼容）；apps/studio 全量通过
（test_scene3d_view.py 30 项含锁定拒绝与 session.json 块）；ui_check 566 项 0 失败；locale_check 0 缺失；
真实资产端到端：1032 顶点编译出 signed+sealed+locked 包（56 927 B 密文），validate --require-signature 退出 0，
改一个字节退出 2；性能报告（perf-report-windows-dev.json）：1032 顶点 compose p50 0.50 ms（30 fps 上限内），
20022 顶点/39480 三角形 compose p50 6.15 ms（约 33 ms 帧的 18%），采集线程 submit p95 < 0.4 ms（合成器被人为放慢到 50 ms）；
长时报告（soak-report-windows-dev.json）：无窗口 10 min/60 fps 尾段 0.354 MB/min，GUI 4 min/30 fps 尾段 0.809 MB/min，
队列上界（mailbox=1、单飞行合成）两者均成立。过程中修掉：GUI 进程里的合成器计时被 GIL/vsync 污染（98.8 ms vs 真值 6.1 ms）、
跨线程读 last_stats 撕裂、key id 无 provider 时会静默写明文包、soak 工具自身记时间列表会无界增长、RSS 读取失败伪装成零增长、
平台锁定不是终态诊断。
- Not in this change: ARM 板卡的能力报告与 2 小时门禁运行（按用户要求暂缓；命令与判定标准已写入阶段 5 文档）；
GPU 显存随时间的测量（无可移植 API，报告说明渲染器缓冲估计恒定且更新路径不新建 GPU 对象）；
`cryptography` 在此环境无法联网安装，本机验收用的是本机已有的 cp310 构建（pyproject 里已声明为可选 extra
`protected-assets`）。
|
2026-09-14 16:44:33 +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 |
|