Intrinsic & epi-fluorescence imaging using the port camera

Some colleagues have asked about the possibility of integrating imaging acquisition from the port camera to do intrinsic and/or epi-fluorescence imaging ahead of targeting a region of interest with two-photon experiments in Scanbox.

We have now added this option to Scanbox.

To use this  option you will need to wire the I2C port on the faceplate of Scanbox.  As nobody seems to be making use of I2c sensors we changed the functionality of these pins.

You will first need a camera with an output TTL signal that provides a rising edge on each frame. Most advanced cameras provide such an option.  That signal needs to be connected to pin #2 (second from the left).  We also need a synchronization signal from our visual stimulus, so we know on which frames it is presented.  A rising edge on pin #3 will be timestamped by the system with the frame number when it occurred.

That’s all you need in terms of hardware connections.

Now, you will find an extra line in the scanbox_config.m file that allows you to select the format you want to use for the port camera.  Some cameras have an 8-bit depth format that is convenient and sufficient if all you are using the camera for is to navigate around the sample. For imaging, you will probably want to use formats with pixel depths ranging from 12 to 16.  You can use Matlab’s imaqtool to see what formats are available for your camera.  Set the pathcamera_format variable to a string reflecting your selection.  For example:

sbconfig.pathcamera_format = 'Mono14';

In Scanbox, you will see a new panel which, at the moment, is sparsely populated with only 3 buttons, but should be enough to get things going.  Two buttons behave in the same way as for the eye and ball cameras: they allow you to define a ROI that will be saved.  The third button “Grab” allows you to manually start and stop the acquisition.  You can only use this button when the port camera is active. Otherwise, you will get a message complaining about it. When the port camera is active, sending a command to start and stop sampling will engage this button as well.  So the same experimental scripts you are now using for two-photon imaging can be used for imaging with the camera port without any change at all.

The data are stored in two separate files, one that contains the images themselves and the other containing the TTL data from the visual stimulation.  To read them, there are two separate functions: sbx_get_ttlevents() and sbx_read_camport_frame().

The first function takes the file name as input and simply returns a list of frame numbers during which a rising edge was present in the “stimulation” input on the I2C connector above.

So, for example:

>> ttl = sbx_get_ttlevents('xx0_111_222')'

ttl =

    200  240  280  320  360  400

This means the onset of six stimuli occurred during those frames.

The second function takes the file name and a vector of frame numbers.  It returns a volume of data where the third dimension corresponds to the selected frames.

So, for example:

>> data = sbx_read_camport_frame('xx0_111_222',ttl(1)-10:ttl(1)+10);

Will read the volume from ten frames before the onset of stimulus #1 to 10 frames after.

As things are now you have to control illumination externally.  We will work to integrate illumination and histograms of ROI values soon.

Sampling on a Surface

Not long ago I mentioned Scanbox’s new ability to sample on a surface. Now you can access this new feature in the GUI by navigating to the Surface Sampling panel.

Surface sampling allows you to link lines of the resonant scan to depths determined by the optotune setting.  In other words, it allows you to sample on a surface along the galvo axis (the vertical axis in Scanbox).  Of course, limits are imposed by the range of the optotune and its dynamical response.

Below is an example of how the process works.  Here, I am imaging a slide of pollen grains that is tilted along the vertical axis.

Because the slide is tilted, different settings of the optotune bring the grains in different lines into focus, as shown at the beginning of the video.

To compensate for the tilt we can establish a link between lines in the scan and depth. To do this, change the optotune setting while focusing, then hit the Link button, and then click on the grains that are in focus.  In this example, I repeat this a handful (3) of times.

Now, when the Enable button is clicked, Scanbox interpolates a value of the optotune for each line given the established links and uploads the resulting values to the Scanbox firmware.  When we image the slide with the link active we see all the grains in focus. In other words, Scanbox is now sampling on a slanted surface and compensating for the tilt of the slide.

This is a useful feature to use when compensating for the curvature of a structure that is being imaged or tilting the imaging plane without physically tilting the objective.

Try it and let me know if you run into any problems.

The use of this feature requires an update of Scanbox and the firmware to version 4.0.


Tiling with Knobby

Knobby scheduler allows the user to move the microscope by specifying a list of relative changes in position at given frame numbers.  One quick way to fill up the table is provided by a set of text fields in the knobby panel.  This allows one to perform (x,y,z) tiling with a given range and step size.


The first row of entries correspond to the range (in um) to be covered in the x, y and z axes respectively.  The second row specifies the step size in each case.  The last entry at the bottom tells Knobby how many frames to sample at each location.

In the example above, Knobby will perform a z-stack with 40um range and 20 um steps (that is, a total of 3 locations), on an (x,y) grid of 3×3 with 200um horizontal and vertical range and steps of 100um.

As you input the desired values the table will update automatically.

Once ready, click the “Arm” checkbox (and the “Return” checkbox if you want knobby to go back to its initial position at the end) and start your acquisition.

