Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Setting up ScanImage

Basic set up of ScanImage for use with BakingTray

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. 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 autofluorescence 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 autofluorescence or where there is 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 is 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 manually 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 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

You can automate the setting of the min and max values using mpqc.record.power from https://github.com/SWC-Advanced-Microscopy/multiphoton-qc. This requires a ThorLabs power meter to be connected via USB. Install drivers before first connecting. We have found it's much easier to accurately set the power this way, as the intercept term is hard to obtain manually.

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 one 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.

Choosing the field of view

Imaging speed is influenced strongly by the field of view of the microscope. Stage motions plus software overhead lead to a roughly 300 ms time penality for each tile position. A larger field of view substantially reduces the number of tile positions (as this scales with FoV area). To achieve a reasonable acquisition time, we therefore compromise a bit with vignetting (drop-off of illumination at the field edges). Most BrainSaw systems are imaging with a field of view of around 1 mm, often a little above, and a Nikon 16x NA 0.8 objective.

The image below shows uniformity of illumination by imaging a uniform Chroma slide and analysing the data with our multi-photon QC tools. It was taken on a BrainSaw system. The edges of the field are cropped before stitching but nonetheless, in this case edges of the field are around 25% of the central peak. This is just about acceptable and the final image is assembled with almost no indication that illumination dropped this low at the edges. In this case, the microscope was later tweaked and the drop-off improved. When setting up a new system, try the largest FoV first and see how that stitches. Only decrease if you have to. Get in touch if you find artefacts in stitching you can't explain. You could also choose a larger FoV for less demanding samples, such as electrode tracks, and a slightly smaller FoV for cell counting.

Vignetting imaged with a green fluorescent Chroma slide on a BrainSaw microscope.

Monitoring acquisitions

The tile-scan preview in BakingTray reverts to one channel only during acquisition for performance reasons. It is not intended as a way to monitor acquisition as they progress. For that, there is a web preview applet available via StitchIt. Once BakingTray is mostly working, you will want to make sure you have set up a Linux analysis PC to pull data off the acquisition PC for pre-processing and remote monitoring. See the StitchIt docs for more information.

Choosing scan settings for linear scanners

This setting is for users 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 determine 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 acquisitions

  5. In User functions add BT_timer (which will need to be in your path) to 'acqModeStart', 'frameAcquired', and 'acqDone', 'acqMode'

  6. The pixels/line affects microns per pixel. Set zoom to 1 and make 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.

Last updated