FOV Curvature Correction

Introduced in ScanImage 2023.2.0 is a miscellaneous device to handle defining curvature of the scanfield. This can be used either for

  • correction of the curvature of the field of view, or

  • addition of curvature to the FOV to image more ROIs per individual frame

It works by using a paired fastZ device to vary the depth of the focal point as a function of XY positiion in the FOV. Care must be taken to scan at rates that accommodate the performance of the paired fastZ device.

Note

There was and still exists an old, similar, but undocumented means for correcting for FOV curvature and it does not incorporate a helpful GUI. This is available in both basic and premium ScanImage. To use it, ellipsoid semi-axes lengths must be input from the machine data file and the Correct Field Curvature checkbox must be checked from the main controls window.

Do not place a check in the Correct Field Curvature checkbox if you are using this feature.

Configuration

In ScanImage, open the Resource configuration window from the launch window or from the Main Controls window under File>Configuration.

  1. From the Resource Configuration window, click the + button. Select Miscellaneous from the sidebar, and select the Thorlabs Liquid Crystal Analog FastZ device from the list of devices. Click Add.

  2. A window like shown below should appear. Below is a description of each of the configuration parameters

../_images/CurvatureCorrectionMDF.png

FastZ Table

Select the FastZ actuators that should be controlled by this curvature correction device.

Open Curvature GUI

Once ScanImage has been launched, the curvature of the FOV can be defined in the GUI launched by clicking this button. The GUI can also be launched by clicking the image in the widget.

Enable Curvature Correction

If checked, subsequent acquisitions will apply the curvature settings defined in the GUI to the selected fastZ actuator’s analog output buffer thus correcting for or adding field curvature.

Enable Live Update

If checked, then the analog output buffer can be recalculated while in the middle of an acquisition if the analog output buffer is small enough that it makes sense to attempt live updating (less than 3e6 samples).


Note

The number of samples of an acquisition is equal to the sample rate for tasks multiplied by the duration of a frame for a planar acquisition or the duration of the volume for fast stack acquisition

Correct Curvature within Resonant Period

If checked and the imaging scanner is configured for resonant scanning, the curvature is corrected within the resonant period.

GUI

The GUI is subdivided into 3 parts:

  1. Axes

  2. Settings Panel

  3. Sliders

../_images/GlobalCurvatureCorrectionGUI.png

Axes

The axes are plotted in microns in each of XYZ and display 4 things:

  1. Control Surface - The light blue surface used to define curvature at key Zs. Alpha of this surface can be controlled with the Control Surface Alpha slider

  2. Scan Bounds - The part of sample space that can be scanned

  3. Scanfields - The scanfields as they are currently configured for the next grab or loop acquisition. Scanfield colors can be selected by clicking the Colors button beside its corresponding checkbox.

4) Last Image - The last planar or stack image data acquired. They imported as flat planes at the sample Zs they were acquired at. This takes on the color configured as the merge color from the Channels window. This is plotted with alpha controlled by the Last Image Alpha Map slider

The visibility of each can be toggled from its corresponding checkbox.

The mouse controls for the axes are: - Scroll - zoom in and out - Left click and drag - pan - Middle click or Shift and left click and drag - Orbit

Settings Panel

The table contains all the curvature data for each key Z. The cells of the table are editable except for the key Z. Clicking a table cell renders the Control Surface at the depth of the cell’s corresponding key Z. Clicking the X at the last column deletes the row.

The save and load buttons save and load the curvature data displayed in the table.

The Determine Sample Tilt and Align to surface normal buttons are specialized functions.

If using a headfixed headbar, it may be useful to determine the tilt of the headbar relative to the optical axis of the microscope. For this, one mount a sample with a thin coating of fluorescent ink and grab a stack traversing the whole thickness of the ink. Then you can open the Global Curvature Correction GUI, check the Last Image checkbox, and then click the Determine sample tilt button to automatically fill in the azimuth and elevation values to match the tilt of the sample.

If the sample is tilted and several key Zs were defined, it may be useful to align the scanfield centers to a line at this angle and coincident with the center of the current control surface. This sets the X and Y offset of key Z surfaces both above and below the current control surface.

The FastZ target position [um] is the fastZ position used to define a key surface. The fastZ target position for an plane acquisition or slice of a stack is used to determine the curvature at that plane.

The Sample Z [um] is the Z at which the axes are centered on. It does not necessarily intersect with the Scan Bounds if the user acquires image data and then moves the Z-stage.

Sliders

The sliders are a means to help define the curvature at each key Z.

X Axis

Semi-Axis Length in X of the ellipsoid used to define the control surface.

Y Axis

Length of the Y Axis of the ellipsoid used to define the control surface.

Z Axis

Length of the Z Axis of the ellipsoid used to define the control surface.

