User Guide¶

Table of Contents

4D image format and conversion
DWI data input format
Configuration file format for DWI data simulation
Visualization of spherical function field
- Generate and visualize vtk files
- Visualization using Paraview

4D image format and conversion ¶

nifti format ¶

Diffusion weighted image (DWI) data is a 4D image data with 3D spatial dimensions and 1D diffusion dimension determined by the $\mathbf{q}$ value. In medical image data processing, we normally use nifti format to store the 4D image. .. See nifti header

Multi-Volume image ¶

The common way to store 4D image using nifti format is to sore different 3D volumes separately in memory. We call it as multi-volume image. FSL uses this way. When we use ITK to read this image format, we need to use itk::Image<double,4>

In nifti format, a multi-volume image with size (64,64,20,120) is stored as dim[8] = 4 64 64 20 120 1 1 1, where a scalar value is stored in each 4D voxel. See dim description.

VectorImage ¶

In DMRITool, we mainly use VectorImage format e.g. ITK::VectorImage<double,3> for data processing. In this format, the values for the same voxel is stored continuously in memory. We can still nifti format to store it. We use this format because it is more efficient for processing 4D image data. See this example.

In nifti format, a vectorimage with size (64,64,20,120) is stored as dim[8] = 5 64 64 20 1 120 1 1, where a 120 dimensional vector is stored in each 3D voxel. See dim description.

Conversion between multi-volume image and VectorImage ¶

We provide two executables for conversions between these two image storages.

VectorTo4DImageConverter is to convert a vectorimage to a multi-volume image.

VectorTo4DImageConverter  vectorimage.nii.gz  4dmultivolumeimage.nii.gz

4DToVectorImageConverter is to convert a multi-volume image to a vectorimage.
```
4DToVectorImageConverter  4dmultivolumeimage.nii.gz vectorimage.nii.gz
```

You can also use ImageInfo to check the image header information

ImageInfo vectorimage.nii.gz
ImageInfo 4dmultivolumeimage.nii.gz

If you installed niftilib, you can try:

nifti_tool -disp_hdr -infiles vectorimage.nii.gz
nifti_tool -disp_hdr -infiles 4dmultivolumeimage.nii.gz

DWI data input format ¶

DWI data is a 4D image data where the fourth dimension is determined by a gradient file and a set of b values. It is possible to put gradient file and b values into the image header, as is done in NRRD format. Then the 3 files (e.g. image data file, gradient file, b values) becomes a single file.

In DMRITool, we choose to store the 3 files (e.g. image data file, gradient file, b values) separately, and the routines use a single text file which includes these 3 file names as input. The data reconstruction routines all rely on this input format.

In this format, a 3 shell DWI data with b values of (1000,2000,3000) is stored with a single txt file (e.g. data.txt). This txt file can have two different types.

Type 1:

******in data.txt***********
1000  grad1.txt  dwi1.nii.gz
2000  grad2.txt  dwi2.nii.gz
3000  grad3.txt  dwi3.nii.gz
****************************

Each line is for a single shell data. The gradient file grad1.txt stores a Nx3 matrix. If the dimension N in grad1.txt is smaller than the dimension M in dwi1.nii.gz (dimension XxYxZxM), the first M-N dimension in dwi.nii.gz is for b0 images.

Note

DWI data files (e.g. dwi1.nii.gz) can be a multi-volume image format or vectorimage format. Both formats are OK.

If you just want to use some DWI volumes among these M DWI volumes, you can optionally add a index file in each line to specifically the index of volumes you want to use

******in data.txt**********************
1000  grad1.txt  dwi1.nii.gz index1.txt
2000  grad2.txt  dwi2.nii.gz index2.txt
3000  grad3.txt  dwi3.nii.gz index3.txt
***************************************

The index file shows the index requested for reading. It starts from 0.

Type 2: you can also specifically set all b values for all DWI volumes.

******in data.txt*********************
b1.txt  grad1.txt  dwi1.nii index1.txt
b2.txt  grad2.txt  dwi2.nii index2.txt
b3.txt  grad3.txt  dwi3.nii index3.txt
**************************************

b1.txt and grad1.txt should have the same dimension. The index files are optional. You can also catenate all b value files (gradients, DWI data files) into one b value file (gradients, DWI data files).

******in data.txt******************************
ball.txt  gradall.txt  dwiall.nii indexall.txt
***********************************************

Configuration file format for DWI data simulation ¶

We provides DWISimulator routine to generate DWI data from a customizable configuration file. See example codes in Example/test.sh and example configuration files in Example folder.

The configuration file specially sets the mixture of tensor model or mixture of configuration model for each voxel. The following table explains the parameters in the configuration file

DimSize	output DWI image spatial size.
ElementSpacing	spatial spacing.
Scale	DWI image for `b=0`.
ModelType	Symmetric tensor model, or cylinder model, spherical coordinate or Cartesian coordinate.
DiffusionParameters	First three numbers are for spatial position. The following numbers are respectively for each tensor/cylinder components. For example, when `ModelType=SYMMETRICAL_TENSOR_IN_SPHERICAL_COORDS`, `DiffusionParameters = 3 3 0 90 0 0.0015 0.0003 0.5 90 60 0.0015 0.0003 0.5` means in voxel `(3,3,0)`, two tensors with eigenvalues `(0.0015,0.0003)`, partial volume weight `0.5`, spherical coordinates (90,0) and (90,60) respectively. Thus crossing angle is `60` degree.
BackgroundDiffusionParameters	diffusion parameters for all other voxels which are not specially set in `DiffusionParameters`.
RicianNoiseSigma	Sigma for Rician noise. Suggest to set it as 0, then use DWINoiseGenerator to add noise to the noise-free DWI data.

Visualization of spherical function field ¶

Generate and visualize vtk files ¶

Both ODFs and EAP profile are spherical function fields, where in each voxel there is a spherical function (e.g. ODF, EAP profile with a fixed radius). The spherical function field can be represented using uniform samples of spherical functions or the Spherical Harmonics (SH) coefficients of spherical functions.

We provides some routines to generate mesh files (.vtk format) from the SH coefficients or spherical function samples. Then these vtk files can be visualized in paraview or using the routine vtkviewer and VTKPolyData.py. Please see the command list for visualization. To use VTKPolyData.py, you only need to build VTK with python wrapping. It does not need to build dmritool.

Visualization using Paraview ¶

When using paraview, it is possible to visualize these generated vtk files with a scalar map, e.g. the GFA map, as the background. Paraview originally can visualize vtk files. For the GFA map which is in nifti format, paraview can also visualize it when the AnalyzeNiftiIO plugin is enabled. You can enable it by clicking Tools -> Manage Plugins -> AnalyzeNiftiIO.

Note that it supports .nii file, but not .nii.gz file, and you may need to set the origin manually in paraview such that the gfa map can be visualized in the same coordinate as the EAP profile in vtk format.

In the properties panel, when you click toggle advanced properties, it shows Translation and Scale.
By setting translation, you can translate the image map to different position.
By setting scale, you scale the axis. If you set (-1,1,1) for scale, it reverses the x-axis.

You can also enable other useful plugins for paraview, e.g. quadview.