two photon microscope

New alignment and segmentation tools

Improved alignment and segmentation tools have now been released in the latest version of Scanbox, while retaining much of the functionality of the last version.

sbxaligntool. The new alignment tool, shown below, adds batch processing of files, including the processing of eye and ball motion if those data are present.  A region-of-interest (ROI) can optionally be selected manually or automatically.  For file entries where manual selection was specified, the program will stop and present a rectangle on the screen for the user to specify the ROI.  Typically, automatic ROI works fine, and it does not require the user to stand by the computer to specify the ROI each time a new file starts to process.


As the files are aligned, the Status column and Status message will display the progress. The alignment procedure can also be visualized by clicking the Live update checkbox, which will display the mean of the entire image stack as the process moves along.  Pan and Zoom buttons allow the user to inspect details in the live image, such as fine branches, as the system is carrying out the alignment. This tool performs rigid alignment and the result is stored in a *_rigid.sbx file.  The original data is left untouched. The tool can align images relatively fast (about 65 frames/sec in my computer), but it will take a few minutes to compute the reference image if the sequence is 15 min or more (please be patient). Alignment improves with the number of passes requested.  Usually one pass is very good, but you can try two or more passes by changing the appropriate entry in the column. The alignment algorithm has been improved.

sbxsegmenttool. The segmentation tool works in a similar way as before. After loading the aligned *_rigid.sbx file, it will display the correlation map.  Segmentation then proceeds as in the previous version.


Once a number of cells are selected, you must save the segmentation and then extract the signals by pressing the corresponding buttons. After the signals are extracted you can select a cell with the pull down menu on the bottom left and the traces corresponding to that cell (now highlighted in green) will be displayed.  The blue trace represents the average signal within the cell, the gray trace is the neuropil, and the trace is the estimated spike rate using the Vanilla algorithm with parameters optimized for GCaMP6f.

Improvements include an Undo button, which will remove the last cell segmented. The ability to load a previous segmentation (it will load automatically after you select the *_rigid.sbx file), to continue adding cells to it.  The ability to define a ROI in the correlation map to automatically increase the contrast of the correlation map as the most salient cells are selected. A zoomed version of the mean image on the right to go along with the correlation map.  And the tool now saves the neuropil and deconvolved signal as well.

Give these tools a try. Report back any suggestions for improvements or problems you encounter.

Measuring the field of view and validating the uniformity of spatial correction

If you followed the instructions on spatial calibration you should have a nice uniform field in Scanbox.  One simple way to measure the resulting spatial resolution and spatial uniformity at each zoom setting is to mount a 40 line pairs per mm RONCHI calibration slide on top of a green aut0-fluorescent slide.  By aligning the slide with the horizontal and vertical axis of the scan you can precisely measure the size of your field:



You can also superimpose them to visually judge if the spatial correction is isotropic throughout the field… which, in our setup it is rather uniform:


The dark side bands are blanked by the pockels cell and their size is controlled by deadband configuration parameter.

Bidirectional scanning and resonant driver calibration

Resonant mirrors vary somewhat in their resonant frequency and the settings of the mirror controller must be adjusted to obtain the best possible images in bidirectional mode.

A synchronization signal from the resonant board must be adjusted so that it is both symmetric and its phase is aligned with the zero crossings of the mirror velocity.

First, connect an oscilloscope to the HSYNC signal in the extension header of Scanbox.  The HSYNC signal is exposed on the header only in the latest version of the firmware, so please download and install it from Github before proceeding.  It is the fourth pin from the left on the top row of the connector as one looks from the top.  Tip: A jumper wire makes it easy to get access to this signal without shorting nearby pins with your scope probe.


Look at this signal on the oscilloscope while scanning.  Any modern oscilloscope will allow you to measure the period of the signal as well as the positive and negative pulse width.  In the example below, the resonant frequency is 7928 Hz, the positive pulse width is 63.22 us and the negative pulse width is 62.91 us.


The first step consists in making sure the signal is symmetric.  In other words, the positive and negative pulse widths should be equal.  You can adjust this by rotating the SYM pot on the resonant scanner driver board, which is the small board mounted on top of the main Scanbox card.  There are 3 pots on this card labeled SCALE, SYM and PHASE.  The SYM pot is the one in the middle.  Slowly rotate the pot until you get the high and low pulse widths to be within 0.5 us of each other.  In the example above the difference is 0.31um.

