Skip to end of metadata
Go to start of metadata
Contents

Description


The Machine data file is a MATLAB .m file that contains parameters that describe the hardware configuration of your microscope.  These parameters are expected to rarely change.

It is only read when ScanImage starts; any change during an experiment requires a Matlab restart.

It is required for ScanImage to start.  If the file is missing, you'll be asked to configure or locate one.  For a fresh installation, choose to create a new file.  A new file will be opened in the Matlab editor, and parameters will be added with default values for you to customize.  Be sure to save the file after editing each section.

 

Icon

This file is automatically generated when ScanImage is started for the first time. When asked to locate the Machine Data File on Disk, choose 'Cancel' and select 'Create new file' in the following dialog.

Icon

While the file can be edited with a text editor, it is recommended to use the ScanImage Machine Configuration Editor.

Icon

If you change this file after starting ScanImage, a restart of ScanImage is required for the changes to take effect.

Icon

Save the Machine Data File in a folder named CONFIG at the root of your data directory. This is a good way to ensure that configuration data is backed up whenever the data directory is backed up.

Sections


SectionSection HeaderDescription
ScanImage%% ScanImageGeneral ScanImage behavior (for example, simulated mode).
Shutters%% ShuttersShutter(s) used to prevent any beam exposure from reaching specimen during idle periods.
Beams%% BeamsBeam control and calibration channels. Typically used to control Pockels cells.
ResScan%% ResScan (*ScannerName*)Resonant scanning imaging system
LinScan%% LinScan (*ScannerName*)Linear scanning imaging system (galvo/galvo scanning)
FastZ%% FastZFastZ hardware used for fast axial motion, supporting fast stacks and/or volume imaging.
Motors%% MotorsMotor used for X/Y/Z motion, including stacks. 
Photostim%% PhotostimPhotostimulation configuration.
IntegrationRoiOutputs%% IntegrationRoiOutputs

Configure channels to enable signal outputs based on real-time image analysis.

These outputs can facilitate closed loop experiments that respond to imaging data.

Thorlabs BScope2%% Thorlabs BScope2Thorlabs B-Scope 2 configuration.
Thorlabs ECU1%% Thorlabs ECU1Thorlabs ECU scanner configuration.
GenericPmtController%% GenericPmtControllerPMT Controllers
LSC Pure Analog%% LSC Pure Analog

Configure parameters for a stage controller that accepts an analog voltage position command signal

and optionally provides an analog position sensor feedback signal.

Icon

Section headings in the Machine Data File are significant. They indicate to ScanImage the relevant subsystem to configure. Sections headings are denoted using the MATLAB code-section syntax:

Parameters

ScanImage

 

ParameterDescription
scannerNames Cell array of scannerNames, names must follow convention of Matlab variables (avoid spaces and special characters)
scannerTypes Cell array indicating the type of scanner for each name. Current options: {'Resonant' 'Linear'}
simulatedallows starting ScanImage without any physical hardware present. Note: Simulated DAQ-hardware in MAX is still required.
componentsactivate plugins for specific hardware configurations (ThorECU1, ThorBScope2)
dataDirDirectory to store persistent configuration and calibration data.
objectiveResolutionResolution of the objective in microns/degree of the scan angle. A default value of 15 is provided.
startUpScriptUser defined script that is executed after ScanImage is started and initialized, just before the GUI is displayed.
Example

 

 

Shutters

Icon

Each Parameter of Shutters can be configured as a (cell) array, so that different parameters can be configured for the shutters present in the microscope.
This section allows multiple shutters to be defined. Mapping the shutters to an imaging system is done in a later step. The example below shows the MDF configuration for two shutters. The shutters are controlled by DAQ cards named PXI1Slot3 and Dev2 (DAQ cards can be renamed using NI MAX). The shutters are connected to PFI12 on each respective breakout board for the two DAQs. The variable shutterOpenLevel tells ScanImage if the digital high voltage signal is open or closed. In the example, both shutters open with the high voltage signal. A shutter that closes with the high voltage signal would be configured as, false. Lastly, the example configures the open time for the shutters as 0.1. This time delays the initiation of the start of imaging to ensure that the shutter is fully open.

