Biomedical Imaging GroupSTI
  Download Algorithms
English only   BIG > Download Algorithms >StackReg

 Home Page
 News & Events
 Tutorials and Reviews
 Download Algorithms
 Red bullet Related Work
 Red bullet Technical Explanations
 Red bullet User Manual
 Red bullet Macro
 Red bullet Conditions of Use

 UNIX distribution
 Macintosh distribution
 PC distribution


An ImageJ plugin for the recursive alignment of a stack of images.

Philippe Thévenaz, Biomedical Imaging Group, Swiss Federal Institute of Technology Lausanne

Murine brain before and after registration

Figure 1. Left: Set of Nissl-stained sections of a murine brain. The sections are 0.84mm apart and the pixel size is (0.126mm × 0.126mm). This dataset is available here [465'058 bytes]. Right: Stack after having applied the alignment procedure. The ninth slice was used as anchor slice.

General Description

The purpose of this plugin is to register—in other words, to align or to match—a stack of image slices. In turn, each slice is used as the template with respect to which the next slice is aligned, so that the alignment proceeds by propagation. When the plugin is launched, the current slice acts as a global anchor.

The StackReg plugin requires that a second plugin, named TurboReg, is installed. This ancillary plugin is available here.

After completion of the registration process, the original stack is destroyed and replaced by the result of the registration. The name and the type of the stack is left unchanged; all data types are admissible, except RGB-stack and HSB-stack. (Please note that an RGB-stack is a stack of three color components; it should not be confounded with a stack of RGB-color images: the latter is indeed admissible, while the former is not. In case of doubt, just try; no harm will ensue.)

I. Download

This distribution is dated July 7, 2011. It includes the complete set of source files, along with the precompiled classes.

II. Related Work

The StackReg plugin requires that a second plugin, named TurboReg, is installed. This ancillary plugin is available here.

This set of Java classes is 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. Other relevant on-line publications are available at http://bigwww.epfl.ch/publications/.

It is written as a plugin for ImageJ. Please read the ImageJ documentation to learn how to install plugins.

III. Technical Explanations

Four types of transformation are considered:

  1. Translation. The mapping of coordinates takes the form x = u + Δu. There, the input coordinate u is mapped to the output coordinate x, and the constant vector Δu gives the amount of translation.
  2. Rigid Body. The mapping of coordinates takes the form x = { {cos θ, −sin θ}, {sin θ, cos θ} } ⋅ u + Δu. Because of the presence of the term Δu, translation is considered too, in addition to the rotation by an angle θ.
  3. Scaled rotation. The mapping of coordinates takes the form x = λ { {cos θ, −sin θ}, {sin θ, cos θ} } ⋅ u + Δu. The difference with respect to a rigid-body transformation is the presence of the scalar resizing factor λ.
  4. Affine. The mapping of coordinates takes the form x = { {a11, a12}, {a21, a22} } ⋅ u + Δu. As the four coefficients a11, a12, a21, and a22 are independent, an affine transformation has even more degrees of freedom than a scaled rotation.

Those four types of transformation are available from the scroll list that should appear when the StackReg plugin is launched. The fifth transformation type (bilinear transformation), available in TurboReg, does not appear in StackReg because a combination of bilinear transformations does not generally result in a bilinear transformation. It is therefore not possible to propagate such transformations from slice to slice.

Often, performing a geometric transformation requires access to data beyond the image frame. As such data are not available, they are replaced in the output image by zeroes wherever necessary. Taking the example of a rotation, this would typically result in triangular black borders framing the output image.

IV. User Manual

Dialog box

Dialog box

Figure 2. Dialog box.

The dialog box of Figure 2 will appear upon launching StackReg, provided at least one image or stack is available, and provided the type of the current image is admissible. An explicit error message should appear otherwise. Clicking the [Cancel] button aborts the plugin. Setting a tickmark on the [Credits] checkbox and clicking the [OK] results in the information panel of Figure 3. Simply clicking the [OK] button applies the plugin to the current image or stack. The applied transformation is that which is selected in the [Transformation] scroll list.

The current slice will not be transformed and is used to anchor the registration. During the registration process, the slice being registered is displayed; after the registration process is completed, the display returns to the slice that was the current one at launch time.


Figure 3. Credits.

When a stack of color images is provided, the registration proceeds on a grayscale version that is built as a weighted sum of the red, green, and blue components—even when the stack is pseudo-color. The weights depend on the whole stack and are determined by a principal-component analysis in such a way as to provide the maximum possible contrast. Once the geometry has been determined on the basis of the intermediate grayscale representation, a true color image is reconstructed, and is re-quantized if it is desired to produce pseudo-colors.

The present plugin (StackReg) is used as a front-end to another plugin named TurboReg. Several mechanisms are at work to exchange data between these plugins. One of them involves temporary files which are written into the temporary directory that ImageJ defines. The location of this directory can be examined by issuing the macro command 'print(getDirectory("temp"));'. The names of the written files are

  • StackRegSource
  • StackRegSourceR
  • StackRegSourceG
  • StackRegSourceB
  • StackRegTarget

Warning: existing files of the same name in the temporary directory may be silently overwritten.

V. Macro

StackReg is scriptable and recordable. Here is an example of a call to StackReg from a macro:
run("StackReg ", "transformation=[Rigid Body]");

VI. Conditions of Use

© 2011 Philippe Thévenaz

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

You undertake to include a citation or acknowledgment whenever you present or publish results that are based on this program. EPFL makes no warranties of any kind on this software and shall in no event be liable for damages of any kind in connection with the use and exploitation of this technology.