annotate imagej2_bunwarpj_align.xml @ 0:ab54024c0a88 draft

"planemo upload for repository https://github.com/bgruening/galaxytools/tree/master/tools/image_processing/imagej2 commit b08f0e6d1546caaf627b21f8c94044285d5d5b9c-dirty"

<?xml version='1.0' encoding='UTF-8'?>
<tool id="imagej2_bunwarpj_align" name="Align two images" version="@WRAPPER_VERSION@.0">
    <description>with bUnwarpJ</description>
    <macros>
        <import>imagej2_macros.xml</import>
    </macros>
    <expand macro="fiji_requirements" />
    <command>
<![CDATA[
    python $__tool_directory__/imagej2_bunwarpj_align.py
    --target_image "$target_image"
    --target_image_format $target_image.ext
    --source_image "$source_image"
    --source_image_format $source_image.ext
    #if $align_with_mask_cond.align_with_mask == 'yes':
        --target_mask "$target_mask"
        --target_mask_format $target_mask.ext
        --source_mask "$source_mask"
        --source_mask_format $source_mask.ext
    #end if
    --min_scale_def $min_scale_def
    --max_scale_def $max_scale_def
    --max_subsamp_fact $max_subsamp_fact
    --divergence_weight $divergence_weight
    --curl_weight $curl_weight
    --image_weight $image_weight
    --consistency_weight $consistency_weight
    #if $advanced_options_cond.advanced_options == 'landmarks':
        --landmarks_weight $advanced_options_cond.landmarks_weight
        --landmarks_file "$advanced_options_cond.landmarks_file"
    #else if $advanced_options_cond.advanced_options == 'affine':
        --target_affine_file "$advanced_options_cond.target_affine_file"
        --source_affine_file "$advanced_options_cond.source_affine_file"
    #else if $advanced_options_cond.advanced_options == 'mono':
        --mono "true"
    #else if $advanced_options_cond.advanced_options == 'save_transformation':
        --target_trans_out "$target_trans_out"
        --source_trans_out "$source_trans_out"
    #end if
    --source_out "$source_out"
    --source_out_datatype $source_out_datatype
    #if $advanced_options_cond.advanced_options != 'mono':
        --target_out "$target_out"
        --target_out_datatype $target_out_datatype
    #end if
    --jython_script $__tool_directory__/imagej2_bunwarpj_align_jython_script.py
]]>
    </command>
    <inputs>
        <param format="bmp,eps,gif,jpg,pcx,pgm,png,psd,tiff" name="target_image" type="data" label="Target image"/>
        <param format="bmp,eps,gif,jpg,pcx,pgm,png,psd,tiff" name="source_image" type="data" label="Source image"/>
        <conditional name="align_with_mask_cond">
            <param name="align_with_mask" type="select" label="Align with masks?" help="Source and target mask can be any image format.">
                <option value="no" selected="True">No</option>
                <option value="yes">Yes</option>
            </param>
            <when value="no" />
            <when value="yes">
                <param format="bmp,eps,gif,jpg,pcx,pgm,png,psd,tiff" name="target_mask" type="data" label="Target mask"/>
                <param format="bmp,eps,gif,jpg,pcx,pgm,png,psd,tiff" name="source_mask" type="data" label="Source mask"/>
            </when>
        </conditional>
        <param name="min_scale_def" type="select" label="Initial deformation">
            <option value="0" selected="True">Very Coarse</option>
            <option value="1">Coarse</option>
            <option value="2">Fine</option>
            <option value="3">Very Fine</option>
        </param>
        <param name="max_scale_def" type="select" label="Final deformation">
            <option value="0">Very Coarse</option>
            <option value="1">Coarse</option>
            <option value="2" selected="True">Fine</option>
            <option value="3">Very Fine</option>
        </param>
        <param name="max_subsamp_fact" type="integer" value="0" min="0" label="Image sub-sample factor" help="Power of 2: [0, 1, 2 .. 7]"/>
        <param name="divergence_weight" type="float" value="0.0" label="Weight of the divergence term" help="Value is a floating point number"/>
        <param name="curl_weight" type="float" label="Weight of the curl term" value="0.0" help="Value is a floating point number"/>
        <param name="image_weight" type="float" label="Weight of the image term" value="1.0" help="Value is a floating point number"/>
        <param name="consistency_weight" type="float" label="Weight of the deformation consistency" value="10.0" help="Value is a floating point number"/>
        <param name="target_out_datatype" type="select" label="Save registered target image as format">
            <expand macro="image_datatypes" />
        </param>
        <param name="source_out_datatype" type="select" label="Save registered source image as format">
            <expand macro="image_datatypes" />
        </param>
        <!--
        The following additional options can be added to the advanced_options select
        list as soon as appropriate.  Their use is supported in the imagej2_bunwarp_align.py
        wrapper.

        I invested heavily in working with landmarks, but could never get them to
        produce the same results from both the ImageJ GUI and the command line.  I'm
        convinced this is not a result of using Galaxy as I tested using ImageJ in headless
        mode outside of Galaxy and the results differed from using the ImageJ GUI. Until
        we know the reasons for these differences, we will eliminate this option.
        <option value="landmarks">Apply landmarks</option>

        A separate tool will be needed to create an affine matrix transformation file,
        so we'll eliminate this option until we have that tool.
        <option value="affine">Apply affine matrix transformation</option>
        
        Similar to landmarks, I could not get the ImageJ mono option to produce the same
        results from the ImageJ GUI and in headless mode from the command line.
        <option value="mono">Unidirectional registration (source to target)</option>
        -->
        <conditional name="advanced_options_cond">
            <param name="advanced_options" type="select" label="Advanced options" help="These are mutually exclusive for each execution">
                <option value="none" selected="True">None</option>
                <option value="save_transformation">Save calculated transformations</option>
            </param>
            <when value="none" />
            <!--
            <when value="landmarks">
                <param name="landmarks_weight" type="float" label="Landmark weight" value="0.0" help="Value is a floating point number"/>
                <param format="txt" name="landmarks_file" type="data" label="Landmark file"/>
            </when>
            <when value="affine">
                <param format="txt" name="target_affine_file" type="data" label="Initial target affine matrix transformation"/>
                <param format="txt" name="source_affine_file" type="data" label="Initial source affine matrix transformation"/>
            </when>
            <when value="mono"/>
            -->
            <when value="save_transformation"/>
        </conditional>
    </inputs>
    <outputs>
        <data name="source_out" format="png" label="${tool.name} on ${on_string}: Registered source image">
            <actions>
                <action type="format">
                    <option type="from_param" name="source_out_datatype" />
                </action>
            </actions>
        </data>
        <data name="target_out" format="png"  label="${tool.name} on ${on_string}: Registered target image">
            <filter>advanced_options_cond['advanced_options'] != "mono"</filter>
            <actions>
                <action type="format">
                    <option type="from_param" name="target_out_datatype" />
                </action>
            </actions>
        </data>
        <data format="txt" name="source_trans_out" label="${tool.name} on ${on_string}: Direct source transformation matrix">
            <filter>advanced_options_cond['advanced_options'] == "save_transformation"</filter>
        </data>
        <data format="txt" name="target_trans_out" label="${tool.name} on ${on_string}: Inverse target transformation matrix">
            <filter>advanced_options_cond['advanced_options'] == "save_transformation"</filter>
        </data>
    </outputs>
    <tests>
        <test>
            <!-- Align two images without landmarks or mask and not saving transformation matrices -->
            <param name="target_image" value="dotblot.jpg" />
            <param name="source_image" value="blobs.gif" />
            <param name="min_scale_def" value="0" />
            <param name="max_scale_def" value="2" />
            <param name="max_subsamp_fact" value="1" />
            <param name="divergence_weight" value="0.0" />
            <param name="curl_weight" value="0.0" />
            <param name="image_weight" value="1.0" />
            <param name="consistency_weight" value="10.0" />
            <param name="target_out_datatype" value="png" />
            <param name="source_out_datatype" value="png" />
            <output name="source_out" file="registered_source1.png" compare="sim_size" />
            <output name="target_out" file="registered_target1.png" compare="sim_size" />
        </test>
        <test>
            <!-- Align two images without landmarks or mask, but saving transformation matrices -->
            <param name="target_image" value="dotblot.jpg" />
            <param name="source_image" value="blobs.gif" />
            <param name="min_scale_def" value="0" />
            <param name="max_scale_def" value="2" />
            <param name="max_subsamp_fact" value="1" />
            <param name="divergence_weight" value="0.0" />
            <param name="curl_weight" value="0.0" />
            <param name="image_weight" value="1.0" />
            <param name="consistency_weight" value="10.0" />
            <param name="target_out_datatype" value="png" />
            <param name="source_out_datatype" value="png" />
            <param name="advanced_options" value="save_transformation" />
            <output name="source_out" file="registered_source1.png" compare="sim_size" />
            <output name="target_out" file="registered_target1.png" compare="sim_size" />
            <output name="source_trans_out" file="source_elastic_transformation.txt" />
            <output name="target_trans_out" file="target_elastic_transformation.txt" />
        </test>
        <test>
            <!-- Align two images without landmarks but with mask, not saving transformation matrices -->
            <param name="target_image" value="dotblot.jpg" />
            <param name="source_image" value="blobs.gif" />
            <param name="target_mask" value="mask_white.png" />
            <param name="source_mask" value="mask_ramp.gif" />
            <param name="min_scale_def" value="0" />
            <param name="max_scale_def" value="2" />
            <param name="max_subsamp_fact" value="1" />
            <param name="divergence_weight" value="0.0" />
            <param name="curl_weight" value="0.0" />
            <param name="image_weight" value="1.0" />
            <param name="consistency_weight" value="10.0" />
            <param name="target_out_datatype" value="png" />
            <param name="source_out_datatype" value="png" />
            <output name="source_out" file="registered_source2.png" compare="sim_size" />
            <output name="target_out" file="registered_target2.png" compare="sim_size" />
        </test>
    </tests>
    <help>