ParameterDescription
shutterNamesUser defined name for the shutter.
shutterDaqDevicesDAQ device name where the pin for the shutter is located
shutterChannelIDsChannel ID for each shutter. Default: 'PFI12'
shutterOpenLevellogic level that opens the shutter. Default: true
shutterOpenTimetime in seconds it takes the shutter to fully open
Example

 

 

Beams

ParameterDescription
beamDaqDevicesCell array of DAQ device names {'PXI1Slot4','Dev1',...} that control the shutters. For each device listed in the cell array, the section below needs to be duplicated, and x needs to be replaced by the index of the DAQ device (PXI1Slot4 has index 1, Dev1 has index 2)
beamDaqs(x).modifiedLineClockInan empty string ('') or one of PFI0..15 to which external beam trigger is connected. Leave empty if DAQ device is in main PXI chassis*
beamDaqs(x).frameClockInan empty string ('') or one of PFI0..15 to which external frame trigger is connected. Leave empty if DAQ device is in main PXI chassis*
beamDaqs(x).referenceClockInan empty string ('') or PFI14 to which external beam trigger is connected. Leave empty if DAQ device is in main PXI chassis*
beamDaqs(x).chanIDsArray of integers specifying AO channel IDs, one for each beam modulation channel. Length of array determines number of 'beams' on beamDaqDevice #x
beamDaqs(x).displayNamesString or cell string array of device name(s) containing beam modulation channels. If single string, applies to all channels in beamChanIDs
beamDaqs(x).voltageRangesScalar or array of values specifying voltage range to use for each beam. Scalar applies to each beam on beamDaqDevice #x
beamDaqs(x).calInputChanIDsArray of integers specifying AI channel IDs, one for each beam modulation channel on beamDaqDevice #x. Values of nan specify no calibration for particular beam
beamDaqs(x).calOffsets(optional) Array of beam calibration offset voltages for each beam calibration channel on beamDaqDevice #x
beamDaqs(x).calUseRejectedLightBoolean scalar or array for each calibration channel on beamDaqDevice #x, indicating if the photodiode measures the rejected light from the Pockels cell.
beamDaqs(x).calOpenShutterIDsArray of indices of shutters that need to be opened for the beam illuminating the photodiode.

*Remarks

Icon
  • Clock routing terminals (frame clock, line clock, reference clock) are not required if the beam DAQ board is inside the main PXI chassis
  • For ResScan, only the modified line clock terminal is required
  • For LinScan, the frame clock and the reference clock terminal are required (except the LinScan Aux device and the beam DAQ are connected via a RTSI bus)
  • For all systems a beam must be assigned to a scan path
Example

*Remarks

Icon
  • For all systems a beam must be assigned to a scan path. This is done by setting beamDaqID to the numeric DAQ ID defined in the Beams section.

ResScan

Configures the Resonant Scanning imaging system.

ParameterDescription
nominalResScanFreqnominal frequency of the resonant scanner, in Hz
beamDaqIDnumeric beam DAQ ID (as configured in section 'Beams') that controls Pockels cell(s) to be used with ResScan
shutterIDsnumeric shutter ID(s) (as configured in section 'Shutters') that need to open when imaging with ResScan
digitalIODeviceNamedevice used to import/export triggers and clocks. can be a DAQ device (usually the same as galvoDevice) or the FPGA ('RIOx')
fpgaModuleTypeFlexRIO FPGA module used with ResScan (usually 'NI7961' or 'NI7975') 
digitizerModuleTypeFlexRIO Adapter module used with ResScan (usually 'NI5732' or 'NI5734')
rioDeviceIDname of FlexRIO FPGA adapter module as configured in NI-MAX (usually 'RIO0')
channelsInverttrue/false indicating if polarity of PMT output is inverted
externalSampleClocktrue/false indicating if FlexRIO FPGA adapter module is synchronized to external clock (i.e. laser sync clock)
externalSampleClockRateif externalSampleClock = true nominal rate of external clock in Hz (e.g. 80MHz)
galvoDeviceNameName of DAQ device controlling the (x/)y galvo(s)
galvoDeviceFrameClockInif galvo device is outside PXI chassis, configure terminal that imports the frame clock (e.g. 'PFI0')
galvoAOChanIDX(optional, for multi-ROI mode) AO channel number on Galvo DAQ device that controls the X-Galvo
galvoAOChanIDYAO channel number on Galvo DAQ device that controls the Y-Galvo
xGalvoAngularRange(optional, for multi-ROI mode) full range of x-Galvo in optical degrees (find value)
yGalvoAngularRangefull range of y-Galvo in optical degrees (find value)
galvoVoltsPerOpticalDegreeX(optional, for multi-ROI mode) galvo conversion factor from optical degrees to volts (find value)
galvoVoltsPerOpticalDegreeYgalvo conversion factor from optical degrees to volts (find value)
galvoParkDegreesX(optional, for multi-ROI mode) Park angle for X-Galvo in optical degrees
galvoParkDegreesYPark angle for Y-Galvo in optical degrees
resonantAngularRangefull range of resonant scanner in optical degrees (find value)
resonantZoomDeviceNameName of DAQ device controlling the resonant scanner amplitude (zoom)
resonantZoomAOChanIDAO channel number on resonant scanner DAQ device that controls the resonant scanner amplitude zoom)
rScanVoltsPerOpticalDegreefull range of resonant scanner in optical degrees (find value)
resonantScannerSettleTimetime in seconds needed for the resonant scanner to reach a stable oscillation

 

