Icon

This documentation is for a legacy ScanImage version. The current documentation is ScanImage 2019.

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

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 (hopefully!) backed up.

Sections


SectionDescription
ScanImageGeneral ScanImage behavior (for example, simulated mode).
ShuttersShutter(s) used to prevent any beam exposure from reaching specimen during idle periods.
BeamsBeam control and calibration channels. Typically used to control Pockels cells.
ResScanResonant scanning imaging system
LinScanLinear scanning imaging system (galvo/galvo scanning)
FastZFastZ hardware used for fast axial motion, supporting fast stacks and/or volume imaging.
MotorsMotor used for X/Y/Z motion, including stacks. 
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 2015 without any physical hardware present. Note: Simulated DAQ-hardware in MAX is still required.
componentsactivate plugins for specific hardware configurations (ThorECU1, ThorBScope2)
dataDir Directory to store persistent configuration and calibration data.
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 secion allows to define shutters. Mapping the shutters to different imaging system is done in a later step.

ParameterDescription
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
primaryPxiChassisNumPXI Chassis ID (as configured in NI MAX) TO BE REMOVED IN FUTURE VERSIONS
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 ResScan
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.
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]
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