<tool id="ip_concat_channels" name="Concatenate images or channels" version="0.5" profile="20.05">
    <description></description>
    <macros>
        <import>creators.xml</import>
        <import>tests.xml</import>
    </macros>
    <creator>
        <expand macro="creators/bmcv"/>
        <expand macro="creators/kostrykin"/>
    </creator>
    <edam_operations>
        <edam_operation>operation_3443</edam_operation>
    </edam_operations>
    <xrefs>
        <xref type="bio.tools">galaxy_image_analysis</xref>
    </xrefs>
    <requirements>
        <requirement type="package" version="0.25.2">scikit-image</requirement>
        <requirement type="package" version="2.3.5">numpy</requirement>
        <requirement type="package" version="2025.10.16">tifffile</requirement>
        <requirement type="package" version="0.5.2">giatools</requirement>
    </requirements>
    <command detect_errors="aggressive"><![CDATA[

        python '$__tool_directory__/concat_channels.py'

        #for $input in $inputs
            '$input'
        #end for

        '$output'
        '$axis'

        $mode

        #if $sort_by != ""
            --sort_by '$sort_by'
        #end if

    ]]></command>
    <inputs>
        <param name="inputs" type="data" multiple="true" format="tiff,png" label="Images to concatenate"/>
        <param name="axis" type="select" label="Concatenation axis" help="The images will be concatenated along this axis.">
            <option value="X">X-axis (concatenate images or image sequences horizontally)</option>
            <option value="Y">Y-axis (concatenate images or image sequences vertically)</option>
            <option value="T">T-axis (concatenate images as frames of a temporal image sequence)</option>
            <option value="Z">Z-axis (concatenate images as slices of a 3-D image or image sequence)</option>
            <option value="C" selected="true">C-axis (concatenate the channels/samples of images or image sequences)</option>
            <option value="Q">Q-axis (concatenate along other or unknown axis)</option>
        </param>
        <param name="mode" type="select" label="Scaling of values" help="If the brightness is to be preserved (default), then the values will be scaled between 0 and 1, and a floating point pixel data type will be used.">
            <option value="" selected="true">Preserve brightness</option>
            <option value="--preserve_values">Preserve range of values</option>
        </param>
        <param name="sort_by" type="select" label="Sort images before concatenating">
            <option value="" selected="true">Do not sort (keep the order of the datasets)</option>
            <option value="z_position">Sort images by their position along the Z-axis</option>
        </param>
    </inputs>
    <outputs>
        <data format="tiff" name="output"/>
    </outputs>
    <tests>
        <!-- Test with "preserve brightness", vertical concatenation -->
        <test>
            <param name="inputs" value="input1_uint8.png,input2_float.tiff"/>
            <param name="axis" value="Y"/>
            <param name="mode" value=""/>
            <param name="sort_by" value=""/>
            <expand macro="tests/intensity_image_diff" name="output" value="res_preserve_brightness.tiff" ftype="tiff"/>
            <assert_stdout>
                <has_line line="Output TIFF shape: (238, 119, 4)"/>
                <has_line line="Output TIFF axes: YXC"/>
                <has_line line="Output TIFF resolution: (1.0, 1.0)"/>
            </assert_stdout>
        </test>
        <!-- Test with "preserve range of values", vertical concatenation -->
        <test>
            <param name="inputs" value="input1_uint8.png,input2_float.tiff"/>
            <param name="axis" value="Y"/>
            <param name="mode" value="--preserve_values"/>
            <param name="sort_by" value=""/>
            <expand macro="tests/intensity_image_diff" name="output" value="res_preserve_values.tiff" ftype="tiff">
                <!--

                The input files have values ranging between 0 and 255.

                Below, we use an assertion in addition to the `image_diff` comparison, to ensure that the range of
                values is preserved. The motiviation behind this is that the expectation images are usually checked
                visually, which means that the `image_diff` comparison is likely to ensure that the brightness of
                the image is correct, thus it's good to double-check the range of values.

                -->
                <has_image_mean_intensity min="0" max="255"/>
            </expand>
            <assert_stdout>
                <has_line line="Output TIFF shape: (238, 119, 4)"/>
                <has_line line="Output TIFF axes: YXC"/>
                <has_line line="Output TIFF resolution: (1.0, 1.0)"/>
            </assert_stdout>
        </test>
        <!-- Test concatenation of channels (axis *exists* in both images) -->
        <test>
            <param name="inputs" value="input1_uint8.png,input2_float.tiff"/>
            <param name="axis" value="C"/>
            <param name="sort_by" value=""/>
            <output name="output" ftype="tiff">
                <assert_contents>
                    <has_image_width width="119"/>
                    <has_image_height height="119"/>
                    <has_image_depth depth="1"/>
                    <has_image_channels channels="8"/>
                    <has_image_frames frames="1"/>
                </assert_contents>
            </output>
            <assert_stdout>
                <has_line line="Output TIFF shape: (119, 119, 8)"/>
                <has_line line="Output TIFF axes: YXC"/>
                <has_line line="Output TIFF resolution: (1.0, 1.0)"/>
            </assert_stdout>
        </test>
        <!-- Test concatenation of frames (axis *does not* exist in both images) -->
        <test>
            <param name="inputs" value="input1_uint8.png,input2_float.tiff"/>
            <param name="axis" value="T"/>
            <param name="sort_by" value=""/>
            <output name="output" ftype="tiff">
                <assert_contents>
                    <has_image_width width="119"/>
                    <has_image_height height="119"/>
                    <has_image_depth depth="1"/>
                    <has_image_channels channels="4"/>
                    <has_image_frames frames="2"/>
                </assert_contents>
            </output>
            <assert_stdout>
                <has_line line="Output TIFF shape: (2, 119, 119, 4)"/>
                <has_line line="Output TIFF axes: TYXC"/>
                <has_line line="Output TIFF resolution: (1.0, 1.0)"/>
            </assert_stdout>
        </test>
        <!-- Test concatenation of z-slices with metadata -->
        <test>
            <param name="inputs" value="heart_ct_4043.tiff,heart_ct_3983.tiff,heart_ct_3953.tiff,heart_ct_3923.tiff"/>
            <param name="axis" value="Z"/>
            <param name="mode" value="--preserve_values"/>
            <param name="sort_by" value=""/>
            <output name="output" ftype="tiff">
                <assert_contents>
                    <has_image_width width="512"/>
                    <has_image_height height="512"/>
                    <has_image_depth depth="4"/>
                    <has_image_channels channels="1"/>
                    <has_image_frames frames="1"/>
                    <has_image_center_of_mass slice="0" center_of_mass="254.83911700, 251.72483820" eps="1e-8"/><!-- 4043 -->
                    <has_image_center_of_mass slice="1" center_of_mass="254.94356937, 251.88178729" eps="1e-8"/><!-- 3983 -->
                    <has_image_center_of_mass slice="2" center_of_mass="254.95107235, 252.04425222" eps="1e-8"/><!-- 3953 -->
                    <has_image_center_of_mass slice="3" center_of_mass="254.91235475, 252.24777978" eps="1e-8"/><!-- 3923 -->
                </assert_contents>
            </output>
            <assert_stdout>
                <has_line line="Output TIFF shape: (4, 512, 512)"/>
                <has_line line="Output TIFF axes: ZYX"/>
                <has_line line="Output TIFF resolution: (1.137778101526753, 1.137778101526753), unit: mm, z_position: -219.860001, z_spacing: 2.5"/>
            </assert_stdout>
        </test>
        <!-- Test concatenation of z-slices with metadata + sorting by `z_position` (inputs in wrong order) -->
        <test>
            <param name="inputs" value="heart_ct_3953.tiff,heart_ct_3983.tiff,heart_ct_4043.tiff,heart_ct_3923.tiff"/>
            <param name="axis" value="Z"/>
            <param name="mode" value="--preserve_values"/>
            <param name="sort_by" value="z_position"/>
            <output name="output" ftype="tiff">
                <assert_contents>
                    <has_image_width width="512"/>
                    <has_image_height height="512"/>
                    <has_image_depth depth="4"/>
                    <has_image_channels channels="1"/>
                    <has_image_frames frames="1"/>
                    <has_image_center_of_mass slice="0" center_of_mass="254.83911700, 251.72483820" eps="1e-8"/><!-- 4043 -->
                    <has_image_center_of_mass slice="1" center_of_mass="254.94356937, 251.88178729" eps="1e-8"/><!-- 3983 -->
                    <has_image_center_of_mass slice="2" center_of_mass="254.95107235, 252.04425222" eps="1e-8"/><!-- 3953 -->
                    <has_image_center_of_mass slice="3" center_of_mass="254.91235475, 252.24777978" eps="1e-8"/><!-- 3923 -->
                </assert_contents>
            </output>
            <assert_stdout>
                <has_line line="Output TIFF shape: (4, 512, 512)"/>
                <has_line line="Output TIFF axes: ZYX"/>
                <has_line line="Output TIFF resolution: (1.137778101526753, 1.137778101526753), unit: mm, z_position: -219.860001, z_spacing: 2.5"/>
            </assert_stdout>
        </test>
        <!-- Test concatenation of z-slices with a missing slice in between (`z_position` must increase) -->
        <test>
            <param name="inputs" value="heart_ct_4043.tiff,heart_ct_3983.tiff,heart_ct_3923.tiff"/>
            <param name="axis" value="Z"/>
            <param name="mode" value="--preserve_values"/>
            <param name="sort_by" value=""/>
            <output name="output" ftype="tiff">
                <assert_contents>
                    <has_image_width width="512"/>
                    <has_image_height height="512"/>
                    <has_image_depth depth="3"/>
                    <has_image_channels channels="1"/>
                    <has_image_frames frames="1"/>
                    <has_image_center_of_mass slice="0" center_of_mass="254.83911700, 251.72483820" eps="1e-8"/><!-- 4043 -->
                    <has_image_center_of_mass slice="1" center_of_mass="254.94356937, 251.88178729" eps="1e-8"/><!-- 3983 -->
                    <has_image_center_of_mass slice="2" center_of_mass="254.91235475, 252.24777978" eps="1e-8"/><!-- 3923 -->
                </assert_contents>
            </output>
            <assert_stdout>
                <has_line line="Output TIFF shape: (3, 512, 512)"/>
                <has_line line="Output TIFF axes: ZYX"/>
                <has_line line="Output TIFF resolution: (1.137778101526753, 1.137778101526753), unit: mm, z_position: -220.27666766666667, z_spacing: 3.75"/>
            </assert_stdout>
        </test>
    </tests>
    <help>

        **Concatenates images along arbitrary axes.**

        This can be used, for example, to spatially concatenate images, or along their channels.

        This tool either preserves the image brightness, or the range of values.
        In general, both cannot be preserved when concatenating images of different pixel types (e.g., uint8 and uint16).

    </help>
    <citations>
        <citation type="doi">10.1016/j.jbiotec.2017.07.019</citation>
    </citations>
</tool>