ykcheungab
28e955a817
控制器经 AcquireGate / ImageSink / ShellNotes 与信号接线，采集 tick 用 acquire_presenter 上屏；三维测试证明分析结果已喂 3D 后，重算并入 on_analysis_requested。 验证：apps/studio 下相关 pytest 与 tools/ui_check.py（634 checks）通过。
60 lines
4.1 KiB
Markdown
60 lines
4.1 KiB
Markdown
# Sensor bundles
|
|
|
|
Every sensor configuration the Studio offers is a folder under `apps/studio/config/sensors/`
|
|
holding `sensor.json` — the processing configuration. `orisys_app_shared.sensors.bundle_catalog`
|
|
scans that folder and the writable user root beside it, and resolves each candidate through the
|
|
SDK's `orisys.sensors.resolve_bundle`, so the picker shows what the SDK decided rather than a
|
|
second opinion computed in the UI.
|
|
|
|
`finger/` also carries `manifest.json`, the bundle descriptor. A descriptor states the profile's
|
|
identity and its files instead of leaving both to be inferred, which is what lets the bundle keep
|
|
its meaning when the folder is moved or renamed.
|
|
|
|
## The finger descriptor
|
|
|
|
| Field | Value | Why |
|
|
|---|---|---|
|
|
| `schema_version` | `1` | The SDK's current descriptor schema (`CURRENT_DESCRIPTOR_SCHEMA`). |
|
|
| `profile_id` | `orisys.finger.r01` | The processing profile this folder is: finger design revision `r01`, whose unroll map and camera scale the configuration pins. Never a product-family name. |
|
|
| `display_name` | `Finger R01` | Shown in the picker. Excluded from the processing fingerprint. |
|
|
| `product_family` | `finger` | What the operator calls it. `finger-mems` is a different family on a different pipeline. |
|
|
| `processing_backend` | `uv_unroll` | The pipeline the finger actually runs: `FingerRuntime` builds a UV domain from the export's unroll map, then flow and force. |
|
|
| `sensor_json` | `sensor.json` | The configuration, still the only place camera, tracker and contact settings live. |
|
|
| `computational_assets.unroll_map` | `assets/30fps-0703/unroll_map_uv_s0.42.npz` | The map the chain loads. `finger_worker` derives that name for itself from the export folder and `camera.source_scale`, so the descriptor and the chain are checked against each other. Required: without it the profile fails. |
|
|
| `assets.scene` | `scene/finger-display-1.0.0.oryscene` | The compiled package the 3D pane draws. Visualization only: a missing one never blocks processing. |
|
|
|
|
Every path is relative to the bundle root, and the SDK refuses an absolute path or a `..` escape
|
|
when it parses the descriptor. `assets/visualization/` is deliberately left out of `assets`: it is
|
|
offline compiler input, the packaged build strips it, and nothing at runtime reads it.
|
|
|
|
`sensor.json` declares `"type": "single_camera"` while the descriptor says `uv_unroll`. With a
|
|
descriptor present the descriptor decides, and it is the truthful one — the finger path never
|
|
builds a single-camera processor. Do not "correct" `type`: it is part of the hashed configuration
|
|
(only `name`, `version` and `display_name` are skipped), so editing it would re-identify every
|
|
recorded finger pass and change no number.
|
|
|
|
## Compatibility keys
|
|
|
|
`name`, `assets_dir` and `viz_pose` are kept beside the descriptor fields — the shape this bundle
|
|
had before it carried a descriptor. They are relative too, so they do not weaken rename safety,
|
|
and they keep readers that never learned about the descriptor working:
|
|
|
|
| Key | Reader |
|
|
|---|---|
|
|
| `assets_dir` | `orisys/configs.resolve_sensor_bundle` → `resolve_sensor_asset_dir`, which `orisys.finger.exports` consults for a bundled export; `acquisition/geometry.py::describe_sensor_geometry`, the device-geometry check the 3D pane runs; `build/studio/build.ps1`, which checks the packaged copy; `orisys-sdk/examples/gui/viewer3d/presets.py`. |
|
|
| `viz_pose` | `orisys-sdk/examples/viz/mesh_camera.py`. |
|
|
| `name` | Nothing reads it today; it is kept because it belongs to the legacy shape. |
|
|
|
|
Dropping a key means migrating those readers first, not tidying up the JSON.
|
|
|
|
## Verification
|
|
|
|
`apps/studio/tests/test_sensor_catalog_root.py` asserts the descriptor's fields, that every
|
|
declared path is relative and present, that the declared map is the one the running chain derives
|
|
for itself (the SDK's `scaled_map_cache_path`, so `_s0.42.npz` and never a neighbouring
|
|
`_s0.4.npz`), and that a copy of the bundle under another folder name keeps its `profile_id`, its
|
|
processing fingerprint and all of its resolved paths inside the copy.
|
|
|
|
The descriptor grammar itself is owned by the SDK:
|
|
[orisys-sdk/docs/sensor-bundles.md](../../../../orisys-sdk/docs/sensor-bundles.md).
|