============
Installation
============
Simply unzip the DWIregistration.zip file on a temporal directory. There are two script files to install on mac (install_mac.sh) and on linux (install_linux.sh). Symply run the corresponding scripts on the temporal directory (for instance sh install_linux.sh) making sure that you have privileges to write to your local FSL directory. The installation of this software assumes FSL has already been installed on the $FSLDIR directory.

The files installed are new C++ files that do not overwrite any of the existing C++ files in FSL. However, in order to compile the new code, the corresponding makefiles in FSL are overwritten. If this is not the behavior you want, then do not use the scripts, copy the C++ files in the corresponding directories (the new files are stored in directories with the same name as in the $FSLDIR/src directory) in $FSLDIR/src/newimage, $FSLDIR/src/flirt, $FSLDIR/src/fnirt and compile yourself those files starting with the ones in the $FSLDIR/src/newimage directory.

=============
Examples of use
=============
After Installation, typing ./flirt4D or ./fnirt4D will provide the list of options available. Here I'm going to present some examples of use:

FLIRT4D:

The following examples assume there are 2 DW-MRIs on directories $FSLDIR/data/Subject1 and $FSLDIR/data/Subject2 with their corresponding b-values file (bvals) and gradient table (bvecs), also there is an affine transformation matrix on $FSLDIR/data/FLIRT/. 

The following command apply the affine transform indicated in Subject1_to_Subject2_aff.txt to Subject1 taking Subject 2 as reference applying also angular interpolation. The output will be Subject1_to_Subject2_AI using 4 threads

./flirt4D -init $FSLDIR/data/FLIRT/Subject1_to_Subject2_aff.txt -verbose 3 -in $FSLDIR/data/Subject1/data -ref $FSLDIR/data/Subject2/data -applyxfm -angInt4DImage -out $FSLDIR/data/FLIRT/Subject1_to_Subject2 -refbfiles $FSLDIR/data/Subject2/bvals $FSLDIR/data/Subject2/bvecs -testbfiles $FSLDIR/data/Subject1/bvals $FSLDIR/data/Subject1/bvecs -noProcessors 4

The following command registers Subject 1 to Subject 2 using angular interpolation:

./flirt4D -verbose 3 -omat $FSLDIR/data/Subject1/Subject1_to_Subject2 -in $FSLDIR/data/Subject1/data -ref $FSLDIR/data/Subject2/data -out $FSLDIR/data/FLIRT/Subject1_to_Subject2_FLIRT_AI -angInt4DImage -testbfiles $FSLDIR/data/Subject1/bvals $FSLDIR/data/Subject1/bvecs -refbfiles $FSLDIR/data/Subject2/bvals $FSLDIR/data/Subject2/bvecs -noProcessors 4

Other options are also possible such as register the whole DW-MRI without angular interpolation:

./flirt4D -verbose 3 -omat $FSLDIR/data/Subject1/Subject1_to_Subject2 -in $FSLDIR/data/Subject1/data -ref $FSLDIR/data/Subject2/data -out $FSLDIR/data/FLIRT/Subject1_to_Subject2_FLIRT4D -testbfiles $FSLDIR/data/Subject1/bvals $FSLDIR/data/Subject1/bvecs -refbfiles $FSLDIR/data/Subject2/bvals $FSLDIR/data/Subject2/bvecs -noProcessors 4

or using a single volume (b0 in this case):

./flirt4D -verbose 3 -omat $FSLDIR/data/Subject1/Subject1_to_Subject2 -in $FSLDIR/data/Subject1/data -ref $FSLDIR/data/Subject2/data -out $FSLDIR/data/FLIRT/Subject1_to_Subject2_b0 -useSingleVolume 0 -testbfiles $FSLDIR/data/Subject1/bvals $FSLDIR/data/Subject1/bvecs -refbfiles $FSLDIR/data/Subject2/bvals $FSLDIR/data/Subject2/bvecs -rotbVectors $FSLDIR/data/Subject1/bvecs_rot_to_Subject2_b0 -noProcessors 4

This last command uses the b0 volume registration and applies it to every volume in the DW-MRI and also provides the rotated bvecs to be used in dtifit to compute second order tensors for instance (AI does not need rotated b-vecs).

FNIRT4D:

The following command applies the deformation field "Subject1_to_Subject2_field" to the linearly registered image Subject1_to_Subject2_FLIRT_AI (obtained before) using angular interpolation, all 129 volumes in the image (you can choose less) and 8 threads:

./fnirt4D --ref=$FSLDIR/data/Subject1/Subject1_to_Subject2_FLIRT_AI --in=$FSLDIR/data/FLIRT/Subject1_to_Subject2_AI --applyXform --inwarp=$FSLDIR/data/FNIRT/Subject1_to_Subject2_field --numVols=129 --angInterp --bvals=$FSLDIR/data/Subject1/bvals --bvecs=$FSLDIR/data/Subject1/bvecs --iout=$FSLDIR/data/FNIRT/Subject1_to_Subject2_FNIRT --numProc=16 

The following command applies nonlinear registration with angular interpolation, assuming there is a fictitious configuration file called Subject_x_to_Subjecty.cnf (provided as an example in a separated file):

./fnirt4D --config=$FSLDIR/data/FNIRT/configFiles/Subject_x_to_Subjecty_AI.cnf --in=$FSLDIR/data/Subject1/data --inmask=$FSLDIR/data/Subject2/nodif_brain_mask --iout=$FSLDIR/data/Subject1/Subject1_to_Subject2_FNIRT_AI --fout=$FSLDIR/data/Subject1/Subject1_to_Subject2_field_AI

The different options can be seen in the configuration file.