About this Documentation
ScanImage 3.7 is quite similar to 3.6. documentation describes changes and new features since ScanImage 3.6. Aside from these changes, the [ScanImage 3.6 Documentation] still applies.
Version Compatibility
Please note/follow the Matlab and NI version compatability information. Use of other versions will likely result in trouble. As discussed further below, it is possible to co-install ScanImage 3.7 with earlier ScanImage versions, by installing multiple Matlab versions on a machine. In such cases, DAQmx 8.8 should be used.
New Features in ScanImage 3.7
Major New Features
Other New Features
Upgrading from ScanImage 3.5 or 3.6 (Important Changes)
- 3.7 has a new model INI file
, which is thoroughly self-documenting. You should make a new standard.INI file based on this model, following the comments.
It is recommended to create a separate folder(s) for your INI/CFG/USR files under 3.7, to keep them separate from data files for any older version you may also maintain installed.
- The
Unknown macro: {blue}values are replaced byUnknown macro: {blue}values, in theUnknown macro: {report-info}dialog. They now represent the full-angle (peak-peak) of the scan range, specified in optical degrees, rather than half-angle as in 3.6 (and half-voltage of command signal in earlier versions). Therefore new values will generally be twice theUnknown macro: {blue}values in ScanImage 3.6.
In general, the new default
Unknown macro: {blue}values of 15 optical degrees should not often require modification by most users. If you see the field-of-view is different (smaller) than you're used to, look closely at theUnknown macro: {blue}value/notes in the INI file.
- If using two boards (i.e. second board for Pockels and/or new clock export signals), ScanImage 3.7 requires the clock synchronization between boards be on RTSI 7, not RTSI 6 as with ScanImage 3.6.
If running both 3.6 & 3.7 (see below), you should connect both RTSI 6 and RTSI 7(or connect all, with a ribbon cable).
If running both 3.5 & 3.7 (see below), no change is required
- The INI file now contains a
Unknown macro: {blue}value which should be set correctly to convert optical degree values specified in ScanImage to correctly scaled voltage commands. Please read the comments carefully!
If the
Unknown macro: {blue}value in 3.7 differs compared to yourUnknown macro: {blue}setting in 3.6 , you will need to (further) adjust yourUnknown macro: {blue}values compared to previousUnknown macro: {blue}values.
- The
Unknown macro: {blue}andUnknown macro: {blue}values that previously were specified as X & Y are now referred to as FAST & SLOW. A new control inUnknown macro: {report-info}dialog indicates mapping from X/Y to FAST/*SLOW*axes. Adjusting this allows you to rotate the image 90 degrees.
- The INI file now contains the separate mapping of X/Y to DA Channels 0 & 1 (
Unknown macro: {vi-statevar}values) which is fixed on initialization.
- It is recommended to copy your old CFG files to a separate folder for 3.7, and then load and re-save each of them individually. This will make your CFG files 3.7 compatible.
Note the
Unknown macro: {blue}values from 3.6 will not be applied in 3.7. The newUnknown macro: {blue}values should be adjusted before saving each CFG file.
Running ScanImage 3.7 together with earlier versions
You can run 3.7 together on same machine that is running 3.6.x or 3.5.x
- Typically, your newer Matlab will set path to 3.7 and older Matlab will set path to older version
- If running both 3.5/3.6 & 3.7 on same machine, DAQmx 8.8 is required. This is earliest version of DAQmx supported by 3.7, while 3.5/3.6 doesn't run on 8.9 or higher.
- Note that X series boards are only supported from 9.0 forward.
- Note that maintaining multiple Matlab versions on same machine does not require an additional license or count as an additional activation.
Major New Features
Power Adjustment During Stacks
When collecting image stacks in scattering tissue, the power level required at each slice in the stack generally increases with depth in order to maintain a fixed signal. ScanImage 3.7 can make this adjustment automatically, using a simple exponential length constant (Lz).
The
panel allows this capability to be enabled:
Renew your license to continue
Your evaluation license has expired. Contact your administrator to renew your Composition license.
ShowMe...">
Show Me...
From the
panel, ScanImage 3.7 also provides a facility to measure the Lz value suited for the given preparation:
Renew your license to continue
Your evaluation license has expired. Contact your administrator to renew your Composition license.
ShowMe...">
Show Me...
Frame/Line/Pixel Clock Export
ScanImage 3.7 introduces a Frame/Line/Pixel clock export feature intended to allow external hardware to be synchronized with start (or end) of each Frame, Line, or Pixel during image acquisition.
The
dialog controls the Frame/Line/Pixel clock feature:
Renew your license to continue
Your evaluation license has expired. Contact your administrator to renew your Composition license.
ShowMe...">
Show Me...
External triggering enhancements, including Next Triggering
ScanImage 3.7 has more options for external triggering. There are now two types of external triggers:
- Start Triggers: Trigger signals which initiate GRAB/LOOP acquisitions, when EXT is enabled in the
Unknown macro: {report-info}window
- Next Triggers: Trigger signals which stop or advance data file of ongoing GRAB/LOOP acquisition. They may also act as a Start trigger and initiate acquisitions.
External trigger signals to ScanImage are input on one of the PFI (programmable function interface) lines specified in the INI file as
and
. These specify the list of available trigger sources on a particular rig/setup.
The
dialog, accessed from Settings >> Triggers... on the
menu, allows selection of which trigger source to use:
Renew your license to continue
Your evaluation license has expired. Contact your administrator to renew your Composition license.
ShowMe...">
Show Me...
Enhanced User Functions capability
ScanImage 3.6 and earlier had some support for User Functions. The original implementation had a few critical limitations, however:
- Only one event – the end of a GRAB acquisition or LOOP repeat – lead to user function execution
- User functions were required to be on the Matlab search path
- No ability to pass arguments to the user functions, i.e. to modulate their function
ScanImage 3.7 re-implements User Functions to overcome these limitations. The new implementation makes use of the concept of events recently added to Matlab.
Renew your license to continue
Your evaluation license has expired. Contact your administrator to renew your Composition license.
ShowMe...">
Show Me...
Enhanced Fast Configurations
ScanImage 3.7 enhances the interface and capabilities of Fast Configurations – configurations which are configured to be rapidly loaded, at the touch of one key or one button. ScanImage users are encouraged to create several configurations, to represent each of the imaging/experimental modes they use.
The new Fast Configurations window is accessed via Settings >> User Functions... on the Main Controls menu:
: Launches file browser to select CFG file to attach to numbered (1-6) Fast Configuration
: Removes association of current file to particular numbered Fast Configuration
: Name of CFG file associated with particular numbered Fast Configuration (selected using
button)
Note that full path of selected file is stored/used. To see the full path of an already specified Fast Configuration, press button – the file selector dialog will start in the current file's directory (can hit Cancel to abort new selection).
Loading/Starting Fast Configurations
Fast Configurations are loaded (or auto-started, if applicable) in one of two ways:
- Press the desired Fast Configuration numbered button on the
window
- Press the <F1>-<F6> key (using CTRL at same time, if specified)
Six numbered buttons on the MAIN CONTROLS window are used to load (or optionally auto-start) specified Fast Configuration with one button. When is enabled for particular Fast Configuration, the button appears as green.
When is enabled, <SHIFT>+<F1-F6> or the right mouse button can be used to suppress the auto-start feature, i.e. to load the chosen fast configuration but not start acquisition immediately.
At present time, the feature's utility is somewhat limited by the fairly slow time (>500ms) to load a configuration. This is anticipated to improve in future ScanImage releases.
Continuous File Streaming Improvements
ScanImage 3.5 introduced continuous file streaming as an option for non-stack GRAB/LOOP acquisitions (i.e. acquisitions where # Slices=1). This feature saves files to disk as they are acquired, rather than waiting till the end of an acquisition to save the file. This permits unlimited, uninterrupted acquisitions.
ScanImage 3.7 now uses continuous file streaming for stack acquisitions and removes the ability to enable/disable continuous file streaming mode – this mode is now always used when AutoSave is checked in Main Controls:
AutoSave: When checked, continuous disk streaming is enabled, to the file <Basename><Acquisition #>.tif in the path specified by File >> Set Save Path...
As a consequence, ScanImage 3.7 no longer typically maintains a buffer in memory (RAM) of the entire acquisition. However, there are times when it is useful to data buffered in RAM, e.g. for online processing in User Functions so ScanImage 3.7 maintains a buffer of the most recent acquired frames in the
state variable (in the Matlab global workspace). This is the same variable that was used in ScanImage 3.6 (and earlier) to maintain a buffer of the entire acquisition; however the variable is now somewhat differently structured. The variable was previously a cell-array of 3-d arrays; in ScanImage 3.7, it is now a nested cell array of 2-D images (frames), indexed as follows:
>> state.acq.acquiredData{<FrameIndex>}{<ChannelIndex>}(<lineIndex>,<pixelIndex>)
where <FrameIndex> counts from the most recent frame.
The User Settings dialog (Settings >> User Settings... from Main Controls menu) has several relevant settings:
Max Buffered Frames (AutoSave ON): When AutoSave is ON, this specifies number of most recent frames to maintain in RAM (in the
variable).
Max Buffered Frames (AutoSave OFF): When AutoSave is OFF, this specifies number of most recent frames to maintain in RAM. Value of Inf implies to keep all frames of the acquisition, i.e. to buffer entire acquisition.
# Frames/File: Limits number of frames saved to each file – data is saved in chunks named <Basename><Acquisition #>_<ChunkIndex>.tif
In addition, there are two useful new settings:
Root Save Path: Specifies root folder to display when selecting File >> Set Save Path... to specify path for file-saving. E.g. can be C:\Data\MyName, so that search/specification of folder is faster.
Root Path is Default Path: Specifies that Root Save Path is the default save path if none other has been specified. Selecting this and saving to USR file loaded on subsequent startup avoids need to specify a save path (File >> Set Save Path...) on the first acquisition.
All settings in User Settings dialog are, unsurprisingly, User Settings, i.e. saved to USR files.
DAQ Toolbox No Longer Required
ScanImage 3.7 no longer requires use of the DAQ toolbox. Instead, it uses a Matlab class which wraps the NI DAQmx library. This approach has several advantages:
- Faster data read times are achieved (>4x faster), which increases amount of time available for user functions
- More comprehensive coverage of DAQmx features is achieved, compared to DAQ toolbox. For example, the DAQ toolbox does not support counter/timer channels which underlie several of the new features in ScanImage 3.7.
Other New Features
Finite LOOP acquisitions
In earlier versions, LOOP mode acquisitions were indefinite – the user was required to
the acquisition manually. In ScanImage 3.7, the
panel contains a new control specifying the
. LOOP acquisitions will automatically terminate after specified number of Repeats. The value Inf (default) can be entered to mimic the original, indefinite looping behavior.
Fractional zoom adjustment
In earlier versions, the
control in the
panel allowed the zoom value to be specified in only integer increments. ScanImage r3.7 now allows fractional zoom values, providing greater control over the scan range directly from the
panel.
The
value simply represents a division of (both) the
values in the
panel. For most users, the
values do not require modification – the
control should provide sufficient adjustment flexibility over the scanned range.
When a Scan Parameter Array is specified in the
panel, any non-integer
values are rounded to determine the scan parameters (
,
, and
) in effect at specified
.
Slider adjustment of power during FOCUS
In ScanImage 3.7, a new
control on the
panel allows the slider to be adjusted during [*FOCUS*], if selected:
The
control (rarely used) previously on the
panel has been relocated to the
dialog.
More image display colormap options
In earlier versions, the Image Display windows are always displayed with a grayscale colormap, with the possibility of displaying
In ScanImage 3.7, most Colormap controls are moved to the
panel. The
menu allows a wider selection of colormaps, including the Matlab jet colormap and options to display Channels 1 and 2 as red & green (in either order).
In addition, a user-specified colormap can be specified, for each Channel, in the
dialog.
Option to average binned samples
To date, ScanImage has summed the input samples obtained at each pixel of the scanned image (see Input Data Processing). The number of samples at each pixel is computed as the
, displayed on the
panel; its value is determined by the
,
, and
.
Some users may prefer to average, rather than sum, the samples obtained at each pixel. This makes the intensity values for each Image Display window (and hence the
and
levels that are appropriate) independent of the
(and hence the
,
, and
values).
ScanImage 3.7 adds an
control to select this option. See the
panel documentation.
Support for shutter located before Pockels
The Shutter control signal feature in earlier ScanImage versions assumed that shutter is located after any/all Pockels/modulators in system – i.e. a single shutter is used for all the Beams in use.
ScanImage 3.7 adds option for the Pockels/EOM to be located before the Pockels. This is most commonly used when there is only one beam. To select this option, the
value in the INI file should be set to 1.
The one & only effect of selecting this option is that shutter is opened/closed at start/end of Pockels calibration
One effect of the
value is that the beam is transmitted through to scope, and potentially specimen, during Pockels calibration. Careful attention should be paid to the
INI file values; the scanner is directed to this angle during Pockels calibration.
Ability to set root save file path
ScanImage requires that user select save path, via File >> Set Save Path... dialog on the
panel before a
acquisition with
selected.
ScanImage 3.7 speeds this folder selection by allowing the
to be specified as a User Setting in the
dialog. This path is used as the starting point for the folder selection dialog in File >> Set Save Path.... For instance, 'c:\data' or 'c:\data\<username>' might be specified as the
.