= BDP Add-ons =
This page lists some utility functions which could be useful for data processing with [[http://brainsuite.org/processing/diffusion/|BrainSuite Diffusion Pipeline (BDP)]]. BDP is a part of BrainSuite and is geared towards analysis with diffusion MRI data. Most of the utilities listed here are developed using a combination of MATLAB and C (via mex) and should be used with MATLAB, unless otherwise mentioned.

 * [[#affineReg|Rigid and affine registration of 3D volumes - register_files_affine]]
 * [[#mergeDWIs|Merge multiple set of diffusion datasets]]
 * [[#eig2nifti|Eigen file (.eig) to NIfTI converter]]
 * [[#prepfmap|Converting scanner saved fieldmap to units of radians/sec]]

Please note that while we attempt to make sure the scripts distributed here works as intended, this code is largely research code with limited documentation and support. 


<<Anchor(affineReg)>><<BR>><<BR>><<BR>>
== Rigid and affine registration of 3D volumes - register_files_affine ==
{{{register_files_affine}}} can be used for various rigid and affine registration of 3D volumes. It supports several similarity measures and allows flexible options. It is useful for co-registration of inter- and intra-modal medical images. It also supports translation-only transformation with 1, 2 and 3 degrees of freedom. The estimated affine transformation can also be applied to other volumes and surfaces by using the included utility functions. 

'''Download:''' [[http://neuroimage.usc.edu/~chitresh/BDPinternal/BDP_addons/register_files_affine_v12.zip|register_files_affine_v12.zip]] (See included README file for documentation)<<BR>>Last modified: 02-Jun-2015, Author: [[http://www-scf.usc.edu/~cbhushan|Chitresh Bhushan]]



<<Anchor(mergeDWIs)>><<BR>><<BR>><<BR>>
== Merge diffusion datasets ==
{{{mergeDWIs}}} allows to concatenate multiple diffusion MRI datasets together into a single dataset. It takes multiple NIfTI files along with corresponding diffusion parameters as input and writes out a single concatenated diffusion dataset. 

'''Download Link:''' [[http://neuroimage.usc.edu/resources/mergeDWIs.p|mergeDWIs.p]] (Author: [[Members|Chitresh Bhushan]], Last Modified: Jul 25, 2014)

=== Usage ===
Either of following syntax is supported: 
{{{
mergeDWIs(out_file_base, dwi1, bval1, bvec1, dwi2, bval2, bvec2, ...)
mergeDWIs(out_file_base, dwi1, bmat1, dwi2, bmat2, ...)
mergeDWIs(out_file_base, dwi1, bval1, bvec1, bmat1, dwi2, bval2, bvec2, bmat2, ...)
}}}
where, {{{out_file_base}}} is output file base name, {{{dwi1}}} is name of 3D/4D nifti file (with extension .nii/.nii.gz/.img/.hdr), {{{bval1}}} and {{{bvec1}}} are names of b-value file and diffusion gradient direction file respectively. {{{bmat1}}} is name of bMatrix file. {{{dwi2}}}, {{{bval2}}}, {{{bvec2}}} and {{{bmat2}}} are like-wise. More than two diffusion dataset can also be specified in similar fashion. All the input parameters should be character arrays. The order of filenames are important for correct execution. 

Note that {{{bval1}}}, {{{bvec1}}} and/or {{{bmat1}}} should contain same number of entries as number of images in 3D/4D NIfTI file {{{dwi1}}} and so on. Also, {{{mergeDWIs}}} does not try to fix orientation differences, if any, in different dataset and assumes that all input datasets are oriented in the same manner. 

Following is an example run with outputs from MATLAB command prompt:
{{{
>> mergeDWIs('merged_dwi', 'data1.nii.gz', 'data1.bval', 'data1.bvec', 'data2.nii.gz', 'data2.bval', 'data2.bvec')

Input mode: 3
Reading dataset 1 ...
Reading dataset 2 ...
Saving merged nifti file: merged_dwi.nii.gz
Saving merged bval/bvec file: 
merged_dwi.bval
merged_dwi.bvec
}}}


<<Anchor(eig2nifti)>><<BR>><<BR>><<BR>>
== Eigen file (.eig) to NIfTI converter ==
{{{eig2nifti}}} converts {{{.eig.nii.gz}}} files saved by BDP to standard NIfTI-1 format. It takes {{{.eig.nii.gz}}} file as input and writes out corresponding eigenvector and eigenvalue files in standard NIfTI-1 format. 

'''Download Link:''' [[http://neuroimage.usc.edu/resources/eig2nifti.zip|eig2nifti.zip]] (Author: [[Members|Chitresh Bhushan]], Last Modified: Oct 9, 2013)

=== Syntax ===
{{{
eig2nifti(input_eig_file, output_base)
}}}
where, {{{input_eig_file}}} is a character array of input filename ({{{.eig.nii.gz}}}) and {{{output_base}}} is character array of file-prefix for output filenames. Following example shows {{{eig2nifti}}} in action and explains the output files:  
{{{
>> eig2nifti('2467264c.dwi.RAS.correct.eig.nii.gz', '2467264c.tensor')
Reading eig file...Done
Saving files...
Saved V1 file: 2467264c.tensor.V1.nii.gz
Saved V2 file: 2467264c.tensor.V2.nii.gz
Saved V3 file: 2467264c.tensor.V3.nii.gz
Saved L1 file: 2467264c.tensor.L1.nii.gz
Saved L2 file: 2467264c.tensor.L2.nii.gz
Saved L3 file: 2467264c.tensor.L3.nii.gz
}}}
where {{{L1 file}}} contains the largest eigenvalues with corresponding eigenvector saved in {{{V1 file}}}. Similarly, {{{L2 file}}} contains the second largest eigenvalues with corresponding eigenvector saved in {{{V2 file}}} followed by {{{L3 file}}} and {{{V3 file}}}. All eigenvalue files ({{{L1,L2,L3}}}) are 3D volume while eigenvector files ({{{V1,V2,V3}}}) are 4D volume with last dimension containing the eigenvectors.

{{{eig2nifti}}} depends on several other functions which are included along with the download zip. All files should be added to the MATLAB path. See included {{{sample_eig2nifti.m}}} for another example of running {{{eig2nifti}}}.

<<Anchor(prepfmap)>><<BR>><<BR>><<BR>>
== Prepare Fieldmap ==
{{{prepare_fieldmap}}} is a command line tool for converting scanner saved fieldmap to units of radians/sec. As of now it only works with fieldmap saved with Siemens sequence 'gre_field_mapping'. 

'''Download Links:''' [[http://neuroimage.usc.edu/resources/prepare_fieldmap_win64.zip|Windows 64 bit]] (Author: [[Members|Chitresh Bhushan]], Last Modified: August 12, 2013)
 * Requires [[https://www.mathworks.com/products/compiler/mcr/|MATLAB compiler runtime (v2012a)]].

{{{prepare_fieldmap}}} can be run from command line using following syntax:
=== NIfTI input: ===
{{{
prepare_fieldmap.exe --out=<output_filename> [options] --in=<scanner_saved_fieldmap>
}}}
=== Dicom input: ===

{{{
prepare_fieldmap.exe --out=<output_filename> [options] -d <dicom_dir 1>..<dicom_dir N>
}}}
where, {{{<scanner_saved_fieldmap}}} is the input filename of scanner saved fieldmap in NIfTI format (.nii or .nii.gz), {{{<output_filename>}}} is the output filename. {{{[options]}}} is optional input defined below. {{{<dicom_dir 1>}}},..,{{{<dicom_dir N>}}} is the path to dicoms saved by scanner. These dicoms paths should contain only dicom files for fieldmap sequence. In case dicom input is not working as expected, please first convert dicom image to nifti format using some external converter and use nifti input as shown above.

'''Optional Arguments: '''

{{{
--ref-vol=<reference_volume>
}}}
where, {{{<reference_volume>}}} is filename of reference volume NIfTI format (.nii or .nii.gz) which can be used to estimate or define a mask of the head. This mask is used to replace noisy fieldmap estimate outside the head by extrapolating the fieldmap. The reference volume can be the 3D/4D magnitude image used for fieldmap estimation (and as saved by the scanner) OR it can be a manually drawn mask. In the former case, {{{prepare_fieldmap}}} will estimate the head mask from the reference volume based on instensity. The Estimated mask is also saved to disk with file name as {{{<output_filename>.mask.nii.gz}}}. In case the automatic estimated mask is not accurate, please refine the mask manually in BrainSuite and re-run with refined mask as reference volume.

<<BR>><<BR>><<BR>>