Now, measure the laser frequency at the wavelength you typically image.  This can be done by measuring the frequency of the signal that comes out of the SYNC OUT of the Chameleon.  It will be close (but not exactly) to 80 MHz.  In my case, I get 80.10 MHz.


Now, we need to calculate the number of samples that comprise one line.  This is ratio between the laser frequency and the resonant frequency divided by 8 (because each period is two lines and each pixel is 4 samples).  Given the numbers above, we get: round(80100000/7928/8) = 1263 samples per line.

Ideally, this is where lines should be “folded” during bidirectional scanning to get even and odd lines aligned.  So, lets start by setting the ncolbi variable to be 1263 (or the value that you found for your setup) for all 3 entries in the scanbox_config file.  (Remember you need to restart Scanbox for these new values to take effect).

Now scan a target that has some nice structure at a magnification of x1.  It may still be the case that the lines are not perfectly aligned.  While looking at the image, rotate the PHASE pot on the resonant controller to make the even and odd lines align as close as possible.  Warning: this pot is VERY sensitive, so turn it slowly.  The result does not need to be perfect, but close enough so that even and odd lines do not look obviously displaced from each other.

Now, with the target in place, run the auto-calibration procedure described here.  Scanbox should be able to find the optimal values that makes the even/odd lines align as much as possible.

Note: your PMT amplifiers should be set at full-bandwidth and a gain of 10^4, resulting in a bandwidth of 80 MHz for this procedure (and for imaging in general).

After going through this procedure you should be getting nice, sharp images in bidirectional mode across the entire field (both in the center and the sides of the image).

Update 9/28/16:

It is typical for some resonant mirrors to experience a small change in frequency with time.  A typical measurement looks like this:


Resulting in 2 parts per 8000 change in frequency over the first 5 min of operation.  This change can misalign the odd/even lines by ~1 or 2 pixels, which is visible.  To ensure stable calibration and operation during bidirectional scanning, we recommend you use Scanbox in continuous resonant mode.  Here, the resonant mirror will remain in operation throughout your acquisition session.  Of course, you should also perform the above calibration after the mirror has been operating for 5 min or more.

Quick start guide to the Optotune and volumetric scanning

Scanbox uses an on-board current source to control the Optotune lens, so that changes in depth are synchronized to the beginning of each microscope frame.

Once the lens is installed, the easiest way to verify its function is to start imaging a sample and move the slider in the Optotune panel to change the plane of focus.  The value of the slider can be read at the bottom, ranging from 0 to 4095.  In the example below, the slider is set at 1879. (*)


To image a volume at approximately constant intensity Scanbox allows linking the power of the laser to different settings of the focal distance.

Start by moving the slider to the top of your imaging volume and adjust the laser power to the desired level.  By pressing the Link button on the right of the slider you establish a link between the current depth and the power level.

Repeat the process by moving the slider to focus at lower depths, which will probably require you to increase the laser power to achieve the same intensity as before.  It is typically sufficient to define 3-5 points bracketing the range of depths you will image.  Scanbox linearly interpolates among these points to cover the entire range.

Finally, to activate the link between focal plane and laser power click the Enable checkbox right below the “Link” button.  If at any point you want to define a new link between depth and power you must first clear the existing table by clicking on Clear.

Once a link between focal point and laser power is activated it will be automatically used by the system.  Try imaging a volume and change the depth using the optotune slider.  You should see the power of the laser change accordingly on the fly while keeping an approximately uniform illumination. If this is the case, you are in a position to start your volumetric imaging.

Finally, you can use the controls on the right of the panel to choose a z-scanning method.  The three boxes define the minimum value of the current, the maximum value, and its period in microscope frames. The pull-down menu allows you to switch among different waveforms: square, triangular, sinusoidal and saw-tooth.  Once you finished defining the parameters of the waveform click the upload button to send it to the Scanbox card then check Enabled in the check-box below to make the waveform active.

Now you are ready to go!

If you start scanning you should see the system scanning the desired volume, at approximate intensity throughout, and with the waveform selection you used.

You can use the Optotune in both unidirectional and bidirectional scanning.

All the optotune parameters used to collect data are stored in the info structure saved by Scanbox.

The video below illustrates the process described above:

(*) Presently the slider saturates at around 3000 due to the maximum current the present version of the board can generate (this will be corrected in future version of the board.)



Simultaneous control of an electrically tunable lens and a pockels cell

We are preparing Scanbox for fast, volumetric scanning, by providing simultaneous control of an electrically tunable lens (to focus on different planes) and a Pockels cell (to control laser power).

