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）、限速与真实统计、二维后端统一均未动。
This commit is contained in:
ykcheungab
@@ -56,6 +56,13 @@ difference, and a wrong factor looks plausible.
|
||||
Expected result: `1032 vertices`, `1974 triangles`, `geometry_id` starting
|
||||
`1a2e0e92…`, a 56 KB package, and `validate_scene.py` reporting every check `ok`.
|
||||
|
||||
The package also records a **unit-free** `source_geometry_id` (`46a03a5f…` for the
|
||||
shipped bundle). It is the only geometry identity the acquisition side can reproduce
|
||||
without the unit statement above, so it is what lets the running application verify
|
||||
that the scene it is drawing was built from the same surface — and the same mapping,
|
||||
via `field_domain_id` — that the device is actually running. A package that predates
|
||||
this record is still accepted, and reported as *unverified* rather than as a match.
|
||||
|
||||
## Where the application looks for a package
|
||||
|
||||
1. `preference.json` → `"scene3d_package": "<path>"` (an absolute path; also the way
|
||||
|
||||
@@ -229,6 +229,7 @@ def main(argv: list[str] | None = None) -> int:
|
||||
"triangles": report.part_triangle_counts,
|
||||
"geometry_id": assets.geometry_id,
|
||||
"field_domain_id": assets.field_domain_id,
|
||||
"source_geometry_id": assets.source_geometry_id,
|
||||
"envelope": envelope,
|
||||
"platform_lock": (
|
||||
assets.platform_lock.to_dict() if assets.platform_lock is not None else None
|
||||
@@ -242,6 +243,10 @@ def main(argv: list[str] | None = None) -> int:
|
||||
f"triangles={report.part_triangle_counts}"
|
||||
)
|
||||
print(f" geometry_id={assets.geometry_id}")
|
||||
print(
|
||||
" source_geometry_id="
|
||||
+ (assets.source_geometry_id or "(none: no world_xyz in the map)")
|
||||
)
|
||||
print(f" asset_hash={report.asset_hash}")
|
||||
print(
|
||||
f" envelope=v{envelope['envelope_version']} {envelope['payload']}"
|
||||
|
||||
@@ -126,6 +126,7 @@ def _legacy_report(args) -> tuple[int, dict]:
|
||||
geometry_id=assets.geometry_id,
|
||||
field_domain_id=assets.field_domain_id,
|
||||
shape_hw=assets.shape_hw,
|
||||
source_geometry_id=assets.source_geometry_id,
|
||||
)
|
||||
try:
|
||||
validate_assets(assets, expected)
|
||||
@@ -133,6 +134,12 @@ def _legacy_report(args) -> tuple[int, dict]:
|
||||
except ThreeDError as exc:
|
||||
record("device description", False, exc.diagnostic.code)
|
||||
report["geometry_id"] = assets.geometry_id
|
||||
report["field_domain_id"] = assets.field_domain_id
|
||||
report["source_geometry_id"] = assets.source_geometry_id
|
||||
report["compatible"] = {
|
||||
"sensor_model": assets.compatible_sensor_model,
|
||||
"hardware_revisions": list(assets.compatible_hardware_revisions),
|
||||
}
|
||||
report["asset_hash"] = assets.asset_hash
|
||||
report["binding"] = {
|
||||
"rows": int(assets.binding.sample_indices.shape[0]),
|
||||
@@ -239,6 +246,7 @@ def _package_report(args) -> tuple[int, dict]:
|
||||
str(contents.manifest.get("geometry_id")),
|
||||
str((contents.manifest.get("field_domain") or {}).get("id")),
|
||||
tuple(int(v) for v in (contents.manifest.get("field_domain") or {}).get("shape_hw", (0, 0))),
|
||||
str(((contents.manifest.get("source_geometry") or {}) or {}).get("id") or ""),
|
||||
)
|
||||
if args.sensor_model
|
||||
else None
|
||||
@@ -246,6 +254,16 @@ def _package_report(args) -> tuple[int, dict]:
|
||||
assets = scene_from_contents(contents, expected)
|
||||
record("scene builds and validates", True,
|
||||
f"{assets.sensing_part().positions_sensor_m.shape[0]} vertices")
|
||||
record(
|
||||
"source geometry recorded",
|
||||
# Not a failure: a package without the record is still publishable, it just
|
||||
# cannot be compared with a device's own geometry. ``--require-signature``
|
||||
# is where a release gets to demand more.
|
||||
True,
|
||||
assets.source_geometry_id[:16] if assets.source_geometry_id else
|
||||
"not recorded (this package predates the record: a device reports it as "
|
||||
"unverified rather than as a match)",
|
||||
)
|
||||
except ThreeDError as exc:
|
||||
record("scene builds and validates", False,
|
||||
f"{exc.diagnostic.code}: {exc.diagnostic.message}")
|
||||
|
||||
Reference in New Issue
Block a user