home news gallery staff research publications teaching software join lab contact

PoorMan3DReg

A poor man's 3D registration plugin for aligning dynamic 3D volumes.

 

Introduction

So you spent all night collecting a time series of your favorite developing embryo, your growing neuron, or your dividing cell. Hey, even better: with your fancy confocal microscope, for each time point, you took a series of images at different depths through your sample. However, your sample is alive (well, you're actually quite happy about that since you've spent the last six month perfecting your technique to avoid that it dies too quickly!). Unfortunately, a live sample means it may drift or that supporting tissue may grow. Worse, you moved your Petri dish while you were resetting the microscope after the acquisition software had crashed. And now the nice movie you were planning to show at this upcoming conference is jumping from one position to the next. And you can't even think of tracking those cells (well, you tried, but you ended up tracking how your sample moved away from the field of view...). You know there must be a solution: one of those superfancy image-processing programs will let you re-align your data. But, which of those programs can actually do that?

How often did people like you walk into my office to ask me that question? I used to be quite embarassed when telling them their simple registration problem was not all that simple. But since recently, I can point them to StackReg, an excellent citeware ImageJ plugin (written by Philippe Thévenaz, the author of TurboReg, the engine that powers the StackReg plugin). But 30 seconds later, when I mention that the plugin will not register their spiffy 3D time series unless they collapse the z-stacks into a single plane, I get, at best, a horrified look: all that work to finally loose the 3D information? What a pity! Isn't there a 3D time-series registration program out there? Well, none that I know of can handle 3D time series. And certainly none that you could use for a reasonable price (such as an acknowledgement or a citation at the end of your next paper...)

Countless tears finally decided me to adapt StackReg to become a poor man's 3D registration plugin: PoorMan3DReg.

 

Why "poor man's" 3D?

Because the program does not truly align data in 3D. PoorMan3DReg starts by collapsing your data to a 2D time series. It then realigns this 2D time series: each frame is registered to its predecessor. Then, at every time point, the program applies the same transformation it applied to the projection to each of the z-slices. PoorMan3DReg will therefore not compensate for axial movement (movement in the Z-direction) and is therefore not truly 3D, hence the name.

 

So how do I use PoorMan3DReg?

You will first need to install the plugin. Here is how. Download and install ImageJ. Download and install the TurboReg plugin. Decompress the file and put the folder into the plugin folder inside the imageJ folder. Finally, do the same with PoorMan3DReg. You will also need to install the Grouped ZProjector plugin. If you want to load uncompressed LSM files from your Zeiss Microscope you will want to install the LSMReader plugin as well. Finally, if you wish to render the aligned data, some software packages may require that you save the volumes in separate files for each time-point, which you can do with the SaveToVolume plugin (included in the PoorMan3DReg distribution).

PoorMan3DReg requires that your 4D data be in a single stack [grayscale (8bit, 16bit, 32bit) or RGB (24bit)]. As you move through the stack, you go through Z then through time. For example, lets say you acquired images at 3 time points t1, t2, t3 and took 4 z-slices at position z1, z2, z3, z4. The 12 images will be ordered t1z1, t1z2, t1z3, t1z4, t2z1, t2z2, t2z3, t2z4, t3z1, t3z2, t3z3, and t3z4. Still not clear? Read on and look at the figure below.

Load your 4D data. The LSMReader plugin may come in handy. Merge the different channels into an RGB image (PoorMan3DReg is limited to 3 channels): Image → Color → RGB Merge...

Once your stack is ready, choose PoorMan3DReg from the plugins menu. This will open the following dialog:

Window of PoorMan3DReg

You may choose among 4 transformations for your registration. Depending on which one you choose, you will allow your images to be translated, translated+rotated (rigid body), translated+rotated+scaled, or translated+rotated+scaled+skewed (affine transformation).

Transformations

You need to specify how many Z slices were acquired at each time point, and what method to use for the projection of the slices (projection is used internally, your data will remain 4D).

