Channels and Display

Two components share responsibility for what you see: hSI.hChannels decides which channels are acquired, displayed and saved, and hSI.hDisplay owns the channel windows and the frame buffers.

hSI.hChannels

scanimage.components.Channels. Channel settings are stored per imaging system, so switching hSI.imagingSystem restores that system’s channel configuration.

Property	Description
`channelDisplay`	Array of channel numbers currently displayed.
`channelSave`	Array of channel numbers currently logged to disk.
`channelsActive`	Read-only. Channels that are displayed or saved.
`channelName`	Cell array of channel name strings.
`loggingEnable`	Enable file logging for GRAB and LOOP acquisitions.
`channelOffset`	Dependent. Offsets subtracted from image data, in native units.
`channelSubtractOffset`	Dependent. Per-channel logical: subtract the offset or not.
`channelInputRange`	Dependent. Cell array of `[min max]` input ranges.
`channelAvailableInputRanges`	Dependent, read-only. Ranges the digitizer supports.
`channelAdcResolution`	Read-only, in bits.
`frameAverageTau`	Per-channel exponential averaging time constant, in seconds.
`alpha`	Read-only. The exponential smoothing coefficient derived from `frameAverageTau` and the current frame timing.
`loggingSmoothing`	Per-channel flag: apply exponential smoothing to the data being logged.
`useFrameTimestampsForAveraging`	When true, the averaging coefficient uses the measured frame timestamps; when false it uses the ideal, constant frame period. Set it to false when running online analysis on averaged data, so that a hiccup in MATLAB’s frame retrieval cannot look like a signal transient.
`imagingSystemSettings`	Struct holding the saved channel settings for each imaging system.

hSI.hChannels.channelDisplay = [1 2];
hSI.hChannels.channelSave    = 1;
hSI.hChannels.loggingEnable  = true;

% 3-frame-time exponential average on channel 1, for display and logging
tau = 3 * hSI.hRoiManager.scanFramePeriod;
hSI.hChannels.frameAverageTau(1) = tau;
hSI.hChannels.loggingSmoothing(1) = true;

Methods

Method	Description
`hSI.hChannels.registerChannels()`	Re-read the channel count and capabilities from the active imaging system.
`hSI.hChannels.saveCurrentImagingSettings()`	Store the current channel settings into `imagingSystemSettings` for the active imaging system.

hSI.hDisplay

scanimage.components.Display.

Display behavior

Property	Description
`frameAverageFactor`	Number of frames averaged for display.
`alpha`	Exponential smoothing coefficient for the displayed frame data.
`displayRollingAverageFactorLock`	Lock the display average factor to the logging average factor.
`volumeDisplayStyle`	`'3D'`, `'Tiled'` or `'Current'`.
`selectedZs`	Z values to show. Empty shows all.
`autoScaleSaturationFraction`	`[black white]` fraction of pixels driven into saturation by auto scaling.
`channelsMergeEnable`	Update the channel merge window.
`channelsMergeFocusOnly`	Update the merge window only while focusing.
`renderer`	`'auto'`, `'painters'` or `'opengl'`.
`lineScanHistoryLength`	Number of lines retained in the line-scan display.
`roiDisplayEdgeColor`, `roiDisplayEdgeAlpha`	Appearance of ROI edges in the display.
`roiProjectionDisplayEdgeColor`, `roiProjectionDisplayEdgeAlpha`	Appearance of ROI projection edges.
`mouseHoverInfo`	Read-only struct describing what the cursor is currently over in the ROI display.

Scanfield displays

Property	Description
`enableScanfieldDisplays`	Enable the scanfield display window.
`scanfieldDisplays`	Struct array, one entry per display, with fields `enable`, `name`, `channel`, `roi` and `z`.
`showScanfieldDisplayNames`	Draw the scanfield names.
`scanfieldDisplayTilingMode`	`'Auto'`, `'Set Columns'` or `'Set Rows'`.
`scanfieldDisplayColumns`, `scanfieldDisplayRows`	Tiling size for the corresponding mode.

Reading acquired data

Property / method	Description
`lastFrame`	Cell array holding the most recent frame for each channel.
`lastAveragedFrame`	Cell array holding the most recent averaged frame for each channel.
`lastFrameChannels`	Channel number for each entry of `lastFrame`.
`lastFrameTimestamp`	Timestamp of `lastFrame`.
`lastFrameNumber`, `lastFrameNumberAcquisition`	Frame number overall and within the current acquisition.
`hRoiData = hSI.hDisplay.getRoiDataArray()`	The current `scanimage.mroi.RoiData` array - image data together with the ROI geometry it belongs to. This is the right entry point for MROI-aware analysis.

% grab the most recent frame of the first displayed channel
img = hSI.hDisplay.lastFrame{1};

% ROI-aware access
hRoiData = hSI.hDisplay.getRoiDataArray();
for idx = 1:numel(hRoiData)
    fprintf('%s: %d channels\n',hRoiData(idx).hRoi.name,numel(hRoiData(idx).channels));
end

Note

For per-frame processing, prefer the frameAcquired user function event over polling lastFrame. The user function fires exactly once per frame.

Window control

Method	Description
`hSI.hDisplay.channelAutoScale(ch,pixels)`	Auto-scale the lookup table of a channel.
`hSI.hDisplay.resetActiveDisplayFigs(preserveCameraProps)`	Reset the display windows of all active channels.
`hSI.hDisplay.resetDisplayFigs(chansToReset,resetMergeTF,preserveCameraProps,deactivatedChans)`	Reset selected channel windows.
`hSI.hDisplay.saveCameraProps()` / `restoreCameraProps(chansToReset)`	Save and restore the 3D camera position of the channel windows.