Discover sensor bundles from the SDK catalog, not a product list

The picker listed a hard-coded product list and treated any *.json beside sensor.json as a configuration, so a folder of stray JSON could be offered as a sensor. Discovery now scans the shipped root and a writable user root beside it, keeps the SDK's verdict for every entry (listing rejected ones with their reason) and flags duplicate profile_ids instead of shadowing them; verified by shared/tests and apps/studio/tests.
2026-10-05 09:30:04 +08:00
parent a92a2ba237
commit 25ccffd814
11 changed files with 1513 additions and 43 deletions
@@ -0,0 +1,129 @@
+"""The picker lists what the catalog returns, including what it refuses.
+
+This is the selector side of the catalog contract: an entry the SDK rejects must still be
+listed (that is how its reason reaches the operator), a duplicate ``profile_id`` must be listed
+twice with both sides named, and ``start_blocked_reason()`` must be the answer a caller can
+refuse to start on. The catalog itself is tested in ``shared/tests``; here it is a fixture tree
+pointed at the widget, so the assertions are about the combo contents rather than the
+filesystem.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+from orisys_app_shared.sensors import FAMILY_UNIDENTIFIED, scan_sensor_catalog
+from orisys_studio.ui import sensor_picker as picker_module
+from orisys_studio.ui.sensor_picker import SensorPickerWidget
+from PySide6.QtCore import Qt
+
+CONFIG = {
+    "name": "fixture",
+    "camera": {
+        "resolution_raw": [640, 480],
+        "fps": 30,
+        "resolution_stitch": [100, 100],
+    },
+    "tracker": {"algorithm": "dis"},
+}
+
+
+def _write(path: Path, payload: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def _descriptor(profile_id: str) -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "profile_id": profile_id,
+        "display_name": "Mini lab",
+        "product_family": "mini",
+        "processing_backend": "single_camera",
+        "sensor_json": "sensor.json",
+    }
+
+
+def _make_picker(qt_app, tmp_path, monkeypatch, build: Callable[[Path], None]):
+    """A picker whose catalog is a fixture tree instead of the installed one."""
+    root = tmp_path / "user"
+    build(root)
+    catalog = scan_sensor_catalog(
+        shipped_root=tmp_path / "no-shipped-root", user_root=root
+    )
+    monkeypatch.setattr(picker_module, "scan_sensor_catalog", lambda: catalog)
+    return SensorPickerWidget()
+
+
+@pytest.fixture
+def mixed_picker(qt_app, tmp_path, monkeypatch):
+    """Two bundles sharing a profile_id, plus a folder holding only a calibration."""
+
+    def build(root: Path) -> None:
+        for name in ("mini-a", "mini-b"):
+            _write(root / name / "sensor.json", CONFIG)
+            _write(root / name / "manifest.json", _descriptor("orisys.mini.same-r1"))
+        _write(root / "stray" / "force_calibration.json", {"schema_version": 2})
+
+    widget = _make_picker(qt_app, tmp_path, monkeypatch, build)
+    yield widget
+    widget.deleteLater()
+
+
+def test_a_calibration_folder_is_listed_as_invalid_with_its_reason(mixed_picker):
+    picker = mixed_picker
+    assert picker.type_combo.findData(FAMILY_UNIDENTIFIED) >= 0
+    picker.set_sensor_type(FAMILY_UNIDENTIFIED)
+    assert picker.config_combo.count() == 1
+    entry = picker.selected_entry()
+    assert entry is not None and not entry.valid
+    # The internal "no product family" marker is named in the operator's language, not leaked.
+    assert FAMILY_UNIDENTIFIED not in picker.config_combo.itemText(0)
+    tooltip = picker.config_combo.itemData(0, Qt.ItemDataRole.ToolTipRole)
+    assert "force_calibration.json" in tooltip
+    assert "sensor.json or a manifest.json descriptor" in tooltip
+    assert picker.start_blocked_reason() == entry.start_blocked_reason
+
+
+def test_a_shared_profile_id_is_listed_twice_and_can_be_refused(mixed_picker):
+    picker = mixed_picker
+    picker.set_sensor_type("mini")
+    assert picker.config_combo.count() == 2, "one of the duplicates was shadowed"
+
+    first = picker.selected_entry()
+    picker.config_combo.setCurrentIndex(1)
+    second = picker.selected_entry()
+    assert first is not None and second is not None
+    assert {first.profile_id, second.profile_id} == {"orisys.mini.same-r1"}
+    assert {first.folder, second.folder} == {"mini-a", "mini-b"}
+    # Each side names the other, and the verdict follows the *selected* entry.
+    for index, other_ref in ((0, "user/mini-b"), (1, "user/mini-a")):
+        picker.config_combo.setCurrentIndex(index)
+        entry = picker.selected_entry()
+        assert entry is not None and entry.duplicates == (other_ref,)
+        reason = picker.start_blocked_reason()
+        assert reason is not None and other_ref in reason
+    # Both stay selectable: the list shows the ambiguity instead of resolving it silently.
+    assert picker.config_combo.count() == 2
+
+
+def test_a_single_valid_entry_is_listed_with_its_identity_and_not_blocked(
+    qt_app, tmp_path, monkeypatch
+):
+    def build(root: Path) -> None:
+        _write(root / "mini-lab" / "sensor.json", CONFIG)
+        _write(root / "mini-lab" / "manifest.json", _descriptor("orisys.mini.lab-r1"))
+
+    picker = _make_picker(qt_app, tmp_path, monkeypatch, build)
+    assert picker.type_combo.findData("mini") >= 0
+    picker.set_sensor_type("mini")
+    label = picker.config_combo.itemText(0)
+    assert "orisys.mini.lab-r1" in label
+    assert "mini" in label and "user" in label and "degraded" in label
+    assert picker.start_blocked_reason() is None
+    entry = picker.selected_entry()
+    assert entry is not None and entry.profile_id == "orisys.mini.lab-r1"
+    picker.deleteLater()
@@ -0,0 +1,271 @@
+"""The catalog against the configuration the studio actually ships, and the rename contract.
+
+The first half asserts what ``apps/studio/config/sensors`` contains *today*, entry by entry, so
+a change to the shipped tree shows up here instead of only on a machine that happens to have
+the right folders.
+
+``finger`` is the one shipped bundle that carries a descriptor, so its identity is the profile
+the descriptor declares instead of one derived from its folder name. Its declared asset paths
+are asserted to be the files in the tree, because a rename that silently resolved elsewhere is
+exactly the failure the descriptor exists to prevent.
+
+The second half is the rename contract: a bundle keeps its identity when its folder is renamed.
+That is true because every descriptor path is relative to the bundle root, so it belongs to
+discovery — the catalog is where a renamed bundle is compared with the one it was copied from.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+import pytest
+from orisys.sensors import DescriptorError, resolve_bundle
+from orisys.unroll import scaled_map_cache_path
+from orisys_app_shared.acquisition.finger_worker import resolve_finger_export_dir
+from orisys_app_shared.paths import sensors_dir
+from orisys_app_shared.sensors import (
+    ORIGIN_SHIPPED,
+    ROOT_KIND_FALLBACK,
+    ROOT_KIND_SIBLING,
+    scan_sensor_catalog,
+)
+
+#: The identity the shipped finger descriptor declares. A copy of the bundle keeps it.
+FINGER_PROFILE_ID = "orisys.finger.r01"
+
+#: What the shipped root provides today, as the SDK resolves it.
+EXPECTED_SHIPPED: dict[str, tuple[str, str, str, bool, str]] = {
+    # folder: (family, profile_id, backend, valid, state)
+    "box": ("box", "orisys.box.legacy", "compound_eye", True, "degraded"),
+    "finger": ("finger", FINGER_PROFILE_ID, "uv_unroll", True, "degraded"),
+    "finger-mems": (
+        "finger-mems",
+        "orisys.finger-mems.legacy",
+        "compound_eye",
+        True,
+        "degraded",
+    ),
+    "mini": ("mini", "orisys.mini.legacy", "compound_eye", True, "degraded"),
+}
+
+
+@pytest.fixture(scope="module")
+def shipped():
+    return scan_sensor_catalog()
+
+
+def test_the_shipped_root_is_the_one_the_app_resolves(shipped):
+    assert shipped.shipped_root == sensors_dir()
+    assert shipped.roots[0].exists is True
+
+
+def test_the_shipped_root_offers_exactly_its_four_bundles(shipped):
+    refs = {entry.ref for entry in shipped.entries_for_origin(ORIGIN_SHIPPED)}
+    assert refs == {
+        "shipped/box",
+        "shipped/finger",
+        "shipped/finger-mems",
+        "shipped/mini",
+    }, sorted(refs)
+
+
+def test_every_shipped_entry_reports_its_family_profile_and_verdict(shipped):
+    for folder, (family, profile_id, backend, valid, state) in EXPECTED_SHIPPED.items():
+        entry = shipped.by_ref(f"shipped/{folder}")
+        assert entry is not None, folder
+        assert entry.product_family == family, folder
+        assert entry.profile_id == profile_id, folder
+        assert entry.processing_backend == backend, folder
+        assert entry.valid is valid, f"{folder}: {entry.reason}"
+        assert entry.state == state, f"{folder}: {entry.reason}"
+        assert entry.origin == ORIGIN_SHIPPED
+        # The verdict is the SDK's, not a second opinion computed here.
+        assert (entry.start_blocked_reason is None) == (
+            valid and not entry.duplicate
+        ), folder
+
+
+def test_the_shipped_families_keep_the_picker_order(shipped):
+    assert shipped.families() == ["box", "mini", "finger", "finger-mems"]
+
+
+def test_box_mini_and_finger_mems_are_legacy_sensor_json_bundles(shipped):
+    for folder in ("box", "mini", "finger-mems"):
+        bundle = sensors_dir() / folder
+        assert (bundle / "sensor.json").is_file(), folder
+        assert not (bundle / "manifest.json").exists(), folder
+        entry = shipped.by_ref(f"shipped/{folder}")
+        assert entry.profile is not None and entry.profile.sensor_json_path.is_file(), (
+            folder
+        )
+
+
+def test_the_finger_bundle_ships_a_descriptor_naming_the_files_it_has(shipped):
+    """The shipped ``finger/manifest.json`` is a *descriptor*, not the legacy shape.
+
+    Its identity is declared rather than inferred from the folder name, and every path it
+    declares is relative to the bundle root. The declared files are asserted to exist, so
+    renaming a shipped map or scene without updating the descriptor fails here.
+    """
+    bundle = sensors_dir() / "finger"
+    manifest = json.loads((bundle / "manifest.json").read_text(encoding="utf-8"))
+    assert manifest["schema_version"] == 1, "the descriptor contract is version 1"
+    assert manifest["profile_id"] == FINGER_PROFILE_ID
+    assert manifest["display_name"]
+    assert manifest["product_family"] == "finger"
+    assert manifest["processing_backend"] == "uv_unroll"
+    assert manifest["sensor_json"] == "sensor.json"
+
+    declared = [
+        manifest["sensor_json"],
+        *manifest["computational_assets"].values(),
+        *manifest["assets"].values(),
+    ]
+    assert declared, "a descriptor that names no file describes nothing"
+    for relative in declared:
+        assert not Path(relative).is_absolute(), relative
+        assert ".." not in Path(relative).parts, relative
+        assert (bundle / relative).is_file(), f"declared but absent: {relative}"
+
+    entry = shipped.by_ref("shipped/finger")
+    assert entry.profile is not None
+    assert entry.profile.sensor_json_path == bundle / "sensor.json"
+    assert entry.valid and entry.start_blocked_reason is None, entry.reason
+    # The verdict is the SDK's, and the undeclared-asset failure is gone for good.
+    assert "assets.computational" not in entry.reason, entry.reason
+
+
+def test_the_declared_assets_are_the_files_the_running_chain_loads(shipped):
+    """The descriptor's asset paths and the live chain agree, file name included.
+
+    The finger chain builds its UV map cache name for itself, from the export directory and
+    ``camera.source_scale`` (the SDK's ``scaled_map_cache_path``). That derivation and the
+    descriptor are two statements of the same fact, so they are compared here: a bundle whose
+    map was renamed would otherwise keep resolving to the name the chain still asks for.
+    """
+    bundle = sensors_dir() / "finger"
+    profile = shipped.by_ref("shipped/finger").profile
+    assert profile is not None
+
+    export_dir = resolve_finger_export_dir(profile.sensor_json_path)
+    assert export_dir == bundle / "assets" / "30fps-0703"
+    chain_map = Path(
+        scaled_map_cache_path(
+            str(export_dir / "unroll_map_uv.npz"), profile.config["camera"]["source_scale"]
+        )
+    )
+    declared_map = profile.computational_assets["unroll_map"]
+    assert declared_map == chain_map
+    # The scale suffix is the configuration's (0.42), never a neighbouring variant.
+    assert declared_map.name == "unroll_map_uv_s0.42.npz"
+    assert declared_map.is_file()
+    assert not (export_dir / "unroll_map_uv_s0.4.npz").exists()
+
+    declared_scene = profile.assets["scene"]
+    assert declared_scene == bundle / "scene" / "finger-display-1.0.0.oryscene"
+    assert declared_scene.is_file()
+    assert profile.capabilities.visualization_3d.available
+
+
+def test_a_calibration_file_is_never_offered_as_a_configuration(shipped):
+    """``box/`` holds ``sensor.json`` and ``force_calibration.json``: one entry, not two."""
+    box = sensors_dir() / "box"
+    assert (box / "force_calibration.json").is_file(), "the premise of this test"
+    entries = shipped.entries_for_family("box")
+    assert len(entries) == 1, [entry.key for entry in entries]
+    assert Path(entries[0].key).name == "sensor.json"
+    for entry in shipped.entries:
+        assert Path(entry.key).name != "force_calibration.json"
+        assert "force_calibration" not in entry.folder
+
+
+def test_the_user_root_is_absent_today_and_that_is_not_an_error(shipped):
+    """Nothing is offered from a user root that does not exist, and no error is raised.
+
+    W2 will import bundles into that root; when it does, this assertion is the one to revisit —
+    the point being that an absent root is empty, not broken.
+    """
+    assert shipped.user_root_kind in (ROOT_KIND_SIBLING, ROOT_KIND_FALLBACK)
+    assert shipped.user_root_exists is False, shipped.user_root
+    assert shipped.entries_for_origin(shipped.roots[1].origin) == ()
+    # The shipped root is never the place user bundles go.
+    assert shipped.shipped_root != shipped.user_root
+    assert shipped.shipped_root not in shipped.user_root.parents
+
+
+# ------------------------------------------------------------------ rename contract
+def _copy_finger(destination: Path, *, descriptor: bool = True) -> Path:
+    """Copy the shipped finger bundle, optionally stripping its descriptor."""
+    shutil.copytree(sensors_dir() / "finger", destination)
+    if not descriptor:
+        (destination / "manifest.json").unlink()
+    return destination
+
+
+def test_a_renamed_bundle_keeps_its_identity(tmp_path):
+    """The descriptor's relative paths are what make moving or renaming a bundle safe."""
+    root = tmp_path / "bundles"
+    first = _copy_finger(root / "finger-a")
+    second = _copy_finger(root / "somewhere-else-entirely")
+    assert first.name != second.name
+
+    catalog = scan_sensor_catalog(
+        shipped_root=tmp_path / "no-shipped-root", user_root=root
+    )
+    a = catalog.by_ref("user/finger-a")
+    b = catalog.by_ref("user/somewhere-else-entirely")
+    assert a is not None and b is not None
+    assert a.valid and b.valid, (a.reason, b.reason)
+
+    assert a.profile_id == b.profile_id == FINGER_PROFILE_ID
+    assert a.product_family == b.product_family == "finger"
+    assert a.processing_backend == b.processing_backend == "uv_unroll"
+    assert a.display_name == b.display_name
+    assert a.profile.processing_fingerprint == b.profile.processing_fingerprint
+    # The reproducible snapshot is bundle-relative, so the folder name cannot appear in it.
+    assert a.profile.inventory() == b.profile.inventory()
+    inventory = a.profile.inventory()
+    assert inventory["sensor_config"] == "sensor.json"
+    assert inventory["computational_assets"]["unroll_map"]["path"] == (
+        "assets/30fps-0703/unroll_map_uv_s0.42.npz"
+    )
+    assert inventory["visualization_assets"]["scene"] == (
+        "scene/finger-display-1.0.0.oryscene"
+    )
+    assert str(tmp_path) not in json.dumps(inventory)
+
+    # Every resolved path stays inside the copy it was resolved from.
+    for entry, copy in ((a, first), (b, second)):
+        inside = copy.resolve()
+        assert entry.profile.bundle_root == inside
+        assert entry.profile.sensor_json_path.is_relative_to(inside)
+        for role, path in entry.profile.computational_assets.items():
+            assert path.is_file(), role
+            assert path.is_relative_to(inside), path
+        for role, path in entry.profile.assets.items():
+            assert path.is_relative_to(inside), path
+
+    # One profile, two bundles: the catalog names the twin instead of picking one silently.
+    assert a.key != b.key
+    assert a.duplicates == ("user/somewhere-else-entirely",)
+    assert b.duplicates == ("user/finger-a",)
+    assert a.start_blocked_reason is not None
+
+
+def test_the_same_copy_without_a_descriptor_is_refused_by_its_folder_name(tmp_path):
+    """The negative control: rename a *legacy* bundle and it is no longer identifiable."""
+    plain = _copy_finger(tmp_path / "finger-a", descriptor=False)
+    with pytest.raises(DescriptorError) as failure:
+        resolve_bundle(plain)
+    assert "not a built-in bundle" in str(failure.value)
+
+    catalog = scan_sensor_catalog(
+        shipped_root=tmp_path / "no-shipped-root", user_root=tmp_path
+    )
+    entry = catalog.by_ref("user/finger-a")
+    assert entry is not None, "a bundle that cannot be resolved is still listed"
+    assert not entry.valid
+    assert "not a built-in bundle" in entry.reason
+    assert entry.start_blocked_reason == entry.reason