Example

*Remarks

Icon
  • For all systems a beam must be assigned to a scan path. This is done by setting beamDaqID to the numeric DAQ ID defined in the Beams section.

LinScan

Configures the LinScan imaging system (galvo/galvo scanning). Please review Configuring LinScan (Galvo Galvo scanning) for setup instructions.

ParameterDescription
deviceNameAcqDAQ device name used for PMT inputs
deviceNameGalvoDAQ device name used for Galvo control
deviceNameAuxDAQ device name used for trigger import/output and clock generatione
channelsInvertlogical scalar or array indicating if the polarity of the PMT outputs is inverted
beamDaqIDnumeric beam DAQ ID (as configured in section 'Beams') that controls Pockels cell(s) to be used with LinScan
shutterIDsnumeric shutter ID(s) (as configured in section 'Shutters') that need to open when imaging with LinScan
resScanframeClockInPFI line for importing the resonant scanning frame clock. Required for simultaneous imaging and photo stimulation monitoring/logging. Leave empty if galvo control DAQ is installed in PXI chassis.
referenceClockInPFI line for importing a 10MHz reference clock. Required for simultaneous imaging and photo stimulation monitoring/logging. Leave empty if galvo control DAQ is installed in PXI chassis.
enableRefClkOutputEnables/disables the export of the 10MHz reference clock on PFI14.
XMirrorPosChannelIDThe numeric ID of the Analog Input channel to be used to read the X Galvo position (optional).
YMirrorPosChannelIDThe numeric ID of the Analog Input channel to be used to read the Y Galvo position (optional).
XMirrorChannelIDAO channel ID on the Galvo control DAQ board that controls the X-Galvo
YMirrorChannelIDAO channel ID on the Galvo control DAQ board that controls the Y-Galvo
xGalvoAngularRangeFull range of the X-Galvo in optical degrees
yGalvoAngularRangeFull range of the Y-Galvo in optical degrees
scanParkAngleXPark position of the X-Galvo in optical degrees
scanParkAngleYPark position of the Y-Galvo in optical degrees
voltsPerOpticalDegreeXgalvo conversion factor from optical degrees to volts
voltsPerOpticalDegreeYgalvo conversion factor from optical degrees to volts
scanOffsetAngleXgalvo scan offset in optical degrees (can correct for small alignment issues)
scanOffsetAngleYgalvo scan offset in optical degrees (can correct for small alignment issues)
channelIDsArray of AI IDs on Acquisition DAQ board for PMT input. Leave empty for default value of [0,1,2,3]
deviceNameOffsetString identifying NI DAQ board that hosts the offset analog outputs.
XMirrorOffsetChannelIDNumeric ID of the Analog Output channel to be used to control the X Galvo offset.
YMirrorOffsetChannelIDNumeric ID of the Analog Output channel to be used to control the Y Galvo offset.
XMirrorOffsetMaxVoltageMaximum allowed voltage output for the channel specified in XMirrorOffsetChannelID
YMirrorOffsetMaxVoltageMaximum allowed voltage output for the channel specified in YMirrorOffsetChannelID
deviceNameGalvoFeedback 
internalRefClockSrc 
Example

 

 

