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.
From the Resource Configuration window, click the
+
button. SelectMiscellaneous
from the sidebar, and select the Thorlabs Liquid Crystal Analog FastZ device from the list of devices. ClickAdd
.A window like shown below should appear. Below is a description of each of the configuration parameters
![../_images/CurvatureCorrectionMDF.png](../_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:
Axes
Settings Panel
Sliders
![../_images/GlobalCurvatureCorrectionGUI.png](../_images/GlobalCurvatureCorrectionGUI.png)
Axes¶
The axes are plotted in microns in each of XYZ and display 4 things:
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
Scan Bounds - The part of sample space that can be scanned
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.