FastZ and StackManager

hSI.hFastZ drives the fast axial actuator; hSI.hStackManager defines what a stack or volume consists of and counts progress through it.

hSI.hFastZ

scanimage.components.FastZ.

Property	Description
`enable`	Enable FastZ stacking.
`hasFastZ`	Read-only. True when the active imaging system has a FastZ actuator.
`position`	Current FastZ position. This is what drives hCSFocus.
`waveformType`	The waveform the actuator follows.
`flybackTime`	Seconds allowed to ramp from the end of a volume back to its start.
`actuatorLag`	Acquisition delay of the actuator, in seconds.
`volumePeriodAdjustment`	Adjustment added to the nominal volume period when computing the sawtooth period.
`enableFieldCurveCorr`	Use FastZ to correct scanner field curvature.
`positionInterpolationAlgorithm`	Interpolation used to derive the per-frame z position.
`numDiscardFlybackFrames`	Frames discarded per flyback.
`numDiscardFlybackFramesForDisplay`	Frames discarded per volume for display purposes.
`discardFlybackFrames`	Logical: discard frames during flyback.

Method	Description
`hSI.hFastZ.move(hFastZ,position,force)`	Move a FastZ actuator to a position.
`hSI.hFastZ.park()`	Park the actuator.
`hSI.hFastZ.readTarget()`	Commanded position.
`hSI.hFastZ.readOutput()`	Position currently being output.
`hSI.hFastZ.readFeedback()`	Position read back from the actuator’s feedback channel.
`[toutput,desWvfm,cmdWvfm,tinput,respWvfm] = hSI.hFastZ.testActuator()`	Drive a test waveform and return the commanded and measured responses. The basis for actuator tuning.
`hSI.hFastZ.calibrateFastZ(silent)`	Run the FastZ calibration.
`hSI.hFastZ.wrapFastZs(hFastZs)`	Wrap device objects into the FastZ scanner objects the waveform manager uses.

hSI.hFastZ.enable = true;
hSI.hFastZ.flybackTime = 10e-3;

[t,desired,commanded,tIn,measured] = hSI.hFastZ.testActuator();
plot(t,commanded,tIn,measured);

hSI.hStackManager

scanimage.components.StackManager.

Defining the stack

Property	Description
`enable`	Enable stack acquisition.
`stackMode`	`scanimage.types.StackMode`: `slow` or `fast`.
`stackActuator`	`scanimage.types.StackActuator`: `motor` or `fastZ`.
`stackDefinition`	`scanimage.types.StackDefinition`: `uniform`, `bounded`, `arbitrary` or `calculator`.
`boundedStackDefinition`	`scanimage.types.BoundedStackDefinition`: `numSlices` or `stepSize` - which of the two is held fixed for a bounded stack.
`stackFastWaveformType`	`scanimage.types.StackFastWaveformType`: `sawtooth` or `step`.
`numSlices`	Z depths per acquisition.
`numVolumes`	Volumes per acquisition.
`stackZStepSize`	Microns between slices.
`framesPerSlice`	Frames acquired at each depth, for a slow stack.
`arbitraryZs`	Explicit list of z values, for an arbitrary stack.
`arbitraryZsAreSampleRelative`	Interpret `arbitraryZs` in sample-relative rather than reference coordinates.
`centeredStack`	Treat the current z as the center of the stack rather than its start.
`stackReturnHome`	Return to the starting z when the stack completes.
`closeShutterBetweenSlices`	Close the shutter between slices of a slow stack.
`useStartEndPowers`	Bounded stacks: ramp beam power between the start and end power.
`stageStackCalculator`, `fastZStackCalculators`	`scanimage.components.stackmanager.StackCalculator` objects used when `stackDefinition` is `calculator`.

Derived and status

Property	Description
`actualNumSlices`, `actualNumVolumes`, `actualStackZStepSize`	What the current configuration will really produce, after all constraints.
`numFastZActuators`	Number of FastZ actuators used.
`numFramesPerVolume`, `numFramesPerVolumeWithFlyback`	Frame counts per volume.
`stackZStartPos`, `stackZEndPos`	Bounded-stack bounds, in sample-relative coordinates.
`volumesDone`, `slicesDone`, `framesDone`	Live counters. `AbortSet` and observable, so they are cheap to listen to.

Methods

Method	Description
`hSI.hStackManager.setStackStart()` / `clearStackStart()`	Use the current z as the start of a bounded stack, or clear it.
`hSI.hStackManager.setStackEnd()` / `clearStackEnd()`	Use the current z as the end of a bounded stack, or clear it.

% a 100 um fast volume of 50 slices
hSI.hStackManager.enable          = true;
hSI.hStackManager.stackMode       = scanimage.types.StackMode.fast;
hSI.hStackManager.stackActuator   = scanimage.types.StackActuator.fastZ;
hSI.hStackManager.stackDefinition = scanimage.types.StackDefinition.uniform;
hSI.hStackManager.numSlices       = 50;
hSI.hStackManager.stackZStepSize  = 2;
hSI.hStackManager.numVolumes      = 10;

hSI.startGrab();

% follow progress
hL = most.ErrorHandler.addCatchingListener(hSI.hStackManager,'slicesDone','PostSet', ...
     @(varargin)fprintf('slice %d of %d\n', ...
         hSI.hStackManager.slicesDone,hSI.hStackManager.actualNumSlices));