ScanImage® Utility Functions

Compute Resonant Scan Mask

Description: The ‘Compute Resonant Scan Mask’ utility is a MATLAB function that is provided to calculate how many samples are binned to form a pixel along a line in a raster scan. See Line Formation for an explanation of why this is done.

mask = scanimage.util.computeresscanmask(scanFreq, sampleRate, fillFractionSpatial, pixelsPerLine, bidirectional)

Input/Output Parameters:

scanFreq

The frequency with which the X-axis scanner makes a full oscillation of the mirror

sampleRate

The sampling rate of the acquisition DAQ analog input connected to the PMT(s)

fillFractionSpatial

The fraction scanner travel where pixels are acquired as a ratio of the optical degrees while acquiring to the total optical degrees range during the scan.

pixelsPerLine

Pixel resolution of the acquisition along the x-axis

mask

a vector of size pixelsPerLine where each row is the number of samples acquired for a pixel in a line

Daq Task Get Max Sample Rate

Description:

The ‘Daq Task Get Max Sample Rate’ utility is a MATLAB function that is provided as a workaround for the bug in DAQmx 9.8.0f3 where ‘sampClkMaxRate’ reports faster clock rates for multi-channel AOs than supported by hardware (observed with PCIe-6321).

rate = scanimage.util.daqTaskGetMaxSampleRate(hTask, numChans)

Input/Output Parameters:

hTask

‘hTask’

numChans

‘numChans’

rate

‘rate’

Details:

The following was communicated with NI:

Hardware: PCIe-6321, PXIe-6341

DAQmx version: 9.8.0f3

Problem description:

According to the specifications, the PCIe-632x and PXIe-634x support the following AO sample rates:

  • 1 channel: 900 kS/s

  • 2 channels: 840 kS/s per channel

  • 3 channels: 775 kS/s per channel

  • 4 channels: 719 kS/s per channel

When configuring an AO task with multiple channels on one of these cards, the maximum sample rate of 917431.19 Hz is returned by the property SampClock.MaxRate, regardless of the number of channels within the task.

Expected behavior: SampClock.MaxRate should return the maximum sample rate for the AO task that is actually achievable. (For AI tasks, this works already in DAQmx 9.8).

Setting a sample clock that is too high should coerce the value to an achievable rate and/or return an error.

Actual behavior: If the sample rate of a task with multiple AO channels is set to the value of SampClock.MaxRate, it will abort with error -200018: ‘DAC conversion attempted before data to be converted was available.’

Steps to reproduce:

Install a PCIe-632x or PXIe-634x. Open the attached VI. Run it with one channel -> no error occurs Configure 2 channels and start -> error -200018 occurs. Note that the maximum reported sample rate is incorrect (according to the specs). Workaround: Set the Sample Clock Reduction Factor to 0.92 and run the task again -> the task should be executable now.

Generate Multi-ROI Data From Tiff

Description:

The ‘Generate Multi-ROI Data From Tiff’ utility is a MATLAB function that extracts and returns a cell array of scanimage.mroi.RoiDataSimple objects containing information found in the given Tiff file.

Syntax:

scanimage.util.getMroiDataFromTiff()

scanimage.util.getMroiDataFromTiff(filename)

scanimage.util.getMroiDataFromTiff(filename, debugMode)

[roiDataCellArray] = scanimage.util.getMroiDataFromTiff(...)

[roiData, roiGroup, header, imageData] = scanimage.util.getMroiDataFromTiff(varargin)

Input/Output Parameters:

filename

‘filename’ is an optional parameter that states the fully qualified name of the ScanImage® Tiff file to open. It can be supplied with or without the .tif extension. If ‘filename’ is omitted, a dialog is launched to allow interactive selection.

debugMode

‘debugMode’ is an optional flag that indicates whether (true) or not (false) to display detailed information about the Tiff.

roiDataCellArray

‘roiDataCellArray’ stores the generated cell array of scanimage.mroi.RoiDataSimple objects that contain information found in the Tiff file.

roiData

‘roiData’ stores the generated cell array of scanimage.mroi.RoiDataSimple objects that contain information found in the Tiff file.

