DOC: Update documentation. Code is now broken

doc/fsl.scripts.rst

@@ -5,6 +5,7 @@
    :hidden:
 
    fsl.scripts.atlasq
+   fsl.scripts.fsl_convert_x5
    fsl.scripts.fsl_ents
    fsl.scripts.imcp
    fsl.scripts.imglob

fsl/transform/flirt.py

@@ -4,7 +4,7 @@
 #
 # Author: Paul McCarthy <pauldmccarthy@gmail.com>
 #
-"""This module contains functions for working with FLIRT affime transformation
+"""This module contains functions for working with FLIRT affine transformation
 matrices. The following functions are available:
 
 .. autosummary::
@@ -16,6 +16,18 @@ matrices. The following functions are available:
    toFlirt
    flirtMatrixToSform
    sformToFlirtMatrix
+
+
+
+FLIRT transformation matrices are affine matrices of shape ``(4, 4)`` which
+encode a linear transformation from a source image to a reference image. FLIRT
+matrices are defined in terms of *FSL coordinates*, which is a coordinate
+system where voxels are scaled by pixdims, and with a left-right flip if the
+image ``sform`` has a positive determinant.
+
+
+FLIRT matrices thus encode a transformation from source image FSL coordinates
+to reference image FSL coordinates.
 """
 
 
@@ -97,13 +109,8 @@ def flirtMatrixToSform(flirtMat, srcImage, refImage):
     transformation from the source image voxel coordinate system to
     the reference image world coordinate system.
 
-    FLIRT transformation matrices transform from the source image scaled voxel
-    coordinate system into the reference image scaled voxel coordinate system
-    (voxels scaled by pixdims, with a left-right flip if the image sform has a
-    positive determinant).
-
-    So to construct a transformation from source image voxel coordinates
-    into reference image world coordinates, we need to combine the following:
+    To construct a transformation from source image voxel coordinates into
+    reference image world coordinates, we need to combine the following:
 
       1. Source voxels -> Source scaled voxels
       2. Source scaled voxels -> Reference scaled voxels (the FLIRT matrix)
@@ -121,10 +128,10 @@ def sformToFlirtMatrix(srcImage, refImage, srcXform=None):
     """Under the assumption that the given ``srcImage`` and ``refImage`` share a
     common world coordinate system (defined by their
     :attr:`.Nifti.voxToWorldMat` attributes), this function will calculate and
-    return a transformation matrix from the ``srcImage`` scaled voxel
-    coordinate system to the ``refImage`` scaled voxel coordinate system, that
-    can be saved to disk and used with FLIRT, to resample the source image to
-    the reference image.
+    return a transformation matrix from the ``srcImage`` FSL coordinate system
+    to the ``refImage`` FSL coordinate system, that can be saved to disk and
+    used with FLIRT, to resample the source image to the space of the
+    reference image.
 
     :arg srcImage: Source :class:`.Image`
     :arg refImage: Reference :class:`.Image`

fsl/transform/fnirt.py

@@ -5,7 +5,7 @@
 # Author: Paul McCarthy <pauldmccarthy@gmail.com>
 #
 """This module contains functions for working with FNIRT non-linear
-transformation matrices. The following functions are available:
+transformations. The following functions are available:
 
 .. autosummary::
    :nosignatures:
@@ -13,6 +13,112 @@ transformation matrices. The following functions are available:
    readFnirt
    toFnirt
    fromFnirt
+
+
+Non-linear registration using FNIRT
+-----------------------------------
+
+
+FNIRT is used to calculate a non-linear registration from a source image to a
+reference image. FNIRT outputs the resulting non-linear transformation as
+either:
+
+ - A deformation/warp field which contains displacements or coordinates.
+ - A coefficient field which can be used to generate a warp field.
+
+
+Non-linear registration using FNIRT generally follows the process depicted
+here:
+
+
+.. image:: images/nonlinear_registration_process.png
+   :width: 80%
+   :align: center
+
+
+First, an initial linear registration is performed from the source image to
+the reference image using FLIRT; this provides an initial global alignment
+which can be used as the starting point for the non-linear registration. Next,
+FNIRT is used to non-linearly register the aligned source image to the
+reference image.  Importantly, both of these steps are performed using FSL
+coordinates.
+
+
+Note that we have three spaces, and three sets of coordinate systems, to
+consider:
+
+ 1. Source image space - the source image, before initial linear registration
+    to the reference image
+
+ 2. Aligned-source image space - the source image, after it has been linearly
+    transformed to the reference image space
+
+ 3. Reference image space
+
+
+The initial affine registration calculates a transformation between spaces 1
+and 2, and the non-linear registration calculates a transformation between
+spaces 2 and 3. Note that the fields-of-view for spaces 2 and 3 are
+equivalent.
+
+
+The non-linear transformation file generated by FNIRT will contain the initial
+linear registration, with it either being encoded directly into the warps (for
+a warp field), or being stored in the NIfTI header (for a coefficient field).
+
+
+FNIRT warp fields
+^^^^^^^^^^^^^^^^^
+
+
+A FNIRT deformation field (a.k.a. warp field) is defined in the same space as
+the reference image, and may contain:
+
+ - *relative displacements*, where each voxel in the warp field contains an
+   offset which can be added to the reference image coordinates for that
+   voxel, in order to calculate the corresponding source image coordinates.
+
+ - *absolute coordinates*, where each voxel in the warp field simply contains
+   the source image coordinates which correspond to those reference image
+   coordinates.
+
+
+If an initial linear registration was used as the starting point for FNIRT,
+this is encoded into the displacements/coordinates themselves, so they can be
+used to transform from the reference image to the *original* source image
+space.
+
+
+.. image:: images/fnirt_warp_field.png
+   :width: 80%
+   :align: center
+
+
+FNIRT coefficient fields
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+A FNIRT coefficient field contains the coefficients of a set of quadratic or
+cubic B-spline functions defined on a regular 3D grid overlaid on the
+reference image voxel coordinate system. Each coefficient in this grid may be
+referred to as a *control point* or a *knot*.
+
+
+Evaluating the spline functions at a particular location in the grid will
+result in a relative displacement which can be added to that location's
+reference image coordinates, in order to determine the corresponding source
+image coordinates.
+
+
+If an initial linear registration was used as the starting point for FNIRT,
+the generated displacement field will encode a transformation to *aligned*
+source image coordinates, and the initial affine will be stored in the NIfTI
+header of the coefficient field file.
+
+
+.. image:: images/fnirt_coefficient_field.png
+   :width: 80%
+   :align: center
 """