ScanImage Scripting API

ScanImage is fully scriptable using Matlab’s command window and/or user defined functions. This article describes the ScanImage Application Programming Interface (API) and how to use it to automate ScanImage and extend ScanImage’s functionality.

ScanImage Architecture

The ScanImage architecture is based on the Model-View-Controller design pattern. The application’s logic and hardware control is accessed via hSI, the ScanImage handle.

hSI grants the user access to the ScanImage components, the building blocks of an acquisition. This includes Matlab handles to hardware devices (PMTs, shutters, beam modulators, etc.), configuration managers (ROI manager, waveform manager, motion, etc.), imaging systems, etc.

ScanImage’s GUI is accessible through the handle hSIGui, which is split up into a left panel, middle panel, and right panel.

The left panel contains the basic acquisition settings and more advanced options are available depending on experiment requirements. The middle panel contains the viewport (where the acquisition can be visualized in space) and the auxiliary panel (for configuring and using helpful features). The right panel stores the widget bar for quick visual device information and access.

---

Basic Functionality

hSI lives in the base workspace whenever ScanImage is running. Everything below assumes it is in scope; inside a user function you get it from src.hSI.

hSI.acqState                     % 'idle', 'focus', 'grab', 'loop', 'loop_wait', 'point'
hSI.hScan2D.name                 % the active imaging system
hSI.hRoiManager.scanFrameRate    % frames per second at the current settings

hSI.startFocus();                % live view, nothing logged
hSI.abort();

hSI.startGrab();                 % one acquisition
hSI.startLoop();                 % hSI.acqsPerLoop acquisitions

The start methods return immediately once the acquisition is armed. They do not block until it finishes - to run code at the end of an acquisition, hook the acqModeDone event rather than polling.

See also

hSI: Acquisition Control for the full set of properties and methods on hSI itself, and Component API for the components underneath it.

---

Recipes

Configure and run a logged acquisition

The properties are spread over several components: resolution and zoom on the ROI manager, file names on the imaging system, the logging switch and channel selection on the channels component.

% geometry and resolution
hSI.hRoiManager.pixelsPerLine  = 512;
hSI.hRoiManager.linesPerFrame  = 512;
hSI.hRoiManager.scanZoomFactor = 2;

% channels
hSI.hChannels.channelDisplay = [1 2];
hSI.hChannels.channelSave    = [1 2];

% where the files go
hSI.hScan2D.logFilePath    = 'C:\data\2026-09-04';
hSI.hScan2D.logFileStem    = 'mouse01_fov1';
hSI.hScan2D.logFileCounter = 1;
hSI.hChannels.loggingEnable = true;

% how much to acquire
hSI.hStackManager.enable     = false;
hSI.hStackManager.framesPerSlice = 500;

hSI.startGrab();

Note

Not every property can be changed while an acquisition is running. Setting one that cannot be during a focus makes ScanImage abort, apply, and restart the focus; during a grab or loop the change is refused with a message. See Component Framework.

Acquire a fast volume

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       = 30;
hSI.hStackManager.stackZStepSize  = 3;      % microns
hSI.hStackManager.numVolumes      = 100;

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

fprintf('%.2f volumes/s\n',hSI.hRoiManager.scanVolumeRate);
hSI.startGrab();

See also

FastZ and StackManager.

Run code on every frame

Register a user function on frameAcquired. Guard on endOfFrame - with striping enabled the event can fire on a partial frame.

function meanIntensityUserFcn(src,evt,varargin)
    hSI = src.hSI;
    sd  = hSI.hDataManager.lastStripeData;

    if isempty(sd) || ~sd.endOfFrame
        return
    end

    for idx = 1:numel(sd.roiData)
        hRd   = sd.roiData{idx};
        chIdx = find(hRd.channels == 1);
        if isempty(chIdx); continue; end

        img = hRd.imageData{chIdx}{1}.';    % channel first, z second, transposed
        fprintf('frame %d  roi %s  mean %.1f\n', ...
            sd.frameNumberAcqMode, hRd.hRoi.name, mean(img(:)));
    end
end

Register it from the command window:

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

Warning

This runs on the acquisition path. Keep it short, and watch sd.stripesRemaining - if it grows, your callback is too slow and frames will be dropped. Buffer and process on a timer instead.

See also

Acquisition Data Structures for the shapes of StripeData and RoiData.

Move the stage and image a list of positions

positions = [0 0 0; 200 0 0; 200 200 0; 0 200 0];   % sample-relative microns

