orisys-app/apps/studio/docs/sensor-bundles.md

# 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.

## Picker rows

A configuration row in the sensor dialog is **the bundle's name and nothing else**: the
descriptor's `display_name` when there is one, otherwise the folder name (`box`, `mini`, `finger`,
`finger-mems`, and whatever the operator called their own folder). Everything else — the origin,
the resolved root, the `profile_id`, the bundle shape, the SDK's verdict with what it means, the
calibration selection and every finding — is written in the details surface directly under the
selector, where the sentences fit.

One exception: two entries offered together that would otherwise read alike each get a suffix.
Across roots that is the origin (`Box (shipped)` beside `Box (user)`); when one root supplies both
(for example one `display_name` declared by two folders) the origin cannot separate them and the
folder is used instead. Nothing is collapsed or shadowed, and the same tree always produces the
same rows.

## 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` | 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).