ScanImage r3.6 Documentation (Beta)

This documentation is provisional

ScanImage 3.6 has been developed primarily to add basic support for bidirectional scanning as well as somewhat faster 'sawtooth' scanning. These scan modes allow for faster line rates and hence faster frame rates.

To support these scan modes effectively, the Configuration GUI(s) have been significantly reworked into a single new Configuration GUI. This new GUI is described below, followed by discussions of considerations for bidirectional and sawtooth scanning individually.

Configuration Dialog Overview

For convenience, the Configuration... dialog can be shown/hidden by using the CFG >> button now visible at the bottom right of the window.

This page contains macros or features from a plugin which requires a valid license.

You will need to contact your administrator.

Configuration Dialog in r3.6

• The Configuration... dialog window can now remain open during acquisition (i.e. it is no longer 'modal').
• The Configuration... dialog is now a single window, rather than being separated into 'basic' and 'advanced' dialogs. Commonly modified settings are placed at the top, whereas more advanced settings are below, and can be shown/hidden by the \/ control.

Generally speaking, changes made in the Configuration GUI are not immediately applied. When a modification is detected, the Save and Apply buttons will become active. Until changes are applied, no acquisition (FOCUS/GRAB/LOOP) can be started - those buttons are grayed out. The Save button will remain active until/if changes are saved (to the current configuration, or a newly named one if none is presently active).

Live Scan Params

The parameters in this panel – Acquisition Delay, Scan Delay, and Fill Fraction. – are discussed more fully in the following section. Changes made to any of these parameters in the midst of a FOCUS acquisition are automatically applied. The scan will be stopped and restarted, after the command waveforms have been recomputed (typically ~1s). Note that changes made when not FOCUSing must be applied as usual (via the Apply button).

Scan Param Array

This panel contains an array of settings for each of the parameters in the LIVE Scan Params section. This allows a different set of values to be stored as part of the configuration for use with different zoom levels. The length of the array is determined by the Constant @ Zoom >= field. The values for each of the parameters are kept constant at zoom levels above this value. The default value is 1, i.e. a scalar array for each parameter The section also contains a Min Zoom parameter, which specifies a minimum zoom level to allow for the current/saved configuration. This can be used to prevent the user from driving a mirror set too hard, when running at high speeds.

Adjusting the @ Zoom control at left allows the array elements to be viewed and, if desired, edited. The values stored in this array are synchronized with the values in the LIVE Scan Params section, i.e. updates to either automatically update the other (depending on the current zoom level specified in the window.

Pockels Parameters

The parameters for the Pockels Cell command waveform(s) are somewhat changed. The checkbox Blank Flyback? specifies whether to output a command waveform that turns off the Pockels Cell transmission during flyback (or turnaround, for bidi scaning). If this is unchecked, a constant power level is transmitted during normal scans. The Fill Frac Adjust parameter indicates how much additional time beyond the fill fraction to allow light to be transmitted.

Scan Parametrization & Optimization

General Notes on Scan Parameters

• Scan Amplitude (X&Y): These settings now refer to the (half) amplitude of the acquired scan, i.e. the command voltage range traversed during the acquisition time for the specified Ms/Line setting. The actual command signal amplitude exceeds that of the Scan Amplitude in a manner determined by the Fill Fraction and Scan Delay parameters. Scan amplitude values in ScanImage 3.6 will be somewhat smaller than in earlier versions, in order to obtain the same sized field-of-view.

• Ms/Line: As in previous ScanImage versions, this setting specifies the nominal line period. Strictly speaking, the setting specifies the acquisition period, which can be computed by multiplying the nominal ms/line value times 0.8192, which is the 'reference' value of the Fill Fraction parameter.

• Fill Fraction: When this parameter is varied from the reference value (.8192), the actual line period – i.e., the sum of the acquiring and non-acquiring portions of each line period – is also varied. Strictly speaking, the Fill Fraction directly specifies the non-acquiring portion of each line period. Compared to previous versions, there are now a larger number of available Fill Fraction values, particularly on the lower end.

Sawtooth Scanning Parameters

For sawtooth scanning, the non-acquisition time specified by the Fill Fraction parameter serves two purposes. First, it provides time for the mirror to 'flyback' following the scan of a line. Second, it provides time to extend the ramp portion of the command waveform, thereby increasing the amplitude of the command waveform relative to the desired scan amplitude. This serves to 1) compensate for the attenuation of the scanner response relative to the command waveform, and 2) provide time for the scanner response to settle, i.e. for all ripple to subside, prior to the acquisition period.

The Scan Delay parameter specifies the portion of the non-acquisition time used to extend the command ramp; the remainder of the time is allocated for flyback. The scan delay is appended to the beginning of the ramp; hence, the command waveform is asymmetric. This parameter increases the amplitude of the command waveform relative to the acquisition Scan Amplitude value.

The Acquisition Delay specifies the delay between the command waveform and the actual scanner response. Within ScanImage, the Acquisition Delay specifies the beginning of the acquisition window for each line (beyond the Scan Delay value).