**What it does**

<![CDATA[
Performs a simultaneous registration of two images, A and B. Image A is elastically deformed
in order to look as similar as possible to image B, and, at the same time, the "inverse"
transformation (from B to A) is also calculated so a pseudo-invertibility of the final deformation
could be guaranteed.  RGB Color images will be converted to grayscale during the registration
process but the resulting transformations will be applied to the original color images.

Two images are produced: the deformed versions of A and B images.

.. image:: ./static/images/bunwarpj_scheme.png

Both selected images will work simultaneously as source and target, their tags are there only for the sake
of clarification. The registration mode is currently restricted to "Fast" ("Mono" has been eliminated for now).
The registration mode "Mono" perfoms only unidirectional registration, i.e. from source to target.  The
registration mode "Fast" involve performing bidirectional registration and affects the stopping criteria
internally used by the bUnwarpJ program.

Using the **Align with masks** otion, masks are introduced together with the input images.  In this mode, the
input images is treated as the first slice of the mask pair and the mask is treated as the second slice.  In this
way, the mask can have any shape.

The **Initial deformation** and **Final deformation** options allow you to select the coarsest and finest scale
of the spline deformation field. "Very coarse" corresponds to 4 splines (one in each corner of the image). As you
increase the deformation level, the number of splines is doubled in each direction (horizontal and vertical).

The value of the **Image sub-sample factor** will enable the registration to be calculated using the subsampled
versions of the images but the results will be applied to the original ones. The image subsampling parameter can
be set from 0 and 7, i.e. the image dimensions can be reduced by a factor of 20 = 1 to 27 = 128. This is very
useful when registering large images.

The different weights of the goal function control the relative weight of each one of the terms. These weights
are not restricted to be between 0 and 1, and they may take any value as long as it is non-negative=2E.

If the **Advanced option - Save transformation** option is selected, two files are produced in addition to
the registerd source and target images: the direct transformation matrix of A and the inverse transformation
matrix of B.
]]>

    </help>
    <expand macro="bunwarpj_citations" />
</tool>