3daee6d40753319da921983d16c88396412d5a1f
12 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 ykcheungab
|
ccedb9ddd9 | migrate pyqt5 to pyside6 | ||
|
ykcheungab
|
e276b5de0f | autocal layout first design | ||
|
ykcheungab
|
c538dbf074 | fixed label under 3d view | ||
|
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（若不是，面板会写明并回退到光流）。 |
||
|
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
|
e2570925e8 |
feat(studio-3d): 能力控件、真实色标与复位语义 —— 只提供数据源真正喂得出来的控制（阶段 8 第一批）
- What:
1. **能力声明**：`contracts.SceneCapabilities`（quantity/unit/displacement_available/
displacement_quality/source_kind）；两个适配器都声明 `displacement_available = False`（它们只把标量
画在表面上，从不发布位移）；`Scene3DView.capabilities()` 从**实际绑定的适配器**读出并推给面板。
`ThreeDPanel.set_capabilities()` 因此把"放大形变"/增益置灰并给出原因（新键 `scene3d.deform_unavailable`），
`settings()` 在能力缺失时**强制** `deform_enabled=False`（否则持久化的增益会悄悄作用在没有东西可放大的源上）；
禁用状态在 `set_enabled`/`apply_settings` 之后仍然成立（原来 `apply_settings` 只按复选框状态使能增益）。
2. **真实色标**：`GLRenderer` 记录并暴露本次绘制**真正使用的**上下限与模式（`effective_scale()`），
写进 `RenderStats.scale_lower/scale_upper/scale_mode`；`_scalar_range` 在 `release()` 与
`upload_scene()` 重置（原来换场景/重建 context 后首个自动范围沿用旧场景）；面板新增 `ColorScaleBar`
（用 `gl_backend.lut_rgba` 的同一张 256×1 表绘制），图例改为
`{quantity} [{unit}] · {自动|固定}色标 {lower} – {upper} · {quality}`（新键 `scene3d.legend_effective`/
`legend_auto`/`legend_fixed`），自动模式下不再让被禁用的输入框冒充"当前范围"。
3. **文案**：`scene3d.quantity_flow_magnitude`="光流幅值"/`quantity_depth_response`，preset "default" 显示为
"默认视角"（数据仍是资产里的真名），`scene3d.stats` 的"丢弃"改为"显示跳帧"（与录像丢帧区分）。
4. **复位语义**：`Scene3DView.reset_view()` 改为回到**资产自己的默认视角**（`camera_presets[0]`），
与首次显示一致；只有在没有 preset 时才退回 `OrbitCamera.reset()`。原来它把 yaw/pitch 清零并 refit，
与首帧呈现的 preset 视角不是同一个画面。
5. `describe()` 记录 `capabilities`（含 `displacement_available`）与 `effective_scale`（实际上下限与模式），
这样一条录像能说明"当时的颜色代表什么"，而不是只留下操作者输入框里的数字。
- Why: 审查报告 R6：`FingerFrameAdapter` 只输出光流幅值、`displacement_sensor_m` 始终为 None，而面板仍允许
"放大形变"和 0×..500×——用户能操作一个没有真实输入的功能；自动色标每帧按实际范围变化，但面板范围输入框
仍是保存的 0..1，没有把颜色和数值联系起来的图例；`reset_view()` 与首次显示用的资产 preset 语义不一致。
报告明确要求"由 SceneCapabilities / 当前 FieldDescriptor 控制控件可用性""新增独立 effective_scale 输出"
"复位也应统一语义"。
- Verification:
· `test_scene3d_view.py` +3：无位移源 → 形变控件禁用且带原因、`settings().deform_enabled` 仍为 False、
`describe()["capabilities"]["displacement_available"] is False`；图例显示实际上下限（0.25–7.5）与"自动"、
不再出现内部键、`describe()["effective_scale"]` 三项一致；复位后的相机矩阵等于
`apply_preset(camera_presets[0])` 的结果（先 orbit+zoom 离开再复位）。
· `test_scene3d_skeleton.py` 的图例断言改为"不含内部键、含操作者语言的名字"。
· 全量：apps/studio 240 项 0 失败 14 跳过；真 GL 冒烟 14 项 0 失败 0 跳过；ui_check 587 项 0 失败；
locale_check 0 缺失。
- Not in this change: **画布布局（2D/3D 页签容器、参数收进"显示设置"抽屉、窄窗口回退）留作阶段 8 的第二批**
（需要同时改 `ui_check` 的布局断言与截图对比，风险与工作量都更大，独立提交更易审阅）；曲线量程的
"可见区间自动/固定"开关（报告建议项）也留到第二批；诊断抽屉的结构调整同理；阶段 9（限速、真实耗时统计、
保护包密钥注入、ARM 与 2 小时门禁）未开始。
|
||
|
ykcheungab
|
3c0424b90c |
feat(studio-3d): 设备几何身份接入 —— 同尺寸不同映射/不同表面被拒绝，资产加载只采用最新请求
- What:
1. **设备侧自己说几何**（新增 `shared/.../acquisition/geometry.py`）：`describe_sensor_geometry()`
从运行时真正加载的文件推导——`manifest.json` 的 `assets_dir`、`sensor.json` 的
`camera.resolution_stitch`/`source_scale`、以及据此命名的 unroll map（`unroll_map_uv_s0.4.npz`）。
产出 `DeviceGeometry(expected, verified, detail)`：`field_domain_id` + `shape_hw`（映射身份，含
flip/scale/映射内容摘要）与 **无单位** 的 `source_geometry_id`（地图里 `world_xyz` 的内容摘要）。
米制 `geometry_id` 需要"1 源单位 = N 米"这句只有人能做的声明，设备侧**故意留空**。两类失败区分对待：
定位不到 bundle / 没写 `assets_dir` → `verified=False`（可显示，但不声明已校验）；bundle 变了
（map 缺失、与 `resolution_stitch` 不符）→ 直接拒绝并指名两个形状/文件。
2. **契约**：`ExpectedGeometry += source_geometry_id`；`SceneAssets += source_geometry_id,
compatible_sensor_model, compatible_hardware_revisions`；诊断码 `geometry_unverified`（info）；
`digest.source_geometry_digest(world_xyz)`；`legacy.convert()` 写入 `source_geometry_id`；
`package.py` 的 manifest 增 `source_geometry` 块（数组名与单位写明），读取时把 `compatible` 与
`source_geometry` 一并还原（旧包读到空串）。`validate_assets()` 的 expected 段重写：**只比较已声明的
字段**，`source_geometry_id` 不符即拒绝，包内未记录该身份 → 返回 `geometry_unverified` 警告而不是
静默通过；顺带修掉 `expected.sensor_model != assets.parts[0].role` 这行毫无意义的比较，改成真正的
型号/硬件版本比对（`*` = 任意版本）。
3. **接线**：`app_window._sync_3d_source()` 传 `expected_provider=`（一个闭包，指向当前传感器配置）；
`SceneAssetLoader` 在**工作线程**上解析它（`_resolve_and_load`）；`view.use_scene(assets, source_id,
expected)` 改为 `validate_assets(assets, expected)` 并把警告送到面板，同时记录 `device_verified`；
`_make_snapshot()` 用**设备**的身份构造 adapter（设备没声明的字段才回退资产），使
"帧与场景匹配" 第一次成为独立检查而不是自证；`describe()` 记录 `scene.device_verified` 与设备身份。
4. **资产加载请求身份（R7-a）**：`SceneAssetLoader` 增请求号与 pending 槽——忙时不再丢弃新请求，而是
保留最新一个并在前一个结束后启动；完成信号带请求号（`loaded(assets, 描述, id, device)` /
`failed(diag, id)`），`Mesh3dPanel` 丢弃过期完成（否则旧文件的场景会落回新选择上）。失败后可重试。
5. **工具与包**：`compile_scene.py`/`validate_scene.py` 报告 `geometry_id`/`field_domain_id`/
`source_geometry_id`/兼容信息；README 写明无单位身份是什么、为什么设备侧用它；**重编发布包**
`apps/studio/config/sensors/finger/scene/finger-display-1.0.0.oryscene`（geometry_id 仍为
`1a2e0e92…`、1032 顶点 / 1974 三角形，新增 `source_geometry_id=46a03a5f…`，因此 asset_hash 变为 `ea4beab6…`）。
- Why: 审查报告 P1/R3：主窗口只传 sensor_type 与 package_override，`Mesh3dPanel._expected` 永远是 None，
`validate_assets(assets, None)` 跳过全部设备比对，而 adapter 的 geometry_id/field_domain_id/shape_hw
全部来自**已选中的资产**——于是收到的数据被贴上"资产自己期望的身份"。结果：shape 相同但 UV 映射、
flip_v、source_scale 或相机配置不同时无法区分。P1/R7：`SceneAssetLoader.load()` 在忙时直接 return，
既没保留最新请求也没有 generation，`_on_loaded` 又用当前 `_source` 标记已加载路径，快速切换配置时旧
文件的任务会回到新选择上。
- Verification:
· 证据探针 `.repro/probe_stage6_device.py` → `probe_stage6_device.json`（真实 bundle + 真实包）：
设备描述 `verified=true`、domain `feb7f71e…`、source geometry `46a03a5f…`、shape 300x280、
米制 id 未声明、map = `unroll_map_uv_s0.4.npz`；发布包通过该描述；**同尺寸不同映射**（只改 map 一个
像素的坐标）→ domain 变化、shape 不变、包被 `field_domain_mismatch` 拒绝；设备什么都不声明 →
接受 + `geometry_unverified`。
· 新增 `shared/tests/test_scene3d_device_geometry.py` 9 项：描述来源、发布包通过、同尺寸不同映射拒绝、
同 map 不同表面拒绝、定位不到 bundle → unverified、`resolution_stitch` 与 map 不符拒绝、map 缺失
指名文件、无 `assets_dir` → unverified、map 命名规则。
· `test_scene3d_contracts.py` +4（未声明身份 → 警告而非匹配、source geometry 不符拒绝/缺记录 → 警告、
型号与硬件版本、`source_geometry_digest` 的稳定性与形状校验）；`test_scene3d_package.py` +2
（`source_geometry` 往返、旧包读成"未声明"）；`test_scene3d_view.py` +6（adapter 身份来自设备、
设备 domain 不符 → 拒绝且不上屏、无描述 → `geometry_unverified` 且 `device_verified=false`、
**最新请求才运行**、面板丢弃过期完成、失败后可重试）。
· 全量：apps/studio 0 失败（`--junitxml`：231→236 项）；shared 0 失败（含 device_geometry 9 项）；
`validate_scene.py` 对重编包全项 ok。
- Not in this change: 生产侧仍不声明米制 `geometry_id`（那句单位声明只有人能写；要设备端复算它需要把
`meters_per_source_unit` 与刚体变换记进配置，属可选加强项，已在本提交的 `DeviceGeometry.detail` 里留位）；
`ExpectedGeometry.mapping_digest` 未加——`field_domain_id` 本身就是由映射内容摘要派生的，再加一个字段
只是同一个事实的第二个名字；`docs/architecture/studio-3d-contracts.pyi` 与本阶段新契约的同步放在阶段 6
的文档提交里；保护包密钥注入（R4）、限速与真实统计、二维后端统一均未动。
|
||
|
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
|
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 秒后明确报错而不是空转。
|
||
|
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 + 已确认尺度）。 |
||
|
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`）。 |
||
|
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` 包（发布产物，且其单位与变换必须由人声明）。 |