As their names imply, the Acquisition Delay generally has no effect on the scanner command waveform, whereas the Scan Delay parameter does impact the scanner command.
Note that the modulator (e.g. Pockels) command waveform does depend on the Acquisition Delay.

Sawtooth Scanning Optimization

Prior to experimental work, the user should optimize the Fill Fraction, Scan Delay, and Acquisition Delay parameters for their scanner system. There are two regimes that are illustrative of how to carry out this optimization: the linear and nonlinear regimes.

Linear Regime

In the linear regime, the user elects to mostly avoid the velocity and/or acceleration limits of the scanner. Such thresholds confer nonlinearity on the response. When operating withing these limits for typical galvos/servos, the Acquisition Delay and Scan Delay parameters become in fact intertwined. They both reflect the scanner's (small-angle) settling time, which is a fundamental property of the scanner. Here are the steps recommended:

1. Operate the scanner at a modest rate and observe (e.g. with an oscilloscope) the response and command waveforms. If needed, adjust the scaling for the response waveform so that the slopes of the two waveforms, during the main ramp, are matched.
2. Measure the time lag between the command and response during the main ramp, e.g. at a zero-crossing. Enter this value as the Acquisition Delay, while entering the Scan Delay as 2x this value. Careful observation will reveal that there is residual ripple at the onset of the line's ramp for the duration of the Scan Delay - this is the scanner's settling time¹. Note that these values are constrained in ScanImage to increments of data acquisition board sampling periods, and may differ somewhat from the entered values.
3. Now adjust the Ms/Line, Scan Amplitude, and zoom level to the desired values to be configured. Observe the response waveform amplitude. Adjust the Fill Fraction to find the largest value at which the starting point of the response waveform's ramp, beyond any visible ripple, is at or just before the desired ramp start point (i.e. the negative of Scan Amplitude).
4. Repeat steps 2-3 at higher zoom levels, if desired, storing increasingly higher Fill Fraction values as the zoom level is increased. The number of zoom levels (fill fractions) to store is left to the user. Note that one can always use a lower Fill Fraction than is required; thus the level need not be optimized at all zoom levels. Note that the Acquisition Delay and Scan Delay values are held constant.
5. Commence live imaging of a test specimen. At each of the zoom levels stored, adjust the Acquisition Delay to the point where a 'reflection' is observed on the right edge of the image. Reduce the Acquisition Delay one increment to eliminate this reflection. Note that the adjustment of Acquisition Delay relative to the measured value should be small and/or not needed.

By following these steps, the scan and acquired image at all zoom levels will correspond to the ramp amplitude and slope specified by the Scan Amplitude and Ms/Line values. There will be minimal (ideally none) offset as the zoom level is changed; ROI selections should be highly accurate.

¹ Based on private communication with Cambridge Technology; observations by the developers have largely confirmed this relationship when operating at modest rates.

Nonlinear Regime

It is possible to achieve higher Fill Fraction values at each zoom level, thereby providing the fastest possible scan rate. This requires operating the galvo/servo in a nonlinear regime, where the response will be limited by the servo current and/or voltage limits.

Operating in the nonlinear regime often causes significantly faster heating and. See Thermal Considerations for more information.
Tests have only been done to date using Class 1 servos. The use of the nonlinear strategy with Class 0 servos could conceivably cause damage.

For nonlinear operation, the following procedure is suggested for each zoom level at a given Ms/Line and Scan Amplitude:

1. Select a target Fill Fraction value
2. Starting with a low value, adjust the Scan Delay value increasingly upwards until the response of the response waveform begins, following any ripple, at or before the desired ramp start point. (In general, the desired ramp end point should be reached regardless of settings).
3. If this is not possible, decrease the Fill Fraction and repeat step 2 as needed until a combination is found that allows the response to match the start & endpoints. (Alternatively, if response appears settled well before the desired it is readily possible, a higher Fill Fraction could be tried).
4. Commence live imaging of a test specimen. At each of the zoom levels stored, adjust the Acquisition Delay to the point where a 'reflection' is observed on the right edge of the image. Reduce the Acquisition Delay one increment to eliminate this reflection.

In general, following this procedure will cause the command waveform to be an almost discontinuous function, forcing the servo/scanner to respond at the fastest possible rate. In tests done to date, no disadvantage has been found, beyond the increased rate of heating, to employing the nonlinear regime – i.e. no significant degradation of image quality or image positioning has been found.

Bidirectional Scanning Parameters and Optimization

For bidirectional scanning, the Scan Delay becomes a read-only parameter, because the non-acquiring time specified by the Fill Fraction no longer needs to be divided between flyback and ramp extension. Only ramp extension occurs. The Scan Delay now refers to half of the total ramp extension; the same amount is added to both the start and end of the ramp. Unlike with sawtooth scanning, the command waveform for bidirectional scanning is symmetric (with respect to the Scan Offset and Scan Shift values for the fast dimension).

