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
@@ -0,0 +1,162 @@
|
||||
"""Stage 6 acceptance for the *device's own* geometry description.
|
||||
|
||||
The review's R3 finding was that the internal-consistency check was never wired to the
|
||||
acquisition side: the adapter was built from the asset, so "the frame matches the scene"
|
||||
was a sentence the asset wrote about itself. These tests are about the other half — the
|
||||
description the acquisition side derives from the files the runtime actually loads, and
|
||||
what happens when those files and the package disagree.
|
||||
|
||||
The bundle used here is the shipped one (``apps/studio/config/sensors/finger``); the
|
||||
tests that need it skip when it is absent, because the module is also imported by runs
|
||||
that only have the SDK.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import shutil
|
||||
from dataclasses import replace
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
from orisys_app_shared.acquisition.geometry import (
|
||||
describe_sensor_geometry,
|
||||
map_path_for,
|
||||
)
|
||||
from orisys_app_shared.scene3d.contracts import ThreeDError
|
||||
from orisys_app_shared.scene3d.package import PackagedAssetLoader
|
||||
|
||||
BUNDLE = (
|
||||
Path(__file__).resolve().parents[2]
|
||||
/ "apps"
|
||||
/ "studio"
|
||||
/ "config"
|
||||
/ "sensors"
|
||||
/ "finger"
|
||||
)
|
||||
PACKAGE = BUNDLE / "scene" / "finger-display-1.0.0.oryscene"
|
||||
|
||||
|
||||
def _require_bundle() -> None:
|
||||
if not (BUNDLE / "sensor.json").is_file():
|
||||
pytest.skip("the shipped finger bundle is not present")
|
||||
|
||||
|
||||
def _require_package() -> None:
|
||||
_require_bundle()
|
||||
if not PACKAGE.is_file():
|
||||
pytest.skip("the compiled finger package is not present")
|
||||
|
||||
|
||||
def test_the_map_name_follows_the_scale_the_sdk_would_use(tmp_path):
|
||||
assert map_path_for(tmp_path, 0.4).name == "unroll_map_uv_s0.4.npz"
|
||||
assert map_path_for(tmp_path, 1.0).name == "unroll_map_uv.npz"
|
||||
assert map_path_for(tmp_path, None).name == "unroll_map_uv.npz"
|
||||
|
||||
|
||||
def test_the_device_description_comes_from_the_files_the_runtime_loads():
|
||||
_require_bundle()
|
||||
device = describe_sensor_geometry("finger", BUNDLE / "sensor.json")
|
||||
assert device.verified, device.detail
|
||||
assert device.expected.sensor_model == "finger"
|
||||
# The metre-scaled identity needs the operator's unit statement; a device that
|
||||
# cannot make it must say nothing rather than echo the asset's id back.
|
||||
assert device.expected.geometry_id == ""
|
||||
assert device.expected.field_domain_id
|
||||
assert device.expected.source_geometry_id
|
||||
assert tuple(device.expected.shape_hw) == (300, 280)
|
||||
assert Path(device.detail["map"]).name == "unroll_map_uv_s0.4.npz"
|
||||
assert device.detail["shape_hw"] == "300x280"
|
||||
|
||||
|
||||
def test_the_shipped_package_passes_the_shipped_device_description():
|
||||
_require_package()
|
||||
device = describe_sensor_geometry("finger", BUNDLE / "sensor.json")
|
||||
assets = PackagedAssetLoader().load(PACKAGE, device.expected)
|
||||
assert assets.source_geometry_id == device.expected.source_geometry_id
|
||||
assert assets.compatible_sensor_model == "finger"
|
||||
|
||||
|
||||
def test_a_same_size_different_mapping_is_refused(tmp_path):
|
||||
"""The risk the review named: 300x280 is not one mapping."""
|
||||
_require_package()
|
||||
fake = tmp_path / "finger"
|
||||
shutil.copytree(BUNDLE, fake)
|
||||
map_path = fake / "assets" / "30fps-0703" / "unroll_map_uv_s0.4.npz"
|
||||
with np.load(map_path, allow_pickle=False) as handle:
|
||||
data = {key: handle[key] for key in handle.files}
|
||||
# The same grid, the same valid area — a different mapping.
|
||||
data["map_x"] = np.asarray(data["map_x"], dtype=np.float32).copy()
|
||||
data["map_x"][0, 0] = float(data["map_x"][0, 0]) + 3.0
|
||||
np.savez(map_path, **data)
|
||||
|
||||
shipped = describe_sensor_geometry("finger", BUNDLE / "sensor.json")
|
||||
other = describe_sensor_geometry("finger", fake / "sensor.json")
|
||||
assert tuple(other.expected.shape_hw) == tuple(shipped.expected.shape_hw)
|
||||
assert other.expected.field_domain_id != shipped.expected.field_domain_id, (
|
||||
"two different mappings of the same size produced the same domain id"
|
||||
)
|
||||
with pytest.raises(ThreeDError) as excinfo:
|
||||
PackagedAssetLoader().load(PACKAGE, other.expected)
|
||||
assert excinfo.value.diagnostic.code == "field_domain_mismatch"
|
||||
|
||||
|
||||
def test_a_changed_mesh_behind_the_same_map_is_refused(tmp_path):
|
||||
"""The other half: the map is identical, the surface behind it is not."""
|
||||
_require_package()
|
||||
device = describe_sensor_geometry("finger", BUNDLE / "sensor.json")
|
||||
other_geometry = replace(device.expected, source_geometry_id="somebody-elses-surface")
|
||||
with pytest.raises(ThreeDError) as excinfo:
|
||||
PackagedAssetLoader().load(PACKAGE, other_geometry)
|
||||
assert excinfo.value.diagnostic.code == "geometry_mismatch"
|
||||
|
||||
|
||||
def test_a_bundle_that_cannot_be_described_is_unverified_not_a_match(tmp_path):
|
||||
_require_bundle()
|
||||
unknown = tmp_path / "nowhere"
|
||||
device = describe_sensor_geometry("finger", unknown)
|
||||
assert device.verified is False
|
||||
assert device.expected.geometry_id == ""
|
||||
assert device.expected.source_geometry_id == ""
|
||||
assert "could not be located" in device.detail["reason"]
|
||||
|
||||
|
||||
def test_a_bundle_whose_map_disagrees_with_the_config_is_refused(tmp_path):
|
||||
"""``resolution_stitch`` and the map are two statements of one grid."""
|
||||
_require_bundle()
|
||||
fake = tmp_path / "finger"
|
||||
shutil.copytree(BUNDLE, fake)
|
||||
config = json.loads((fake / "sensor.json").read_text(encoding="utf-8"))
|
||||
config["camera"]["resolution_stitch"] = [280, 299]
|
||||
(fake / "sensor.json").write_text(
|
||||
json.dumps(config, ensure_ascii=False), encoding="utf-8"
|
||||
)
|
||||
with pytest.raises(ThreeDError) as excinfo:
|
||||
describe_sensor_geometry("finger", fake / "sensor.json")
|
||||
assert excinfo.value.diagnostic.code == "field_domain_mismatch"
|
||||
|
||||
|
||||
def test_a_missing_map_names_the_file_it_looked_for(tmp_path):
|
||||
_require_bundle()
|
||||
fake = tmp_path / "finger"
|
||||
(fake / "assets" / "30fps-0703").mkdir(parents=True)
|
||||
(fake / "manifest.json").write_text(
|
||||
json.dumps({"assets_dir": "assets/30fps-0703"}), encoding="utf-8"
|
||||
)
|
||||
shutil.copy(BUNDLE / "sensor.json", fake / "sensor.json")
|
||||
with pytest.raises(ThreeDError) as excinfo:
|
||||
describe_sensor_geometry("finger", fake / "sensor.json")
|
||||
assert excinfo.value.diagnostic.code == "asset_rejected"
|
||||
assert "unroll_map_uv_s0.4.npz" in excinfo.value.diagnostic.message
|
||||
|
||||
|
||||
def test_a_bundle_without_an_assets_dir_is_unverified(tmp_path):
|
||||
fake = tmp_path / "finger"
|
||||
fake.mkdir()
|
||||
(fake / "manifest.json").write_text(json.dumps({"name": "finger"}), encoding="utf-8")
|
||||
(fake / "sensor.json").write_text(json.dumps({"camera": {}}), encoding="utf-8")
|
||||
device = describe_sensor_geometry("finger", fake / "sensor.json")
|
||||
assert device.verified is False
|
||||
assert "assets_dir" in device.detail["reason"]
|
||||
Reference in New Issue
Block a user