FastZ

ParameterDescription

fastZControllerType

If supplied, one of {'useMotor2', 'pi.e665', 'pi.e816', 'npoint.lc40x'}

fastZCOMPort

Integer identifying COM port for controller, if using serial communication

fastZBaudRate

Value identifying baud rate of serial communication. If empty, default value for controller used.

fastZDeviceName

String specifying device name containig AI channel used for FastZ position sensor

frameClockIn

an empty string ("") or one of PFI0..15 to which external beam trigger is connected. Leave empty if the DAQ device is in the main PXI chassis.

fastZAOChanID

Scalar integer indicating AO channel used for FastZ control on the FastZ DAQ device

fastZAIChanID

Scalar integer indicating AI channel used for FastZ sensor on the FastZ DAQ device
Example

 

 

Motors

ParametersDescription

motorControllerType

If supplied, one of  {'thorlabs.bscope', 'sutter.mp285', 'sutter.mpc200', 'scientifica', 'pi.e665', 'pi.e816'}

motorDimensions

If supplied, one of {'XYZ', 'XY', 'Z'}. Defaults to 'XYZ'.

motorStageType

Some controller require a valid stageType be specified

motorCOMPort

Integer identifying COM port for controller, if using serial communication

motorBaudRate

Value identifying baud rate of serial communication. If empty, default value for controller used.

motorZDepthPositive

Logical indicating if larger Z values correspond to greater depth

motorPositionDeviceUnits

1x3 array specifying, in meters, raw units in which motor controller reports position. If unspecified, default positionDeviceUnits for stage/controller type presumed.

motorVelocitySlow

Velocity to use for moves smaller than motorFastMotionThreshold value. If unspecified, default value used for controller. Specified in units appropriate to controller type.

motorVelocityFast

Velocity to use for moves larger than motorFastMotionThreshold value. If unspecified, default value used for controller. Specified in units appropriate to controller type.

motor2ControllerType

If supplied, one of {'thorlabs.bscope', 'sutter.mp285', 'sutter.mpc200', 'scientifica', 'pi.e665', 'pi.e816'}

motor2StageType

Some controller require a valid stageType be specified

motor2COMPort

Integer identifying COM port for controller, if using serial communication

motor2BaudRate

Value identifying baud rate of serial communication. If empty, default value for controller used

motor2ZDepthPositive

Logical indicating if larger Z values correspond to greater depth

motor2PositionDeviceUnits

1x3 array specifying, in meters, raw units in which motor controller reports position. If unspecified, default positionDeviceUnits for stage/controller type presumed.

motor2VelocitySlow

Velocity to use for moves smaller than motorFastMotionThreshold value. If unspecified, default value used for controller. Specified in units appropriate to controller type.

motor2VelocityFast

Velocity to use for moves larger than motorFastMotionThreshold value. If unspecified, default value used for controller. Specified in units appropriate to controller type.

moveCompleteDelay

Delay in sceonds from when stage controller reports move is complete until move is actually considered complete. Allows settling time for motor

 

Example

 

 

PhotoStim

ParametersDescription
photostimScannerNameName of scanner (from the General ScanImage Settings section) to use for photostimulation. Must be a linear scanner.
BeamAiIdAI channel to be used for monitoring the Pockels cell output
loggingStartTrigger

The PFI terminal where the imaging frame clock is connected, to synchronize photostimulation with imaging.

This only needs to be specified if the photostimulation DAQ is not in same PXI Chassis as the imaging DAQ.


Example

 

 

IntegrationRoiOutputs

ParametersDescription
channelNamesUser defined name for each output channels e.g. {'My first channel','My second channel','My third channel'}
deviceNamesNames of DAQ device for each channel, use 'Software' if no physical device is used e.g. {'Dev1','Dev1',''}
deviceChannelsChannel index for each channel: numeric values for analog outputs, strings for digital outputs, use empty array for software output e.g {'PFI0', 'port0/line0', ''} for AO0, port0/line0 and a software output

 

Example

 

 

Thorlabs BScope2

