epidewarp.fsl - fieldmap-based EpiUnwarping tool


epidewarp.fsl --mag <magvolid> --dph <phasediffvolid> --exf <examplevolid> --epi <epivolid> --tediff <tediff> --esp <esp> --sigma <sigmamm> [<options>]


Positional Arguments


Required Flagged Arguments

--mag <magvolid>

B0 magnitude volume

Magnitude volume from the B0 fieldmap. If more than one frame is present, then only the first is used.

--dph <phasediffvolid>

B0 phase difference volume

Phase difference volume (Echo2-Echo1). These are assumed to be scaled between 0 to 4095 for -pi to pi. Eg, dph.img

--exf <examplevolid>

example func volume (or use epi)

Single volume to use as the example func. If not supplied, then the middle time point from the EPIs will be used. This volume must have enough anatomy to be able to register with the mag. It should also have the exact same geometry as any EPIs. This option allows the user to specify a functional for the example and then a statistical map as the EPI.

--epi <epivolid>

EPI volume to unwarp

EPI volume to dewarp. This could be a time series or a single frame statistical map. If it is a stat map, then supply an example func (--exf) to assure that there is some anatomy for registration to the mag volume.

--tediff <tediff>

difference in B0 field map TEs

Difference in the echo times of the B0 field map in ms. This number is set when acquiring the field map. This is often set to 2.46 ms at 3T, which is the amount of time it takes for the fat and water to rephase. The rephase time scales with field strength.

--esp <echospacing>

EPI echo spacing

Time (ms) between the start of the readout of two successive lines in k-space during the EPI acquisition. This can also be thought of as the time between rows. This parameter is not available in the Siemens DICOM header. However, it can be obtained from the console. Open the protocol for the functional scan (NOT the field map). Go to the Sequence tab. Go to Part 1. The Echo Spacing is displayed on the bottom right. It will also be on the protocol print out (select the functional protocol in the Exam Explorer, right click, and select Print...). If one saves the raw kspace data, then the echo spacing can be found next to the m_lEchoSpacing tag in the meas.asc and is in usec. Note that the echo spacing is not the same as the time to read out a line of k-space and it cannot be computed from the bandwidth because neither of these methods takes into account the dead time between lines when no data are being read out.

--sigma <sigmamm>

2D spatial gaussing smoothing stddev (def 2mm)

2D Smoothing VSM with gaussian with stddev of sigmamm (in mm). Default is 2 mm. This tends to have minimal impact but can clean things up around the edge of the brain.

Optional Flagged Arguments

--vsm <vsmvolid>

voxel shift map (required)

Voxel shift map. This is a volume the same size as the EPI. The value at each voxel indicates the amount the voxel has shifted in the phase encode direction due to B0 distortion. This argument is required.

--exfdw <exfdwvolid>

dewarped example func volume

This is exf volume or the middle time point from the EPI time series (the "example functional") with B0 distortion removed. Mainly good for checking how good the dewarping is without having to dewarp the entire time series.

--epidw <epidwvolid>

dewarped epi volume

This is the EPI time series with B0 distortion removed.

--tmpdir <tmpdir>

save intermediate results here

Location to put the directory for storing temporary files. By default, this will be in a directory called tmp-epidewarp.fsl under the directory to hold the VSM volume. When --tmpdir is used or --nocleanup is specified, then this directory will not be deleted. Otherwise or with --cleanup it will automatically be deleted.


do not delete tmpdir

Do not delete the tmp dir. --tmpdir automatically implies --nocleanup.


force deletion of tmpdir

Forces deleting of the tmp dir regardless of whether --tmpdir or --nocleanup have been specified.


Prints copious amounts to the screen.






Front end for FSLs Prelude and Fugue programs to correct for B0 distortion in functional EPI scans. The programs use a B0 fieldmap. This is assumed to be two conventional GREs collected at two different echo times (TEs). The field map should be acquired with the same slice prescription, slice thickness, slice skip, voxel resolution, and field-of-view as the EPI. This script uses only FSL commands (ie, FreeSurfer not needed).

For the stock Siemens field map, two field maps are required, one to get the phase and another to get the magnitude (this will change with new version so the Siemens scanner software). The volume that is stored as the phase is actually the phase difference and is scaled between 0 to 4095 for -pi to pi. The magnitude volumes for both TEs are saved, but only one is needed.

All volumes are assumed to be in analyze 4D format. All volumes should be referred to as volid.img. If the EPI or EXF volume has a .mat file, this will be propagated to the outputs.

Suggested Field Map Parameters

These field map parameters are begin used by the Birn:

TR = 500ms (1000ms with phased-array)
TE1: Minimum possible
TE2 = TE1 + DeltaTE

DeltaTE = 4.92ms for 1.5T
Flip Angle: 65 for 1.5T
DeltaTE = 2.46ms for 3T 
Flip Angle: 55 for 3T 
DeltaTE = 1.845ms for 4T
Flip Angle: 55 for 4T 

FatSat: Off
Bandwidth: Maximum
Slice Prescription, FOV, Thickness, Skip, Pixel Resolution, Matrix Size: same as functional


The output will not necessarily be registered with the mag volume. To compare the mag with the dewarped output, first register the mag to the dewarped output.


Example 1


Example 2




See Also



FSL, Fugue, Prelude,

Methods Description


1.  Create a brain mask from the mag volume (BET)
2.  Create a head mask by dilating the brain mask 3 times
3.  Rescale the phase image to -pi to pi
4.  Unwrap the phase (PRELUDE)
5.  Create and smooth the voxel shift map (VSM) (FUGUE)
6.  Remove in-brain mean from VSM
7.  Forward warp the mag volume (FUGUE)
8.  Register the forward warped mag with the example func (FLIRT)
9.  Resample the VSM into EPI space (FLIRT)
10. Dewarp the EPI and/or Example Func (FUGUE).



Reporting Bugs

Report bugs to <>



epidewarp.fsl (last edited 2008-04-29 11:45:46 by localhost)