At each zoom level desired, the Fill Fraction should be reduced to at least the point where no ripple is observed in the response waveform within the range specified by the Scan Amplitude. The ripple represents the settling time for the scanner in response to the change in slope of the command waveform.

At each zoom level, the Acquisition Delay should be adjusted while live imaging to ensure that the image appearing on successive lines is well-aligned. This value should vary only slightly as the zoom level is varied. The Fine? checkbox becomes active when bidirectional scanning, allowing the Acquisition Delay to be stepped in fine increments.

Thermal Considerations

Beyond the considerations discussed to ensure the scanner response matches the desired scan start and endpoints, the thermal implications of scan parameters must also be considered for physical scanners such as galvos.

When using higher speeds and/or larger amplitudes, it may be necessary to reduce the Fill Fraction value below that determined based on the servo/scanner response. Below are results of measurements to determine the optimal Fill Fraction value accounting for thermal considerations, in a particularly stringent case (remain below the thermal limit of 50°C for 1 hour of continuous scanning).

General Observations

At a fixed scan amplitude, zoom value, scan delay, and nominal line period, higher fill fractions (lower actual line periods) always imply a greater rate of heating. Note that the use of a higher fill fraction increases the amplitude of the command waveform. Thus it is the frequency and size of acceleration events, more than scan amplitude alone, which determines the thermal response.

Based on these results, the use of high speed sawtooth scans (1ms/line or faster) over the full field does not seem feasible in the absence of active cooling (i.e. using water, forced air, or solid-state cooling).

Advanced Configuration Options

Three new options are present in the 'advanced' portion of the Configuration Dialog.

Increase Cmd Output Rates
This increases the AO rate for scanner and modulator command signals from the default 50kHz to 250kHz. This is recommended when employing the Power Box feature with higher scan rates and, in particular, bidirectional scanning. This ensures the Power Box will be accurately localized and, in the bidirectional case, will have minimal artifact due to rounding effects. Increasing the AO rate also allows the cycloid shape employed for the sawtooth command waveform to be more reliably transmitted. However, no significant benefit to using the higher rate has been observed to date by the developers.

Disable Image Striping
ScanImage by default displays acquired data to the channel image figures in 'stripes' rather than one frame at a time, in order to increase the apparent update rate. For technical reasons¹, this interferes with the display of the 'crosshair' on image figures while imaging (as can be specified in the User Preferences dialog). Disabling image striping will allow the 'crosshair' to be displayed while imaging. In addition, disabling image striping decreases the data processing loads; it may be required for some computers when operating at high frame rates, particularly if disk logging.

Staircase Cmd In Slow Dim
Selecting this option causes the command waveform for the slow (typically Y) dimension to be a 'staircase' rather than a slow ramp. In other words, the scan position is held constant during the scan of each line.
¹ Matlab Technical Solution 1-1Y9REZ

Bugfixes/Enhancements/Changes

Input Channel Enhancements

The use of 4 input channels is now supported. Launching the *Channels...* allows the 4'th channel to be activated, in a manner similar to the others. In addition, the voltage range for each input channel. Lastly, the color associated for each channel when using the Merge display feature can now be user-specified.

The channel selection settings and the voltage range settings are considered configuration (CFG) settings. The Save CFGbutton allows/reminds the user to save these settings for the current configuration. If the user maintains several configurations (typical/encouraged), they should remember to set and save their channel settings for each configuration.

The Merge display settings, including the color per channel, are considered user (USR) settings. The Save USR button allows/reminds the user to save these settings. User settings are not toggled when switching configurations.

Graphical Interaction Enhancements

The various graphical interaction operations - selection of linescan angle (LS), scan center (CT), ROI, or power box - now have a unified means for identifying the image figure (i.e. one of the 4 imaging channels, or the merge window) in which to make the selection.

By default, the user must first select the window to target by clicking in it. Following this, the selection of a line or rectangle can be made. If no figure is selected within 5 seconds, the operation is cancelled.

Additionally, the user can now select a default image figure to target from the drop-down menu at the bottom of the Look Up Table window. The default image figure is saved as a user (USR) setting. If specified, the requirement to first click in the target image figure is removed (provided the specified image figure is visible).

The Zoom/Histogram/Statistics tools available in earlier versions from the Look Up Table window are now consolidated into one button each. As with the other graphical operations, they are targeted to a user-specified window or the default target window.

The zoom tool and the newly added 'data tip' tools are identical to those in normal Matlab figures. These two buttons are toggle buttons, i.e. the mode must be turned on and then back off with the same button.

Other Bugfixes/Enhancements/Changes

• The Image Processing toolbox is no longer required for ScanImage operation. (The facilities to select a line or box no longer depend on their functions).
• When selecting a line (for LS), the selection now correctly ends after 2 points are selected.
• The 'Infinite Focus' option now appears in the User Preferences dialog box
• The Uncaging Mapper, Power Transitions, and Power Box Stepper features are no longer supported (but, as of this beta, have not been removed yet from the UI)