= About xuvtools - the ''eXtent Ur Viev Toolset'' =

The xuv toolset currently consists of the following tools:
* xuvstitch (xuvstitch, overlay_stacks, bleachcorrect and find_absolute_positions)

Planned, but not yet released are:
* xuvhdr

= About xuvstitch =

The approach of our stitcher to the problem is best illustrated in the following image:
[[Image:Stitching-principle-overview01.jpg|thumb|Basic principle]]

=== Example usage ===

All tools support the command line options -h / --help, and will print out detailed usage information.

A common way of usage would be the following:
* Given is a dataset ''example.nc'', consisting of X (time-)stacks and Y channels: t0_channel0 to tX_channelY
* calling the stitcher with the dataset (fill in the names of the rest of the stacks at [...]):
 FILE="example"
 xuvstitch \
  --objfile ./${FILE}.nc --outfile ./${FILE}_corr.nc \
  --channels Y --verbose 8 --sampling 20 \
  --stacks t0_channel t1_channel [...] tX_channel
* calling the position estimation with the correlation result (using an initial threshold of 0.3):
 find_absolute_positions \
  --corrfile ./${FILE}_corr.nc --outfile ./${FILE}_pos.nc \
  --verbose 4 --corrthresh 0.3
* create a color overlay to visualize stitching quality (the important argument is --color):
 overlay_stacks \
  --objfile ./${FILE}.nc --positionfile ./${FILE}_pos.nc --outfile ./${FILE}_color.nc \
  --color --verbose 4 --blending 4
* apply bleaching correction to the stacks (the important argument is --width <in um>):
 bleachcorrect \
  --objfile ./${FILE}.nc --positionfile ./${FILE}_pos.nc --outfile ./${FILE}_bcorr.nc \
  --verbose 4 --thresh 10 --factor 0.60 --width 60
* create the final overlay with the bleachcorrected stacks:
 overlay_stacks \
  --objfile ./${FILE}_bcorr.nc --positionfile ./${FILE}_pos.nc --outfile ./${FILE}_overlay.nc \
  --verbose 4 --blending 4



= Installation HowTo =

=== Installation of xuvtools on i386 or/and x86_64 ===

This HOWTO describes the full local installation of the current CVS snapshot. It assumes you are running a linux (or compatible) box on an x86 (or compatible) platform. The installation 
process will allow to compile and install builds for different architectures based on one source tree. Using a bash shell for installation is recommended, for then nearly all the 
following commands can be simply copied into the terminal (except for the CVS command, that requires you to fill in your user name)

'''Prerequisites''':

g++ (4.x recommended), libtool, autoconf, automake, libtiff, libnetpbm, libgsl, cvs

 aptitude install g++ libtool autoconf automake libtiff4-dev libnetpbm10-dev cvs libgsl0-dev

The list may be not complete, install missing packages as needed.

* Change to the base directory you want xuvtools to reside below later (e.g. /misc/database/<login>/)
* Checkout current version of xuvtools (replace <login> with your cvs login name, the one you have gotten from us)

 cvs -d :pserver:<login>@falballa.informatik.uni-freiburg.de:/xuvtools login
 cvs -d :pserver:<login>@falballa.informatik.uni-freiburg.de:/xuvtools co xuvtools

The checkout creates a new directory 'xuvtools' in the current working directory. Create a variable with the path to that directory for later usage. Additionally create a variable for the 
destination of libraries, binaries, etc. The destination path depends on your platform. The usage of "$HOSTTYPE" gives a good choice for the name of the destination directory and enables 
the possibility of automatic environment setup on different machines.
 export XUVSRC=${PWD}/xuvtools
 export XUVDEST=${XUVSRC}/$HOSTTYPE
"$HOSTTYPE" will return something similar to i386 for a 32bit and x86_64 for a 64bit machine

* Add xuvtools binary paths to your PATH environment variable. This is necessary, because subsequent packages need to find config scripts of dependent packages.
 export PATH=${XUVDEST}/bin:${XUVDEST}/ext/bin:${PATH}

* Create subdirectories for the external libraries to embed them into the xuvtools build tree
 
* Finally install xuvtools itself (Depending on the machine you're using this may need some time)
Currently the default configure options should be optimal for most people. xuvtools include a recent blitz++, fftw and netcdf-release. If you do not want to use the included packages but 
rather a package that you have previously installed, you can specify it using --with-<package>=/path/to/installdir.
It is important to note that one should not enable openmp using --with-openmp because it is broken as of now (October 2007)!
 cd ${XUVSRC} && \
 ./bootstrap.sh && \
 mkdir ${XUVDEST} && \
 cd ${XUVDEST} && \
 ${XUVSRC}/configure --prefix=$PWD && \
 make && make install

* That's all... if you want to install a build on a different platform, ssh to a machine of that type, and repeat the configuration and installation steps as above.

That should do. If you experience any problems during installation, don't hesitate to contact us.

To really benefit from the build structure you can add a few lines to your .bashrc (or some other startup script) like
 export XUVSRC=${PWD}/xuvtools
 export XUVDEST=${XUVSRC}/$HOSTTYPE
 export PATH=${PATH}:${XUVDEST}/bin:${XUVDEST}/ext/bin
 export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${XUVDEST}/lib:${XUVDEST}/ext/lib


Mario (thanks to Thorsten for the great installation template).

