>
= GUI and command line software =
Two interfaces exist for applying FUGUE to unwarp images: (i) a GUI, that is part of the FEAT preprocessing options, and (ii) a command-line script, `epi_reg`. We strongly recommend that new users make use of the pre-stats part of FEAT to do all such processing (note that it is not necessary to have fMRI data for this - even single volumes can be processed in FEAT by selecting pre-stats only). A GUI also exists for getting fieldmaps into the right form for FEAT. See the detailed documentation on FEAT and documentation below on using making fieldmaps for FEAT.
More experienced users, or those wanting to use fieldmap-based distortion-correction in other situations, can use the `epi_reg` command. The documentation for this command can be found as part of [[FLIRT]].
----
<
>
= Making Fieldmap Images for FEAT =
This section outlines some of the most common ways to construct the required fieldmap images for B0 unwarping in FEAT. Also see the documentation on [[FEAT]] for more information on fieldmapping and its use in FEAT pre-stats processing.
Each scanner/site/sequence can give you different data. As the phase is of great importance in fieldmapping, but is normally not saved in other sequences, these images are often quite different from the standard images.
== SIEMENS and GEHC data ==
If you have data from a SIEMENS or GEHC scanner then we strongly recommend that the tool `fsl_prepare_fieldmap` is used to generate the required input data for FEAT or `fugue`. Fieldmap data from a SIEMENS scanner takes the form of one phase difference image and two magnitude images (one for each echo time). Fieldmap data from a GEHC scanner similarly takes the form of a fieldmap in Hertz and the corresponding magnitude (more information on how to collect [[https://github.com/mr-jaemin/ge-mri/tree/main/B0fieldmap|fieldmap data from a GEHC scanner|target="_blank"]]). In the following, where a magnitude image is required, pick the "best looking" one. This image is used for registration and masking but the process is not particularly sensitive to the quality and typically either image will work fine.
There are both GUI and command-line versions of the `fsl_prepare_fieldmap` tool. It is recommended that new users use the GUI.
The `Fsl_prepare_fieldmap` GUI requires the following inputs:
* Phase image ( currently SIEMENS-style only )
* Magnitude image (brain extracted - see note below)
* Difference of Echo Times - this is a sequence parameter that should be in the protocol parameter PDF/printout (TE1 and TE2), if not your radiographer/ operator/technician can look this up
Brain extraction of the magnitude image is very important and must be ''tight'' - that is, it must exclude all non-brain voxels and any voxels with only a small partial volume contribution. The reason for this is that these areas are normally very noisy in the phase image (look at them in FSLView - if they are not noisy then this is not so important). It is crucial that the mask (derived from this brain extracted image) contains few of these noisy voxels. This is most easily done by making the brain extraction very tight, erring on excluding brain voxels. The exclusion of brain voxels in this instance is actually fine and will have no repercussions, since the fieldmap is extrapolated beyond this mask, and that is the only purpose that the mask plays. Therefore make sure your mask is (if it can't be perfect) too small. As noted above, either magnitude image (from the different echos) can normally be used here - it is not that important.
The output of the `Fsl_prepare_fieldmap` GUI is a correctly calibrated fieldmap in units of rad/s (as the B0 field can be measured in Tesla, Hz or rad/s in MRI as they are all proportional).
The usage of the `fsl_prepare_fieldmap` command-line tool is very similar to the GUI (and all the above considerations apply):
{{{
Usage: fsl_prepare_fieldmap [--nocheck]
Prepares a fieldmap suitable for FEAT from SIEMENS or GEHC data - saves output in rad/s format
must be SIEMENS or GEHC_FIELDMAPHZ
should be the phase difference for SIEMENS and the fieldmap in HERTZ for GEHC_FIELDMAPHZ
should be Brain Extracted (with BET or otherwise)
is the echo time difference of the fieldmap sequence - find this out form the operator
(defaults are *usually* 2.46ms on SIEMENS)
(defaults are *usually* 2.304ms for GEHC 2D-B0MAP at 3.0T and 2.272 ms GEHC 3D B0MAP at 3.0T)
--nocheck supresses automatic sanity checking of image size/range/dimensions
e.g. fsl_prepare_fieldmap SIEMENS images_3_gre_field_mapping images_4_gre_field_mapping fmap_rads 2.65
e.g. fsl_prepare_fieldmap GEHC_FIELDMAPHZ 3dB0map_fieldmaphz mag_3dB0map fmap_rads 2.272
}}}
----
----
== Other data ==
Currently `fsl_prepare_fieldmap` does not work with data from other scanner manufacturers.
For users with Philips data we highly recommend looking at the following document from Anna van 't Veer, Anne Hafkemeijer, Henk van Steenbergen and Janna Marie Bas-Hoogendam (Leiden University / Leiden Institute for Brain and Cognition): https://osf.io/hks7x/ This goes through the whole process of preparing and using a fieldmap from a Philips scanner, which is hopefully standardized across scanners and sites, although at the time of writing we do not know how generally true this is.
For other scanners we welcome collaboration from people using such scanners in order to enhance this tool.
In the meantime, when dealing with data from other scanner manufacturers, or with non-standard sequences, the first step in practice is to find out what kind of fieldmap acquisition data you can get from the scanner, operator or reconstruction software. There are three main types:
1. Complex data containing images at two different echo times
1. Separate phase images for the two different echo times
1. A single, real fieldmap image (showing the field inhomogeneity in each voxel)
If the images from the scanner are in ANALYZE or NIFTI form then you can determine their type, use `fslinfo`. If not, you must convert to either ANALYZE or NIFTI format before progressing. See the FSL FAQ for information about conversion.
When `fslinfo` is run it will display a datatype string or number (the value 32 represents a complex image). You can convert a complex image into its phase and magnitude components by using `fslcomplex` or, alternatively, leave it in this format. The number of images contained in each file is shown as the `dim4` value.
To further check what sort of images you have, use `slices` to display the image and then see which of the following images it most closely resembles. Note that for complex images, slices will display two separate images - one phase and one magnitude. If you only have a single image (dim4=1) then it is possible that it has already been reconstructed fully into a fieldmap.
Typical complex images
||