DataManager, UserFunctions and ConfigurationSaver

Three infrastructure components: one distributes acquired data, one lets user code hook into the acquisition, one persists the model to CFG and USR files.

hSI.hDataManager

scanimage.components.DataManager. It receives each acquired stripe and turns it into the scanimage.mroi.RoiData array that the display, the integration ROI manager and the motion manager all consume.

Member	Description
`hRoiDatas`	Read-only array of `scanimage.mroi.RoiData` for the current acquisition.
`hTranslator`	The object that maps stripes onto ROI data. Defaults to `scanimage.components.datamanager.DefaultTranslator`; `LightBeadsTranslator` and `MultiFastZTranslator` are used by the corresponding acquisition modes.
`hSI.hDataManager.setupROIData()`	Rebuild `hRoiDatas` for the current ROI group and channel selection.
`hSI.hDataManager.clearROIData()`	Clear it.
`hSI.hDataManager.stripeAcquired(stripeData)`	Entry point called by the imaging system for each acquired stripe.

Events

Event	Fires when
`RoiDataSetup`	`hRoiDatas` has been rebuilt - the ROI geometry or channel set changed.
`RoiDataUpdated`	New image data is available in `hRoiDatas`.
`HistogramDataUpdated`	New histogram data is available.

hL = most.ErrorHandler.addCatchingListener(hSI.hDataManager,'RoiDataUpdated', ...
     @(src,evt)myAnalysis(hSI.hDataManager.hRoiDatas));

Note

These events fire on the acquisition path. Anything slow in the callback shows up directly as display lag or dropped frames - do the heavy work off the callback, for example by buffering and processing on a timer.

hSI.hUserFunctions

scanimage.components.UserFunctions. User functions are the supported way to run your own code at defined points in the acquisition. They are stored with the configuration, so they travel with the experiment rather than living in a script.

Property	Description
`userFunctionsCfg`	`N x 1` struct array of user functions saved with the CFG file.
`userFunctionsUsr`	`M x 1` struct array of user functions saved with the USR file.

Each entry has the fields EventName, UserFcnName, Arguments and Enable.

s = struct('EventName','frameAcquired', ...
           'UserFcnName','myFrameCallback', ...
           'Arguments',{{}}, ...
           'Enable',true);
hSI.hUserFunctions.userFunctionsCfg(end+1) = s;

Your function is called as myFrameCallback(src,evt,varargin), where varargin is whatever you put in Arguments.

Warning

userFunctionsCfg and userFunctionsUsr are in DENY_PROP_LIVE_UPDATE - they cannot be changed during an acquisition, not even through the focus abort-and-restart fallback.

Events

Every event below can be hooked. They are declared on UserFunctions and fired by the components that own the corresponding behavior.

Event	Fires when
`applicationOpen`	ScanImage has finished starting up.
`applicationWillClose`	ScanImage is about to close.
`acqModeArmed`	A GRAB or LOOP mode is armed and waiting for a trigger.
`acqModeStart`	A GRAB or LOOP mode has started.
`acqModeDone`	A GRAB or LOOP mode has completed.
`acqStart`	A new acquisition within an ongoing GRAB / LOOP has started.
`acqDone`	A GRAB, or one iteration of a LOOP, has completed.
`acqAbort`	A GRAB or LOOP was aborted.
`focusStart`, `focusDone`	A FOCUS acquisition started or completed.
`frameAcquired`	A frame has been acquired.
`sliceDone`	One slice of a multi-slice acquisition has completed.
`overvoltage`	The digitizer reported an overvoltage condition.
`lostFrames`	Frames were dropped while logging.
`motionCorrected`	ScanImage moved an actuator to correct motion.
`motorPositionUpdate`	The motor position has, or may have, changed.
`cfgFileSaved`, `cfgFileLoaded`	A configuration file was saved or loaded.
`cycleDataGroupDone`	A cycle data group finished its last iteration.
`onDmdStimStart`, `onDmdStimSingleComplete`, `onDmdStimComplete`, `onDmdStimExtSel`	On-demand photostimulation lifecycle.
`seqStimStart`, `seqStimAdvance`, `seqStimSingleComplete`, `seqStimComplete`	Sequence photostimulation lifecycle.
`photostimAbort`	The photostimulation module aborted.

hSI.hConfigurationSaver

scanimage.components.ConfigurationSaver. Saves and restores the publicly settable properties of the ScanImage model - not the hardware configuration, which lives in the machine data file.

Member	Description
`cfgFilename`	Read-only. Path of the currently loaded CFG file.
`hSI.hConfigurationSaver.cfgSaveConfig()`	Save to the currently loaded CFG file.
`hSI.hConfigurationSaver.cfgSaveConfigAs(fname,transientSave)`	Save to a named or interactively chosen file. `transientSave` skips updating the remembered “last configuration” path.
`hSI.hConfigurationSaver.cfgLoadConfig(fname,transientLoad)`	Load a CFG file. With no arguments it opens a file dialog.

hSI.hConfigurationSaver.cfgLoadConfig('C:\configs\two_color.cfg');
% ... change settings ...
hSI.hConfigurationSaver.cfgSaveConfigAs('C:\configs\two_color_v2.cfg');

The cfgFileSaved and cfgFileLoaded user function events fire around these operations, which is a convenient place to apply settings that are not themselves saved.