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` 放宽为只看读取结果是一行改动，已写进计划的风险项）。
This commit is contained in:
ykcheungab
@@ -32,12 +32,24 @@ from orisys_studio.scene3d.adapters import (
|
||||
|
||||
@dataclass
|
||||
class FakePacket:
|
||||
"""The parts of ``SdkPacket`` the adapters look at."""
|
||||
"""The parts of ``SdkPacket`` the adapters look at.
|
||||
|
||||
The provenance flags default to *stated fresh*: that is what both production
|
||||
workers now write, and it keeps the older tests about grids and units about grids
|
||||
and units. A test that wants a stale or unstated field says so — that is the
|
||||
behaviour under test.
|
||||
"""
|
||||
|
||||
flow: Optional[np.ndarray] = None
|
||||
depth: Optional[np.ndarray] = None
|
||||
valid_mask: Optional[np.ndarray] = None
|
||||
frame_id: int = 1
|
||||
invalid_reason: str = ""
|
||||
flow_valid: Optional[bool] = True
|
||||
flow_frame_id: Optional[int] = None
|
||||
depth_valid: Optional[bool] = True
|
||||
depth_frame_id: Optional[int] = None
|
||||
forces_valid: Optional[bool] = True
|
||||
|
||||
|
||||
def _identity(generation: int = 1) -> FrameIdentity:
|
||||
@@ -242,7 +254,8 @@ def test_the_finger_adapter_does_not_colour_outside_the_uv_island(scene):
|
||||
)
|
||||
|
||||
|
||||
def test_a_device_mask_from_another_grid_is_ignored_not_stretched(scene):
|
||||
def test_a_device_mask_from_another_grid_refuses_the_frame(scene):
|
||||
"""Neither stretching it nor ignoring it is honest — so the frame is refused."""
|
||||
adapter = FingerFrameAdapter(
|
||||
geometry_id=scene.geometry_id,
|
||||
field_domain_id=scene.field_domain_id,
|
||||
@@ -253,8 +266,117 @@ def test_a_device_mask_from_another_grid_is_ignored_not_stretched(scene):
|
||||
frame = adapter.snapshot(
|
||||
FakePacket(flow=flow, valid_mask=wrong), runtime=None, identity=_identity()
|
||||
)
|
||||
assert frame is None, "a mask from another grid must not widen the trusted area"
|
||||
item = adapter.last_diagnostic
|
||||
assert item is not None and item.code == "field_domain_mismatch"
|
||||
assert item.details["mask"] == "7x7"
|
||||
assert item.details["domain"] == f"{scene.shape_hw[0]}x{scene.shape_hw[1]}"
|
||||
|
||||
|
||||
# ------------------------------------------------- field provenance (stage 6, R2)
|
||||
def _finger(scene) -> FingerFrameAdapter:
|
||||
return FingerFrameAdapter(
|
||||
geometry_id=scene.geometry_id,
|
||||
field_domain_id=scene.field_domain_id,
|
||||
shape_hw=scene.shape_hw,
|
||||
)
|
||||
|
||||
|
||||
def test_a_stale_flow_is_refused_instead_of_coloured(scene):
|
||||
"""R2: the array is still finite, but it is not this frame's measurement.
|
||||
|
||||
This is the audit's reproduction: a packet with ``valid=False``/``stale_forces``
|
||||
and a filled ``flow`` used to be coloured as valid data with no diagnostic.
|
||||
"""
|
||||
adapter = _finger(scene)
|
||||
flow = np.full((*scene.shape_hw, 2), 4.0, dtype=np.float32)
|
||||
frame = adapter.snapshot(
|
||||
FakePacket(
|
||||
flow=flow,
|
||||
flow_valid=False,
|
||||
invalid_reason="compute: ValueError: boom",
|
||||
),
|
||||
runtime=None,
|
||||
identity=_identity(),
|
||||
)
|
||||
assert frame is None, "a failed chain's leftover flow was coloured as current"
|
||||
item = adapter.last_diagnostic
|
||||
assert item is not None and item.code == "field_stale"
|
||||
assert "boom" in item.message
|
||||
|
||||
|
||||
def test_an_unstated_flow_is_unverified_not_fresh(scene):
|
||||
"""No statement is not the same as "it is mine"."""
|
||||
adapter = _finger(scene)
|
||||
flow = np.full((*scene.shape_hw, 2), 1.0, dtype=np.float32)
|
||||
frame = adapter.snapshot(
|
||||
FakePacket(flow=flow, flow_valid=None), runtime=None, identity=_identity()
|
||||
)
|
||||
assert frame is None
|
||||
item = adapter.last_diagnostic
|
||||
assert item is not None and item.code == "field_unverified"
|
||||
|
||||
|
||||
def test_flow_computed_for_another_frame_is_refused(scene):
|
||||
adapter = _finger(scene)
|
||||
flow = np.full((*scene.shape_hw, 2), 2.0, dtype=np.float32)
|
||||
frame = adapter.snapshot(
|
||||
FakePacket(flow=flow, flow_frame_id=3),
|
||||
runtime=None,
|
||||
identity=_identity(), # frame_id == 1
|
||||
)
|
||||
assert frame is None
|
||||
item = adapter.last_diagnostic
|
||||
assert item is not None and item.code == "field_stale"
|
||||
assert item.details["computed"] == "3" and item.details["frame"] == "1"
|
||||
|
||||
|
||||
def test_a_fresh_flow_records_the_frame_it_belongs_to(scene):
|
||||
"""The identity travels with the frame, so the display side can re-check it."""
|
||||
adapter = _finger(scene)
|
||||
flow = np.full((*scene.shape_hw, 2), 3.0, dtype=np.float32)
|
||||
frame = adapter.snapshot(
|
||||
FakePacket(flow=flow, flow_frame_id=1), runtime=None, identity=_identity()
|
||||
)
|
||||
assert frame is not None
|
||||
assert np.asarray(frame.valid).all()
|
||||
assert frame.computed_frame_id == 1
|
||||
assert validate_surface_frame(frame) == ()
|
||||
|
||||
|
||||
def test_the_box_adapter_skips_a_stale_depth_and_uses_the_flow(scene):
|
||||
"""A failed deformation chain does not have to cost the flow as well."""
|
||||
adapter = BoxFrameAdapter(
|
||||
geometry_id=scene.geometry_id,
|
||||
field_domain_id=scene.field_domain_id,
|
||||
shape_hw=scene.shape_hw,
|
||||
)
|
||||
depth = np.full(scene.shape_hw, 0.5, dtype=np.float32)
|
||||
flow = np.zeros((*scene.shape_hw, 2), dtype=np.float32)
|
||||
flow[..., 0] = 1.0
|
||||
frame = adapter.snapshot(
|
||||
FakePacket(depth=depth, depth_valid=False, flow=flow),
|
||||
_identity(),
|
||||
ExpectedGeometry("box", "rev", scene.geometry_id, scene.field_domain_id, scene.shape_hw),
|
||||
)
|
||||
assert frame is not None and frame.scalar_descriptor == FLOW_MAGNITUDE
|
||||
assert np.allclose(np.asarray(frame.scalar), 1.0)
|
||||
|
||||
|
||||
def test_the_box_adapter_refuses_when_no_field_is_its_own(scene):
|
||||
adapter = BoxFrameAdapter(
|
||||
geometry_id=scene.geometry_id,
|
||||
field_domain_id=scene.field_domain_id,
|
||||
shape_hw=scene.shape_hw,
|
||||
)
|
||||
depth = np.full(scene.shape_hw, 0.5, dtype=np.float32)
|
||||
frame = adapter.snapshot(
|
||||
FakePacket(depth=depth, depth_valid=False),
|
||||
_identity(),
|
||||
ExpectedGeometry("box", "rev", scene.geometry_id, scene.field_domain_id, scene.shape_hw),
|
||||
)
|
||||
assert frame is None
|
||||
item = adapter.last_diagnostic
|
||||
assert item is not None and item.code == "field_stale"
|
||||
|
||||
|
||||
def _run_map():
|
||||
|
||||
Reference in New Issue
Block a user