The Scanbox card has an integrated, 12-bit current source used to control the focus tunable lens. Similarly, an integrated DAC on the Scanbox card controls laser power via a Pockels cell. The mechanism implemented still allows for user-defined blanking of the margins.  Arbitrary tables can be uploaded from the Scanbox GUI to the card to allow for simultaneous changes in these variables that are precisely synchronized to the frames of the microscope.

Below is a demonstration showing a sinusoidal change in focusing along with matching changes in laser power.  Fast scanning with synchronized depth/power control is coming to Yeti soon!

[vimeo 119605807 w=500&h=280]

basic processing pipeline

Scanbox includes some basic processing functions that you can use to (a) align the images to compensate for (x,y) movement, (b) segment cells, (c) extract the signals corresponding to the segmented cells from the image sequences.

Motion compensation (sbxalignx & sbxaligndir)

The first step that is sometimes required is to compensate for motion in the (x,y) plane.  The basic algorithm we employ was described here.  The basic function used to align the images is called sbxalignx().

function [m,T] = sbxalignx(fname,idx)

% Aligns images in fname for all indices in idx
% m - mean image after the alignment
% T - optimal translation for each frame

This function takes the name of an image sequence (*.sbx files) and a set of indices (usually from 0 to N-1 where N is the total number of frames in the sequence) and returns an optimal translation for each frame (T) and the mean image of the stack after the alignment (m).

Typically one starts by aligning all experiments, so there is a simple function that will align all the images within a directory called sbxaligndir().  All you have to do is change the working directory in matlab to the one containing the data and simply call sbxaligndir without any arguments.  The results are saved in *.align files with the same root name as the original.

Here is what it does:

function sbxaligndir

% Align all *.sbx files in a directory

d = dir('*.sbx');
    fn = strtok(d(i).name,'.');
    if(exist([fn '.align'])==0)
       sbxread(fn,1,1);  % read one frame to read the header of the image sequence
       global info;      % this struct contains the information about the structure of the image
       [m,T] = sbxalignx(fn,0:info.max_idx-1); % align the file
       save([fn '.align'],'m','T');            % save the result
       sprintf('Done %s: Aligned %d images in %d min',fn,info.max_idx,round(toc/60))
       sprintf('File %s is already aligned',fn)
     sprintf('Could not align %s',fn)

If you open an *.align file you can check the average, aligned image and the optimal translation for each frame.

>> load -mat fc1_000_001.align
>> figure, imagesc(m),truesize,colormap gray, axis off
>> figure, plot(T)

Once images are aligned

Segmentation (sbxsegmentpoly)

Once the images are aligned one possible way to proceed is to segment the individual cells.  There are various semi-automatic ways of doing this published in the literature and we are exploring them.  At the moment we are simply manually segmenting the cells using a GUI-based tool that you can call by typing sbxsegmentpoly in the Matlab window.


The tool allows you to select arbitrary polygonal regions on the screen that define the cells.  Begin by loading an *.align file for an experiment that you have already aligned.  You can navigate around the image using the zoom and pan buttons on the top left. When ready to segment a cell hit the button that says “poly”.  This will change the cursor on the screen and allow you to click a number of vertices for your polygon.  After you trace the boundary of the cell you can close the polygon by double clicking the last vertex.  You need to hit “poly” again to segment the next cell… and so on.  You can hit “Save” any time during the process to save the areas you have already segmented.  If you open an *.align file for which a segmentation was in progress the program will load all the work you have already done.  At the end of this manual segmentation process the program generates a corresponding *.segment file that contains the segmentation data.  You can visualize the resulting segmentation as follows”

>> load -mat ge7_000_000.segment
>> imshow(label2rgb(mask,'jet','k','shuffle'))


Signal extraction (sbxpullsignals)

Now we are ready to extract the signals for each of the segmented cells from the image sequence.  The function sbxpullsignals reads the images, corrects for motion, and extract the mean signal within each of the segmented areas.  The result is a matrix with each row corresponding to each of the frames of the sequence and each columns corresponding to each of the cells.  This matrix is written into a corresponding *.signals file (the variable is named “sig”) and also returned as the output of the function.  Cell #1 (the first column) corresponds to the segmented cell for which mask=1 and so on.  So, to plot the activity of cell #10 we simply do:

>> sig = sbxpullsignals('ge7_000_000');  %% this can take time...
>> plot(sig(:,10)), axis off 


and zooming in into a segment of the  trace:


Now that you have your signals you are ready to start the specific analyses of your experiment.

