bUnwarpJ

When calling the plugin like this, if the "save_transformations" parameter is set to true, the transformations files will be saved in the following predefined format (not save dialog is shown): source image name + "_direct_transf.txt" and target image name + "_inverse_transf.txt".

SIFT and MOPS support

You can see an example of the combination of both methods in the macro AffineConsistentElasticRegistration.txt by Marta Rivera-Alba and Ignacio Arganda-Carreras. It uses MOPS and bUnwarpJ to register an entire stack of images using the first slice as reference.

bUnwarpJ v1.1

• bUnwarpJ_.jar [151 KB] .
  
• ZIP file [152 KB].
• RAR file [140 KB].
• TAR.GZ file [146 KB].
  

API documentation - bUnwarpJ v1.1

The API documentation can be reached online here or downloaded from here:

• ZIP file [111 KB].
• RAR file [100 KB].
• TAR.GZ file [77 KB].

Installation - bUnwarpJ v1.1

bUnwarpJ v1.1 works as a plugin for ImageJ, but can be also called from the command line. To use it with the ImageJ interface there are several options:

You can download and uncompress one the files above to the plugins folder. We recommend to create a "bUnwarpJ" folder there. Then, restart ImageJ and there will be a new "bUnwarpJ" or "bUnwarpJ > bUnwarpJ" (if a folder was created) command in the Plugins menu. Instead of restarting ImageJ, it is possible as well to use the "Plugins > Compile and Run..." option selecting the corresponding "bUnwarpJ_.java" file from the plugins folder.

Or you can simply download bUnwarpJ_.jar to the plugins folder of ImageJ (or subfolder), restart ImageJ and there will be a new "bUnwarpJ" command in the Plugins menu, or submenu.

To execute bUnwarpJ v1.1 as a macro or from the command line, see the description in the User Manual - bUnwarpJ v1.1.

User manual - bUnwarpJ v1.1

Generalities

First of all, the plugin must be installed as described on Installation (for further information go to ImageJ). Once it is properly installed, the plugin should appear in the main menu under Plugins > bUnwarpJ > bUnwarpJ. Two images need to be opened in order to be able to use the plugin. The main options of the program are preserved from the previous work (UnwarpJ - user manual), so we will only describe here the relevant novelties.

Consistency weight

Under the "Advanced options" panel of the main bUnwarpJ v1.1 window there is a new parameter to play with: the Consistency Weight. This number forces the algorithm to move into solutions that ensure the invertibility of the resulting deformations. Therefore, higher is this number, more strictly is one deformation the inverse of the other. Due to the different units, there is no rule for selecting the right parameters. For instance, to perform the registration of the tumor images above, we recommend consistency weight values around 20.0.

Figure 1: Advanced Options window (v1.1).

One important advantage of bUnwarpJ over the previous method lies in the fact that many registration problems can be solved without using the landmarks and regularization terms of the energy function (that means setting their corresponding parameters to 0.0). Therefore, no user interaction is needed and the computational complexity of the algorithm is reduced.

Validation and transformations' comparison

When using the "I/O Menu" from the toolbar, we have the possibility of processing different input and output files that will affect the registration.

Figure 2: ImageJ toolbar when using bUnwarpJ v1.1 plugin. I/O menu option is selected.

Figure 3: I/O Menu options.

After last release, the plugin presents the following Input/Output options:

• Load Landmarks: it allows loading landmarks files.
• Save Landmarks As: it allows saving the image landmarks into a file.
• Show Landmarks: it forces the landmarks to be displayed.
• Load Elastic Transformation: it loads an elastic transformation from a file and applies it to the so-called source image. The transformation file must be in the format of the plugin B-spline transformations, i.e. the same format as the files created with the "Save Transformation" option.
• Load Raw Transformation: it loads a raw transformation from a file and applies it to the so-called source image. The transformation file must be in "raw" format, i.e. the same format as the files created with the "Convert Transformation To Raw" option. See raw_transformation_template.txt for a format description.
• Compare Opposite Elastic Transformations: it calculates the warping index of two elastic transformations, i.e. the average of the geometrical distance between every pixel and its version after applying both transformations (direct and inverse). This value is given as a result. The transformation files must be in the format of the plugin B-spline transformations (same format as the files created with the "Save Transformation" option).
• Compare Raw Transformations: it calculates the warping index of two raw transformations. The transformation file must be in "raw" format, i.e. the same format as the files created with the "Convert Transformation To Raw" option.
• Convert Transformation To Raw: it converts a B-spline transformation file into a raw transformation file.
• Compose Elastic Transformations: it composes two elastic transformations into a raw transformation. The input files must be in the B-spline transformation format, and the output file will be in "raw" format.
• Compose Raw Transformations: it composes two raw transformations into another raw transformation. Both input and output files will be in "raw" format.
• Compose Raw and Elastic Transformations: it composes one raw transformation and one elastic transformation into a raw transformation.
• Evaluate Image Similarity: it calculates de current similarity error between the source and target images. The results is displayed in the "Results" window.
• Adapt Coefficients: it transforms the coefficients of an specific elastic transformation according to an integer image factor. Very useful for example when we have very large images. We can register subsampled versions of our images (let us say 4 times smaller) and then adapt the result transformations (image factor = 4) so we can apply to the high resolution images.
• Load Source Mask: it loads a mask from file (binary image) in the source image.
• Load Source Initial Affine Matrix: it loads an affine matrix as starting point for the source-target transformation.

These new options allow the user to compare the result of our program with any other registration method. 

You can also test bUnwarpJ v1.1 with SplineDeformationGenerator, a new ImageJ plugin that allows the user to generate five different image deformations: elastic, fisheye, perspective, barrel/pincushion and smile effect. SplineDeformationGenerator uses the same raw transformation file format as bUnwarpJ v1.1, so they are completely compatible.

Results

After the registration process, the results are presented in two stacks. Every stack presents the registered image, the corresponding target image and the warped source mask. In addition, if the "Verbose" option was marked in the "Advanced options" panel, the stacks will present as well the deformation field and grid, and a "Results" window will appear during the whole registration process showing the optimizer's steps.