scanbox

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

plugin

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;

while(true)

 disp('Waiting for imaging data stream');

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

 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)

 otherwise
 disp('Invalid plugin id number');
 end

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

 end
 end
end

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.

aligntool

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.

segmenttool

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.

How to update Scanbox?

Installing updates is not very difficult.  Here is a step-by-step guide.

  • Download the latest Scanbox distribution from GitHub (download ZIP file — don’t clone).
  • Uncompress the zip file in Documents/MATLAB/<new scanbox directory>.  Keep your old distribution intact, in case something does not work and you want to restore the old version.
  • Start Matlab
  • Type “edit scanbox_config” in the Matlab window to edit the scanbox_config.m from the old version.
  • Use pathtool in Matlab to add all the subdirectories in the new distribution to the path.
  • Type “edit scanbox_config” to edit the new configuration file.  You should now have both the old and new config files on the Matlab editor. Copy the required settings form the old file to the new one.
  • To update the firmware in Scanbox do the following:
    1. Open the Cypress Bootloader Host (seearch for Bootloader if you can’t find it)
    2. For the file entry in the Bootloader Host, select the file <newdir>/drivers/DarioBox.cyacd
    3. In the Matlab command window type “scanbox_config; sb_open; sb_reset; sb_close”
    4. In the ports panel of the Bootloader host you will see a USB Human Interface Device listed immediately.  Select the device and click the Download button at the top left of the Bootloader Host Window (it is the one with an arrow pointing down). Note: you ave 20 seconds to upload the new firmware (from the time you issued the Matlab commands), otherwise Scanbox will continue booting normally. The Log panel in the Bootloader host will show if the programming of the box was successful.  You can now quit the Bootloader host.
    5. The new firmware version should now show up on the Scanbox LCD display.
  • Now we need to update Knobby.  To do so, simply go to the Matlab window and type “knobby_update”.  Wait for Knobby to update.
  • Now we need to update the firmware in the motor box.  To do so follow the instructions here
  • Close Matlab.
  • Run the vc_redist.x64.exe file in the scanbox/core/ directory.
  • Make sure you have the latest nVidia drivers and download/install any updates from here.
  • Open a command window and type “conda install pyserial”.  This will update the python serial library and any dependent components.  Reply [yes] when asked to proceed with the update.

That’s all.  Restart Matlab and launch Scanbox.  You have been upgraded!

If something goes wrong it will likely happen during startup and you will get a corresponding error message (in the form of red text in the Matlab window).  Send me the message and I will help.

Bada boom! New system coming soon!

So why the long silence in the Scanbox blog?

We have been working hard on a the development of our new system. A modular, expandable system that will run the new line of Neurolabware microscopes (aka the Kraken microscope) and is backward compatible with our previous box.

Want a sneak peak?

Bada boom!

 

nlw-full-tower

Here is a closeup of some of the LCD/power modules…

nlw-lcd-module

nlw-pwr-open

If you are interested in the new features of the Kraken microscope and the new modular system please get in touch with Neurolabware.

Virtual Knobby

Happy new year! We have plenty of exciting Scanbox developments happening this year, so stay tuned to the blog.  You don’t want to miss anything!

We recently introduced a wireless version of knobby that runs on Android tablets. The same software is now available to run on Windows, side-by-side your Scanbox application.

virtual_knobby

The controls and behavior are identical to the tablet version.  To use virtual knobby simply set the tri_knob configuration variable to “127.0.0.1”.

After launching Scanbox from Matlab go to the yeti/knoby_virtual/ directory and launch the knobby_virtual.exe application.  That’s all…  Go ahead, give it a try!

So you now have three options for position control: classic knobby, knobby tablet and virtual knobby.

Note also that if you are a user of classic knobby and run into some issues (like a rotary encoder going bad) you can always use virtual knobby as an emergency replacement while the hardware version gets fixed.  So no more downtime for a broken knobby.

 

 

Surface sampling in Scanbox

Answering a request from colleagues in London, the upcoming version of the Scanbox firmware will allow users to change the depth of imaging on a line-by-line basis.

Up to now, during volumetric imaging, users were allowed to change the setting of the electronically tunable lens (ETL) once per frame (during the transition from one frame to another).

