ScanImage architecture
The ScanImage architecture is based on the Model-View-Controller design pattern. This architecture divides the software into three parts:
| Description | Access Via | |
|---|---|---|
| Model | Application logic and hardware control | hSI |
| View | GUI - display model state | hSICtl |
| Controller | GUI - glue layer to manipulate model | hSICtl |
This architecture ensures a strict separation between program logic and GUI. In principle, ScanImage can be run without a GUI. To get a better understanding of the concept, inspect the scanimage startup script. In the Matlab command window, type
>> edit scanimage
Find the following section in the startup script:
try
hSI = scanimage.SI(mdf);
hSI.initialize();
hSICtl = scanimage.SIController(hSI);
hSICtl.initialize(usr);
assignin('base','hSI',hSI);
assignin('base','hSICtl',hSI.hController{1});
catch ME
...
Note that two objects are created: hSI and hSICtl; hSI is the ScanImage model and contains all program logic to control the microscope hardware, acquire frames and log data. Once the model is started and initialized, the GUI (hSICtl) is launched and initialized. Finally, both object handles are assigned in the base workspace to give the user direct access to ScanImage via the Matlab command window.
When a control in the GUI is changed, the controller manipulates the model accordingly. When the state of the model changes, the controller's event listeners notice the change and update the GUI. However, the model can be manipulated and queried directly by the user as well. As a first example, type the following command into the Matlab command window:
>> hSI.acqState ans = idle
This command returns the current acquisition state of ScanImage. Next type:
>> hSI.hRoiManager.scanZoomFactor = 10;
Note that the appropriate control in the GUI is updated accordingly.
ScanImage API
ScanImage is organized in multiple components (stored in the folder scanimage\components) that are managed by the class +scanimage\SI.m. To access the documentation for a component, locate the component in the Matlab file overview and press 'F1'. This will launch the Matlab help that gives an overview of all publicly accessible properties and methods of the component.
The following example illustrates an automated ScanImage acquisition:
- move the stage to a desired position
- determine the path for saving the acquired data
- set the zoom factor
- set the number of frames to acquire
- start the acquisition
function automatedGrab()
% example for using the ScanImage API to set up a grab
hSI = evalin('base','hSI'); % get hSI from the base workspace
assert(strcmpi(hSI.acqState,'idle')); % make sure scanimage is in an idle state
hSI.hMotors.motorPosition = [0 0 0]; % move stage to origin Note: depending on motor this value is a 1x3 OR 1x4 matrix
hSI.hScan2D.logFilePath = 'C:\'; % set the folder for logging Tiff files
hSI.hScan2D.logFileStem = 'myfile' % set the base file name for the Tiff file
hSI.hScan2D.logFileCounter = 1; % set the current Tiff file number
hSI.hChannels.loggingEnable = true; % enable logging
hSI.hRoiManager.scanZoomFactor = 2; % define the zoom factor
hSI.hRoiManager.framesPerSlice = 100; % set number of frames to capture in one Grab
hSI.startGrab(); % start the grab
end
Accessing a component's help within Matlab.
User Functions
ScanImage allows to execute User Functions at pre-defined ScanImage events. This helps to adapt ScanImage to the specific needs of the user. The example below shows a function that is configured to be executed on every new acquired frame. The function uses the ScanImage API to retrieve the frame. Further processing could be done to extract features in the image and control hardware (e.g. execute a stimulus or send a trigger)
function myFrameAcquiredCallback(src,evt,varargin)
hSI = src.hSI; % get the handle to the ScanImage model
% scanimage stores image data in a data structure called 'stripeData'
% this example illustrates how to extract an acquired frame from this structure
lastStripe = hSI.hDisplay.stripeDataBuffer{hSI.hDisplay.stripeDataBufferPointer}; % get the pointer to the last acquired stripeData
channels = lastStripe.roiData{1}.channels; % get the channel numbers stored in stripeData
for idx = 1:length(channels)
frame{idx} = lastStripe.roiData{1}.imageData{idx}{1}; % extract all channels
end
% the last frame for all channels stored in the cell array 'frame'
% now we can go on to process the data...
end
Defining a user function for the event 'frameAcquired'