Once you press OK, PoorMan3DReg projects the Z-sections at each time point. The latter are recursively aligned. The image that is active in the stack at the moment PoorMan3DReg is called determines the reference slice (which will remain untransformed). Based on the registrations of the projected images, the initial, 3D images are transformed. At each time point, the same transformation is applied to all depths. The latter transformation is determined by the registration of the projected slices.

PoorMan3DReg Schematic

Your aligned data are now ready to be imported into your favorite 4D imaging software. Some visualization software packages may require that there is no more than one XYZ volume per file, i.e. that there is one file (containing one XYZ volume) per time-point. The SaveToVolumes plugin has been written for that purpose.

Credits

PoorMan3DReg was written by Michael Liebling. PoorMan3DReg is essentially a modification of the StackReg plugin, written by Philippe Thévenaz and includes, to a lesser extent, code from Charlie Holly's Grouped ZProjector plugin. I take full credit for the bugs I may have added.

PoorMan3DReg relies on TurboReg, a registration program based on the following paper:
P. Thévenaz, U.E. Ruttimann, M. Unser, "A Pyramid Approach to Subpixel Registration Based on Intensity," IEEE Transactions on Image Processing, vol. 7, no. 1, pp. 27-41, January 1998.

Please acknowledge this and my work whenever you publish a result that you obtained using PoorMan3DReg.

Download
• To install PoorMan3DReg, download the file poorman3dreg.zip (37KB) decompress it and put it into the ImageJ/plugins/ directory. The archive also contains the SaveToVolumes plugin, which lets you save the concatenated volumes to separate files (one volume per file, one file per time-point).

Release note (9/24/2010): when working on grayscale images (8-bit, 16-bit, 32-bit), the previous version of poorman3dreg would wrongly return z-projections in all slices and at all timepoints (except at the reference time point). Thanks to Liang Cai for reporting the bug.

Important: PoorMan3DReg won't work if these two plugins are not installed:
TurboReg plugin
Grouped ZProjector plugin



You may also want to download a test dataset: rgbtimedepthstack.tif (472KB)
It is a stack of 16 slices, i.e. 4 z-slices at 4 time points. The legend is given below.

4D dataset legend

The source of the programs is available here: PoorMan3DReg_.java, SaveToVolumes_.java

<-->

Limitations

PoorMan3DReg does not support more than 3 channels.

 

Feedback

Please send bug reports and comments about PoorMan3DReg and this page to Michael Liebling. However, please understand that this software is provided "AS IS" and that I cannot provide any support.

 

Frequently Asked Questions

My files are huge, PoorMan3DReg dies with an "Out of Memory" error. Is there a workaround?
If you have already increased the memory available to ImageJ, using the Edit/Options/Memory command to make more memory available to ImageJ, you may want to split your data into several chunks, i.e. have t1 to t50 in the first file, t51-t100 in the next file, etc. Register each chunk separately after adding (prepending) the last timepoint of the previous chunk to the beginning of the chunk corresponding to the next interval.
Here is how this is done. Apply PoorMan3DReg to the first chunk. If you have n z-slices, the last n slices of the 4D stack correspond to the last timepoint of the first chunk. Save this sub-stack to a separate file. You may want to use the Substack Maker plugin for that. Close the stack corresponding to the first time interval and open the second time interval. Concatenate the last timepoint of the first interval and the stack corresponding to the second time interval (using the Concatenator plugin). Now, apply PoorMan3DReg to this stack. Then remove the first timepoint with Substack Maker (the timepoint that you initially added). Save the n last slices corresponding to the last timepoint of the second chunk if you have a third time interval to process and repeat all steps on the third time interval. Finally, you may concatenate all registered chunks (from within you visualization program).

 

Copyright and Disclaimer

Copyright © 2005-2010 Michael Liebling. All rights reserved.

By downloading this software from this site, you agree to the following terms and conditions.

IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, OF ANY KIND WHATSOEVER, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF HE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION IS PROVIDED "AS IS". THE COPYRIGHT HOLDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.