ef487098c9756e265b9529914c7fffa44d23143b
5 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 ykcheungab
|
ef487098c9 |
feat(studio-3d): 限速、真实耗时统计、无位移复用资产几何，以及保护包密钥注入（阶段 9 上半）
- What:
1. **显示限速真的生效**（R5）：`ThreeDCoordinator.tick()` 用注入的单调时钟与
`display_period_s() = 1/max_fps` 限制**合成启动**频率（窗口定时器仍是 16 ms，但"显示帧率"是给操作者的
承诺，不是定时器的描述）；声明边界（activate/begin_session/show_rest/隐藏）把预算清零，所以按下开始后的
第一帧立刻合成。生产者侧改为**按需**跳过：`Scene3DView.submit_packet()` 在
`coordinator.has_pending_frame()`（mailbox 里已有一帧等待）时不再构造快照——那是 O(H×W) 的拷贝，
而 mailbox 只保留最新一帧，两次拷贝里必然丢一个；被跳过的数量计入新的 `skipped_producer`，
与"显示跳帧"分开。**不丢任何本该显示的帧**（等待中的那一帧仍在）。
2. **真实统计**：`RenderFrame.compose_ms`（composer 在构造帧之前测量并写入，不再读会被下一任务改写的
`last_stats`）；`GLRenderer` 的绘制计数改名为 `paint_calls`，`RenderStats.displayed_frames` 由
**widget 按帧身份**统计（相机旋转/色标改动只是重画，不再是"多显示了一帧"）；`render_totals()` 增
`compose_ms`/`latency_ms`（合成开始→被接受的单调耗时）/`paint_calls`/`skipped_producer`，并且
`shown`/`compose_ms` 改从 widget 读（无 GL 的机器也能报告，之前只有画过才有数）。
3. **无位移时复用资产几何**（R5 建议）：`SceneComposer` 缓存 `asset_hash → (positions, normals)`；
变形时照旧从形变后的位置重算法线，不变形时直接用资产自己的（只读、零拷贝）数组。20k 顶点实测：
compose p50 **6.15 ms → 1.03 ms**（法线段 4.9 ms → 0.0001 ms，剩余是采样 1.01 ms）；
真实发布包（1032 顶点）compose p50 **0.50 ms → 0.17 ms**。
4. **保护包密钥注入**（R4）：新增 `scene3d/keys.py`——从 preference 读取
`scene3d_verify_key`（验签公钥 PEM）/`scene3d_content_key_file` + `scene3d_content_key_id`
（内容密钥，经 `protect.load_key_file`）/`scene3d_require_signature`（发布模式，拒绝无签名包），
组装成 `SceneKeys` 交给 `SceneAssetLoader` → `load_package` → `PackagedAssetLoader.load(keys=…,
verify_key_pem=…)`；`AppWindow._sync_3d_source()` 解析它并 `Mesh3dPanel.set_keys()`。
缺失/不可读的密钥是**状态而不是崩溃**（`describe()` 里带原因），密钥材料永不进日志；
`Mesh3dPanel.describe()` 的 scene 块记录 `keys`（布尔 + 路径）。
- Why: 审查报告 R5（`max_fps` 只被存储与显示、`draw()` 硬编码 `compose_ms=0.0`、`_displayed_frames` 把
重画也算新帧、`SceneComposer.last_stats` 被显示链路完全未读）与 R4（底层支持签名/加密包，Studio 加载
入口却从不传验签公钥与 KeyProvider，合法保护包打不开，只能发明文包或关掉校验）。R5 的另一半是
"当前只有曲面着色、没有 displacement 时，composer 仍每帧重算法线并重新打包位置"——缓存后 20k 顶点
降低到六分之一。
- Verification:
· `test_scene3d_coordinator.py` +6：15 fps 的假时钟下 1.32 s 内只启动约 20 次合成（60 fps 对照 ≥55 次）、
`display_period_s()` 跟随设置、结果延迟是真实单调差值、`has_pending_frame()` 随 mailbox 变化；
`test_scene3d_live.py` +3：无位移时发布帧直接**就是**资产自己的（只读）数组、force_deform 但仍无位移时
给出 `field_unavailable` 诊断、有标定位移时仍重算、`compose_ms` 属于该帧且不被下一次合成改写；
`test_scene3d_view.py` +2：等待中的帧让生产者跳过第二个快照且取出后立即恢复、`render_totals()` 的
compose 成本与延迟是真实值；新增 `test_scene3d_protected_package.py` 7 项：Studio 入口打开签名包、
用 preference 里的内容密钥打开加密包、缺验签公钥 → `asset_auth_failed`、密钥文件缺失/无 key id →
状态而非崩溃、发布模式拒绝无签名包而开发模式接受、`SceneAssetLoader` 把密钥交给 worker、面板携带密钥。
· 全量：shared+apps 同一次运行 **588 项 0 失败 15 跳过**；真 GL 冒烟（`QT_QPA_PLATFORM=windows`）
**14 项 0 失败**；ui_check 587 项 0 失败；locale_check 0 缺失。
· 顺带修掉两个**既有的顺序依赖**真 GL 用例（不是本次引入：在上一提交上单跑同样失败）：
`test_the_producer_side_never_waits_for_the_gpu` 的收尾没有排空 mailbox（留下的一帧会被下一个测试
上传），`test_an_automatic_colour_scale_follows_the_frame` 在渲染之前就断言"范围来自本帧"，
且用"不同颜色数"当自动量程的代理（对可见面积敏感）。现在前者排空并断言排空完成，后者先渲染再断言，
判据改为**平均亮度**（固定 0..1000 把 3..7 压进 LUT 最暗的一小段，自动量程铺满整条色带）。
· 性能报告（`.repro/perf-cpu-*-after-9.json`，`bench_scene.py --cpu-only`）：合成 p50
合成 poc 0.016 ms / 20k 顶点 1.03 ms / 真实包 0.17 ms；对比已提交的 `perf-report-windows-dev.json`
（20k 6.15 ms、真实包 0.50 ms）。
- Not in this change: **画布布局第二批**（2D/3D 页签容器、参数抽屉、窄窗口回退、诊断抽屉）与曲线量程开关
仍未做；阶段 9 的门禁部分（`soak_scene.py --minutes 120` GUI 模式、Jetson Orin Nano 与 QCS6490 上的
`probe_gl/bench_scene/soak_scene` 报告）需要长时间运行与板卡，本轮未跑，结论不写"通过"；
签名私钥仍只在构建机（本提交只引入"读"的一半）。
|
||
|
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` 放宽为只看读取结果是一行改动，已写进计划的风险项）。
|
||
|
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` 包（发布产物，且其单位与变换必须由人声明）。 |
||
|
ykcheungab
|
cad795c890 | 补阶段 1 的失败样例：软件渲染被拒、着色器编译失败只降级三维 - What: test_scene3d_gl_smoke.py 增加两项失败样例。其一：把 is_software_renderer 打桩为真后调用 GLDispatch.bind_current_context，断言抛 ThreeDUnsupported、诊断码为 gl_unsupported、且异常带回的 GLCapabilities 明确标着 software_renderer=True（板卡不得在软件光栅器上签收）。其二：把 shader_source 打桩成非法 GLSL，断言 GLRenderer.initialize 抛 diagnostic.code=shader_compile_failed 且 is_initialized 保持假；再用一个 initialize 必然失败的 renderer 构造真实 widget（走公开 API：show/repaint/processEvents），断言视图进入 unavailable、诊断已发出、第二次 repaint 是空操作而不是异常——即三维失败只降级自己，不影响应用。 - Why: 规格 §13 要求每阶段交付含失败样例；阶段 1 的两个失败路径（GL 不足、shader 编译失败）此前只有实现没有验收，而这两条恰恰是板上最可能遇到的情况。 - Verification: 真实 context 下 tests/test_scene3d_gl_smoke.py 10 项全过（原 8 + 新 2）；offscreen 下该文件按设计 skip；shared 全量 187 passed、studio 全量 118 passed、ui_check 554 项 0 失败。 - Not in this change: 未改实现（这一版只是把已有失败路径钉进测试）。 | ||
|
ykcheungab
|
5767b4bf11 | 阶段 1：平台 PoC —— 真实 GL 上跑通静态场景，并修掉它抓出的相机/上下文错误 - What: 按 docs/architecture/studio-3d-stages.md 阶段 1 落地图形栈。OrbitCamera 全部实现（target/distance/yaw/pitch 表示；fit 按包围球与较窄的那个视场轴定距离；orbit/pan/zoom 有界；set_preset 从 eye/target 反解角度使拖动可延续；matrices 输出只读 float32 view/projection；另加 depth_range_m() 便于断言）。gl_backend：GLDispatch.bind_current_context 真正绑定 PyOpenGL 并读 vendor/renderer/GL/GLSL/max texture、判软件渲染、profile 不达标时抛 ThreeDUnsupported 并带回能力；GLRenderer 实现 initialize（两个 program，desktop33/gles30 共用同一份着色器主体、只换头部）、upload_scene（每 part 一套 VAO/VBO/EBO，交错 layout position/normal/scalar/valid = 8 float）、update_surface（只对感知面 glBufferSubData，绝不重建索引）、draw（绑 Qt 的 defaultFramebufferObject、深度测试、按 role 选 program、housing 隐藏即跳过、scalar 经 LUT 纹理与 range uniform 上色，Python 不生成 RGB 数组）、release（幂等）；纯函数 pack_part/pack_scene_part/estimate_gpu_bytes/rest_surface/shader_source/shader_header/lut_rgba/is_software_renderer/profile_from_renderable_type 都可在无 GPU 环境测试。Sensor3DWidget 实现 initializeGL/paintGL/resizeGL/release_resources/aboutToBeDestroyed/showEvent/hideEvent 与鼠标事件；加载场景时先采用资产自带的默认视角再 fit；一帧几何不匹配只"拒绝该帧"（计数 + 诊断 + 用 rest_surface 清掉上次测量）而不是把整个视图打成不可用。shared/scene3d/synthetic.py 提供 PoC 与测试共用的已知场景（20mm 感知板 + 外壳盒，米、sensor 坐标系、带默认三视角预设）。tools/scene_assets/probe_gl.py 真实现：真实窗口取 context 并输出 JSON 报告（平台/Qt/PyOpenGL/vendor/renderer/GL/GLSL/DPR/framebuffer/是否软件渲染），退出码即门禁（0 通过、3 软件渲染、4 无上下文）；apps/studio/pyproject.toml 增加 [three-d] 可选依赖（仅 PyOpenGL；Open3D 不进运行时）。测试：apps/studio/tests/test_scene3d_stage1.py 24 项（相机数学、PoC 场景合规、打包布局、着色器两方言共用主体、LUT、软件渲染识别、renderableType 映射、GPU 预算、参考帧语义，全部无需 GPU）＋ test_scene3d_gl_smoke.py 8 项（真实 context：能力、两个 part 都画出来、外壳可隐藏、参考帧中性 vs 色图有差异、动态更新不动 housing 缓冲、坏几何帧被拒且视图存活、resize 跟随、release 幂等且新 context 能重传场景、探针如实报告）；offscreen 下后者自动 skip。docs/architecture/gl-report-windows-dev.json 为本机平台报告。 - Why: 用户要求"从骨架搭起→计划阶段→逐阶段实现与验收"，并明确 ARM 暂缓。阶段 1 的产出本身就是一份能回答"这块板的图形栈能不能用"的报告，所以先把它做实、把 profile 冻结点定在真实 context 上，而不是先堆屏幕上的东西。 - Verification: 真实 context（QT_QPA_PLATFORM=windows）下 8 项 GL 验收全过；offscreen 下 24 项 CPU 项全过、GL 项按设计 skip；shared 全量 187 passed；studio 全量 116 passed（含新 32 项）；ui_check 554 项 0 失败；probe_gl 输出 verdict=ok（NVIDIA RTX 4080 SUPER、GL 3.3 Core、GLSL 3.30、非软件渲染）。过程中这套验收抓出并修掉了 7 个真实缺陷：Qt renderableType 映射反了（NVIDIA 兼容 ES 着色器所以本机看不出，Intel/ARM 会直接失败）、观察相机是左手基导致整模型镜像（det=-1）、近平面过近使 NDC z 全挤在 0.99（深度精度归零、外壳与感知面会 z-fighting）、手动 makeCurrent 早于 Qt 首次绘制会把 GPU 对象建在被丢弃的 context 里（glBindVertexArray 报 INVALID_OPERATION）、context 重建后不重传场景、一帧几何不匹配把整个视图打死、以及 grabFramebuffer 是 BGRA+stride 导致颜色断言全部读错通道。 - Not in this change: 未接入 app_window/main.py（三维对现有应用仍完全惰性，故"开/关三维 CSV 行序一致"这条验收随阶段 4 做）；阶段 2 的资产导入/坐标/包格式；ARM 平台实测（probe 已可在板上直接运行）。 |