The new version offers the possibility of changing the depth (z) as a function of the line number (y).  For example, the image of a pollen grain below, was obtained using a sinusoidal modulation in depth.

capture-1

There are at least two potential uses for this new feature.

First, one can increase the yield of imaged cells by first measuring a z-stack and then designing a (smooth) sampling surface z = f(y) that maximizes the number of cells that can be imaged.

For example, assume the projection of cell bodies within the volume is given by the scatter-plot below. Then sampling with the solid curve line will yield many more cells (red circles) than sampling with any horizontal plane (such as the dashed horizontal lines).

sampling

I will explain how to calculate an optimal (smooth) function of depth that maximizes the number of cells sampled in a separate post (the algorithm is too large to fit in the margin here.) [Actually, I added it below].

The surface sampling method offers a compromise between random access and volumetric imaging across planes, many of which may not contain many cells, thereby reducing the temporal resolution unnecessarily.  Have any groups done something like this before?

The second use of this new feature is that it can allow us to correct for the ringing in ETL focal plane that results from a step change.

If you have been doing volumetric imaging, where N frames are sampled at each depth, you might have realized that a few of the lines at the top of the frame on the first frame after a depth transition is screwy.  This is due to the ringing of the ETL. One can potentially use the ability to change ETL command on the fly to compensate for this ringing.

I have not yet implemented this.  Are there any Scanbox users doing volumetric imaging that are willing to help?

Algorithm: 

Given a set of cell body projections (y_i, z_i) we want to find a smooth function z=f(y) that intersects as many cell bodies as  possible.

We do this by restricting z(y) to be sum of the first N harmonics, z(y) =a_0+\sum_{k=1}^N a_k \cos ( 2 \pi k y + \phi_k ), so it is both smooth and periodic as well, which will prevent ringing in the ETL during fly back to the first line. The function has 2N+1 parameters.  For simplicity, here we normalize the total number of lines in the frame is normalized to be in the range [0,2 \pi].

Given a set of parameters, denote by d_i the minimum distance between the location of cell i and any of the points on the curve z(y). Our objective function is J= \sum_{k=1}^M \tanh ( (d_i - r_0)  \beta ).  Here, r_0 represents the average radius of a cell and \beta controls the sharpness of the error function near that boundary, M is the total number of cells in the volume. For a give sent of points, we used Matlab’s fminsearch to find the optimal parameters for the curve.

How much improvement in yield can we expect using surface sampling versus just one plane?

We ran a few simulations where the number of points is uniformly distributed within the volume and calculated the fraction of cells we can intersect as a function of the number of harmonics used. Zero harmonics means just the horizontal plane that intersects the maximum number of cells.yield  The graph on the left shows the results.

Even in the simple case of a uniform distribution one can more than double the yield expected from a single plane by having a few (~5-6) harmonics. In other words, using surface sampling we can double the number of cells with respect to a horizontal plane without any penalty in temporal resolution.  Not bad at all.

We will re-do this analysis with some actual volumetric data from our Lab soon. I suspect this estimate represents a lower bound on what can actually be achieved.

 

Disabling Knobby’s automatic reset

[Note: please do not use this feature yet — there are some bugs that need to be worked out. I will keep you posted.]

Up to now starting a new Scanbox session from Matlab causes knobby will auto-reset, bringing all the position counters back to zero and clearing all its position memories. This is done because there is no way for Scanbox to know if the microscope stages were moved manually from its last position (there are no absolute encoders), or if the motor box was powered off, since its last session.

Some users have asked for the option of not resetting Knobby between Scanbox sessions under the assumption that neither the stages nor the motor box have experienced  any changes between runs.  This would preserve the position counters and memories.

You can now obtain this behavior by using the knobbyreset configuration variable in the scanbox_config.m file.  Setting the variable to one will force automatic reset when starting a new Scanbox session (the default behavior up to now); a value of zero will disable the automatic reset.

The feature is now in beta testing so users should make sure everything works as expected before running new experiments with this feature turned on.  Try storing and retrieving memories across sessions, zeroing, and so on.  If you see inconsistent behavior across sessions let me know.

You can use this feature only with the wired version of knobby.  Knobby tablet does not yet support this feature.