We will continue to update the tools of this processing pipeline…  So stay tuned.

Live long and do good science!


Synchronize to the Laser

Scanbox makes sure the data acquisition of the signals from the photo-multipliers are synchronized to the laser pulse.  Let me explain why.  Suppose you run an asynchronous data acquisition clock at 25Mhz while the laser has a pulse rate of 80Mhz.  Then you may obtain images of single cells that look like this:

problemThis is a zoomed in view of a single cell labeled with GCamp6s.  Notice something funny about this picture? If you look along individual lines you will see that bright pixels are often next to black pixels.  If you look at another frame you will see the same pattern, except that the location of bright/dark pixels would have shifted.

What’s going on?

What is happening is that the phase of the 25Mhz clock relative to the laser pulses changes over time, producing a beat pattern.  For these choice of frequencies, the beating pattern has a period of 5 pixels.  This is because 5 pixels @ 25Mhz is the same as 16 pulses @ 80Mhz, both of which are equal to 200ns. The pattern is obvious when you compute the average auto-correlation of the fluctuations of the lines:


Yuck… Two pixels away there is a 40% anti-correlation in the signal!  How do you get rid of this problem?  Running the sampling clock at 20Mhz does not solve it.  Why?  Because the laser does not run exactly at 80Mhz so the relative phase will still drift. Moreover, the actual frequency of the laser changes with your selection of the wavelength and we want a solution that will work for all wavelengths. Another partial solution is  to temporally filter your signal by selecting PMT amplifiers with a relatively low high-cut frequency.  This, however, will decrease the spatial resolution along the resonant axis and will not solve the problem if your selection of frequencies causes the phase to drift slowly in time.  In this case, the overall brightness of your images will drift slowly back and forth between bright and dark levels. The simplest solution to this problem is to synchronize the data acquisition with your laser.  Indeed, then your single frames look nicer (note image is from a different cell) and you get sharp bright/dark edges with single-pixel resolution.


In Scanbox this synchronization is simply achieved by ‘cleaning-up’ the sync out output of the Chameleon with a BBP-70+ band pass filter from Mini-circuits.  Then, the level and slope of the trigger in the Alazartech board is fine-tuned to find the relative phase that achieves a maximal signal. The resulting settings will depend on the PMT filters that you use, but will generate the crispiest, noise-free images you optics can support.

So, if you see the sync-out of your laser not connected to anything, and your single images look like the one at the top, it is time to get this fixed.  Your data will thank you.

Welcome to Scanbox!

Welcome to Scanbox File Exchange.  This is a site where you can find regular updates to the scanbox software for two-photon imaging, report bugs, share data analysis tools and ideas for improvement.

As time goes by we will be posting tips and tricks on how to use the software, insights into the code (the Matlab software is open to the community), and documenting the various functions you can use to analyze the data.

Some of features already implemented in the release version of ScanBox:

  • Two analog and two digital channels sampled at laser frequency (80Mhz) and 16-bit depth.
  • Control of PMT gains.
  • Non-uniform spatial sampling correction in real time (raw data are streamed to disk).
  • Real time averaging and display of data.
  • Uniform power density over scan line by modulation of Pockels cell (an arbitrary waveform can be programmed).
  • Control X, Y, Z stage and tilt angle of objective.
  • Z-stack data collection
  • Movement in a rotated coordinate system that keeps the (x,y) plane normal to the objective.
  • Control of laser parameters (power, shutter, wavelength).
  • Two additional TTL signals timestamped with the frame and line number where they occurred.
  • Two GigE cameras synchronized to the microscope frame to acquire eye pupil/position and ball movement.
  • Additional GigE camera for intrinsic imaging through the same (or different) objective.
  • Additional digital I/O, I2C, SPI, current generator (for electrical tuned lens) expansion capability.
  • Remote control of the microscope over the network (change file names, start acquisition, stop acquisition, etc).
  • Matlab software for reading data, motion correction, segmentation, and signal extraction.

At the heart of the system is an AlazarTech 9440 digitizer and a custom-designed card based on the PSoC 5LP 32-bit ARM-based processor from Cypress that is in charge of generating the scan signals, generate trigger signals for the cameras, timestamp external TTL events, and more.  The card communicates with the host computer through a USB serial line.

That’s it for a quick introduction…  but, before leaving, here is one of the first movies we obtained with the microscope in Josh Trachtenberg’s Lab showing 1 min in the life of prefrontal cortex (please don’t ask me what I was doing there).  Enjoy —