By members and collaborators of the Functional Imaging Laboratory



FieldMap: Description

The FieldMap toolbox addresses the problem of geometric distortions in EPI caused by magnetic field inhomogeneity. The toolbox is designed for creating unwrapped field maps which can then be used for unwarping distorted EPI. The general methods used in the toolbox are based on the field mapping distortion correction approach outlined in Jezzard and Balaban, 1995. It has been shown that using this method for distortion correction results in an improved coregistration between EPI and anatomical images (Hutton et al, 2002). The FieldMap toolbox is designed to be interactive so that the user can see the effect of applying different field maps and unwarping parameters to EPI images. However, it is also possible to script the toolbox routines.

The latest version of Unwarp (described below) allows for a field map to be included in the SPM2 "Realign & Unwarp" option. The FieldMap toolbox can be used to create a field map required by Unwarp.

FieldMap: Latest News

Version 2.0 of FieldMap is now available for SPM5 and can be downloaded with the latest version of SPM5. To ensure full compatibility between the FieldMap toolbox and Realign & Unwarp in SPM5, please also update spm_get_image_def.m and spm_config_realign_and_unwarp.m in the main SPM5 distribution. The main changes are listed below:

a) The convention used to describe the direction of the k-space traversal is now based on the coordinate system used by SPM. In this coordinate system, the phase encode direction corresponds with the y-direction and is defined as positive from the posterior to the anterior of the head. The x-direction is defined as positive from left to right and the z-direction is defined as positive from foot to head. The polarity of the phase-encode blips describes in which direction k-space is traversed along the y-axis with respect to the coordinate system described here. The change in convention means that if previously the polarity of phase-encode blips in the FieldMap gui was usually set to be negative, it should now be positive and vice versa. This also applies to the default value for pm_def.K_SPACE_TRAVERSAL_BLIP_DIR in the pm_defaults.m file which should be set to -1 if it was +1 previously and vice versa.

b) In the previous version of FieldMap, there was a bug in the application of the Jacobian modulation when using an EPI-based field map. This has now been fixed.

c) The toolbox now allows the user to select a specified defaults file. This means it is possible to have more than one default file containing different sets of parameters relating to different field map and /or EPI sequences. This is particularly useful for sites where more than one sequence is routinely used.

d) The toolbox can be run using the new SPM5 User Interface. This will allow FieldMap jobs to be saved serving as a log about how the data was processed. It will also facilitate scripting and batching jobs.

e) The toolbox now reads and writes files in nifti format (as does SPM5). The toolbox now save a vdm5_* file which will also be expected by Realign & unwarp. If doing Unwarp with multiple sessions, but a single vdm5_* file, it will be necessary to select this file for each session.

f) All versions of FieldMap and Unwarp are only designed to work with images collected with the phase-encode direction in y.

Unwarp: Description

The Unwarp toolbox is designed for the estimation and removal of movement-by-susceptibility induced variance in fMRI time series. This refers to the problem with EPI images that an image collected for one subject position will not be identical to that collected at another. This is because the form of the geometric distortions in EPI is dependent on the position of the head in the magnetic field. Unwarp is predicated on the assumption that this susceptibility-by-movement interaction is responsible for a sizable part of residual movement related variance. The methods behind the Unwarp toolbox are described in detail in Andersson et al, 2001.

The latest version of Unwarp allows a field map to be included in the "Realign and Unwarp" process. The required field map can be created from measured field map data using the FieldMap toolbox. This should allow an EPI time series to be corrected for both susceptibility-by-movement effects and the "static" component of the geometric distortion. A more detailed description of this toolbox and its download area can be found at: Unwarp Toolbox

Reading and References

Jezzard P and Balaban RS (1995) Correction for geometric distortions in echoplanar images from B0 field variations. Magn Reson Med 34:65-73

Andersson JLR, Hutton C, Ashburner J, Turner R, Friston K (2001) Modelling geometric deformations in EPI time series. NeuroImage 13:903-919

Hutton C, Bork A, Josephs O, Deichmann R, Ashburner J, Turner R. (2002). Image distortion correction in fMRI: A quantitative evaluation. NeuroImage 16:217-240

Jenkinson M. 2003. Fast, automated, N-dimensional phase-unwrapping algorithm. MRM 49:193-197


The software was developed while JLRA was supported in part by Vetenskapsr�det (VR) grant no. 621-2001-2844. CH is supported by The Wellcome Trust.


This software has been tested by the authors on data collected on two different makes of MR scanners. Undoubtedly there are numerous bugs that will surface when more people start using it. We are grateful for bug reports, and other input, and the more we receive the faster bugs will be weeded out.

FieldMap Toolbox Downloads

FieldMap Toolbox for SPM5 can be downloaded with the latest version of SPM5

Fieldmap Toolbox

FieldMap Example Data Set

Unwarp Toolbox

Installation instructions

Instructions for installing the FieldMap Toolbox:

  1. Copy the file FieldMap_ddmmyy.tar.gz to your 'whatever'/spm2/toolbox directory. (ddmmyy is date of release)
  2. Go to the toolbox directory:
    cd 'whatever'/spm2/toolbox
  3. Type 'gunzip FieldMap_ddmmyy.tar.gz' at the command prompt.
  4. Type 'tar -xvf FieldMap_ddmmyy.tar'
  5. If you are running on a Sun, or on Intel Linux, the binary executable files that come with the distribution may work (ie the *.mexglx or the *.mexsol).
  6. If you're running on another platform or the distributed binaries don't work, it will be necessary to compile the *.c files.
  7. It should be possible to do this simply by typing at the matlab prompt:
    cd FieldMap
    which should create the required executable files.
  8. If the make file doesn't work as it stands it may need editing. Some suggestions can be found in make.m.
  9. When you start SPM the next time there should be a "FieldMap" button in the "Toolbox" menu.
  10. For online help type 'FieldMap.man' in the text field of the SPM help window.

Instructions for downloading the FieldMap Eaxmple Data Set:

  1. Copy FieldMapExampleData.tar.gz to directory of your choice.
  2. Go to that directory.
  3. Type 'gunzip FieldMapExampleData.tar.gz'
  4. Type 'tar -xvf FieldMapExampleData.tar'

Jesper Andersson (jesper.andersson at ks.se)
Chloe Hutton (chutton at fil.ion.ucl.ac.uk)
John Ashburner (john at fil.ion.ucl.ac.uk)
Robert Turner (r.turner at fil.ion.ucl.ac.uk)
Karl Friston (karl at fil.ion.ucl.ac.uk)