c2671e5c2f0fca3b0d9a9d9aac36b1d23c984d2d
2 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
|
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）。 |