Scan2D: Imaging Systems

scanimage.components.Scan2D is the abstract base class of every ScanImage® imaging system. The active one is hSI.hScan2D; all configured ones are in hSI.hScanners, and each also gets a dynamic property on hSI named after it (hSI.hResScan, hSI.hLinScan, …).

Subclass	Description
`scanimage.components.scan2d.ResScan`	Resonant + galvo scanning on National Instruments hardware.
`scanimage.components.scan2d.LinScan`	Galvo-galvo (linear) scanning on National Instruments hardware.
`scanimage.components.scan2d.RggScan`	Resonant-galvo-galvo scanning on the vDAQ. Supports resonant and linear modes.
`scanimage.components.scan2d.SlmScan`	Spatial light modulator based scanning, usually paired with a linear scanner.

hSI.hScan2D.scannerType      % 'RGG', 'Resonant', 'Linear', ...
hSI.hScan2D.hasResonantMirror
hSI.hScan2D.hasXGalvo

Geometry and coordinate system

Member	Description
`hCSZAffineLut`	The scanner’s coordinate system, a CSZAffineLut parented to reference space. This is the modern replacement for `scannerToRefTransform`. See ScanImage Coordinate System Instances.
`scannerToRefTransform`	Legacy 3x3 affine from scanner space to reference space. Kept for backwards compatibility.
`nominalFovCornerPoints`	The scanner’s own field of view corners, in scanner space.
`pts = hScan2D.fovCornerPoints(zRef)`	Field of view corner points in reference space at a given reference z.
`hPts = hScan2D.getNativeFovCornerPoints(zRef)`	The same points as a `Points` object in the scanner’s coordinate system.

Timing and sampling

Property	Description
`sampleRate`	Sample rate of the digitizer and mirror control, in Hz.
`maxSampleRate`	Maximum sample rate the imaging system supports.
`pixelBinFactor`	Acquisition samples per pixel. LinScan only.
`scannerFrequency`	Resonant scanner frequency in Hz. Read-only.
`linePhase`	Phase delay of the fast mirror position, in seconds.
`bidirectional`	Form a line during the fast mirror flyback.
`fillFractionSpatial`	Fraction of the scan field used to form a line.
`fillFractionTemporal`	Dependent, read-only. The corresponding temporal fill fraction.
`settleTimeFraction`	Fraction of `fillFractionTemporal` reserved for the fast mirror to settle.
`flybackTimePerFrame`	Seconds allowed for the galvos to fly back after each frame.
`flytoTimePerScanfield`	Seconds allowed for the galvos to fly between scanfields.
`scanPixelTimeMean`	Mean acquisition time of one pixel.
`scanPixelTimeMaxMinRatio`	Ratio of longest to shortest pixel acquisition time within a line.
`stripingEnable`	Refresh the display in stripes rather than whole frames.
`tfSinusoidalX`	The X scanner follows a sinusoidal rather than a sawtooth waveform.

Channels

Property	Description
`channelsAvailable`, `physicalChannelsAvailable`	Number of channels on the digitizer.
`channelsInputRanges`	Cell array of `[min max]` input ranges, one per channel.
`channelsAvailableInputRanges`	Cell array of the ranges the digitizer supports.
`channelOffsets`	Offsets subtracted from image data, in native units.
`channelsSubtractOffsets`	Per-channel logical: subtract the offset or not.
`channelsAutoReadOffsets`	Measure the offsets automatically at the start of an acquisition mode.
`channelsAdcResolution`, `channelsDataType`	ADC resolution in bits and the data type of the samples.
`channelsFilter`	Channel filter setting, where the hardware supports one.

offsets = hSI.hScan2D.measureChannelOffsets();   % measure and apply dark offsets
means   = hSI.hScan2D.measureMeanSignal(1000);   % mean signal over N samples

Triggering

Property	Description
`trigAcqInTerm`	Terminal for the acquisition start trigger.
`trigNextInTerm`	Terminal for the next-file trigger.
`trigStopInTerm`	Terminal for the stop trigger.
`trigAcqEdge`, `trigNextEdge`, `trigStopEdge`	`'rising'` or `'falling'`.
`trigNextStopEnable`	Enable next / stop triggering.

hSI.hScan2D.trigAcqInTerm = 'D1.0';
hSI.extTrigEnable = true;
hSI.startGrab();                       % waits for the external trigger

% or trigger in software
hSI.hScan2D.trigIssueSoftwareAcq();
hSI.hScan2D.trigIssueSoftwareNext();
hSI.hScan2D.trigIssueSoftwareStop();

Logging

Property	Description
`logFilePath`	Directory the Tiff files are written to.
`logFileStem`	Base file name, without extension.
`logFileCounter`	Number appended to the base name. Incremented per acquisition.
`logFramesPerFile`	Frames per file before rolling over. `Inf` writes one file.
`logFramesPerFileLock`	Lock the frames-per-file value.
`logOverwriteWarn`	Warn before overwriting an existing file.

Logging itself is enabled with hSI.hChannels.loggingEnable.

Devices attached to a scanner

Property	Description
`hFastZs`	The FastZ actuators paired with this scanner.
`hBeams`	The beam modulators paired with this scanner.
`hShutters`	The shutters in this scanner’s light path.
`hSlmScan`	The `SlmScan` paired with this scanner, if any.
`hDataScope`	The data scope object, for raw sample inspection.
`scannerset`	Read-only `scanimage.mroi.scannerset.ScannerSet` describing the scanner combination. It is what the waveform manager uses to turn ROIs into control waveforms.

Shutter and beam helpers on the scanner act on exactly those devices:

hSI.hScan2D.openShutters();
hSI.hScan2D.openExcitationShutters();
hSI.hScan2D.closeShutters();
hSI.hScan2D.activateBeams(true);

Scanner positioning

These are abstract on Scan2D and implemented by every subclass.

Method	Description
`hScan2D.centerScanner()`	Drive the galvos and resonant scanner to zero.
`hScan2D.pointScanner(fastDeg,slowDeg)`	Point the XY scanner at a position, in optical degrees.
`hScan2D.parkScanner()`	Park the scanner and deactivate the resonant scanner.

Events

scannersetChanged fires - debounced - whenever the scanner set settles after a change. Prefer it over a PostSet listener on scannerset, which fires far more often and forces an expensive recomputation on every consumer.

hL = most.ErrorHandler.addCatchingListener(hSI.hScan2D,'scannersetChanged', ...
     @(varargin)disp('scanner configuration changed'));