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: |
|
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.
|
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 |