ParametersDescription
scannerNameScanner name (from from the General ScanImage Settings section) to link to. Must be a resonant scanner. Leave empty if not using a resonant scanner.
ecuComPortNumeric: Serial COM port for ECU2 commands.
galvoGalvoMirrorComPortNumeric: Serial COM port for controlling Galvo-Galvo mirror. Leave empty is mirrors are connected to stage controller (MCM5000).
galvoResonantMirrorComPortNumeric: Serial COM port for controlling Galvo-Resonant mirror. Leave empty is mirrors are connected to stage controller (MCM5000).
flipperMirrorComPortNumeric: Serial COM port for controlling Camera PMT Flipper mirror. Leave empty is mirrors are connected to stage controller (MCM5000).
pmtDevAddressesNumeric serial number or string VISA addresses of USB PMT controllers. For each of 4 PMTs leave empty if controlled by ECU or enter address.
galvoGalvoMirrorInvertOPTIONAL Reverse mirror position polarity for the Galvo-Galvo Flipper mirror.
galvoResonantMirrorInvertOPTIONAL Reverse mirror position polarity for the Resonant-Galvo Flipper mirror.
flipperMirrorInvertOPTIONAL Reverse mirror position polarity for the Camera PMT Flipper mirror.

 

Example

 

 

Thorlabs ECU1

ParametersDescription
scannerNameScanner name (from from the General ScanImage Settings section) to link to. Must be a resonant scanner. Leave empty if not using a resonant scanner.
comPortNumeric: ID of the ThorECU USB Serial Port (e.g. 12 for COM12).

 

Example

 

 

GenericPmtController

ParametersDescription
pmtNamesCell array of names for PMTs e.g.
pmtDaqDeviceNameCell array of NI-DAQ devices to control each PMT channel. If only one device is given, all channels will be mapped onto that one device.
pmtDaqGainAOChannels<optional> Array of numeric analog output channel IDs to control the gain for each PMT; if set to empty array, functionality is disabled.
pmtDaqPowerDOChannels<optional> Cell array of strings specifying the digital port name to switch each PMT on/off; if set to empty cell array, functionality is disabled.
pmtDaqTrippedDIChannels<optional> Cell array of strings specifying the digital port name to detect the trip status for each PMT; if set to empty cell array, functionality is disabled.
pmtDaqTripResetDOChannels<optional> Cell array of strings specifying the digital port name to reset the trip status for each PMT; if set to empty cell array, functionality is disabled.
pmtDaqAOVoltageRange

<required If pmtDaqGainAOChannels is defined> cell array of 1x2 numeric array specifying the minimum and maximum analog output voltage on the NI-DAQ board that controls the PMT gain.

pmtMaxGainValue

<required If pmtDaqGainAOChannels is defined> array specifying the maximum display value for the PMT gain. If only one value is given, this value is used for all PMT channels.

 

Example

 

 

LSC Pure Analog (also used to control an Electrically Tunable Lens or ETL)

ParametersDescription
commandVoltsPerMicronConversion factor for command signal to analog linear stage controller.
sensorVoltsPerMicronConversion signal for sensor signal from analog linear stage controller. Leave empty for automatic calibration.
commandVoltsOffsetOffset value, in volts, for command signal to analog linear stage controller.
sensorVoltsOffsetOffset value, in volts, for sensor signal from analog linear stage controller. Leave empty for automatic calibration.
maxCommandVoltsMaximum allowable voltage command. If empty, default is +10 Volts.
maxCommandPosnMaximum allowable position command in microns. If empty, default is associated micron value of +10 Volts.
minCommandVoltsMinimum allowable voltage command. If empty, default is -10 Volts.
minCommandPosnMinimum allowable position command in microns. If empty, default is associated micron value of -10 Volts.
analogCmdBoardIDString specifying NI board identifier (e.g. 'Dev1') containing AO channel for LSC control.
analogCmdChanIDsScalar indicating AO channel number (e.g. 0) used for analog LSC control.
analogSensorBoardIDString specifying NI board identifier (e.g. 'Dev1') containing AI channel for LSC position sensor.
analogSensorChanIDsScalar indicating AI channel number (e.g. 0) used for analog LSC position sensor.

 

Example