This documentation is for a legacy ScanImage version. The current documentation is ScanImage 2019.
Skip to end of metadata
Go to start of metadata


The MOTOR CONTROLS window pertains to (optional) control of a stage/motor controller system supported by ScanImage.

The Motor Controls panel only appears if a motorControllerType is specified in the Machine Data File. Other motorXXX settings in the Machine Data File pertain to this controller, if specified - e.g. the COM port controller is connected to if it is serial-port controlled.

Secondary Z motor can be activated in the Machine Data File (by specifying the motor2ControllerType).  For example, when the primary motor controller is configured with the default value: motorDimensions='XYZ', adding a Secondary Z motor corresponds to the XYZ-Z configuration as shown below. Other configurations, such as XYZXYZ, and XY-Z show 3 dimensions; inactive dimensions are set to zero.

Current Motor Position

ScanImage vs Motor Relative


ScanImage has its own notion of relative positions, independent of the relative coordinates maintained by some motor controllers, such as the Sutter MP285. To make this distinction clear, the coordinate sets are referred to below as ScanImage Relative and Motor Relative.

These controls play two roles:

    • They display the most recent position read from the motor controller in each of the 3-4 axes.
    • Entering a value for any of the axes commands the motor to move to the specified position for that axis. Following the move, the position will be read and updated for all three axes.



ScanImage always reads the Motor Absolute position from the motor. By default (at ScanImage startup), ScanImage displays and interprets positions in Motor Absolute coordinates. This remains true until (and only if) coordinates are converted toScanImage Relative coordinates by pressing one of the Zero XYZ/Zero XY/Zero Z buttons.

Forces ScanImage to read the current motor position in all three axes and to update the displayed X/Y/Z values, e.g. following manual adjustment of the motor position using the motor controller outside of ScanImage control.
Read-only control that displays the squared-sum of the 3-4 displayed X/Y/Z values

Pressing these buttons forces ScanImage Relative positions to be used in the specified axes (if not used already) and resets the relative origin in the specified axes to the current position (which is first read from the motor controller).



Once ScanImage Relative positions are used in a particular axes, there is no returning to Motor Absolute coordinates. Pressing Zero XYZ/Zero XY/Zero X again simply sets a new ScanImage Relative origin (in the specified axes).

  • In the 4-dimension XYZ-Z case, enabling/disabling this checkbox determines whether primary (disabled) or secondary (enabled) Z motor controller pertains for:
    • Zero Z operation
    • Z step with arrow controls
    • Image Stack acquisitions (for standard, stepping stacks)


Matching Relative Coordinates


A common and recommended approach is to set both the motor controller and ScanImage to operate in matched Relative coordinates. The procedure to accomplish this is as follows:

  1. Adjust the motor controller to display Motor Relative positions, if not already. (For the MP-285, display of Motor Absolute and Motor Relative positions is toggled by hitting <ENTR>)
  2. Set the Motor Relative position to zero at some desired position. (For the MP-285, this is done by hitting <0>,<ENTR>).
  3. Immediately afterwards, press Zero XYZ to set the ScanImage Relative position.

At this point, both the motor controller and ScanImage are operating in Relative coordinates, at position (0,0,0). If desired, these steps can be repeated later at new physical position(s), updating both Relative origins in tandem.

Increment or decrement stage position in X, Y, or Z dimension by the specified step, in microns. In 4-dimension XYZ-Z case, the Sec Z value determines which motor controller is used when incrementing/decrementing the Z position.
Defines the maximum step (in motor coordinates) that ScanImage can perform on each axis. Attempting to execute a bigger step results in an error.

Image Stack Acquisition

These controls configure Image Stack acquisitions, of which ScanImage supports two types:

  • Standard ('Slow Z') stepping stacks
  • Volume Imaging ('Fast Z') stacks (when Enable is selected in the Fast Z Controls)

When value of #Slices is greater than 1, an image stack acquisition is implied for each GRAB or LOOP Repeat. For standard stacks, each Slice is an individually triggered acquisition taken at a distinct axial (Z) position, consisting of one or more Frames, as specified by #Frames on the Main Controls window. See Volume Imaging for more information about FastZ stacks.

Core Image Stack Controls

  • For standard stacks, specifies number of Slices to collect during an Image Stack acquisition.
  • For  Volume Imaging, specifies the number of frames acquired during each volume period.

  • For standard stacks, specifies axial (Z) step to take with the motor controller between each Slice.
  • For Volume Imaging, specifies the axial distance traversed (e.g. swept) between successive frames in each volume period.


    Either a positive or negative value can be specified, so motion may proceed in either axial direction