for idx = 1:size(positions,1)
    hSI.hMotors.moveSample(positions(idx,:));       % blocking

    hSI.hScan2D.logFileStem = sprintf('tile_%02d',idx);
    hSI.startGrab();

    while ~strcmpi(hSI.acqState,'idle')
        pause(0.05);
    end
end

For anything beyond a handful of positions, use hSI.hTileManager or hSI.hCycleManager rather than a loop like this - they handle settling, ordering and metadata.

Convert a point between coordinate systems

Any position in ScanImage is a Points object plus the coordinate system it lives in. Converting is one call.

hCSs = hSI.hCoordinateSystems;

% a point 1 optical degree off-center in the current scanner's space
hPt = scanimage.mroi.coordinates.Points(hSI.hScan2D.hCSZAffineLut,[1 0 0]);

hPtRef    = hPt.transform(hCSs.hCSReference);        % optical degrees, um in z
hPtSample = hPt.transform(hCSs.hCSSampleRelative);   % microns

fprintf('that point is at %.1f %.1f %.1f um in the sample\n',hPtSample.points);

% drive the stage so that point sits under the objective
hSI.hMotors.move(hPtSample);

See also

Coordinate System API, and ScanImage Coordinate System Instances for what each named space means.

Build an MROI ROI group

hRoiGroup = scanimage.mroi.RoiGroup();

for idx = 1:3
    hSf = scanimage.mroi.scanfield.fields.RotatedRectangle();
    hSf.centerXY           = [(idx-2)*2, 0];
    hSf.sizeXY             = [1.5 1.5];
    hSf.pixelResolutionXY  = [256 256];
    hSf.rotationDegrees    = 0;

    hRoi = scanimage.mroi.Roi();
    hRoi.add(0,hSf);                 % scanfield at z = 0

    hRoiGroup.add(hRoi);
end

hSI.hRoiManager.roiGroupMroi = hRoiGroup;
hSI.hRoiManager.mroiEnable   = true;

See also

RoiGroup and Roi API and RotatedRectangle API.

Drive an output from an integration ROI

Online analysis with a closed loop: the integration ROI manager computes traces, a post-processing function transforms them, and the configured output channels emit them.

hSI.hIntegrationRoiManager.enable        = true;
hSI.hIntegrationRoiManager.postProcessFcn = @thresholdPostProcess;

function integrationValues = thresholdPostProcess(rois,integrationDone,arrayIndices, ...
        integrationValueHistory,integrationTimestampHistory,integrationFrameNumberHistory)
    integrationValues = integrationValueHistory(arrayIndices);
    integrationValues = double(integrationValues > 100);   % simple threshold
end

See also

IntegrationRoiManager.

Batch process logged files

The readers give you the header as a struct whose field names mirror the live property paths, so analysis code reads the same way whether it is live or offline.

files = dir('C:\data\2026-09-04\*.tif');

for idx = 1:numel(files)
    fname = fullfile(files(idx).folder,files(idx).name);

    % header only - fast, does not read image data
    header = scanimage.util.opentif(fname);

    fprintf('%s: %dx%d px, %.2f fps, %d slices\n', fname, ...
        header.SI.hRoiManager.pixelsPerLine, ...
        header.SI.hRoiManager.linesPerFrame, ...
        header.SI.hRoiManager.scanFrameRate, ...
        header.SI.hStackManager.actualNumSlices);
end

% MROI data with its ROI geometry
[roiData,roiGroup,header] = scanimage.util.getMroiDataFromTiff(fname);

See also

Acquisition Metadata for the full header map and the list of readers.

Talk to a device directly

Every device is a named resource. This works with ScanImage running or closed.

hRS = dabs.resources.ResourceStore();

% everything in an error state
hBad = hRS.filter(@(h)~isempty(h.errorMsg));
cellfun(@(h)fprintf('%s: %s\n',h.name,h.errorMsg),hBad);

% a specific PMT, through the device API rather than the component
hPmt = hRS.filterByName('PMT1');
hPmt.setGain(0.55);
hPmt.queryStatus();
fprintf('gain %.2f V, tripped %d\n',hPmt.gain_V,hPmt.tripped);

Warning

Writing to a channel or device that ScanImage has reserved fights with whatever is driving it. Check hResource.reserved first, and prefer doing this while ScanImage is idle.

See also

dabs Device API.

React to a change instead of polling

Component properties are observable. Use most.ErrorHandler.addCatchingListener rather than addlistener, so an error in your callback cannot break the acquisition.

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

% ... later
delete(hL);

Some components offer a debounced event that is cheaper than a PostSet listener - prefer hSI.hMotors’s samplePositionChanged and hSI.hScan2D’s scannersetChanged where they exist.

See also

The most Framework.