Setting up ScanImage

USR and CFG files

ScanImage settings can be stored for recall later. Two sets of files are used: "user settings" files and "configuration files". These are outlined here: http://scanimage.vidriotechnologies.com/display/SI2016/CFG+and+USR+Files

Briefly, there will probably be one user settings file that you'll use to start ScanImage each time. It stores things like the window positions and which channels are active. So set up this sort of thing and save it as a user settings file which you call "BakingTray.usr" or similar.

Then set up some configuration files for different scan settings. These ".cfg" files will save stuff like the image size, if the pixels are square, the bidirection scan phase correction, the PMT gains, etc.

e.g. you might have "square" images, where the number of lines per frame and the number of pixels per line are the same. With square images it's pretty easy to just change the number pixels per line to change the resolution. Non-square images are dicussed at the end.

Calibrating the number of microns per pixel

BakingTray uses the number of microns per pixel reported by ScanImage to determine where to move the stages. If this number is wrong you will get stitching problems and nobody wants stitching problems. You will need to perform these steps when you first set up your system and also if you ever have to replace a scanner, since different scanners have slightly different gains.

For square resonant images you do the following:

• In CONFIGURATION check "Pix=Lin" and "Square Pix"
• Copy the scan waveforms to an osciloscope with BNC cables and T-connectors
• Image EM grid (a copper grid will emit visible light when excited at low power with a 2p laser at most wavelengths. e.g. 850 nm will work)
• Orient your EM grid so that the grid axes run parallel to the imaging axes (it's OK to be a few degress out)
• Set zoom to 1
• Choose 512 x 512 pixels

The goal is to obtain the largest FOV possible with the same number of microns per pixel along each axis. When you hit "Focus" you get an image and also you see the amplitude of the scan waveforms. You want a square image of the grid with the resonant mirror control signal at its maximum (probably +5V) To achieve this:

• Run hSI.hScan2D.plotFov2VoltageCurve and try to generate a square-looking image by moving the control points up and down with buttons at the bottom right.
• If you find you need a larger amplitude than the maximum resonant mirror control signal to generate a square-looking image then lower the FOV=1 point to, say, 4.5 then decrease the slow scan multiplier (MAIN CONTROLS) by a bit. Say, to 0.8. The other multiplier will change to 0.8 also.
• Play with these parameters until the grid looks square at a zoom of 1 and a maximum resonant mirror control signal.
• Once this is done it should then be possible to zoom in and the grid remains square (or mostly square, you might need to add more control points on you graph). For our purposes, however, we won't be zooming in. We'll always want to be maximally zoomed out to allow the sample to be tiled with as few stage motions as possible. E.g. with our setup, scan multipliers of 0.75 yields near-square images with a 12 kHz scanner.

Once it looks approximately right, save the image and feed it to Grid2MicsPerPixel function in measurePSF to measure the exact number of microns per pixel along the rows and columns.

ScanImage now needs to be told how many microns correspond to one optical degree of scan angle. You can see the current scan parameters in two ways. One is to do it via BakingTray. Start BakingTray after ScanImage and run:

>> hBT.scanner.returnScanSettings

If you haven't set up BakingTray you can try:

>> S=SIBT
>> S.returnScanSettings

Finally, you can access the values directly (but in a harder to read format) from the ScanImage API:

>> hSI.hRoiManager.imagingFovDeg
>> hSI.hRoiManager.imagingFovUm

Likely the reported image size will be different to that which you measured. This is because you need to tell ScanImage how the number of optcal degrees relates to the number of microns at the sample. This is achieved by setting the property hSI.objectiveResolution which is the number of microns per degree of scan angle. You can just do this at the command line and the value persists across sessions (no need to explicitly save it). So you just do:

>> hSI.objectiveResolution = hBT.scanner.returnScanSettings.scannerMechanicalAnglePP_fast_axis / SIZE_OF_IMAGE_ALONG_COLS

You may now notice a problem: what if the number of microns per pixel down the rows is not the same? There is only one number for linking scan angle to microns. Chances are that the number of degrees per volt isn't completely accurate for your scanners. The easiest way forward to change this scaling factor for the slow axis.

Let's say we have 0.781 microns per pixel along the fast axis and 0.735 microns per pixel along the slow axis. This means that the slow axis is moving by less than we expect. To start with we will change the V/optical degree value by:

new_value  = orig_value * (0.781/0.735)

Then re-image and check.

Hints:

• Leave the resonant scanner on the whole time so that it settles down.
• Average 10 frames to improve SNR.
• Right-click on the channel window and copy data to the base workspace to feed to the measurement function

After this process your slow axis microns per pixel will equal your fast axis microns per pixel.

Setting up rectangular images

The FOV along the fast (X) resonant axis is likely smaller than that along the slow (galvo) axis. With an 8 kHz scanner the difference will be small, but with a 12 kHz scanner it will be large. In our system the fast axis has a range almost three times smaller than the slow axis. After setting up rectangular images we get 400 microns along the fast axis and 1100 microns along the slow axis. This greatly speeds up tile scanning because three times fewer stage motions are needed.

To set up rectangular images that use the whole Y range:

• First perform the steps for square images because you want the number of volts per degree to be equal for two scan axes.
• Now oncheck pix=line in the CONFIGURATION window.
• Set the slow scan multiplier to a number that's as large as possible. On our setup this is 2.1V If you set this value to too large a number you'll get an error about the output buffer being empty.
• Press focus. Note that ScanImage automatically sets the number of lines so that the pixels remain square
• Image th grid and measure. You may need to take a small Z stack if not all of the grid is visible over the whole image. Alternatively manually average three or four depths at the command line with the right-click and export.
• You should get the same number of microns per pixel as before.

You'll now have rectangular frames with a certain number of microns per pixel. You can go to "File > Save Configuration As" in ScanImage to allow you allow you to re-load this in the future. E.g. you could call your file "rectangle_078.cfg" for 0.78 micron/pixel images.

Changing the number of microns per pixel is a bit annoying, unfortunately. Try changing pixels per line with. You'll see that ScanImage also changes the scan multipliers. You could avoid this by unchecking "Square Pix", but then you'd have to calcualte how many lines your frame needs.

My solution is the following:

• Note the two scan multipliers and re-apply them after changing the image size.
• Then save a new configuration. You can now re-load it later. It's likely you'll only ever need three or four these, so no big deal.

Z scan settings

Make sure you set reasonable default values for the Fast Z controls. We find that a flyback time of about 35 ms and a lag of about 5 ms is suitable for most scenarios. You should test this for your hardware and save these values in the configuration file. BakingTray will automatically enable Fast Z when it starts scanning and will use whatever flyback and lag settings are already there.

Choosing scan settings for linear scanners

Linear scanners are slow and driving them too hard has trade-offs with image quality. Here is how to determining scan settings and approximate imaging times:

Set up ScanImage as follows (PMTs and laser can be off):

1. Channels dialog: display chan 1, check save boxes for largest number of channels you anticipate using.
2. Set up saving into a junk directory.
3. Set up the fast z controls (if you use this): step, check enable, set up your typical number of optical sections and distance between sections.
4. In MAIN CONTROLS: set "acqs" to acquire 10 to acquisitions
5. In User functions add BT_timer (which will need to be in you path) to 'acqModeStart', 'frameAcquired', and 'acqDone', 'acqMode'
6. The pixels/line affects microns per pixel. Set zoom to 1 and makes sure Pix=Lin is checked in CONFIGURATION. Suggested pixels per line: between 500 and 1024. At larger numbers (will depend on your PC), you will get faster performance if you also disable viewing of chan1
7. Set the pixel bin factor and sampling rate to get a line period of around 750 to 900 microseconds. You can go as low as 650, but that's not recomended. The image quality will get better above 800 microseconds, since the bidi scan artefacts are largely gone here.
8. Now hit loop.

It then reports reasonable acquisition times: e.g. For 11x15 tiles of 5x10 microns in 220 physical sections

Our setup yeilds the following times:

• 41 hours - 892 microsecond scan lines, 0.98 mics/pix, 2.0 MHz
• 33 hours - 716 microsecond scan lines, 0.98 mics/pix, 2.5 MHz
• 33 hours - 716 microsecond scan lines, 0.98 mics/pix, 2.5 MHz (NO CHAN 1 DISPLAY)
• 49 hours - 856 microsecond scan lines, 0.77 mics/pix, 4.0 MHz
• 106 hours - 834 microsecond scan lines, 0.52 mics/pix, 2.0 MHz (with chan1 display)
• 77 hours - 834 microsecond scan lines, 0.52 mics/pix, 2.0 MHz (WITHOUT chan1 display)

Now repeat but with 3x10 microns and 370 physical sections

• 35 hours - 716 microsecond scan lines, 0.98 mics/pix, 2.5 MHz

Other settings

• ScanImage has the ability to blank the laser turn-arounds. This is mainly used to avoid photo-damage in vivo when using resonant scanners (and to a lesser extent linear scanners). We don't care much about bleaching and photo-damage, since our tissue is dead and we image each frame only once. On the other hand, the blanking can lead to ringing in the amplifier for samples with high autofluoresence or where this bright signal near the tile edges. Disable flyback blanking in ScanImage to minimise these artifacts.