FSLUTILSMiscellaneous FSL Image Utilities | ![]() |
FSLUTILS is a set of useful command-line utilities which allow the conversion, processing etc. of Analyze and Nifti format data sets. Many of them work on both 3D and 4D data. For each of these programs, type just the program name to get the usage help.
The different FSLUTILS programs are:
Orientation, labelling and getting left and right correct are
important but often confusing issues. You should always look at your
data and check if the labels in FSLView are correct. No further
analysis should ever be done if the labels in FSLView are incorrect or
missing. If your labels are fine then you probably will not
need to use any other these tools, although
fslreorient2std
may be useful. If not, then you will need
to read on. We have tried to simplify the usage of the tools for
common tasks involving orientation issues, although still providing
flexible and powerful tools for the expert user.
Common problems
We describe here the most common problems and how to solve
them. If you have a different problem then you will need to work
with the advanced tools described later (and read the information on
NIfTI orientation).
fslswapdim
and fslorient
, to fix the
problem (more info below).
fslreorient2std
which is designed for just this task. However, make sure that the
labels are correct in FSLView to start with, as this tool only works if they are correct.
Tools
MNI152
standard
images - equivalent to the appropriate sform or qform in
a NIfTI file having a negative determinant).
In nifti files it is possible to independently report or modify the qform or sform fields (see below for background information on NIfTI orientation). However, the FSL4.1 output routines will try to keep qform and sform matrices the same whenever one would otherwise be unset. Therefore it is not possible, for instance, to delete only the qform, as if the sform is set then doing this will result in the qform being set equal (as close as possible) to the sform. This is currently done to aid interoperability with other packages. However, if both qform and sform are given different values then these are preserved by the output routines.
This command does not change the data storage at all - only the orientation information in the header and so should be used with great caution. Only modify header information if you understand the information about the NIfTI orientation given below or are following (exactly) a set of steps prescribed by someone who does.
The option -deleteorient
is useful for the first stage
of correcting orientation/label information in images where the
conversion to NIfTI does not provide the correction information. Note
that the first, and by far the best, solution to this problem is to
find a method of converting the images to NIfTI in a way that
correctly stores the information (see above) but if this really is
not possible then a combination of fslorient
and
fslswapdim
can be used to fix it (see below).
The new orientation of the data is specified by selecting what the new axes should represent. This can either be done in terms of the old axes (x y z -x -y -z) or in terms of anatomical labels when this information is available (in a nifti image where either the sform or qform code is non-zero). The anatomical labels are RL LR AP PA SI IS. Note that the anatomical label version will not allow the left-right convention to be changed.
Ordinarily fslswapdim will change the orientation information in the header as well as reordering the data. This is so that the anatomical labels stay attached to the same parts of the image and not fixed to the voxel coordinates. Hence, reordering a coronal image to axial slicing should keep the labels correctly attached to the relevant parts of the image, as long as they were correct initially. If the initial labels are incorrect (see the labels in fslview) then fslorient needs to be used in conjunction with fslswapdim in order to correct this.
When fslswapdim is given arguments that will change the left-right orientation it will issue a warning that the left-right orientation is being flipped. It will also try to modify the orientation information in the header (only when either the sform or qform code is non-zero), but not in a way that swaps this left-right orientation in the header. Hence there is a net change in orientation as the data is swapped while the header is not. If the swap occurs on the x-axis then nothing is done to the header at all. Otherwise, the axis which is being swapped, together with the x-axis, have their orientation changed. In this way the handedness of the header is preserved, the labels associated with the y-axis and z-axis follow the image change, but the x-axis labels do not. It is recommended that if a left-right swap in storage is desired (and this should only be done if the reconstruction is initially incorrect, and cannot be fixed by finding any better conversion method) then the arguments -x y z should be used as this is the simplest form of swapping since it only affects the x-axis data and no labels or header information is changed.
Serious (uncommon) problems
fslorient -deleteorient imagename
fslswapdim imagename a b c imagename
fslorient -setqformcode 1 imagename
Background information on NIfTI Orientation
This section is purely optional but is extremely useful to understand
if you are working with any of the advanced tools, have unusual
problems, or are just plain interested.
The NIfTI standard is confusing for many people on the issue of orientation, largely because it is intrinsically a confusing issue. It is complicated because the intensity data is stored on disk as a list of numbers - there is no concept of spatial or anatomical location with these numbers, and so information and standard conventions are used to associate spatial and anatomical location information with these numbers.
To start with, voxel coordinates are associated with the numbers (intensity values), such that the first number is at coordinate (0,0,0) the second at (1,0,0), the third at (2,0,0), etc. So, for example, say the image was 64 by 64 by 20 in size, then the coordinates would go as (0,0,0) then (1,0,0) ... then (63,0,0) then (0,1,0) then (1,1,0) then (2,1,0) ... then (63,1,0) then (0,2,0) ... then (63,63,0) then (0,0,1) then (1,0,1) ... until (63,63,19). Note that all coordinates start at 0, not 1, and that the first coordinate (i) here is the one that increases the fastest as you go through the list, followed by second (j) and then the third (k). These voxel coordinates - (i,j,k) - give spatial information (using information about how many voxels are in the three spatial directions) but do not attribute any anatomical information at all.
To go from voxel coordinates to more anatomically meaningful
coordinates is the job of the qform
and
sform
matrices that are stored in the NIfTI file. Note
that these matrices only provide useful information if they have a
non-zero code
, since a zero code
indicates
that the matrix is "Unknown" and hence cannot be used. Having two
matrices here is a common source of confusion. They were originally
proposed so that two different coordinates could be kept track of -
one representing the scanner coordinate system (the real space inside
the scanner bore) and the other one relating to standard space
coordinates (e.g. MNI152). However, in practice, it is rare that both
contain different information as they are often set to be the same, or
one of them is "Unknown" in which case the other contains all the
useful information.
Either matrix (qform or sform) is used to convert the voxel coordinates into "real world" coordinates (also called continuous coordinates, or mm coordinates, or other names). These new coordinates - called (x,y,z) here - have units of mm, and can take any values, not just positive whole numbers like the (i,j,k) voxel coordinates. Note that FSLView displays both voxel and mm coordinates. [Aside: the conversion is done by multiplying the matrix with the voxel coordinate, reshaped as a 4x1 vector with the last element equal to 1 - although this detail is not important for any of the discussion or understanding.]
If the qform
(or sform
) is set so that it
gives information about scanner coordinates (as indicated by the
code
), then a standard convention is used to relate the
coordinate values to the anatomy. The convention is: +x = Right; +y =
Anterior; +z = Superior. That is, moving in the positive x-direction
(so that the x-coordinate increases) will be moving to the right,
etc. This now allows left and right to be distinguished, which is
usually not possible just by looking at brain images. Hence this
information is absolutely crucial and getting this right for the
conversion of the image to NIfTI format is extremely important.
If it is incorrect then it would be easy for left and right to be
assigned incorrectly and all analysis results to be on the wrong side.
The information from the qform
and sform
is what is used by FSLView to determine the labels that are shown on
the image.
If the sform
is set so that it gives information about
standard space coordinates then the situation is the same as above,
since the standard convention used above was chosen to be the same as
the convention chosen for the standard space coordinate systems
(MNI152 and Talairach). The main difference between the two
situations is that the transformation to standard space (represented
by the sform
matrix) also involves scaling and shearing
of the coordinate axes to make the brain "fit" the standard templates,
whereas the transformation to scanner space coordinates is normally just a
rotation and translation.
An aside on left-right conventions: it is possible to store an
image in many different ways that are totally and completely
equivalent in terms of the intensities and the (x,y,z) coordinates.
What can be different is the voxel coordinates (and hence the order of
the intensities stored in the file) but these are completely
unimportant for all analysis purposes - they are purely related to the
storage format, in this case NIfTI - only the (x,y,z) coordinates and
the intensity values count with respect to the analysis. That being
said, one common confusion arises when the left-right order of the
storage is changed (but the mm coordinates and intensities are
unchanged). For instance, imagine taking an image where the first
voxel is on the left and then swapping the left-right order so that
the new image is stored such that the first voxel is now the rightmost
one, but modifying the qform
and sform
matrices appropriately so that this rightmost voxel still has the same
(x,y,z) coordinate as it had before - just a different voxel
coordinate. This kind of change will not affect any analysis in FSL
or any programs that are fully NIfTI compliant. However, some
programs are only happy with one sort of ordering (sometimes called
left-handed/right-handed, or radiological/neurological, or RAS/LAS,
etc.)
This used to be the case for old versions of FSL, but is no longer true.
But if only the order of the intensities in the file is swapped,
without compensating for this in the sform
and
qform
matrices, then the swapped version is no longer
equivalent to the original. This is why both the data order and
header information need to be kept in sync, and why running either
fslswapdim
or fslorient
alone to change the
orientation information is dangerous and usually incorrect.
An aside on display orientation: everything that has been said above about the NIfTI format refers to coordinates and data storage and has nothing to do with what way the images can be displayed in different viewing programs. Although the storage can be referred to as "radiological" or "neurological" this does not mean anything with respect to the displayed orientation. A valid NIfTI image can be displayed in any orientation that the viewing tool chooses, with the left side of the brain shown on the right side of the screen (so called radiological convention) or the other way around (neurological convention). It is also possible to display the inferior side of the brain at the top of the image, or any other configuration. It is entirely up to the display software how it chooses to show the image on the screen. What the NIfTI format does do is provide information to determine how to label the different parts of the image (with mm coordinates or anatomical labels such as left, right, anterior, posterior, superior and inferior). As long as the display tool correctly interprets this information and keeps it consistent with its choice of display orientation, there is no conflict between any type of NIfTI image and any displayed orientation.