BDP Add-ons

This page lists some utility functions which could be useful for data processing with 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.

• Rigid and affine registration of 3D volumes - register_files_affine

• Merge multiple set of diffusion datasets

• Eigen file (.eig) to NIfTI converter

• 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.

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: register_files_affine_v12.zip (See included README file for documentation)
Last modified: 02-Jun-2015, Author: Chitresh Bhushan

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: mergeDWIs.p (Author: 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

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: eig2nifti.zip (Author: 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.

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: Windows 64 bit (Author: Chitresh Bhushan, Last Modified: August 12, 2013)

• Requires 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.