Differences between revisions 1 and 2
Deletions are marked like this. Additions are marked like this.
Line 6: Line 6:
* Overview of distortion correction code
* Limitations of the code
* Contents in distribution
* Setting up local environment variables for use
* Use instructions
* Support and contacts
* Acknowledgements
Overview of distortion correction code
Limitations of the code
Contents in distribution
Setting up local environment variables for use
Use instructions
Support and contacts

Gradient Unwarping Software Package

Author: Silvester Czanner (see also: SilvesterNotes)

Overview of distortion correction code Limitations of the code Contents in distribution Setting up local environment variables for use Use instructions Support and contacts Acknowledgements

==== Overview of distortion correction code ===================

Goal: To correct for image distortions in MRI data due to non-linearity

  • of the magnetic fields from the imaging gradient coils.

Method: Described in:

  • Jovicich J, Czanner S, Greve D, Haley E, Kouwe A, Gollub R, Kennedy D,
    • Schmitt F, Brown G, MacFall J, Fischl B, Dale A.

    Reliability in Multi-Site Structural MRI Studies: Effects of Gradient
    • Non-linearity Correction on Phantom and Human Data. NeuroImage

    NeuroImage (Apr 1;30(2):436-43, 2006)

Outline of steps involved:

  • 1) Obtain from your local Siemens or GE vendor the spherical harmonics
    • expansion that represents the gradient coils used in the MRI system you want to correct. This is a text file with proprietory information.
    2) We provide a script (gradient_unwarp_converter.pl ) that reads the spherical
    • harmonics text file and writes out the coefficients in a standard format (for example, avanto.coef).
    3) We provide a script (create_displacement_table) that reads in the standard
    • formatted coefficients (e.g., avanto.coef) of your system and writes out a file that has the tables for displacements along the x,y,z axes and also the intensity correction table due to voxel size distortion (e.g., avanto.gwv).
    4) We provide a script (grad_unwarp) that reads in the correction tables of your
    • system and the dicom image volume you want to correct and writes out the distortion corrected dicom volume. For more details on other image formats see 'Use instructions'.

==== Limitations of the code =============================

- This distortion correction code has been tested on 3D structural images

  • acquired on Siemens (Avanto, Sonata and Allegra gradients) and GE (CRM and BRM gradients) systems

- This code consists of linux bash scripts that call matlab functions - This code has been developed for linux platforms and tested on RED HAT, Fedora Core 2 - This code needs a Matlab license and an Image Toolbox license. - This code has been tested on Matlab's version 7.0 (r14) - We are working on creating a c-version of the code

==== Contents of distribution =============================

The whole distribution package contains 5 subdirectories:

  • matlab // all matlab files scripts // grad_unwarp, create_displacement_table scripts grad_unwarp_tables // *.gvw files, table.mat, files contains the 1st harmonic coefficients

    sample_phantom_data // sample GE & Siemens phantom data, raw and distortion corrected bin // mri_convert - conversion utility for different data formats (DICOM, MGH, Analyze, COR, ...)

===== Setting up local environment variables ==============

You need to set up the following two variables:

Setup the environment variable GRAD_UNWARP_DIR to the grad_unwarp_bash directory. For example:

  • setenv GRAD_UNWARP_DIR /my_home_directory_path/grad_unwarp_bash

Setup the variable MATLAB to the path of your matlab executable file For example:

  • setenv MATLAB /space/lyon/6/pubsw/common/matlab/7.0/bin/matlab

With these environments you can define aliases to run the scripts:

  • alias grad_unwarp $GRAD_UNWARP_DIR/scripts/grad_unwarp alias create_displacement_table $GRAD_UNWARP_DIR/scripts/create_displacement_table

And then just run the scripts by typing:

  • grad_unwarp (or grad_unwarp -help) create_displacement_table (or create_displacement_table -help)

============= How to use it =====================

Script gradient_unwarp_converter.pl is used to convert Siemens .grad or GE .dat to .coef, which is needed to create the displacement table.

Usage: perl gradient_unwarp_converter.pl <filename> Examples: perl gradient_unwarp_converter.pl bay1-gw_coils.dat

  • perl gradient_unwarp_converter.pl coeff_AS05.grad

Script create_displacement_table is used to create a displacement table (*.gwv). It has 2 parameters: vendor and table name. Supported vendor names are siemens and ge. Allowed table names are avanto, sonata, brm, crm. Meaningful combinations are siemens (avanto or sonata), ge (brm or crm)

Usage: create_displacement_table vendor table_name Example: create_displacement_table siemens sonata

  • create_displacement_table ge crm

Script is reading file with the 1st harmonic coefficients (*.coef) from $GRAD_UNWARP_DIR/grad_unwarp_tables and calculates the displacement table. The table is saved into $GRAD_UNWARP_DIR/grad_unwarp_tables directory.

Script grad_unwarp is used to unwarp the warped raw images produced by scanner devices. It uses several options. If you are not sure about the options, just type

alias grad_unwarp $GRAD_UNWARP_DIR/scripts/grad_unwarp grad_unwarp