roiGroup

‘roiGroup’

header

‘header’ stores image header information extracted from the Tiff file.

imageData

‘imageData’ stores the raw image data extracted from the Tiff file.

Details: TODO (NEED MORE INFO??)

The ‘Generate Multi-ROI Data From Tiff’ utility currently only supports RG-mode ROIs information. If the TIFF file indicates that MROI mode was not enabled, the function returns a warning and an empty roiData cell array.

Previous versions of this utility did not support Step-FastZ when using non-default Zs.

Generate ROI Data From Image

Description:

The ‘Generate ROI Data From Image’ utility is a MATLAB function that generates a roiDataSimple object from an image using a provided “default” RoiGroup. If more than one image is supplied, It assumes those images are all consecutive slices in the same volume, and assigns the appropriate stack-Z values.

Syntax:

[roiData] = scanimage.util.genRoiDataFromImage(imgData, defaultRoiGroup)

[roiData roiGroup] = scanimage.util.genRoiDataFromImage(imgData, defaultRoiGroup)

Input/Output Parameters:

imgData

‘imgData’ contains a 2-Dimensional array containing image data.

defaultRoiGroup

‘defaultRoiGroup’ contains the desired roiGroup to use.

roiData

‘roiData’ stores the cell array of a single scanimage.mroi.RoiDataSimple object. The cell array contains the combined information from the image and the defaultRoiGroup.

roiGroup

‘roiGroup’ stores the roiGroup used (see ‘defaultRoiGroup’ parameter above).

Generate a ScanImage® Report

Description:

The ‘Generate ScanImage® Report’ utility is a report generator function for sending to ScanImage® Support.

Syntax:

scanimage.util.generateSIReport(attemptSILaunch, filename)

Input/Output Parameters:

attemptSILaunch

‘attemptSLaunch’ is a boolean value that indicates whether (true) or not (false) ScanImage® should be launched if not already running.

filename

‘filename’ is the fully qualified name of the zip file where the Report data is to be placed.

Details: The ‘Generate ScanImage® Report’ utility launches ScanImage, if indicated and needed, and generates a set of files packaged together in a zip file, with the given filename.

Information included in the report:

<filename>.cfg

ScanImage® binary configuration file.

<filename>.user

ScanImage® binary user file.

<filename>_NIMAX.zip

Compressed file containing extensive NI information generated using the NI’s reporting API.

<filename>_temp.mat

A MATLAB file that can be used to browse through the report information in MATLAB.

Machine_Data_File.m

Machine data file configured for the version of ScanImage® running at the time the report is produced.

TiffHeader.txt

Configuration and ScanImage® settings data collected from the current running ScanImage® instance at the time the report is generated. This is the information placed in a Tiff file when saving scanned images to a Tiff.

mSessionHistory.txt

MATLAB session history.

mFullSession.txt

MATLAB full session information.

NIMAX Information:

  • NI Installation Logs and Summary

  • NI MAX Logs

  • NI MAX Schema Log

  • NI MAX Reports

  • NI Services Status

  • NI Configuration Settings

  • VISA Configuration Settings

Open Tiff

We provide two different methods for opening Tiff files produced by ScanImage. The ScanImageTiffReader is the fastest way of loading whole volumes, and provides some minimal functionality for extracting metadata. The scanimage.util.opentif() provides more functionality for decoding and loading metadata into Matlab, but is not currently optimized for quickly loading image data.

ScanImageTiffReader is a command line tool and library for extracting data from Tiff and BigTiff files recorded using ScanImage. It is a very fast tiff reader and provides access to ScanImage-specific metadata. Interfaces to the library are provided for Python, Matlab and Julia . This library should actually work with most tiff files, but as of now we don’t support compressed or tiled data.

scanimage.util.opentif() A Matlab function included with ScanImage® that decodes metadata information contained in a ScanImage® Tiff file.

Syntax:

scanimage.util.opentif()
scanimage.util.opentif(filename, flagN/flagNArg)
header = scanimage.util.opentif(filename, flagN/flagNArg)
[header, Aout] = scanimage.util.opentif(filename, flagN/flagNArg)
[header, Aout, imgInfo] = scanimage.util.opentif(filename, flagN/flagNArg)

