Setting up ScanImage

Basic set up of ScanImage for use with BakingTray

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.

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 bidirectional scan phase correction, the PMT gains, etc.

At this point you should calibrate the number of microns per pixel.

Scan amplitude

Adjust the scanner settings until the mirrors are moving at their maximum amplitudes at a zoom setting of 1. You might find (either now or in the future) that pressing Grab or Loop generates an error like this:

Error using scanimage.components.scan2d.resscan.Control/start (line 153)
NI DAQmx error (-200462) in call to API function 'DAQmxStartTask':
 Generation cannot be started because the output buffer is empty.

Write data before starting a buffered generation. The following actions can empty the buffer: changing the size of the buffer, unreserving a task, setting the Regeneration Mode property, changing the Sample Mode, or configuring
retriggering.

One way this can happen is if the waveform of the galvo is too large. Check this as follows:

>> max(hSI.hWaveformManager.scannerAO.ao_volts_raw.G)

ans =

         0   10.0527

>> min(hSI.hWaveformManager.scannerAO.ao_volts_raw.G)

ans =

         0  -10.0527

The DAQ is capable of producing values between +/- 10 V, so this is the problem.

Z scan settings

The PIFOC will be controlled by ScanImage and now is a good time to get to know it and ensure it's behaving well. Mount the objective you will be using into the PIFOC. Run the actuator tuning and set up reasonable parameters for, say, 5 depths spaced 10 μm apart. Use the step mode. 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.

Channel names

In the PMT set up dialog in ScanImage you should name the channels appropriately. This matters because the autoROI algorithm that finds the samples works best using the Red PMT. The far-red PMT tends to have too little autofluoresence and in the blue the agar has a lot of autofluorescence at longer excitation wavelengths. You should name your PMTs "Red", "Green", and "Blue". If you have "Far Red" also, that is fine: the system will ignore it when choosing the channels. The names are case-insensitive. Just don't name the PMTs anything else, like "Low", "Med", "Short" or "<490 nm", etc. If you do not name the PMTs the autoROI algorithm will choose the brightest channel upon which to work.

On ScanImage Basic the PMTs should be set up in the same order as the channels so that the first PMT is associated with channel 1, etc. If channel 1 is unused, make a dummy PMT. Suggested PMT names for Basic: "Chan 1: RED", "Chan 2: GREEN", etc Make sure you add the colon.

vDAQ wiring

BakingTray uses line D0.0 for the external trigger. NOTHING MUST BE CONNECTED TO THIS LINE e.g. set up the resonant sync signal on a different line. If you connect the resonant sync signal to D0.0 then tile scanning will behave strangely and fail.

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. The ringing is systematic and will be removed when the average tile is divided out. Disable flyback blanking in ScanImage with caution, therefore.

  • In SI Basic the PMT GUI has a number of annoyances, one of which is that it is not very salient when the PMTs turn on (this has been fixed from Basic 2022 onwards). You can change the colour of the PMTs icon in the ON state to make it more obvious. To do this you will need to edit the file +dabs\+resources\+widget\+widgets\PMTWidget.m Around line 62 you will see the definition for the PMT on state image. The color is defined by a constant that comes from dictionary. The default is most.constants.Colors.darkGrey. You can change this. e.g. you might choose darkGreen for the ON state.

Displaying power in mW in ScanImage

It is very helpful to be able to display to the user power in mW rather than percent power. However, since laser power and offset varies with wavelength, BakingTray needs to update ScanImage as the user changes wavelength. To set this up you will need to ensure that ScanImage able to run the power calibration using a photodiode. See the instructions in ScanImage docs for this. If you do not have a photodiode in your path then you can use a power meter with an analog output at the objective, so long as the sensor is fast enough. You can also reflect the laser light off a piece of white paper after the objective and place a photodiode next to that temporarily. Before starting, make sure the Pockels offset has been set. You can only do this at one wavelength. e.g. choose a wavelength and always use the same one (such as 920 nm) or choose a wavelength in the middle of your range (such as 850 nm). A perfect offset is not very important due to the higher laser powers we are using.

The process for calibrating ScanImage with BakingTray is:

  1. Open the Laser GUI in BakingTray.

  2. Turn on the laser and open the shutter.

  3. Set desired wavelength in the laser GUI.

  4. In ScanImage run the beam calibration function from the beams widget. You should get a nice smooth curve with the calibration tool.

  5. Measure min and max power and set these in the MDF GUI under the laser. You can access this from the gear icon on the beams widget.

  6. Confirm with power meter that the curve makes sense by looking at a few different values. It is normal to be off by about 10% and for low values (e.g. 10 mW) to be off by 50%. For the values typically used for imaging, however, it should be accurate enough.

  7. Run BakingTray.utils.addLaserCalib. This will store the information in a .MAT file and over-write any existing calibration at the same wavelengths, should this exist.

  8. Run this for your commonly used wavelengths. e.g. 920 nm, 800 nm, 780 nm. When you change wavelength, BakingTray will look for the closest calibration file. e.g. if you go to did the above three calibrations and you go to 930 nm, it will load the 920 nm calibration. If the laser wavelength is more than 20 nm from any existing calibration file, then it will not report laser power at all.

You may list existing calibrations with BakingTray.utils.listLaserCalib

If the calibrations fail, check you have a clean signal coming into the DAQ by temporarily looking at the analog input signal in NI MAX. e.g. check your breakout box is set to SE and if necessary you have a terminator in place on the BNC terminal below the on you are recording from.

The above has been tested with ScanImage Basic 2022.3.0 and should work in some earlier versions also. The upcoming release after 2022.3.0 will show power in mW in the BEAMS window. Currently power is only shown in the Beam widget and without a vDAQ only in point mode. This is remedied by the upcoming release.

Upgrading ScanImage

At least for more recent releases of SI Basic, the procedure for manually updating ScanImage is very straightforward:

  • Download the manual installer and unpack to a location of your choice.

  • Copy the known working MDF (and user config files if appropriate) into the directory.

  • Change the path and start ScanImage.

  • When requested, point ScanImage to the location of the copied MDF file.

  • Instruct ScanImage to load your user settings on startup by supplying its location in the startup window.

  • Verify that laser power calibrations are still correct and redo if necessary.

That should be it. Perhaps the automatic installer is more straightforward but we have not tested this. Across some earlier releases of ScanImage there were large changes in settings files, which made the above a bit more awkward.

Choosing scan settings for linear scanners

This setting is for user who have galvos only (no resonant scanner). A resonant scanner is recommended if at all possible. The purpose of this section is to describe how to get a feeling for how long it will take to acquire data with linear scanners and what the images will look like. Before proceeding with this step you should calibrate the number of microns per pixel. 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 with some scanners, but that's not recommended. 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 yields 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

The above numbers will of course be faster for resonant scanning, which uses an FPGA.

PreviousSoftware installationNextHardware setup

Last updated