Rigs and Optical Library
Every recording is acquired by a physical imaging system — one or two cameras, a set of illumination sources, and the optical properties of each — and umIT needs to know which setup produced a dataset in order to interpret it correctly. Rig Manager is where that setup, called a Rig, is described and kept up to date: create a Rig, correct its hardware as your setup changes, and choose the Active rig. The Optical Library underneath it holds the spectral profiles and filter sets that any Rig's cameras and illuminations can reference, so the same physical component doesn't need to be redescribed for every Rig that uses it.
The rig library and the folder rig ledger
Rig information lives in two places with different roles:
- The rig library (this tool) belongs to one computer. It is used only to author rigs and to choose one: to bind a Save Folder to a rig, and to pick the rig of a dual-camera import.
- The folder rig ledger (UMITRigLedger.json, see Save Folder metadata files) belongs to each Save Folder. When a folder is bound to a rig, the ledger keeps a complete copy of the rig's optics and coregistration; it is the only rig information that analysis functions read. Editing, archiving or deleting a library rig therefore never changes the results of a folder that already uses it.
A folder is bound to a rig, or rebound, in DataViewer: Management > Rig > Folder Rig. AcqInfos.mat holds no rig information.
A Rig is not a Project
Rig identity is independent of Project/Subject/Session metadata. Project sessions do not store a rig; the Project Manager only displays the rig recorded in the session's Save Folder.
The Active rig
Exactly one rig of the library is Active; the others are Available or Archived. The Active rig is used:
- by a dual-camera import (ImagesClassification), whose folder is bound to the Active rig and coregistered with its active calibration;
- as the pre-selected choice when a rig must be picked, in DataViewer's Bind / Rebind Rig dialog and in the Camera Coregistration tool.
It is not used by analysis functions: they read the folder rig ledger. The Rigs table marks the Active rig in its Default column, and the Overview tab shows it as Default Rig: Yes. Set Active makes the selected Available rig the Active one; the previous Active rig becomes Available.
Open from DataViewer
Choose Management > Rig > Rig Manager... to administer Rigs: create new ones, correct or update their hardware, archive old configurations, choose the Active rig, and manage the Optical Library. To tell umIT which rig acquired the data of the loaded Save Folder, use Management > Rig > Folder Rig > Bind / Rebind Rig... instead (see Folder rig).
The Rig submenu: Folder Rig acts on the loaded Save Folder; Rig Manager administers the rig library.
Rig Management workspace
The main workspace follows the same left-list/right-detail layout as Project Manager. The top toolbar provides New Rig, Duplicate Rig, Refresh, and Optical Library on the left, and Validate with a Quick/Full mode selector and a compact RigID | Writable | Valid status readout on the right.
The Rigs table lists every Rig with its Default marker (the Active rig), display name, Rig ID, and state (Active, Available, Archived, or Invalid / unreadable). A Show archived Rigs checkbox controls whether archived Rigs appear in the list. Selecting a row opens that Rig below in a details panel with three tabs — Overview, Hardware, and Coregistration — and a row of contextual actions beneath the tabs: Save Details, Revert Details, Rename Rig ID..., Set Active (available for an Available rig), and Archive Rig / Restore Rig.
Built-in and newly created Rigs start with minimal information
A fresh Rig only carries the hardware identity and spectral profiles it needs to function — descriptive fields such as manufacturer, model, and serial number are left blank. Take the time to fill these in for your own equipment so each Rig's record stays meaningful once your lab has more than one.
The Overview tab of the Active rig, made from the OiS200 template. UUIDs are not shown here; they remain in an advanced/details role.
Overview tab
Overview exposes the descriptive fields that are safe to edit with low friction: Rig ID, Display Name, Description, Default Rig (whether this is the Active rig), State, and Created/Modified timestamps.
Hardware tab
Hardware separates the two device categories explicitly instead of exposing a generic metadata table.
Cameras
Camera 1 is always present and shown as the standard configuration: Display Name, Manufacturer, Model, Serial Number, and a required Spectral Profile with Select... and Preview actions.
Camera 2 is treated as an exceptional, opt-in configuration. For a single-camera Rig it collapses to a single Add second camera... action; the full Camera 2 field set (and a Remove Camera 2 action) only appears once a second camera has been deliberately added.
A single-camera Rig: Camera 2 is collapsed to one explicit action, and Illuminations use a compact table.
The built-in OiS200 Rig with Camera 2 already configured.
Illuminations
Red, Green, and Yellow illuminations are always presented as rows of one compact table (Illumination, Display Name, Manufacturer, Model, Spectral Profile) instead of three separate panels. The canonical Illumination names are read-only; descriptive fields and the spectral profile are editable while Hardware editing is active. Selecting a row shows a contextual line below the table (for example Red | Spectrum: Not selected) with Add / Replace..., Remove Spectrum, and Preview Spectrum actions. The spectral profile is never free-text; it is always chosen through the picker described under Optical Library below.
Staged hardware edits
Hardware fields are read-only until Edit Configuration is pressed, which stages changes locally (the status bar reports "Hardware edits are staged until Apply."). Pressing Apply checks that every configured camera has a spectral profile, then asks whether the change is a metadata correction to this Rig or a physical hardware change that should instead Duplicate as new Rig — because changing a camera's or illumination's physical spectral profile, or adding/removing Camera 2, can change how future analysis resolves that Rig. Choosing to duplicate follows the same flow as the toolbar's Duplicate Rig action, described below.
Coregistration tab
This tab exposes the same Rig-owned camera-coregistration resources managed by the Dual-Camera Coregistration tool, but only for review and lifecycle actions — Import..., Activate, Edit Details, Archive, Restore, and Purge — not for running a new calibration.
For a single-camera Rig the tab explains that coregistration only applies to dual-camera Rigs and keeps every action disabled:
Single-camera Rigs keep coregistration visible but inert.
For a dual-camera Rig the same tab becomes an active resource manager:
The OiS200 Rig has Camera 2 configured, so Import and the lifecycle actions are available.
Optical Library
The toolbar's Optical Library action switches the whole workspace to a dedicated view for resources shared across every Rig, with a Back to Rigs action to return. A category selector switches between Illumination Spectra, Camera Spectra, Filter Spectra, and Filter Sets; a search box filters by ID, name, origin, manufacturer, or model.
Selecting an entry plots its spectral response (here, the built-in green LED) and shows its metadata.
Built-in entries can never be removed. User-imported spectra can be removed with Remove User Spectrum unless another Rig still references them, in which case removal is refused and the reason is shown. Filter sets use Add New and Edit Selected instead of Import/Remove, and reject duplicate IDs.
The profiles of a filter set are fixed under its ID, because folders commit a filter set by ID and content. Edit Selected changes the display name in place. When you change an excitation or emission profile, the Rig Manager says so and offers Save as new filter set...: the Add dialog opens with the edited profiles and a free ID (for example MySet_2 for MySet), and the original filter set stays as it was. Folders that already used the original keep working.
Selecting a spectrum for a camera or illumination
The Select... action next to a camera's or illumination's Spectral Profile field opens a picker rather than a plain dropdown of IDs. The picker shows the profile ID, its metadata, whether it is built-in or user-imported, a spectral curve preview, and an Import New... action so a missing spectrum can be added without leaving the Rig you are configuring.
Importing a spectrum
Import New... accepts a plain text, CSV, or spreadsheet file with two numeric columns: wavelength in nanometers, and relative response (transmission, reflectance, or emission — whichever applies to that spectrum). A header row is fine; it is detected and skipped automatically. The source must cover the full 400–700 nm range with strictly increasing wavelengths and nonnegative, non-zero response values — it does not need to already be on a 1 nm grid, since it is resampled and normalized to a 0–1 peak on import.
For example, a manufacturer such as Semrock typically publishes a bandpass filter's transmission curve as a two-column CSV like this (illustrative values, not an exact reproduction of any specific datasheet):
Wavelength (nm),%Transmission 495.0,0.05 500.0,0.20 505.0,1.10 510.0,8.40 515.0,45.30 520.0,92.10 525.0,95.60 530.0,93.20 535.0,60.70 540.0,12.50 545.0,1.80
A file like this — as long as it extends out to cover 400 and 700 nm, even at near-zero transmission — imports directly as a camera, illumination, or filter spectrum.
Creating a new Rig
New Rig starts a guided flow instead of an empty form:
- Choose a starting point: the built-in OiS200 LightTrack Imaging System template, a Blank custom Rig, or Duplicate existing Rig.
- For the OiS200 template, confirm whether to include its optional second camera. For a blank custom Rig, configure Camera 1's (and optionally Camera 2's) spectral profile through the same picker used elsewhere.
- Enter Rig ID, Display Name, and Description.
- Decide whether the new Rig becomes the Active rig (asked only when no Active rig exists yet).
- Review a summary (ID, display name, camera/illumination counts, default status) before confirming Create Rig.
Every camera in the definition must have a spectral profile before creation proceeds; an incomplete configuration is rejected with a specific message naming the missing camera.
Duplicating a Rig
Duplicate Rig (and Duplicate existing Rig from the New Rig flow) creates a new, independent Rig starting from an existing one: its descriptive metadata, cameras, and illuminations are copied over under a new Rig ID, but it never inherits the source's Active status or its camera-coregistration history. Use this — rather than editing a Rig's hardware in place — whenever a physical change to your equipment should be tracked as a new Rig instead of overwriting the history of the one you already have.
Validation, archived, and invalid Rigs
Validate re-checks the selected Rig in Quick or Full mode and updates the RigID | Writable | Valid status text. A Rig that fails validation still opens so you can see what's wrong, but every control that could change it is disabled until the problem is resolved. Archived Rigs remain visible (toggle them with Show archived Rigs) and stay read-only until restored with Restore Rig; a restored Rig comes back as Available. The Active rig is marked in the Rigs table and only changes through Set Active, never by editing Rig metadata directly.
Archiving the Active rig
The library always keeps one Active rig. Archiving the Active rig therefore asks first for a replacement: after the confirmation, the Replacement Active Rig dialog lists the Available rigs; the chosen one becomes Active. Cancel leaves both rigs unchanged.
Choosing the rig that becomes Active when the Active rig is archived.
An archived rig can no longer be bound to a folder, and the Camera Coregistration tool refuses to save a calibration into it. Folders that already use it are not affected: their ledger keeps a copy of its optics.
Moving a rig to another computer
A rig can be copied to another computer as a self-contained .umitrig file. Rig Manager has no button for this; use the MATLAB command line:
% On the first computer:
store = UMITRigStore.openByRigID('RigA');
store.exportRig('C:\transfer\RigA.umitrig');
% On the other computer:
UMITRigStore.importRig('C:\transfer\RigA.umitrig');The file holds the rig, the spectra its cameras and illuminations use, and its camera-coregistration calibrations. Filter sets are not part of a rig and are not exported. The imported rig keeps its identity, so folders bound to it on the first computer show the same rig on the second. Spectra missing from the other library are added; a spectrum with the same ID but different content is refused. If a rig with the same identity or Rig ID already exists, pass 'NewIdentity', true or 'RigID', newID. The imported rig becomes Active only when the library has no Active rig; otherwise it is Available.