Input/Output Parameters:

filename

the fully qualified name of the Tiff file

flagN/flagNArg

Optional Flags (string-valued) and/or flag/value pairs, in any order, specifying options to use in opening the specified file. The flag values are case-insensitive.

  • ‘channel’ or ‘channels’: Argument specifies subset of channel(s) to extract. Ex: 1,[1 3], 2:4.

  • ‘frame’ or ‘frames’: Argument specifies subset of frames present to extract. Use ‘inf’ to specify all frames above highest specified value. Ex: 1:30, [50 inf], [1:9 11:19 21 inf]

  • ‘slice’ or ‘slices’: Argument specifies subset of slices present to extract. Use ‘inf’ to specify all slices above highest specified value. Ex: 1:30, [50 inf], [1:9 11:19 21 inf]

  • ‘volume’ or ‘volumes’: Argument specifies subset of volumes present to extract. Use ‘inf’ to specify all slices above highest specified value. Ex: 1:30, [50 inf], [1:9 11:19 21 inf]

header

‘header’

Aout

‘Aout’

imgInfo

‘imgInfo’ contains basic information about images existent in the given Tiff file: number of images.

Details: This utility opens the given ScanImage® Tiff file, extracting its header information and sequential image data, and, if specified, stores all of the image contents in the output array Aout. In the case where a Tiff file name is not specified, a dialog is launched to allow interactive selection. In the case where ‘Aout’ is specified, a matrix of the size M x N x C x F x S x V is created, where: - C spans the channel indices, - F spans the frame indicies, - S spans the slice indices, and - V the volume indices.

Otherwise, the image file is not actually read; thus, only header information is extracted.

In cases where an error(s) is encountered, the program will attempt to output whatever image data is available to it as an uncategorized stream of images. This stream will be an array of the form M x N x (number of images), raw output without any post-processing, containing all the frames found within the file.

‘imgInfo’ contains the following information:

  • number of channels

  • number of bytes per pixel

  • number of lines per frame

  • number of slices

  • number of volumes

  • number of frames

  • the tiff filename

  • the ScanImage® version

Pulse Generator

Description:

The ‘Pulse Generator’ utility is a MATLAB class that provides functions to simulate a clock. For instance, it could be used to generate a simulated resonant mirror sync pulse.

Syntax: Object creation:

pgObj = pulseGenerator(varargin)

Constructor Parameters: (optional)

Device

Device name as defined in the Machine_Data_File.m.

Number of Channels

Number of Channels

Frequency

Frequency

Destination

Destination

Start Flag

Indicator to determine whether (true) or not (false) …

Name

Name

Methods:

'set.freq()'
'set.destination()'
'start()'
'stop()'
'delete()'

Read Photostim Monitor File

Description: The ‘Read Photostim Monitor File’ utility is a MATLAB function that is provided …

Syntax:

out = scanimage.util.readPhotostimMonitorFile(filename)

Input/Output Parameters:

filename

‘filename’

out

‘out’

Read ROI Group From Appended Tiff Data

Description: The ‘Read ROI Group From Appended Tiff Data’ utility is a MATLAB function that is provided …

Syntax:

[hMroiRoiGroup,hStimRoiGroups,hIntegrationRoiGroup] = scanimage.util.readRoiGroupFromAppendedTiffData(filename, header)

Input/Output Parameters:

filename

‘filename’

header

‘header’

hMroiRoiGroup

‘hMroiRoiGroup’

hStimRoiGroups

‘hStimRoiGroups’

hIntegrationRoiGroup

‘hIntegrationRoiGroup’

Reset Class Data Files

Description: The ‘Reset Class Data Files’ utility is a MATLAB function that is provided to remove the configuration of preferences and components. This is accomplished by removing the classData.mat files.

Syntax:

scanimage.util.function resetClassDataFiles(dataDir)

Input/Output Parameters:

dataDir

‘dataDir’

Details:

