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: ''

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.


Click-and-Center with Knobby Mouse Control

If you have been making use of Knobby’s spatial calibration button, you can now move on to interacting with Knobby remotely.

The new Knobby scheduler panel looks a bit expanded.  The speed (coarse/fine/super-fine), the mode (normal/rotate), and zero (XYZ/XYZA) buttons should be self explanatory. They do exactly the same as if you were to be using them on Knobby.  The action you select on the panel will be reflected on Knobby’s screen as well.


The range, steps and frames entries provide a quick way to edit the scheduler’s table if you intend to do a simple z-stack.  Range is the extent of the distance in z you want to span, steps is the the size of the step (in um), and frames is the number of frames you want to scan at each position.

Finally, there is new checkbox labeled “Mouse control”. When this is active and you are scanning you can easily move around the sample by clicking the cell you want to bring to the center of the screen, as shown by the video example above.  Once you click on a cell, Knobby does the rest. We call this feature click-and-center. This works at all magnifications (even if you change it on the fly). At the same time, scrolling the mouse wheel allows you to focus up and down.  The speed of the movement will be controlled by the selected speed. You may want to start at the slowest speed (Super-fine).

Spatial Calibration and return to origin

We added two new features to the knobby scheduler panel, as shown below by the arrows.


One (left arrow) allows knobby to perform an automatic spatial calibration of the system, measuring the (x,y) size of pixels at all magnifications.  To perform this calculation do the following:

  1. Focus on some pollen grains.  Make sure one of the pollen grains is well centered on the screen at the highest magnification (x8).
  2. Make you there is an empty folder named xx0 in the data directory you selected.
  3. Hit the calibration button (pointed by the left arrow).
  4. The system will ask you if you want to proceed.
  5. Scanbox will then loop over all magnifications, collecting data for 8 sec and moving the sample by a known distance.
  6. When it finishes, Scanbox will display the optimal value of a resonant gain magnification variable that will make your pixels square.  Note that value.

Now, when you restart Scanbox the system will read the new spatial calibration in the calibration button.  The format is [xsize ysize] [xfov yfov].  The left pair shows the width and height of a pixel (in micrometers), and the right pair shows the width and height of the field-of-view at the current magnification setting (also in micrometers).  In the example above, the (x,y) size is [0.72 0.70] um, meaning the aspect ratio is close to one.

If the aspect ratio is far from one, and you prefer square pixels, do the following:

  1. Change the value of the “gain_resonant_mult” variable in the configuration file to the one suggested by the Scanbox spatial calibration, restart Scanbox.
  2. Re-run the spatial calibration.  Thi will create a new calibration file.
  3. Restart Scanbox to read the newly created calibration file.  Now the aspect ratio should be close to one.

The second feature is one is a checkbox labeled Return. When you run a knobby schedule you have click this box to make knobby return to the initial position it started from. So, for example, upon completion of a z-stack the system will go back to where it started. Note: this feature uses the Store/Recall C function, so if you have anything stored there it will be erased.



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.

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.


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

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.



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.


Knobby improvements

We have added a couple of new features to Knobby based on user feedback that some may find useful. These features are presented in different screen pages. You can switch between the three available pages by touching one of the 3 gray disks on the bottom left of the screen.


The first screen is the familiar position control screen. Here, changes in the position of the dials are interpreted as commands to change the positions of the axes by a certain distance. Use this window to navigate small distances (millimeters) around your sample.

When you need to move long distances (centimeters) between experiments, you can now use the velocity control mode in the second screen (instead of trying to move fast by spinning the knobs quickly). In velocity control mode you can move each of the axes while touching the + or – signs on the screen. The movement will continue at a fixed speed until you stop touching the screen. Velocity control is similar to what is achieved with the 3D mouse.

Warning: The microscope moves very fast in this mode, so make sure you know which direction you are moving and verify that there are no obstacles that will impede the movement. In this mode the knobs are disabled.

The third screen is the z-stack control, which allows knobby to automatically step and cover a given depth, in a given number of steps, while stepping a given number of microscope frames. This allows for an efficient collection of z-stack imagery without starting/stopping the microscope.

For Knobby to have access to the microscope frame timing you need to connect the left SMA connector (the one closer to the screen) to the CAM0 trigger output of Scanbox. The parameter values can be changed by moving the X (range), Y (steps), Z (frames) and A (arm/disarm) knobs.  The variable range represents the total travel length you want the z-stack to cover (values can be positive or negative).  The variable steps represents the total number of slices in the z-stack.  For example, if range = 100um and steps = 11, then the spacing between slices is 10um. Finally, the variable frames represents how many frames the microscope will acquire per slice.

After the parameters are set and z-stack armed, switch back to position mode before imaging. To have the best possible resolution set the position step size to S-Fine. If the objective is rotated away from vertical you can choose normal or rotated mode to decide how to move.  In rotated mode the steps will be along the axis of the objective. Now start imaging. You will notice that Knobby will automatically as selected by the parameter values.  During scanning Knobby will display changes in Z (or X and Z in rotated mode), stop once the range has been covered, and disarm automatically. You can use this feature to acquire z-stacks if you have a need to cover a range larger than what you can achieve with the optotune alone.

Here is an example of a z-stack acquired with knobby with 81 planes at 5 um separation:

To use the latest features just update the software and the knobby firmware.

Play with these options and familiarize yourself with their use before using them in an actual experiment. Let us know if you have any questions.

Updating the trinamic firmware

Some updates to Scanbox/Knobby require the update of the firmware in the Trinamic TMCM-6110 card inside the motor controller.  To update the firmware do the following:

  1. Run the program yeti/drivers/TMCL.exe
  2. Select Setup->Options from the menu.
  3. In the connection tab, select the COM port that corresponds to the card (it is typically labeled “Stepper”), and Click Ok.
  4. Select File->Open from the menu.
  5. Navigate to yeti/scanknob/ and select scanknob.tmc.  You will see the window below:tmcl
  6. Finally, click on the Download button shown by the red arrow.  The program will compile and download the code to the card.
  7. Close the program.  You are done.

After updating the motor box you are ready to start Scanbox again.  Make sure you also keep Knobby up to date by updating it with the firmware in each release.