Sweep [deg]

Angle from the Z axis to the outer edge of the ellipse. When adjusting elevation, this is automatically adjusted to prevent multiple zs per XY location.

Azimuth [deg]

The azimuthal angle - angle measured from the reference positive X axis to the X axis of the ellipsoid.

Elevation [deg]

The angle of elevation from the horizontal to the key surface tangent at the surface center point.

X Offset [um]

The offset of the ellipsoid in the reference X direction.

Y Offset [um]

The offset of the ellipsoid in the reference Y direction.

Z Offset [um]

The offset of the ellipsoid in the reference Z direction.

Use

For each fastZ position that a planar acquisition or stack acquisition slice can be made, we aim to shape the curvature of that plane or slice uniquely with this GUI. Given that fastZ actuators are typically driven by analog waveforms, that means that there is a continuum of fastZ positions in the range of the actuator. Thus, one can define the curvature at several key fastZ positions, and then for any fastZ positions not defined, the curvature settings from key Zs are interpolated to define the curvature at intermediate planes. Planes outside the bounds of defined Zs simply use the curvature settings at the nearest bound.

Defining the curvature at any one key Z can be done via dragging sliders in the right pane of the GUI.

Correcting for field curvature involves iteratively acquiring a stack of a known flat fluorescent sample (glass slide with highlighter ink smeared thin over top) without field curvature compensation, defining the curvature at such a depth, moving a Z-stage by some sub-multiple of the fastZ range, and repeating the process for several key depths. The process is done in the tutorial for a single surface, however to map a mostly flat field of view to a curved surface.

Tutorial

The below video shows how the device can be used to image a plane mapped to the curvature of the eye of an insect. It is performed on a microscope equipped with the RMR scanhead and a piezo objective stage.

First a stack is taken without any correction. Then a galvo-galvo scan is performed to precisely follow the curvature for all points in the scanfield. Then a resonant-galvo-galvo scan is performed to follow the curvature along the y-axis of the scan for each ROI. The center of each ROI is made coincident with the surface. If the Correct Curvature within Resonant Period is checked and the fastZ actuator has appropriate performance, then it may be able to follow curvature along the X-Axis while resonant scanning. Then it is shown but not demonstrated via imaging that multiple key Zs can be defined with parameters defining the curvature being interpolated between these key Zs.


Script

ACQUIRE WITHOUT CURVATURE CORRECTION

  • Start with Resonant, 512x512 30Hz

  • Disable curvature correction

  • Focus

  • 10 frames averaging

  • Bring focal point through fastZ range

  • Enable Stack - Bounded 1 frame per slice, 50 slices, 10 volumes, Fast stack, step waveform, 2 discarded frames, 20 ms frame flyback

  • Open Waveform Controls, optimize waveforms

  • Set volume display style to Max to get a nice Max Projection. Shows what we ideally want to see after applying curvature correction

  • Grab 3:00

  • At conclusion, set volume display style to Tile, Jump around

DEFINING AND APPLYING CURVATURE CORRECTION WITH LINEAR SCANNING 3:28

  • open GCC GUI

  • get context stack, set contrast

  • Load Settings

  • Play with settings

  • Switch to linear scanning

  • Disable stack

  • Enable GCC

  • Change Desired Control rate to 10 kHz (to minimize buffer calculation time for slow galvo-galvo acquisition)

  • Set resolution to 256x256, Pixel Bin Factor to 400, sampling rate 1 MHz

  • Set FastZ Target position to overlap eye

  • Open Waveform Manager, go to Z tab, optimize waveforms

  • Focus 8:13

APPLYING CURVATURE CORRECTION WITH MROI SCANNING 8:20

  • Go back to Resonant

  • Change desired control sample rate to 1000 kHz

  • enable MROI

  • open ROI Group Editor

  • Get context image

  • Add ROIs that are not too tall and centered.

  • Set flyto and flyback time to 20 ms

  • Open GCC Gui

  • Show scanfields

  • Open Waveform Manager and optimize Z waveforms.

  • Focus with MROI.

Caveats

Even with an idealized fastZ actuator with infinitesimally short duration step times, the max sample rate of the fastZ task will limit the number of samples that can be fit into a line. For the vDAQ, for instance, the max sample rate that can be used for the fastZ task is 1 MHz (specified from the Advanced tab of the RggScan configuration page). This limitation would only be noticable for the resonant scan mode. For example, 1 MHz sample rate in an acquisition with an 8 kHz resonant scanner with a temporal fill fraction of 0.7192 and bidirectional acquisition of lines yields 1e6 / (2*8e3) * 0.7192 = 44 samples, or 29 samples for a 12 kHz resonant mirror. For an ellipsoid representing the curvature, this should be more than enough. This does make more complicated surfaces less feasible.