Here is the resulting scan for the example above:

Spatial Calibration for Multiple Objectives

Multiple users of the scope may be running projects that require different types of objectives.  How to keep a spatial calibration for each and switch between them when necessary?

Scanbox now includes an “objective” configuration variable — a cell array of strings each with the name of a different objective.  Right now I have:

% objective list
sbconfig.objectives = {'Nikon 16x','Nikon 25x'};

Now, within the Knobby panel you will see a pull down list containing the objective names:


Select the desired objective before performing a calibration.  Once the calibration is finished it will be saved.  If a calibration is not present for a given objective the calibration button will read “No Calibration” and the mouse control will be disabled. If you change the objective, simply select the corresponding entry in the pull down list to apply the new calibration (no need to restart Scanbox).

When collecting data the info structure will include the objective name and calibration data:

info =

struct with fields:

resfreq: 7930
postTriggerSamples: 5000
recordsPerBuffer: 512
bytesPerBuffer: 10240000
channels: 2
ballmotion: []
abort_bit: 0
scanbox_version: 2
scanmode: 1
config: [1×1 struct]
sz: [512 796]
otwave: []
otwave_um: []
otparam: []
otwavestyle: 1
volscan: 0
power_depth_link: 0
opto2pow: []
area_line: 1
calibration: [1×13 struct]
objective: 'Nikon 25x'
messages: {}
usernotes: ''

Visualizing Individual Slices during Volumetic Imaging

During volumetric imaging, Scanbox displays all images as they are acquired. This can be inconvenient if we are trying to visually assess the activity of neurons within any one optical slice.  One solution is to display the images separately in a montage by means of a Scanbox plug-in.  However, it would be better to have such an option integrated into Scanbox.  A new feature offers this possibility.

Turning on a  “Slice” checkbox within the Optotune panel will make a pull-down menu within the display appear.  This menu allows selection of the optical slice you want to visualize. Unchecking the slice checkbox allows Scanbox to go back to its normal operation of showing all images in the incoming stream.

Here is a brief demo showing this feature.  Enjoy…




Automatic Control of Laser Power

A new checkbox within the Laser panel (labeled AGC) allows you to turn an automatic control of laser power on and off.

When AGC is on, Scanbox checks the distribution of pixel values on the image every T seconds, and increases or decreases the laser power by a certain factor if the fraction of pixels above a threshold is outside the desired range.

The values of these parameters are found in a new section of the sbconfig.m file:

% Laser AGC
sbconfig.agc_period = 1;            % adjust power every T seconds
sbconfig.agc_factor = [0.93 1.08];  % factor to change laser power down or up if outside prctile bounds
sbconfig.agc_prctile = [1e-5 1e-3]; % bounds on percent pixels saturated wanted
sbconfig.agc_threshold = 250;       % threshold above which is considered saturated (255 is max value)


Below is a video showing AGC in action.

At the beginning of the video,  I focus on pollen grains using low power. When the AGC is turned on, it brings the power up. Then, if I increase the PMT gain, the laser power is decreased in response.  If the laser power is changed manually, AGC will re-adjust it to bring the pixel distribution within the desired limits.


AGC of laser power is useful when running a z-stack with a range that is larger than 100um or so.  In that case, engaging AGC will make Scanbox adjust laser power as a function of depth. Another situation where AGC may be useful is while running very long experiments/sessions where water may evaporate slowly leading to a reduction of the signal. In that case, turning AGC would compensate and could render the data usable.


Automatic Optotune Calibration

We previously explained how to calibrate the optotune manually.  With the introduction of Knobby 2, we are able to make this process automatic.  You will now find a ‘Calibration’ button in the Optotune panel.  To use it, do the following:

  1. Set the optotune slider to its lowest value (slide all the way down)
  2. Bring some pollen grains into focus
  3. Stop focusing
  4. Make sure the data directory has a directory named xx0
  5. Click the ‘Calibrate’ button
  6. Sit back and relax.  Wait for the process to complete.

Knobby will run some z-stack acquisitions for different values of the optotune current setting.  The volumetric data will be used to calculate the shift in z at various values of the current. A panel will display the progress in processing the images (it takes about 2 min). Scanbox will then plot the raw data and a fit by a quadratic polynomial, which may look something like this:


Scanbox will write a calibration file which will take effect next time you start Scanbox.

After restarting Scanbox, you can check the calibration as follows:

  1. Set the optotune slider to its lowest value (slide all the way down)
  2. Set Knobby to super-fine mode
  3. Focus on some pollen grains
  4. Zero Knobby (XYZ)
  5. Move out-of-focus by moving the optotune slider up to some value
  6. Now bring sample back into focus using the z-axis knob
  7. Compare the reading of the z-axis in Knobby’s screen with the depth noted in the optotune panel. These two numbers should match very closely.


A Plug-in Server

