Introduction
This free code
is an ImageJ
plugin that allows different types of deformations over any given
image. The images are represented by cubic B-splines,
which allows the correct interpolation of non-integer positions and
ensures the images' continuity. SplineDeformationGenerator is now integrated in Fiji.
Ignacio
Arganda-Carreras and Carlos
Óscar Sánchez Sorzano.
Figure 1: some examples of the different deformations available with the plugin. From left to right and from top to down: the original grid image and its corresponding elastic, fisheye, perspective, barrel and smile effect examples of deformations.
General Description
SplineDeformationGenerator is an image processing interface for image deformations developed as an ImageJ plugin. It can perform 5 different types of image deformations:
- Elastic deformations (represented as well by cubic B-splines).
- Fisheye deformations.
- Perspective deformations.
- Barrel/pincushion deformations.
- "Smile" deformations, typical from 2D gels images.
Downloads
The latest distribution of the SplineDeformationGenerator plugin is dated June 12, 2008. If you detect any bug, please, feel free to contact the author. Any feedback will be very appreciated. Both, the source JAVA code and the class files can be downloaded from here:
- JAR file [64.0 KB].
- ZIP file [64.0 KB].
- RAR file [48.0 KB].
- TAR.GZ file [48.0 KB].
Api documentation
The API documentation
can be reached online here
or downloaded from here:
- ZIP file [48.0 KB].
- RAR file [48.0 KB].
- TAR.GZ
file
[32.0 KB].
Installation
SplineDeformationGenerator 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. If so, we recommend to create a "SplineDeformationGenerator"
folder there. Then, restart ImageJ and
there will be a new "SplineDeformationGenerator" or
"SplineDeformationGenerator
> SplineDeformationGenerator" (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 "SplineDeformationGenerator_.java"
file from the plugins folder.
Or you can simply download SplineDeformationGenerator_.jar
to
the plugins folder of ImageJ
(or subfolder), restart ImageJ and there will be a new
"SplineDeformationGenerator" command in the Plugins menu, or submenu.
To execute SplineDeformationGenerator as a macro or from the
command line, see the description
in the User Manual.
User Manual
Generalities
First of all, the plugin must be installed as described on Installation (for further information visit ImageJ). Once it is properly installed, the plugin should appear in the main menu either under "Plugins > SplineDeformationGenerator" > SplineDeformationGenerator" or directly under "Plugins > SplineDeformationGenerator". At least one image needs to be opened in order to be able to use the plugin. If so, the following window will pop up:
Figure 2:
main plugin window.
Select in this window the source image and the deformation model you want to be applied:
- Elastic splines. Specify the scale of the coarsest deformation ("Minimum scale"), the scale of the finest deformation ("Maximum scale") and the spline noise. The plugin perfoms a random elastic deformation of the source image based on these values.
- Fisheye. Specify the number of fisheye magnifiers, their power and radius. The plugin deforms the original image with these magnifiers created from random origins inside the image.
- Perspective. Specify the corresponding scale and shift noise for the perspective deformation to be applied to the source image.
- Barrel/Pincushion. This deformation consists in a radial distortion where the input coordinates are forced to lie in [1, -1] x [1, -1], and its corresponding polar radius r is deformed by f(r) = 1 + k1r2 + k2r4. Therefore, you have only to specify the corresponding K1 and K2 noise values and the barrel/pincushion deformation will be applied to the source image.
- 2D Gels. Specify the percentage of length reduction and maximum shift for the smile effect to be performed over the source image.
If you want to exit the plugin, press "Cancel". When you want the plugin to perform the deformation press "Done".
Output
After running the plugin, normally the result is an output window showing the deformed image:
Figure 3: source image (left) and output window (right) after applying fisheye deformation.
The results can be completed by two transformation windows if the "Show Transformation" box was marked:
Figure 4: output windows showing the x- and y- transformations that corresponds to the deformation of Figure 3
Save Transformation
If the "Save Transformation" box was marked, then a dialog will appear in order to select a file name for the transformation file. This file will follow a simple "raw" transformation format. See raw_transformation_template.txt for a format description. We strongly recommend to install bUnwarpJ plugin in order to have a tool for manipulating this type of files. For further information, see the corresponding Input/Output options in the bUnwarpJ user manual.
Macro and command line call
SplineDeformationGenerator
might be called as well as an ImageJ macro or
from the command line. Here, the program offers six different options:
- -help: shows the syntax of the program
- -elastic: performs an elastic deformation.
- -fisheye: performs a fisheye deformation.
- -perspective: performs a perspective deformation.
- -barrel: performs a barrel/pincushion deformation.
- -gels: performs a 2D gels deformation.
To see the program help we
can call the program from a macro like this:
run("SplineDeformationGenerator ","-help");
Or from the command line
(where $IJDIR
is the directory where ImageJ is installed) like this:
java -Xmx512m -cp $IJDIR/ij.jar:$IJDIR/plugins/ SplineDeformationGenerator_ -help
For the rest of the options, follow the help instructions .
References
[1] Ignacio Arganda-Carreras, Carlos O. S. Sorzano, Roberto Marabini, Jose M. Carazo, Carlos Ortiz de Solorzano, and Jan Kybic, “Consistent and Elastic Registration of Histological Sections using Vector-Spline Regularization”, Lecture Notes in Computer Science, Springer Berlin / Heidelberg, volume 4241/2006, CVAMIA: Computer Vision Approaches to Medical Image Analysis, pages 85-95, 2006.
[2] Carlos O. S. Sorzano, P. Thévenaz, M. Unser, "Elastic Registration of Biological Images Using Vector-Spline Regularization ," IEEE Transactions on Biomedical Engineering, vol. 52, no. 4, pp. 652-663, April 2005. P.
[3] Thévenaz, T. Blu, M. Unser, "Interpolation Revisited," IEEE Transactions on Medical Imaging, vol. 19, no. 7, pp. 739-758, July 2000.
[4] M. Unser, "Splines: A Perfect Fit for Signal and Image Processing," IEEE Signal Processing Magazine, vol. 16, no. 6, pp. 22-38, November 1999.
Conditions of use
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 (http://www.gnu.org/licenses/gpl.txt )
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.
We just expect you to include an acknowledgment or citation (to any of the reference papers) whenever you present or publish results that are based on it.
Enjoy it!