Resetting the Class Data Files will result in the following files being deleted along with the configuration files above:

  • Deleted file - C:SI+mostprivateAPIWrapper_classData.mat

  • Deleted file - C:SI+mostprivateHasMachineDataFile_classData.mat

  • Deleted file - C:SI+scanimage+components+scan2dprivateLinScan_classData.mat

  • Deleted file - C:SI+scanimage+componentsprivateConfigurationSaver_classData.mat

  • Deleted file - C:SI+scanimage+componentsprivatePhotostim_classData.mat

  • Deleted file - C:SI+scanimage+guisprivateAlignmentControls_classData.mat

  • Deleted file - C:SI+scanimage+guisprivateRoiGroupEditor_classData.mat

  • Deleted file - C:SI+scanimage+guisprivateStartupConfig_classData.mat

  • Deleted file - C:SI+scanimageprivateSIController_classData.mat

  • Deleted file - C:SI+scanimageprivateSI_classData.mat

  • Deleted file - C:SI+scanimageprivateStartupConfig_classData.mat

  • Deleted file - C:SIConfigDataMotors_classData.mat

  • Deleted file - C:SIConfigDataResScan_ResScanner_classData.mat

Reset DAQ Devices

Description:

The ‘Reset Daq Devices’ utility is a MATLAB function that is provided to reset DAQ devices directly from matlab if it is suspected that they are malfunctioning.

Syntax:

scanimage.util.function resetDaqDevices()

Input/Output Parameters:

NA

Simulate a Resonant Mirror

Description:

The ‘Resonant Mirror Sim’ utility is a MATLAB class that provides functions to simulate a resonant mirror

Directory Location:

<ScanImage® Application Directory>/+scanimage/+util/

Syntax: Object creation:

rmsObj = scanimage.util.ResMirrorSim(hSI, scanner, dev)

Constructor Parameters:

hSI

hSI

scanner

scanner

dev

dev

Methods:

  • set.phase(phase)

  • set.cyclePeriod(period)

  • resonantScannerOutputVoltsUpdated()

  • writeAnalogData(hTask, ao)

  • delete()

Translate Trigger To Port

Description: The ‘Translate Trigger To Port’ utility is a MATLAB function that is provided …

Syntax:

[digitalLineStr, portNumber, lineNumber] = scanimage.util.translateTriggerToPort(triggerLine)

Input/Output Parameters:

triggerLine

‘triggerLine’

digitalLineStr

‘digitalLineStr’

portNumber

‘portNumber’

lineNumber

‘lineNumber’


Calculate AD951X configuration parameters

Description: The AD951X clock multiplier device has an evaluation board for each of its versions and iterations which are particularly useful for multiplying an external clock to provide a synchronized clock signal that DAQs can readily synchronize to.

For a tutorial on how to use these values, see section Using the AD951X

This function will calculate and print to the command window each of the following parameters needed to configure the AD951X board in the evalutation software

  • divider divisor combinations for ports using the VCO divider and dividers 0,1, or 2

  • divider divisor combinations for ports using the VCO divider and dividers 3 and 4

  • ACounter for setting the VCO frequency

  • BCounter for setting the VCO frequency

Syntax:

[dividerCombos012,dividerCombos34, ACounter, BCounter] = scanimage.util.AD951XCalculator(desiredOutputFrequency_MHz,inputFrequency_MHz)

Input/OutputParameters:

desiredOutputFrequency_MHz

The desired clock frequency to be output from any of the AD951X ports in Megahertz

inputFrequency_MHz

The frequency of the clock that should be multiplied or buffered in Megahertz

dividerCombos012

matrix of divisors that will work. Column 1 is VCO divisors, Column 2 is divider 0,1, or 2 divisors. Each row is a collection of values that together will provide the desired output frequency

dividerCombos34

matrix of divisors that will work. Column 1 is VCO divisors, Column 2 is divider 3 divisors. Column 3 is divider 4 divisors. Each row is a collection of values that together will provide the desired output frequency

A Counter

This is the scalar value that should be input as the A counter Value in the N Divider window

B Counter

This is the scalar value that should be input as the B counter Value in the N Divider window