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.