Demo and batch scripts - abria/TeraStitcher GitHub Wiki

We provide here a brief demonstration of the usage of the command line interface of TeraStitcher and of the Usage of Python with MPI and GPUs to speedup computation intensive steps of the pipeline.

1. download the example dataset from this link (7 rar files) and unrar it to a location we will refer to as <my_data>. It is a 3x3 tiled mouse cerebellum image acquired using CLSM. Each tile has size 512x512x1000 pixels and is stored as 2D tiff image series. Voxel size is 0.8x0.8x1.0 micrometers and reference system is {Y, -X, Z}.

2. import the volume into TeraStitcher to generate metadata files and an XML descriptor named xml_import.xml:

    terastitcher --import --volin=<my_data> --volin_plugin="TiledXY|2Dseries" --imin_plugin="tiff2D" --ref1=y --ref2=-x --ref3=z --vxl1=0.8 --vxl2=0.8 --vxl3=1 --projout=xml_import
   

   Please note that we have set --volin_plugin to "TiledXY|2Dseries" as the volume is tiled along XY and each tile is stored as a series of 2D tiffs (hence the usage of I/O plugin tiff2D which does support 2D tiff images).

   BTW, we could have performed the same operation simply by:

    terastitcher --import --volin=<my_data> --ref1=y --ref2=-x --ref3=z --vxl1=0.8 --vxl2=0.8 --vxl3=1
   

   where we omitted optional user inputs and their default values (see here for further details).

3. an image is stored at <my_data>/test_middle_slice.tif containing a subset of the volume stitched using nominal stage coordinates. This way, you can visually check whether TeraStitcher had correctly imported the volume before proceeding to the next step.

4. align tiles, i.e. find a series of displacements (one per layer: layers divide the volume along Z) for each pair of adjacent tiles:

    terastitcher --displcompute --projin=<my_data>/xml_import.xml --subvoldim=100 --projout=xml_displcomp
   

   where we have set layer thickness --subvoldim to 100 as it is a good compromise between RAM usage and computational effort.

   BTW, we could have performed the same operation simply by:

    terastitcher --displcompute --projin=<my_data>/xml_import.xml
   

   where we omitted optional user inputs and their default values (see here for further details).

5. project displacements so that the "most reliable" displacement is generated for each pair of adjacent tiles:

    terastitcher --displproj --projin=<my_data>/xml_displcomp.xml --projout=xml_displproj
   

   or, equivalently, by:

    terastitcher --displproj --projin=<my_data>/xml_displcomp.xml
   

6. threshold displacements according to a given reliability threshold between 0(unreliable) and 1(reliable):

    terastitcher --displthres --projin=<my_data>/xml_displproj.xml --projout=xml_displthres --threshold=0.7
   

   or, equivalently, by:

    terastitcher --displthres --projin=<my_data>/xml_displproj.xml
   

7. place tiles:

    terastitcher --placetiles --projin=<my_data>/xml_displthres.xml --projout=xml_merging
   

   or, equivalently, by:

    terastitcher --placetiles --projin=<my_data>/xml_displthres.xml
   

8. merge tiles into a 5-level multiresolution representation where each level is stored as a series of 3D tiffs:

    terastitcher --merge --projin=<my_data>/xml_merging.xml --volout=<my_stitched_data> --resolutions=01234 --volout_plugin="TiledXY|3Dseries" --imout_plugin="tiff3D" --imout_format="tif" 
   

   or, equivalently, by:

    terastitcher --merge --projin=<my_data>/xml_merging.xml --volout=<my_stitched_data> --resolutions=01234
   

   Please note that there are many other ways to store stitched data.

1. check prerequisites for using Python and MPI and GPUs

2. create a working directory

3. download the test dataset from this link (1,3 GB) and extract it in the working directory (a subdirectory tostitch will be created containing 54 subdirectories)

4. download the file xml_import.xml from this link, modify it specifying the actual complete path of the directory tostitch at line 4 (attribute value of tag stacks_dir) and put it in the working directory (see snapshot below)
   
   

5. download from this link the zip for your platform (Windows, Linux, MacOS X) containing the precompiled binaries of executables:
   
   terastitcher (minimum required version: 1.11.6)
   teraconverter(minimum required version: 3.1.19)
   mergedisplacements (minimum required version: 1.0.0)

6. download from this link the Python script that executes in parallel multiple instances of TeraStitcher

7. test sequential execution of Align step without CUDA (on Windows '/' should be changed with '\')

    ./terastitcher -2 --projin=./xml_import.xml --projout=./xml_displcomp_seq.xml --sV=58 --sH=33 --sD=0 --noprogressbar
   

8. test parallel execution of Align step without CUDA (the command specifies a 2-way parallelism, to increase parallelism just change the value of option -np; on Windows use mpiexec and '/' should be changed with '\')

   mpirun -np 3 python ./parastitcher.py -2 --projin=./xml_import.xml --projout=./xml_displcomp_par2.xml --sV=58 --sH=33 --sD=0 > ./step2par2.txt
   

   in the file step2par2.txt you find all details of execution including the total elapsed time.

9. set the use of NVIDIA GPU
   on Linux, MacOS X: export USECUDA_X_NCC=1
   on Windows: set USECUDA_X_NCC=1

10. test sequential execution of Align step with CUDA (on Windows '/' should be changed with '\')

    ./terastitcher -2 --projin=./xml_import.xml --projout=./xml_displcomp_seq_cuda.xml --sV=58 --sH=33 --sD=0 --noprogressbar
    

11. test parallel execution of Align step with CUDA (the command specifies a 2-way parallelism, to increase parallelism just change the value of option -np; on Windows use mpiexec and '/' should be changed with '\')

    mpirun -np 3 python ./parastitcher.py -2 --projin=./xml_import.xml --projout=./xml_displcomp_par2_cuda.xml --sV=58 --sH=33 --sD=0 > ./step2par2_cuda.txt
    

    consider that with just one NVIDIA GPU does not make sense to test more than a 2-way parallelism

12. prepare for test execution of the Merge step
    In the working directory create the directory stitched
    Create the subdirectories seq and par of the directory stitched
    

13. Download the file xml_merging.xml from this link, modify it specifying the actual complete path of the directory tostitch at line 4 (attribute value of tag stacks_dir) as done at step 3, and put it in the working directory

14. test sequential execution of the Merge step (on Windows '/' should be changed with '\')

    ./terastitcher -6 --projin=./xml_merging.xml --volout_plugin="TiledXY|3Dseries" --volout=./stitched/seq --resolutions=012 --slicewidth=256 --sliceheight=256 --slicedepth=256 --isotropic --noprogressbar
    

15. test parallel execution of the Merge step (the command specifies a 2-way parallelism, to increase parallelism just change the value of option -np; on Windows use mpiexec and '/' should be changed with '\')

    mpirun -np 3 python ./parastitcher.py -6 --projin=./xml_merging.xml --volout_plugin="TiledXY|3Dseries" --volout=./stitched/par --resolutions=012 --slicewidth=256 --sliceheight=256 --slicedepth=256 --isotropic > ./step6par2.txt
    

    in the file step6par2.txt you find all details of execution including the total elapsed time.