Scanbox has a memory mapped mechanism to share the incoming data stream with other processes that intend to consume the data in real-time.

Examples of simple uses of such data sharing include the calculation of rolling averages, displaying a real-time histogram, or generating a montage display for volumetric data.

Of course, different experiments may need to be processed by different plug-ins.  To simplify this process we now provide a single mechanism that allows the selection of a plug-in via a pull-down menu in the Scanbox GUI.

The configuration variable “plugin” can be used to list a number of different options to call.  In the example below, two possible options are listed.

sbconfig.plugin = {'rolling','montage'}; %plugin options

These must be names of Matlab scripts that will be called to process the data.

When Scanbox starts it will list these options in a pull down menu within the real-time processing panel, along with two check-boxes, one labeled “plugin” and another labeled “focus”.


The pull down menu allows the user to select one plugin among the available selections.

The plug-in checkbox indicates you want the data to be shared via the memory mapped mechanism, and the “focus” checkbox indicates whether you want the data to be shared not only during a grabbing operation, but also when you are focusing.

For example, adjusting the laser intensity by analyzing the histogram of values in the incoming data may be something you want to do ahead of an actual experiment, and something you will want to run while focusing.

Now, when you start Scanbox a new Matlab instance is opened and calls the sbxplugin_server.m script (assuming mmap=true in the config file).  This is a simple script that waits for new data to arrive and calls the selected plug-in.

% Scanbox plug in server script
% This code will run upon startup of Scanbox on a separate matlab instance if mmap=true
% in the scanbox_config file

% Open memory mapped file -- define just the header first

scanbox_config; % read the scanbox config structure

mmfile = memmapfile('scanbox.mmap','Writable',true, ...
 'Format', { 'int16' [1 16] 'header' } , 'Repeat', 1);
flag = 1;

disp('Plugin server ready');

% Process all incoming frames until Scanbox stops

running = false;


 disp('Waiting for imaging data stream');

 while ~running
 running = mmfile.Data.header(1)>=0;

 plugin_id = mmfile.Data.header(7); % get the plug in to be used

 fprintf('Plugin id=%d\n',plugin_id);
 fprintf('ROI=%d Expt=%d\n',mmfile.Data.header(8),mmfile.Data.header(9));

 while running

 running = (mmfile.Data.header(1) ~= -2); % no stop signal present

 if running && mmfile.Data.header(1)>=0 % if not stopped and frame present

 switch plugin_id

 case 1
 % replace the line below with your own script for
 % plugin with id #1
 fprintf('Frame: %05d Plugin: %d\n',mmfile.Data.header(1),plugin_id);

 case 2
 % replace the line below with your own script for
 % plugin with id #2
 fprintf('Frame: %05d Plugin: %d\n',mmfile.Data.header(1),plugin_id)

 disp('Invalid plugin id number');

 mmfile.Data.header(1) = -1; % signal Scanbox that frame has been consumed!


clear(mmfile); % close the memory mapped file
close all; % close all figures

The default server code simply lists number of of the incoming frame and the selected plug-in.  Just add an eval() call to the script name at the indicated locations.

The output of the script, as is, will look like:

Waiting for imaging data stream
Plugin id=2
ROI=0 Expt=0
Frame: 00000 Plugin: montage
Frame: 00001 Plugin: montage
Frame: 00002 Plugin: montage
Frame: 00003 Plugin: montage
Frame: 00004 Plugin: montage
Frame: 00005 Plugin: montage
Frame: 00006 Plugin: montage
Frame: 00007 Plugin: montage
Frame: 00008 Plugin: montage
Frame: 00009 Plugin: montage
Frame: 00010 Plugin: montage
Waiting for imaging data stream

The user can now easily switch between plugins from the Scanbox window by changing the selection in the pull down menu.


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.

Knobby scheduler

CaptureA new Scanbox panel allows users to define arbitrary changes in (x,y,z) position over time (frames) which are then executed by Knobby (version 2 only) while imaging.

Each entry define changes in x, y and z (in micrometers) relative to the present position and the frame number at which they will take place.

The “mem” column allows one to specify one of the stored absolute coordinates instead (memory locations are coded A=1, B=2, C=3).  If a memory location is defined the other entries are ignored and the position in the referenced memory is used instead.

This mechanism extends the z-stack functionality to include the ability to tile a sample and brings back the control window to one of the panels in Scanbox (as opposed to being controlled in Knobby’s screen).  The Knobby table is also saved in the info.knobby_table variable.

Paths can be computed offline and stored in a Matlab file that can be loaded.  The example below shows knobby moving the sample along a circular path.

Update [ 7/3/17]: You will now note an additional checkbox in the Knobby Scheduler panel called “Return”. When you arm knobby scheduler and check this box the microscope will automatically return to the initial position after imaging is done.  This feature uses the Store/Recall C function for functionality.  Anything stored previously in C is going to be erased if you use this feature.