Calculating Line Period and ROI Scan Time for Galvo-Galvo Scanning in ScanImage

Hi everyone,

I use ScanImage 2020 (premium), I am currently working with a galvo-galvo scanner configuration to perform frame scan for calcium functional imaging. My setup involves scanning mROIs groups of rectangular, scattered and rotated ROIs (rotatedRectangles), which include short dendritic segments.

In the mROI editor, I enter all the properties of the rotated rectangles, such as width, height, rotation, pixels, and pixel ratio. Additionally, in the advanced timing settings of the configuration window, I set all the time parameters, including dwell time, bin factor, sampling rate, and fill fraction. Based on these parameters, the line period is calculated in microseconds (µs) and displayed in the configuration window. Depending on the number of ROI lines within the rectangle, the frame rate in Hz is also calculated and displayed.

Objective:
My goal is to be able to accurately infer the line period (the time it takes to scan a single line of an ROI) from rectangles properties. I have noticed that the relationship is only partially linear, and I need assistance understanding the correct calculation method.

Known Properties:

  • Sampling rate: 1.250 MHz (period: 0.0008 ms)
  • Pixel bin factor: 4
  • Pixel dwell time: 3200 ns
  • Rectangular ROIs can be rotated in 2D space
  • Fly-to time between ROIs: 1 ms
  • Fly-back time at the end of the ROI: 1 ms

Given an example ROI with dimensions (82, 132) the theoretical line period should be:

82 * 3200 ns = 262400 ns # -> 0,2624 ms

However, the actual line period always has an excess time, I am guessing due to the turnaround time needed for the scanner mirrors to slow down and reverse direction at the end of a line.

Software Documentation:
According to ScanImage documentation, this excess time (and space) is referred to as the fill fraction:

ft = 2 * line active acquisition time / scanner period
fs = angle of active acquisition / (2 * scanner angular amplitude)
fs = cos((1 - ft) * π/2)

For my galvo-galvo configuration

ft = 0.9
fs = 0.9

Questions:

  1. How is line period calculated?
  2. How is the fill fraction incorporated into the calculation of the line period?
  3. How should the turnaround time be computed considering the fill fraction and the scanner’s angular velocity?
  4. Does line period depend on the overall scattered distribution of ROIs?

Thank you in advancefor any help!

Dario

Hi Dario,

Great to hear from you! Thanks for posting your questions, I try to explain in detail below.

ScanImage has two imaging modes: Linear (Galvo-Galvo) and Resonant (Resonant-Galvo or Resonant-Galvo-Galvo) mode.

In both modes, we have the concept of Spatial Fill Fraction, which is the percentage length of the scan line that is actually acquired. The edges (or excess length) of the scan line is “overscan”, which allows the X scanner to change velocity and turnaround, but is not acquired as data in the final image:

Along with the Spatial Fill Fraction, which describes the percentage length that is acquired each line, there is the Temporal Fill Fraction, which describes the percentage time of the scan cycle to acquire that length.

In Galvo-Galvo, or linear mode, the Temporal Fill Fraction and Spatial Fill Fraction are equal. This is because the scanner moves at a constant velocity, so the amount of space acquired and the amount of time acquired are proportional (and have the same percentage/fraction).

In resonant mode, the scanner has a sinusoidal velocity profile (non-constant velocity), which means that acquiring different length percentages of the line requires different amounts of time. In this case, the relationship between Spatial and Temporal Fill Fraction is non-linear:

This non-linear relationship is where the equations come from in your post (Resonant Fill Fraction documentation), but isn’t necessary or valid for the Linear Acquisition case.

Ultimately, in Galvo-Galvo / Linear mode, we have full control and set a constant scan velocity with user parameters, e.g. the Pixel Dwell Time, Number of Pixels, and Zoom Factor (MROI rectangle). Because of this, the calculation for line period is linear.

How is line period calculated?

For Galvo-Galvo or Linear acquisition, the Acquisition Line Period (does not include overscan) is calculated as:
Acquisition Line Period = Pixel Dwell Time * Number of Pixels per Line