grad_unwarp -help

Grad_unwarp script has been tested with avanto, sonata, brm and crm MGH phantom files and with brm dicom files (series #6). You can find the testing data files in

$GRAD_UNWARP_DIR/sample_phantom_data $GRAD_UNWARP_DIR/sample_phantom_data/dicom_BRM_ucsd

==================== H E L P =========================

grad_unwarp is an unwarping tool. It provides a full 3D unwarping for data from Siemens devices. For data from GE devices there is an assumption that these data are already in-plane dewarped.

There are four gradient-coil types supported at the moment: GE BRM, GE CRM, Siemens Sonata/Trio, Siemens Avanto, Siemens Allegra. For each of these, there is a large file somewhere that is an offsets table - for outvol voxel here, look there in invol. Interpolation in the offsets table is trilinear; interpolation in the input volume may be specified by the user with -interp foo. Default is cubic.

There are three ways to use the grad_unwarp flag -unwarp <type>.

  • (1) If you are using dicom files from a machine we have have specification information on, no type need be supplied: grad_unwarp works it out from

    the dicom headers. For Siemens, it is sufficient to find ManufacturersModelName 'sonata' or 'avanto' in the headers. For GE, unfortunately, there is no such notation about gradient system in the dicom headers, so we resort to ScannerSerialNumber. This is often not set, so we check the (InstitutionName, StationName) pair. For dewarping an mgh volume, the user must always specify an unwarp

    <type>. (2) FYI, one may also supply a full pathname to some offsets file of choice. (3) The specifically-supported choices are 'sonata' 'avanto' 'brm' and 'crm' (case insensitive). The 1.5T GE scanner at UCSD has the BRM gradient coil. The 1.5T GE scanners at BWH, Duke and MGH-Bay1 have CRM. MGH-Bay2 is a Avanto.

A jacobian brightness correction is applied by default - areas of the image that spread out (increase in volume) should dim (decrease in intensity). If for some reason you wish to skip that step, use the -nojac option.

======= E X A M P L E S =================================================

grad_unwarp -i avanto.mgh -o avanto_uw.mgh -unwarp avanto

it will read data stored in avanto.mgh and produce a new dewarped data file avanto_uw.mgh The dewarping will be done based on displacement table stored in file avanto.gvw

grad_unwarp -i dicom_BRM_ucsd/001.dcm -s 6 -o brm_ucsd_uw.mgh -unwarp brm

it will read the data from DICOM file, serie #6 from directory dicom_BRM_ucsd/, dewarp it and create new data file brm_ucsd_uw.mgh in MGH format

============== FORMAT CONVERSION UTILITY ================================

mri_convert is a utility used for a conversion between different volume formats.

Usage: mri_convert [options] <in volume> <out volume>

To see all options type:

alias mri_convert $GRAD_UNWARP_DIR/bin/Linux/mri_convert mri_convert

The input and output file type can be specified in two ways. First, mri_convert will try to figure it out on its own from the format of the file name (eg, files that end in .img are assumed to be in spm analyze format). Second, the user can explicity set the type of file using --in_type and/or --out_type.

Legal values for --in_type (-it) and --out_type (-ot) are:

  • cor - MGH-NMR COR format minc - MNI's Medical Imaging NetCDF format (output may not work) analyze - 3D analyze (same as spm) analyze4d - 4D analyze spm - SPM Analyze format (same as analyze and analyze3d) ge - GE Genesis format (input only) gelx - GE LX (input only) lx - same as gelx ximg - GE XIMG variant (input only) siemens - Siemens IMA (input only) dicom - generic DICOM Format (input only) siemens_dicom - Siemens DICOM Format (input only) afni - AFNI format brik - same as afni bshort - MGH-NMR bshort format bfloat - MGH-NMR bfloat format sdt - Varian (?) outline - MGH-NMR Outline format otl - same as outline gdf - GDF volume (requires image stem for output; use -gis) nifti1 - NIfTI-1 volume (separate image and header files) nii - NIfTI-1 volume (single file)


  • mri_convert -i avanto.mgh -o avanto.img mri_convert -i avanto.mgh -ot COR -o avanto_COR/ mri_convert -i dicom_BRM_ucsd/001.dcm -it dicom -o brm_ucsd.mgh

============== MGH data file Viewer ================================

There is a simple MGH/MGZ/DICOM data file viewer written in matlab. To use it, you have to run matlab, add new path $GRAD_UNWARP_DIR/matlab and type mgh_viewer in matlab's command window. It will create and open an User interface.

To load a MGH/MGZ/DICOM file press button LOAD VOLUME To change a view press one of the buttons SAGITAL, CORONAL and AXIAL To move through the volume by slices use slider Slice #. To change the brightmess and contrast use sliders Window and Level. To quit the Program press button Quit

==== Support and contacts ===============================================

Support is very limited but we will do our best to try to answer your questions. Please email your constructive comments to:

GradUnwarp (last edited 2015-01-22 12:59:17 by NickSchmansky)