hSI: Acquisition Control

hSI is the instance of scanimage.SI created when ScanImage® starts, and is the entry point for everything else in this section. It is itself a component, so it follows the same live-update rules as the components it owns.

Starting and stopping

Method	Description
`hSI.startFocus()`	Start a FOCUS acquisition. Nothing is logged. Runs for `focusDuration` seconds, indefinitely when that is `Inf`.
`hSI.startGrab()`	Start a GRAB acquisition: one acquisition of the configured number of frames, volumes or slices, logged if `hSI.hChannels.loggingEnable` is set.
`hSI.startLoop()`	Start a LOOP acquisition: `hSI.acqsPerLoop` independently started acquisitions.
`hSI.startCycle()`	Start the acquisition through hSI.hCycleManager.
`hSI.abort()`	Stop whatever is running and return every component to idle.
`hSI.scanPointBeam()`	Park the scanner at the center of the field of view and open the excitation shutters. Sets `acqState` to `'point'`. Not permitted during focus.

hSI.hChannels.loggingEnable = true;
hSI.hScan2D.logFilePath   = 'C:\data';
hSI.hScan2D.logFileStem   = 'experiment_01';
hSI.hScan2D.logFileCounter = 1;

hSI.startGrab();

Warning

The start methods return as soon as the acquisition has been armed - they do not block until it finishes. To run code when an acquisition completes, use the acqModeDone user function event rather than polling.

State

Property	Description
`hSI.acqState`	One of `'idle'`, `'focus'`, `'grab'`, `'loop'`, `'loop_wait'`, `'point'`. Read-only in practice.
`hSI.active`	True when an acquisition is running and initialization has completed.
`hSI.acqInitDone`	True once the current acquisition mode has finished initializing.

Acquisition settings

Property	Description
`acqsPerLoop`	Number of independently started acquisitions in LOOP mode.
`loopAcqInterval`	Seconds between LOOP triggers when self-triggering.
`focusDuration`	Seconds to focus for. `Inf` focuses until aborted. Can be changed live.
`extTrigEnable`	Enable the external triggering features of `hSI.hScan2D` for GRAB and LOOP.
`imagingSystem`	Name of the active imaging system. Setting it switches `hSI.hScan2D`.
`objectiveResolution`	Microns per optical degree, derived from `hSI.hMotors.hCSMicron.toParentAffine`. See ScanImage Coordinate System Instances.
`startUpScript`, `shutDownScript`	Scripts run when ScanImage starts and exits.
`mdlCustomProps`, `extCustomProps`	Extra properties to write into the acquisition header.
`useJsonHeaderFormat`	Write the Tiff header as JSON instead of the legacy format.

hSI.imagingSystem = 'ResScan';       % switch imaging systems by configured name
hSI.hScan2D                          % now the ResScan object

Scanners

Member	Description
`hSI.hScan2D`	The active imaging system, a `scanimage.components.Scan2D` subclass.
`hSI.hScanners`	Cell array of every configured `Scan2D`.
`hSI.hScanner(name)`	Look a scanner up by configured name, or by index into `hScanners`. With no argument returns `hScan2D`. Returns `[]` rather than throwing when not found.
`hSI.hSlmScan`	The active `SlmScan`, when one is configured.

ScanImage also adds a dynamic property per configured scanner, so a scanner named ResScan is reachable as hSI.hResScan.

cellfun(@(h)fprintf('%s (%s)\n',h.name,h.scannerType),hSI.hScanners);

Static utilities

Method	Description
`scanimage.SI.version()`	Version string of the installed ScanImage.
`scanimage.SI.cd()`	Change the MATLAB working directory to the ScanImage installation.
`scanimage.SI.code()`	Open the ScanImage source folder.
`scanimage.SI.isMdfCompatible(mdfPath)`	Check whether a machine data file can be loaded by this version.

Header and ROI metadata

str = hSI.getHeaderString();     % the acquisition header, as written into Tiff files
str = hSI.getRoiDataString();    % the serialized ROI group

Both are also embedded in logged files; see Output Files.