The Full Line Period (which does include overscan, i.e. the real amount of time between lines) is computed as:
Full Line Period = Acquisition Line Period / Fill Fraction
(the temporal fill fraction and spatial fill fraction are equal)

How is the fill fraction incorporated into the calculation of the line period?

In linear mode, the fill fraction is used in combination with the desired Dwell Time and Number of Pixels to determine the final full scan period (as mentioned above):
Full Line Period = Acquisition Line Period / Fill Fraction

How should the turnaround time be computed considering the fill fraction and the scanner’s angular velocity?

With the above two values, the total turnaround time can be computed as simply:

Turnaround Time = Full Line Period - Acquisition Line Period

Does line period depend on the overall scattered distribution of ROIs?

In the case with multiple ROIs, the calculation is based on the number of pixels per line in each ROI:

Acquisition Line Period of ROI = Pixel Dwell Time * Number of Pixels per Line in ROI
Full Line Period of ROI = Acquisition Line Period ROI / Fill Fraction

One final note: for each of the calculations, we need to ensure the computed time periods are actually valid timepoints that we can achieve using discrete sampling rates on the DAQ. This is done by finding the closest possible values to the user parameters (e.g. Pixel Dwell Time, Fill Fraction, etc) that can work with the DAQ sampling rate. The actual values are reported in the GUI, and are stored in the metadata of the Tiff (along with the rest of the scan parameters), which can be queried in software using tools like ScanImage Tiff Reader.

Hope this helps, let me know if I can elaborate further.

All the best,

Nelson Downs (MBF)

Hello Nelson,

thanks for your answer and the detailed clarification :slight_smile:

My question originated from the struggles in calculating the frame rate of a given group of rectangles.

My objective is to arbitrarily draw ROIs and adjust their parameters to achieved a desired frame rate.

I would like to come back to the final note you mentioned, and I’ll provide a concrete example.

Let’s say I created 3 arbitrary rectangular (rotated) ROIs, within a single z-plane.

Those rectangles have a known width, height, rotation, pixel to µm ratio, pixel number, and so on; all the advanced time settings are also known (dwell time, flyback time, flyto time, and so on).

If I calculate a “theoretical” frame rate following your guidelines, I get 16.465 Hz.

However, if I input these 3 rectangles into the mROI manager (with unchaged parameters), the actual frame rate displayed in the time settings is 15.77 Hz. I thought I was not correctly calculating frame rate, but after your post, I think it might depend on the DAQ sampling rate.

Does the difference between “theoretical” and “actual” frame rate depend on a frame rate re-calculation made by ScanImage to ensure that the computed time periods are valid timepoints achieved using discrete sampling rates on the DAQ?

If yes, how are parameters adjusted to get to 15.77 Hz?

Looking into the Tiff metadata, I found a sampling_rate_ctl: is this the DAQ sampling rate?

Thanks again for your help,

All the best.

Dario

Hi Dario,

The sample rate in question refers to the control sample rate, which is used for analog output (AO) tasks that manage Galvos, beam modulators, and fastZs. This rate defaults to the slowest output setting in the event you have more than one DAQ with different AO specs.

As Nelson notes, the primary focus is on samples, as these are what are written to a task. Therefore, we can revise Nelson’s equations as follows:

  1. Acquisition Line Period:

    Acquisition Line Period = Pixel Dwell Time x Number of Pixels per Line

  2. Acquisition Line Samples:

    Acquisition Line Samples = Acquisition Line Period x sampling_rate_ctl

  3. Turnaround Samples:

    Turnaround Samples = Acquisition Line Samples / fillfraction - Acquisition Line Samples

    (Round up to ensure an integer number of samples.)

  4. Scan Line Samples:

    Scan Line Samples = Acquisition Line Samples + Turnaround Samples

  5. Full Line Period:

    Full Line Period = Scan Line Samples / sampling_rate_ctl

Using the Full Line Period, you can determine the frame rate with the following formula

Final Note: The calculation may vary slightly with the vDAQ, but the principle remains the same. Be aware that you might get a slightly different result when using the vDAQ.

Best,
Boris