If enabled, motor controller returns to Home position – the initial axial position when a GRAB or LOOP was initiated – following the GRAB acquisition or each LOOP Repeat. This ensures subsequent acquisitions or Repeats traverse the same axial positions.


For LOOP acquisitions, this option should typically be enabled. If not enabled, successive Repeats will image progressively further along the axial direction specified, which is typically not desired.

If enabled, axial position at start of Image Stack acquisition is taken as the center of the stack. Motor is moved backwards by half the total span implied by #Slices and Step/Slice prior to the start of the stack acquisition.


If Centered Stack is enabled and #Slices is even, then no Slice will be obtained or centered on the starting axial position at time of GRAB/LOOP initiation.

Locks the step/slice step size during auto-calculations. Users can set the start and end position of a stack and ScanImage will auto calculate the # of slices and the step per slice needed to achieve this. Because scanning partial slice is not practical this auto-calculation will find the nearest whole number of slices that will accommodate the stack start and end position. However users may decide that the step size is of a greater priority. Enabling this will lock the step per slice value an instead adjust the # of slices so that the entire stack can imaged with the specified step size. This will necessarily mean that the total stack will exceed the limits of the stack determined by the stack start and end.

Image Stack Endpoint & Power Controls

Often, users may wish to select the starting and ending axial positions, as well as the imaging power, interactively, i.e. during FOCUS when the axial position and power can each be adjusted during live imaging.

Endpoints for Slow Z Only


The stack position and power start/endpoint constraints only apply to standard (Slow Z) stacks. However, using interactive stack start & endpoint selection can still be useful for Volume Imaging to determine/set the Lz (length constant) value in Power Controls by using Override Lz.

Sets the starting axial position of stack interactively. Motor controller will be moved to specified axial position at start of subsequent (standard) Image Stack acquisitions.
Sets the current axial position as Posn start.
Sets the ending axial position of stack interactively. When both Posn start and Posn end are set, the values of #Slices and Step/Slice are constrained so that Image Stacks traverse the specified axial extent.
Sets the current axial position as Posn end.
Clears Posn start, Posn end, Power start, and Power end (if configured.)
Clears Posn end and Power end (if configured) only.

The constraint on #Slices and Step/Slice remains in effect until either clr all or cir end is pressed.

P/Z Adjust

If P/z Adjust is enabled for a particular Beam on the Power Controls window, the following controls pertain:

Power to use at starting axial position of stack can be set interactively. If Use start pwr is enabled, then power is adjusted to this level (for selected/displayed Beam) at start of subsequent (standard) Image Stack acquisitions.


The power in the Power Controls window will not update to reflect the change until after the start of a standard Image Stack acquisition. Do not be alarmed if you do not see the power change upon checking the box.

Power to use at ending axial position of stack can be set interactively. When both Posn start and Posn end are set, user can choose to automatically or manually Override Lz, i.e. override the length constant Lz set on the Power Controls for the selected Beam, with the exponential length-constant value implied by (computed from) the start/end positions and powers.


The Lz constant and the Power Z-Profile plot in the Power Controls window will not update to reflect the change until after the start of a standard Image Stack acquisition. Afterwards, only the plot will update. The Lz constant will not change to maintain previous default setting as opposed to the automatically overridden value.

When Posn start/end and Power start/end values are all set, the Lz (length constant) value in Power Controls can be overridden with value computed from the specified position/power endpoints.

  • With checkbox enabled, the Power Controls Lz value is automatically overridden when all endpoints are set

Motor Alignment


Opens the Motor Alignment Window that allows to align the motor coordinate system to the scan coordinate system.

When Power start or Power end are set, current power values are captured/stored for each Beam. Stored value for only the currently selected Beam in Power Controls is shown at a time. 


Power end values are stored for Beams for which P/z Adjust is disabled on Power Controls have no effect.

Set Lz Once


The Lz length constant values for each Beam are saved as part of the ScanImage User Settings (*.USR) file. For a given specimen type, the length constant describing the additional power required as a function of depth can be expected to remain generally constant. Thus, users may typically set the power and position levels interactively (spanning a wide axial extent) and manually select Override Lz to compute the length constant. Then this value can be saved to the *.USR file, avoiding requirement to interactively set/determine the length constant in future ScanImage sessions.