Looking for up-to-date ScanImage documentation? That has moved here: docs.scanimage.org

This documentation is for a legacy ScanImage version. The current documentation is ScanImage 2019.
Skip to end of metadata
Go to start of metadata


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 automat ScanImage and extend ScanImage's functionality.


View the complete documentation of the ScanImage 2019 API

Table of content


ScanImage architecture

The ScanImage architecture is based on the Model-View-Controller design pattern. This architecture divides the software into three parts:

 DescriptionAccess Via
ModelApplication logic and hardware controlhSI
ViewGUI - display model statehSICtl
ControllerGUI - glue layer to manipulate modelhSICtl

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

Inspect the ScanImage startup script

Find the following section in the startup script:

scanimage startup script excerpt

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:

Access ScanImage from the Matlab command prompt

This command returns the current acquisition state of ScanImage. Next type:

Access ScanImage from the Matlab command prompt

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.


If you have questions about the ScanImage API, a specific method or property, or how to perform a specific task in ScanImage using the API, please create a support ticket at support.vidriotech.com or contact us at support@vidriotech.com.


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

Automated Grab
Accessing the API help


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)

Frame Acquired Callback

The default ScanImage image format is in row-major order, while Matlab uses column-major order for images. To display ScanImage frames in Matlab, they need to be transposed first.

Defining a user function for the event 'frameAcquired'

  • No labels