Skip to content, Skip to search

Changes

BUnwarpJ

5,787 bytes added, 08:39, 28 October 2019
m
Acknowledgements: Fix link
{{Infobox| software = Fiji| name = bUnwarpJ| author = {{Person|Iarganda}}| maintainer = Ignacio Arganda-Carreras ([mailtoComponentStats:iargandacarreras@gmail.com iargandacarreras@gmail.com])| filename = {{Maven | g=sc.fiji | a=:bUnwarpJ_}}| source = {{GitHub|org=fiji|repo=bUnwarpJ}}| released = July 20<sup>th</sup>, 2006| latest version = 2.6.3, June 25<sup>th</sup>, 2015| status = stable, active| category = [[:Category:Registration|Registration]]}}{|
|style="vertical-align:top" |[[Image:BUnwarpJ_scheme.png|390px|bUnwarpJ scheme: bidirectional Unwarping in Java.]]
|}
* '''Show Landmarks''': it forces the landmarks to be displayed in a separate table.
* '''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_templatethe [[BUnwarpJ#What_is_the_format_of_the_raw_transformation_file.txt 3F| raw transformation example]] 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 Elastic/Raw Transformations''': it calculates the warping index of an elastic and a raw transformation (same direction). The second transformation file must be in "raw" format, i.e. the same format as the files created with the "Convert Transformation To Raw" option.
* '''Compare Raw Transformations''': it calculates the warping index of two raw transformations (same direction). 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.
* '''Convert Transformation To Elastic''': it converts a raw transformation file into a B-spline transformation file (approximation).
* '''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.
* '''Invert Raw Transformation''': it approximates the inverse of 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 a real 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 them to the high resolution images.
===Macro call===
Since [[bUnwarpJ v2.0 ]] is completely compatible with the plugin allows using [http://rsb.info.nih.gov/ij/developer/macro/macros.html ImageJ macro language] . When in doubt, use the [[Introduction_into_Macro_Programming#The_recorder|Macro Recorder]] to identify which commands need to be calledused. Therefore, the ====Main dialog====The user can launch the plugin from a macro by setting all the parameters of the plugin main windowdialog, for instance:
<source lang="java">
run( "bUnwarpJ", "source_image=A target_image=B registration=Accurate
image_subsample_factor=0 initial_deformation=[Very Coarse]
final_deformation=Fine divergence_weight=0 curl_weight=0 landmark_weight=0
image_weight=1 consistency_weight=10 stop_threshold=0.01 save_transformations save_direct_transformation=/my-path/A_direct_transf.txt save_inverse_transformation=/my-path/B_inverse_transf.txt" );
</source>
When calling Notice the plugin like this, path to the transformation files are only needed if the "save_transformations" parameter option is set to trueused.====I/O methods====To use the main Input/Output options from a macro, there is a corresponding static method defined in the main class (bUnwarpJ_). Again, the transformations files [[Introduction_into_Macro_Programming#The_recorder|Macro Recorder]] will be saved in provide with the following predefined format right macro command for each of them. For example:* Load elastic transformation to source image:<source lang=java>call(not save dialog is shown"bunwarpj.bUnwarpJ_.loadElasticTransform", "/my-path-to-transf/source_elastic_transf.txt", "target-image.png", "source-image.png");</source>* Load raw transformation to source image: <codesource lang=java>call("bunwarpj.bUnwarpJ_.loadRawTransform", "/my-path-to-transf/source_raw_transf.txt", "target-image.png", "source -image name + .png"_direct_transf);</source>* Compare opposite elastic transforms:<source lang=java>call("bunwarpj.bUnwarpJ_.compareOppositeElasticTransforms", "/my-path-to-transf/inverse_transf.txt" , "/my-path-to-transf/direct_transf.txt", "target-image.png", "source-image.png");</source>* Compare elastic and raw transforms (same direction):<source lang=java>call("bunwarpj.bUnwarpJ_.compareElasticRawTransforms", "/my-path/source_direct_transf.txt", "/my-path/source_direct_transf_RAW.txt", "target -image name + .png", "_inverse_transfsource-image.txtpng");</codesource>* ... and so on.
Only the main registration method can be called like this=====Old methods=====Before bUnwarpJ v2. To use the main Input/Output options from a macro6.7, the call function must be usedthese calls were done using methods that work on image files (not open in ImageJ). There is a corresponding static method defined in the plugin for any of this optionsFor backward compatibility reasons, these methods are still usable: [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#elasticTransformImageMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) elasticTransformImageMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#rawTransformImageMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) rawTransformImageMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#composeRawElasticTransformationsMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) composeRawElasticTransformationsMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#composeRawTransformationsMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) composeRawTransformationsMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#composeElasticTransformationsMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) composeElasticTransformationsMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#compareElasticRawTransformationsMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) compareElasticRawTransformationsMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#compareElasticTransformationsMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) compareElasticTransformationsMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#compareRawTransformationsMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) compareRawTransformationsMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#convertToRawTransformationMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) convertToRawTransformationMacro], [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#adaptCoefficientsMacro(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String) adaptCoefficientsMacro].
Notice here that the input and output file names must include the path, since they are not taken from the list of images. For instance, if we want to apply an elastic deformation stored in the file ''A_direct_transf.txt'' to the source image ''A.jpg'' with target image ''B.jpg'' and save the result in ''output.tif'', we call:
*<code>-adapt_transform</code>: adapts an specific elastic transformation given a resolution image factor
For instance, to see the program help we can call the program from the command line (where $IJDIR is the directory where ImageJ is installed) like thisin Linux:
<code>java -Xmx512m -cp $IJDIR/ij.jar:$IJDIR/plugins/bUnwarpJ_.jar bunwarpj.bUnwarpJ_ -help</code>
====Consistency weight====
It forces the resulting deformations to be one (source to target) as close as possible to the inverse of the other one (target to source). Values '''between 10.0 and 30.0''' usually work fine. It is only taken into account for registration modes "Fast" or "Accurate".
===How do I choose the initial and final deformations? What do they mean?===
These values determine the level of detail of the initial and final deformations. In [[bUnwarpJ]] this is defined by the number of B-splines that we use to represent the deformations:
 
{| class="wikitable" style="text-align:center;"
!Deformation
!Number of intervals (in the B-spline grid)
|-
|Very coarse
|1x1
|-
|Coarse
|2x2
|-
|Fine
|4x4
|-
|Very Fine
|8x8
|-
|Super fine
|16x16
|}
 
How to choose the initial and final deformation? It depends on how misaligned your images are. If they start very far away from the right alignment, it is usually a good idea to go from "Very Coarse" to "Very Fine". If they start close to the right alignment, using a very coarse initial deformation could cause the algorithm to fail. So, in that case, it would be enough to set initial deformation to "Fine" and final deformation to "Very Fine". Use "Super Fine" only when you need a very high level of accuracy, because it makes the algorithm quite slower depending on the image sizes.
===Can bUnwarpJ register 3D images?===
Unfortunately, '''no'''. If you call [[bUnwarpJ]] with two stacks as input images, it will use the second slice of every stack as the corresponding mask of the first slice. If you're looking for 3D image registration software, you may want to have a look at [http://elastix.isi.uu.nl/ Elastix], an excellent open source toolkit to perform image registration written in [http://www.itk.org/ ITK].
===How do I cite bUnwarpJ?===
The corresponding paper citation is on the [[BUnwarpJ#References|References]].
===Can I run bUnwarpJ without the graphical interface?===
'''Yes''', you can. You have different possibilities:
* You could call the program from the command line as explained in the [[BUnwarpJ#User_Manual|user manual]],
* or you can make a [[BUnwarpJ#Macro_call|macro call]] in batch mode,
* or you could as well create a script and use any of the methods called [http://javadoc.imagej.net/Fiji/bunwarpj/bUnwarpJ_.html#alignImagesBatch(ij.ImagePlus,%20ij.ImagePlus,%20ij.process.ImageProcessor,%20ij.process.ImageProcessor,%20int,%20int,%20int,%20int,%20double,%20double,%20double,%20double,%20double,%20double) bUnwarpJ_.alignImagesBatch].
===My result images are 32-bit although my input images are 8-bit, is that a bug?===
No this is not a bug. To calculate the elastic-transformed images [[bUnwarpJ]] needs to interpolate the pixel values, so the first step in the process consists of converting the 8-bit (byte) images into 32-bit (float). You may want to convert them back to 8-bit after registration (Image > Type > 8-bit) and adjust the contrast (Process > Enhance Contrast).
===How do I integrate the SIFT/MOPS results into bUnwarpJ?===
If you are using the ImageJ graphical interface, wait until the SIFT/MOPS plugin shows the results and then call immediately [[bUnwarpJ]]. The correspondences found after the SIFT or MOPS algorithms are automatically converted into [[bUnwarpJ]] landmarks. Please, be aware that if you touch any of the input images before calling [[bUnwarpJ]] you will probably loose the point selections (SIFT/MOPS correspondences) of that image and then no landmark will be displayed.
 
If you do a macro call or use the method bUnwarpJ_.alignImagesBatch, the landmarks will be read as well from the point selections of the input images.
 
If you are calling [[bUnwarpJ]] from the command line, you will have to save the SIFT/MOPS point selections in a file and use the file name in the command line call.
===What does "source and target" mean? Which image is being transformed?===
The "source" image is the image being transformed, i.e. the ''moving image'', while the "target" image is the ''fixed image''. In the "Accurate" and "Fast" modes, both images work as source and target.
===What is the format of the raw transformation file?===
The raw transformation file should be a text file with the following structure:
<source>
Width=[TARGET IMAGE WITH]
Height=[TARGET IMAGE HEIGHT]
 
X Trans -----------------------------------
[(Height * Width) coordinates representing the X transformation for every pixel on the target image]
Y Trans -----------------------------------
[(Height * Width) coordinates representing the Y transformation for every pixel on the target image]
</source>
 
== References (Citation) ==
The algorithm implemented on bUnwarpJ and its technical explanations are detailed on a publication. If you use it successfully for your research please be so kind to cite our work:
== References ==
The algorithm implemented on bUnwarpJ and its technical explanations are detailed on the paper:
* I. Arganda-Carreras, C. O. S. Sorzano, R. Marabini, J.-M. Carazo, C. Ortiz-de Solorzano, and J. Kybic, [http://cmp.felk.cvut.cz/ftp/articles/kybic/Arganda-CVAMIA2006.pdf "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.
[[bUnwarpJ]] has been developed during several years already and many people need to be acknowledged for:
It started as an extension of [[UnwarpJ]] from [http://biocomp.cnb.csic.es/~coss/ Carlos O. S. Sorzano] and thanks to him and [http://cmp.felk.cvut.cz/~kybic/ Jan Kybic] at the [http://cmp.felk.cvut.cz/Center for Machine Perception] in Prague, [[bUnwarpJ]] was born in the summer 2005 and published online in 2006.
Many of the plugin updates and improvements would have never been possible without the [[hackathon|hackathons]] that took place in [https://www.janelia.org/ Janelia Research Campus] (Virginia, summer 2008) and the [https://www.ini.uzh.ch/ Institute of Neuroinformatics] (Zürich, winter 2008).
[[Category:Plugins]]
[[Category:Registration]]
[[Category:Citable]]
Bureaucrat, emailconfirmed, incoming, administrator, uploaders
718
edits