Differences

This shows you the differences between two versions of the page.

Link to this comparison view

reference:ft_volumerealign [2018/08/23 14:43] (current)
Line 1: Line 1:
 +=====  FT_VOLUMEREALIGN =====
 +
 +Note that this reference documentation is identical to the help that is displayed in MATLAB when you type "help ft_volumerealign"​.
 +
 +<​html><​pre>​
 +  <a href=/​reference/​ft_volumerealign><​font color=green>​FT_VOLUMEREALIGN</​font></​a>​ spatially aligns an anatomical MRI with head coordinates based on
 +  external fiducials or anatomical landmarks. This function does not change the
 +  anatomical MRI volume itself, but only adjusts the homogeneous transformation
 +  matrix that describes the mapping from voxels to the coordinate system. It also
 +  appends a coordsys-field to the output data, or it updates it. This field specifies
 +  how the x/y/z-axes of the coordinate system should be interpreted.
 + 
 +  For spatial normalisation and deformation (i.e. warping) an MRI to a template brain
 +  you should use the <a href=/​reference/​ft_volumenormalise><​font color=green>​FT_VOLUMENORMALISE</​font></​a>​ function.
 + 
 +  Different methods for aligning the anatomical MRI to a coordinate system are
 +  implemented,​ which are described in detail below:
 + 
 +  INTERACTIVE - Use a graphical user interface to click on the location of anatomical
 +  landmarks or fiducials. The anatomical data can be displayed as three orthogonal
 +  MRI slices or as a rendering of the head surface. The coordinate system is updated
 +  according to the definition of the coordinates of these fiducials.
 + 
 +  FIDUCIAL - The coordinate system is updated according to the definition of the
 +  coordinates of anatomical landmarks or fiducials that are specified in the
 +  configuration.
 + 
 +  HEADSHAPE - Match the head surface from the MRI with a measured head surface using
 +  an iterative closest point procedure. The MRI will be updated to match the measured
 +  head surface. You can optionally do an initial manual coregistration of the two head
 +  surfaces.
 + 
 +  SPM - Align the individual MRI to the coordinate system of a target or template MRI
 +  by matching the two volumes.
 + 
 +  FSL - Align the individual MRI to the coordinate system of a target or template MRI
 +  by matching the two volumes.
 + 
 +  Use as
 +    [mri] = ft_volumerealign(cfg,​ mri)
 +  or
 +    [mri] = ft_volumerealign(cfg,​ mri, target)
 +  where the first input is the configuration structure, the second input should be an
 +  anatomical or functional MRI volume and the third input is the the target anatomical MRI
 +  for SPM or FSL.
 + 
 +  The configuration can contain the following options
 +    cfg.method ​        = string representing the method for aligning
 +                         '​interactive'​ use the GUI to specify the fiducials
 +                         '​fiducial' ​   use pre-specified fiducials
 +                         '​headshape' ​  match the MRI surface to a headshape
 +                         '​spm' ​        match to template anatomical MRI
 +                         '​fsl' ​        match to template anatomical MRI
 +    cfg.coordsys ​      = string specifying the origin and the axes of the coordinate
 +                         ​system. Supported coordinate systems are '​ctf',​ '​4d',​
 +                         '​bti',​ '​yokogawa',​ '​asa',​ '​itab',​ '​neuromag',​ '​acpc',​
 +                         and '​paxinos'​. See http://​tinyurl.com/​ojkuhqz
 +    cfg.clim ​          = [min max], scaling of the anatomy color (default
 +                         is to adjust to the minimum and maximum)
 +    cfg.parameter ​     = '​anatomy'​ the parameter which is used for the
 +                          visualization
 +    cfg.viewresult ​    = string, '​yes'​ or '​no',​ whether or not to visualize aligned volume(s)
 +                         after realignment (default = '​no'​)
 + 
 +  When cfg.method = '​fiducial'​ and a coordinate system that is based on external
 +  facial anatomical landmarks (common for EEG and MEG), the following is required to
 +  specify the voxel indices of the fiducials:
 +    cfg.fiducial.nas ​   = [i j k], position of nasion
 +    cfg.fiducial.lpa ​   = [i j k], position of LPA
 +    cfg.fiducial.rpa ​   = [i j k], position of RPA
 +    cfg.fiducial.zpoint = [i j k], a point on the positive z-axis. This is
 +                          an optional '​fiducial',​ and can be used to determine
 +                          whether the input voxel coordinate axes are left-handed
 +                          (i.e. flipped in one of the dimensions). If this additional
 +                          point is specified, and the voxel coordinate axes are left
 +                          handed, the volume is flipped to yield right handed voxel
 +                          axes.
 + 
 +  When cfg.method = '​fiducial'​ and cfg.coordsys = '​acpc',​ the following
 +  is required to specify the voxel indices of the fiducials:
 +    cfg.fiducial.ac ​     = [i j k], position of anterior commissure
 +    cfg.fiducial.pc ​     = [i j k], position of posterior commissure
 +    cfg.fiducial.xzpoint = [i j k], point on the midsagittal-plane with a
 +                           ​positive Z-coordinate,​ i.e. an interhemispheric
 +                           point above ac and pc
 +  The coordinate system will be according to the RAS_Tal convention i.e.
 +  the origin corresponds with the anterior commissure the Y-axis is along
 +  the line from the posterior commissure to the anterior commissure the
 +  Z-axis is towards the vertex, in between the hemispheres the X-axis is
 +  orthogonal to the YZ-plane, positive to the right
 + 
 +  When cfg.method = '​interactive',​ a user interface allows for the specification of
 +  the fiducials or landmarks using the mouse, cursor keys and keyboard.The fiducials
 +  can be specified by pressing the corresponding key on the keyboard (n/l/r or
 +  a/p/z). When pressing q the interactive mode will stop and the transformation
 +  matrix is computed. This method supports the following options:
 +    cfg.viewmode ​   = '​ortho'​ or '​surface',​ visualize the anatomical MRI as three
 +                       ​slices or visualize the extracted head surface (default = '​ortho'​)
 +    cfg.snapshot ​    = '​no'​ ('​yes'​),​ making a snapshot of the image once a
 +                       ​fiducial or landmark location is selected. The optional second
 +                       ​output argument to the function will contain the handles to these
 +                       ​figures.
 +    cfg.snapshotfile = '​ft_volumerealign_snapshot'​ or string, the root of
 +                       the filename for the snapshots, including the path. If no path
 +                       is given the files are saved to the pwd. The consecutive
 +                       ​figures will be numbered and saved as png-file.
 + 
 +  When cfg.method = '​headshape',​ the function extracts the scalp surface from the
 +  anatomical MRI, and aligns this surface with the user-supplied headshape.
 +  Additional options pertaining to this method should be defined in the subcfg
 +  cfg.headshape. The following option is required:
 +    cfg.headshape.headshape ​     = string pointing to a file describing a headshape or a
 +                                   ​FieldTrip-structure describing a headshape, see <a href=/​reference/​ft_read_headshape><​font color=green>​FT_READ_HEADSHAPE</​font></​a>​
 +  The following options are optional:
 +    cfg.headshape.scalpsmooth ​   = scalar, smoothing parameter for the scalp
 +                                   ​extraction (default = 2)
 +    cfg.headshape.scalpthreshold = scalar, threshold parameter for the scalp
 +                                   ​extraction (default = 0.1)
 +    cfg.headshape.interactive ​   = '​yes'​ or '​no',​ use interactive realignment to
 +                                   align headshape with scalp surface (default =
 +                                   '​yes'​)
 +    cfg.headshape.icp ​           = '​yes'​ or '​no',​ use automatic realignment
 +                                   based on the icp-algorithm. If both '​interactive'​
 +                                   and '​icp'​ are executed, the icp step follows the
 +                                   ​interactive realignment step (default = '​yes'​)
 + 
 +  When cfg.method is '​fsl',​ a third input argument is required. The input volume is
 +  coregistered to this target volume, using FSL-flirt. Additional options pertaining
 +  to this method should be defined in the sub-structure ​ cfg.fsl and can include:
 +    cfg.fsl.path ​        = string, specifying the path to fsl
 +    cfg.fsl.costfun ​     = string, specifying the cost-function used for
 +                           ​coregistration
 +    cfg.fsl.interpmethod = string, specifying the interpolation method, can be
 +                           '​trilinear',​ '​nearestneighbour',​ or '​sinc'​
 +    cfg.fsl.dof ​         = scalar, specifying the number of parameters for the
 +                           ​affine transformation. 6 (rigid body), 7 (global
 +                           ​rescale),​ 9 (traditional) or 12.
 +    cfg.fsl.reslice ​     = string, specifying whether the output image will be
 +                           ​resliced conform the target image (default = '​yes'​)
 + 
 +  When cfg.method = '​spm',​ a third input argument is required. The input volume is
 +  coregistered to this target volume, using SPM. You can specify the version of
 +  the SPM toolbox to use with
 +    cfg.spmversion ​      = string, '​spm2',​ '​spm8',​ '​spm12'​ (default = '​spm8'​)
 +  Additional options pertaining to SPM2 and SPM8 should be defined in the
 +  sub-structure cfg.spm and can include:
 +    cfg.spm.regtype ​     = '​subj',​ '​rigid'​
 +    cfg.spm.smosrc ​      = scalar value
 +    cfg.spm.smoref ​      = scalar value
 +  Additional options pertaining to SPM12 are
 +    cfg.spm.sep ​         = optimisation sampling steps (mm), default: [4 2]
 +    cfg.spm.params ​      = starting estimates (6 elements), default: [0 0 0  0 0 0]
 +    cfg.spm.cost_fun ​    = cost function string:
 +                           '​mi' ​ - Mutual Information (default)
 +                           '​nmi'​ - Normalised Mutual Information
 +                           '​ecc'​ - Entropy Correlation Coefficient
 +                           '​ncc'​ - Normalised Cross Correlation
 +    cfg.spm.tol ​         = tolerences for accuracy of each param, default: [0.02 0.02 0.02 0.001 0.001 0.001]
 +    cfg.spm.fwhm ​        = smoothing to apply to 256x256 joint histogram, default: [7 7]
 + 
 +  With the '​interactive'​ and '​fiducial'​ methods it is possible to define an
 +  additional point (with the key '​z'​),​ which should be a point on the positive side
 +  of the xy-plane, i.e. with a positive z-coordinate in world coordinates. This point
 +  will subsequently be used to check whether the input coordinate system is left or
 +  right-handed. For the '​interactive'​ method you can also specify an additional
 +  control point (with the key '​r'​),​ that should be a point with a positive coordinate
 +  on the left-right axis.
 + 
 +  To facilitate data-handling and distributed computing you can use
 +    cfg.inputfile ​  ​= ​ ...
 +    cfg.outputfile ​ =  ...
 +  If you specify one of these (or both) the input data will be read from a
 +  *.mat file on disk and/or the output data will be written to a *.mat
 +  file. These mat files should contain only a single variable,
 +  corresponding with the input/​output structure.
 + 
 +  See also <a href=/​reference/​ft_read_mri><​font color=green>​FT_READ_MRI</​font></​a>,​ <a href=/​reference/​ft_volumereslice><​font color=green>​FT_VOLUMERESLICE</​font></​a>,​ <a href=/​reference/​ft_interactiverealign><​font color=green>​FT_INTERACTIVEREALIGN</​font></​a>,​ <a href=/​reference/​ft_electroderealign><​font color=green>​FT_ELECTRODEREALIGN</​font></​a>,​
 +  <a href=/​reference/​ft_determine_coordsys><​font color=green>​FT_DETERMINE_COORDSYS</​font></​a>,​ SPM_AFFREG, SPM_NORMALISE,​ SPM_COREG
 +</​pre></​html>​