User guide: Applications

Introduction

The following notes give general guidance on some of the different executables available in the project as well as some brief examples. The executables are divided into broad categories depending on the type of data they use and generate.
Image registration
Landmark registration
Surface registration
Transforming images, points, etc.
Using transformations
General image processing

rreg

top

Usage:
  rreg [target] [source] <options>
  where <options> is one or more of the following:
  <-parin file>        Read parameter from file
  <-parout file>       Write parameter to file
  <-dofin  file>       Read transformation from file
  <-dofout file>       Write transformation to file
  <-Rx1 value>         Region of interest in both images
  <-Ry1 value>         Region of interest in both images
  <-Rz1 value>         Region of interest in both images
  <-Rx2 value>         Region of interest in both images
  <-Ry2 value>         Region of interest in both images
  <-Rz2 value>         Region of interest in both images
  <-Tx1 value>         Region of interest in target image
  <-Ty1 value>         Region of interest in target image
  <-Tz1 value>         Region of interest in target image
  <-Tx2 value>         Region of interest in target image
  <-Ty2 value>         Region of interest in target image
  <-Tz2 value>         Region of interest in target image
  <-Sx1 value>         Region of interest in source image
  <-Sy1 value>         Region of interest in source image
  <-Sz1 value>         Region of interest in source image
  <-Sx2 value>         Region of interest in source image
  <-Sy2 value>         Region of interest in source image
  <-Sz2 value>         Region of interest in source image
  <-Tp  value>         Padding value in target
  <-debug>             Enable debugging information
Notes:
Estimate a rigid transformation between two images. The rigid transformation is represented by six degrees of freedom when registering 3-D images. Three degrees of freedom encode rotations about the axes and the remainder encode components of a translation. Three degrees of freedom can encode a rigid transformation between 2-D images, one for a rotation about the origin and two for a translation.
The mandatory arguments are the file names of two images, the first is treated as a `target' image and the second is treated as a `source' image. The transformation that is estimated maps locations in the target to locations in the source. This can be achieved by this simple example:
  rreg a.nii.gz b.nii.gz -dofout rreg-b-a.dof
In this example, the estimated transformation will be written to the file rreg-b-a.dof. If no file is specified with the -dofout flag, the transformation is only written to standard out.
The -dofin flag can be used to give a initial estimate for the rigid transformation. This is used as a starting point for the registration. The initial estimate could be, for example, estimated by a manual alignment:
  rreg a.nii.gz b.nii.gz -dofout rreg-b-a.dof -dofin rreg-init-b-a.dof
The -parin flag allows a parameter file to be specified. This file contains a list of parameter names and their corresponding values for use during the registration. Specifying a parameter file is optional. If no file is specified, default values are used. The parameters listed in the file do not need to be exhaustive, i.e. only those parameters the user wishes to set need to be listed. See the separate notes on registration parameters below.
The -parout flag is used to specify a file in which to write the parameters used during the registration. This is useful if there is a need to record these parameters. It is possible to identify the default parameters used during registration by specifying a `-parout' file without specifying a `-parin' file. The file specified is written at the outset of the registration process.
The -Tp flag can be used to specify a padding value within the target image. If used, all voxels in the target with a value less than or equal to the padding value are ignored. This restricts the registration to a region of interest consisting of the unpadded voxels. A padding value can also be specified in a parameter file.
The -debug flag can be used to capture the data used by the registration during its intermediate stages. For example, if pre-processing steps such as blurring or resampling are specified by the registration parameters, then the pre-processed images are saved during the registration. If more than one image resolution is used during registration, the intermediate images and transformation files are also saved.
The flags -Rx1, -Rx2, etc. can be used to restrict the registration to a region of interest in both of the images. Replacing `R' with `T' or `S' restricts the region of interest to the target or source images. An example is the following:
  rreg a.nii.gz b.nii.gz -dofout rreg-b-a.dof -Tx1 20 -Tx2 100
where the registration is restricted to a target region corresponding to slices perpendicular to the (image) x-axis. Eighty slices are used beginning with the twentieth.
Registration parameters:
The registration parameter file contains specifications for a set of parameters in the format
    <parameter name> = <parameter value>
Lines that start with a `#' character are ignored when the parameter file is read and can be used to insert comments into the file. All parameters are optional and only need to be specified if the default values are to be overridden. To identify the default values for the parameters, the -parout command line option can be used as described above.
Parameter name : "Padding value"
Parameter value : A number used to determine if voxels in the target image are used during registration. All voxels with an intensity less than or equal to the padding value are ignored.
Parameter name : "Interpolation mode"
Parameter value : One of the following options:
    NN
    Linear
    CSpline
    BSpline
    Sinc
This determines how the source image is interpolated during registration. NN represents nearest nearest neighbour interpolation.
Parameter name : "Similarity measure"
Parameter value : This can be chosen from the following list, the meanings of the abbreviations is written on the right.
    SSD	    Sum of squared differences
    CC	    Cross correlation
    CR_XY   Correlation ratio of the target given the source
    CR_YX   Correlation ratio of the source given the target
    JE	    Joint entropy
    MI	    Mutual information
    NMI	    Normalised mutual information
    LC	    Label consistency
    K	      Kappa coefficient
The LC and K metrics are intended for label images and should be used in conjunction with the NN interpolator. The metrics requiring least computation are those that do not require a joint histogram to be constructed, these are SSD, CC and LC.
Parameter name : "No. of bins"
Parameter value : A Number to determine the number of bins when constructing the joint histogram for the target and source. The joint histogram is used to calculate the similarity metric for the images based on the current transformation estimate. This parameter is only used if a similarity metric is used that requires a joint histogram.
Setting the number of bins to zero creates a histogram with one bin for each of the intensity values in the images. If no value is specified the default value of 64 bins is used.
Parameter name : "Epsilon"
Parameter value : A floating point number to determine a stopping point for the iterations of the optimisation. For example, if a value of 0.00001 is set, the registration stops when the similarity between the images changes by less than 0.00001 between successive iterations.
Parameter name : "Optimization method"
Parameter value : This can be chosen from the following list:
    GradientDescent
    SteepestGradientDescent
    DownhillDescent
    ConjugateGradientDescent
Each choice determines the method used to optimise the transformation parameters during registration.
Parameter name : "No. of resolution levels"
Parameter value : A positive integer. This determines the number of different resolution levels for the target and source images during registration. If the number of resolution levels is not specified, one level is used by default.
If more than one resolution level is required, the registration is first run with a blurred and/or down-sampled version of the target and source images. A blurred and down-sampled version of an input image represents structures at a coarser scale and starting the registration at a larger scale increases the likelihood of registration success.
The transformation estimated at the first coarse scale is then used as a starting point for the subsequent (finer) scale and so on. The degree of blurring and the resampled voxel sizes for each image are specified by further parameters (see below).
The resolution levels are numbered in reverse order with respect to the order in which they are carried out, e.g. for three resolution levels, level number 3 (coarsest) is run first and level number 1 (finest) is optimised last.
Parameter name : "Resolution level"
Parameter value : A number to indicate that following parameters are restricted to a particular image resolution level. For example, if 3 resolution levels are specified, then the values that can be used for the "Resolution level" are 1, 2 or 3.
This is an optional parameter that affects certain other registration parameters, allowing them to be specified individually for each resolution level. The parameters that can be specified in this way are those that control the blurring and resampling of the images, the number of iterations during optimisation and the length and number of steps used. These parameters are described below.
Specifying a resolution level with a line such as
  Resolution level = 2
ties all the affected parameters to the specified resolution level until the next appearance of a similar line for a different resolution level.
Parameter name : "Target blurring (in mm)" "Source blurring (in mm)"
Parameter value : A floating point number. These parameters determine the size of the Gaussian kernel used to blur the source and target images. A value of zero indicates that no blurring should be done.
The degree of blurring can be specified separately for each resolution level using the "Resolution level" parameter as described above. If a blurring parameter is only specified once, without specifying a resolution level, then the value is assumed to relate to resolution level number 1 (the final level). The values for assigned to the remaining levels are obtained by successive doubling of the specified value.
Parameter name : "Target resolution (in mm)" "Source resolution (in mm)"
Parameter value : Floating point number(s). These parameters determine the voxel size of the resampled images during registration. A value of zero indicates that the images should not be resampled. If a single number is specified, the resampled voxel size is isotropic, e.g.:
  Target resolution (in mm) = 2
Alternatively, giving multiple values allows anisotropic resampling to be carried out, e.g., for a 3-D image:
  Target resolution (in mm) = 2 2 3
The resampling resolutions can be specified separately for each resolution level using the "Resolution level" parameter as described above. If a resolution parameter is specified only once, without specifying a resolution level, then the value is assumed to relate to resolution level number 1 (the final level) with the values for any other levels obtained by successive doubling of the specified value.
Parameter name : "No. of iterations"
Parameter value : A number to specify the number of iterations to use during optimisation. This is used as a stopping condition. The optimisation may stop before the number specified if the similarity metric changes by a negligible amount between iterations (see the `Epsilon' parameter)
Different numbers of iterations can be specified for each resolution level using the "Resolution level" parameter as described above. Specifying the number of iterations once, without specifying a resolution level, means that the same number of iterations is used for all resolution levels.
Parameter name : "Length of steps"
Parameter value : A positive floating point number to determine the amount by which the parameters are incremented when optimising the transformation parameters.
A different step length can be specified for each resolution level using the "Resolution level" parameter as described above. If a single value is given, without specifying a particular resolution level, then the value is assigned to resolution level 1 (final level) and the values assigned to the remaining levels are obtained by successive doubling of the specified value.
Parameter name : "No. of steps"
Parameter value : A positive integer. It is possible to run the optimisation in a `coarse-to-fine' manner. This starts by using large parameter steps (see `Length of steps' above) and estimating the transformation parameters, the parameter step is then halved and the optimisation is continued. The 'No. of steps' parameter determines the number of step sizes used. For example, if, for a particular resolution level, `Length of steps' is set to 8 and 'No. of steps' is set to 3, the optimisation will first use a step length of 8 and this is followed by step lengths of 4 and 2.
This parameter can be separately specified for each resolution level using the "Resolution level" parameter as described above. If a single value is given, without specifying a particular resolution level, then the value is applied to all resolution levels.

areg

top

Usage:
  areg [target] [source] <options>

  where <options> is one or more of the following:

  <-parin file>        Read parameter from file
  <-parout file>       Write parameter to file
  <-dofin  file>       Read transformation from file
  <-dofout file>       Write transformation to file
  <-p9>                Affine transformation with 9 dofs
  <-p12>               Affine transformation with 12 dofs
  <-Rx1 value>         Region of interest in both images
  <-Ry1 value>         Region of interest in both images
  <-Rz1 value>         Region of interest in both images
  <-Rx2 value>         Region of interest in both images
  <-Ry2 value>         Region of interest in both images
  <-Rz2 value>         Region of interest in both images
  <-Tx1 value>         Region of interest in target image
  <-Ty1 value>         Region of interest in target image
  <-Tz1 value>         Region of interest in target image
  <-Tx2 value>         Region of interest in target image
  <-Ty2 value>         Region of interest in target image
  <-Tz2 value>         Region of interest in target image
  <-Sx1 value>         Region of interest in source image
  <-Sy1 value>         Region of interest in source image
  <-Sz1 value>         Region of interest in source image
  <-Sx2 value>         Region of interest in source image
  <-Sy2 value>         Region of interest in source image
  <-Sz2 value>         Region of interest in source image
  <-Tp  value>         Padding value in target
  <-debug>             Enable debugging information
Notes:
Estimate an affine transformation between two images. The affine transformation is represented by 9 or 12 degrees of freedom when registering 3-D images. The degrees of freedom encode rotations (3), translation (3), scaling (3) and shears (3). No shearing is used of the -p9 flag is used to specify 9 degrees of freedom. Otherwise, all 12 transformation parameters are optimised by default or if the -p12 flag is used.
The mandatory arguments are the file names of two images, the first is treated as a `target' image and the second is treated as a `source' image. The transformation that is estimated maps locations in the target to locations in the source. This can be achieved by this simple example:
  areg a.nii.gz b.nii.gz -dofout areg-b-a.dof
In this example, the estimated transformation will be written to the file areg-b-a.dof. If no file is specified with the -dofout flag, the transformation is only written to standard out.
The -dofin flag can be used to give a initial estimate for the affine transformation, which can be either an affine or a rigid transformation. This is used as a starting point for the registration. The initial estimate could be, for example, estimated by an earlier rigid registration step:
  areg a.nii.gz b.nii.gz -dofout areg-b-a.dof -dofin rreg-b-a.dof
The -parin flag allows a parameter file to be specified. This file contains a list of parameter names and their corresponding values for use during the registration. Specifying a parameter file is optional; if no file is given, default parameter values are used. The parameters listed in a specified file do not need to be exhaustive, i.e. only those parameters the user wishes to set need to be listed. See the separate notes on registration parameters below.
The -parout flag is used to specify a file in which to write the parameters used during the registration. This is useful if there is a need to record these parameters. It is possible to identify the default parameters used during registration by specifying a `-parout' file without specifying a `-parin' file. The file specified is written at the outset of the registration process.
The -Tp flag can be used to specify a padding value within the target image. If used, all voxels in the target with a value less than or equal to the padding value are ignored. This restricts the registration to a region of interest consisting of the unpadded voxels. A padding value can also be specified in a parameter file.
The -debug flag can be used to capture the data used by the registration during its intermediate stages. For example, if pre-processing steps such as blurring or resampling are specified by the registration parameters, then the pre-processed images are saved during the registration. If more than one image resolution is used during registration, the intermediate images and transformation files are also saved.
The flags -Rx1, -Rx2, etc. can be used to restrict the registration to a region of interest in both of the images. Replacing `R' with `T' or `S' restricts the region of interest to the target or source images. An example is the following:
  areg a.nii.gz b.nii.gz -dofout areg-b-a.dof -Tx1 20 -Tx2 100
where the registration is restricted to a target region corresponding to slices perpendicular to the (image) x-axis. Eighty slices are used beginning with the twentieth.
Registration parameters:
The registration parameter file contains specifications for a set of parameters in the format
    <parameter name> = <parameter value>
Lines that start with a `#' character are ignored when the parameter file is read and can be used to insert comments into the file. All parameters are optional and only need to be specified if the default values are to be overridden. To identify the default values for the parameters, the -parout command line option can be used as described above.
Parameter name : "Padding value"
Parameter value : A number used to determine if voxels in the target image are used during registration. All voxels with an intensity less than or equal to the padding value are ignored.
Parameter name : "Interpolation mode"
Parameter value : One of the following options:
    NN
    Linear
    CSpline
    BSpline
    Sinc
This determines how the source image is interpolated during registration. NN represents nearest nearest neighbour interpolation.
Parameter name : "Similarity measure"
Parameter value : This can be chosen from the following list, the meanings of the abbreviations is written on the right.
    SSD	    Sum of squared differences
    CC	    Cross correlation
    CR_XY   Correlation ratio of the target given the source
    CR_YX   Correlation ratio of the source given the target
    JE	    Joint entropy
    MI	    Mutual information
    NMI	    Normalised mutual information
    LC	    Label consistency
    K	    Kappa coefficient
The LC and K metrics are intended for label images and should be used in conjunction with the NN interpolator. The metrics requiring least computation are those that do not require a joint histogram to be constructed, these are SSD, CC and LC.
Parameter name : "No. of bins"
Parameter value : A Number to determine the number of bins when constructing the joint histogram for the target and source. The joint histogram is used to calculate the similarity metric for the images based on the current transformation estimate. This parameter is only used if a similarity metric is used that requires a joint histogram.
Setting the number of bins to zero creates a histogram with one bin for each of the intensity values in the images. If no value is specified the default value of 64 bins is used.
Parameter name : "Epsilon"
Parameter value : A floating point number to determine the stopping point for the iterations of the optimisation. For example, if a value of 0.00001 is set, the registration stops when the similarity between the images changes by less than 0.00001 between successive iterations.
Parameter name : "Optimization method"
Parameter value : This can be chosen from the following list:
    GradientDescent
    SteepestGradientDescent
    DownhillDescent
    ConjugateGradientDescent
Each choice determines the method used to optimise the transformation parameters during registration.
Parameter name : "No. of resolution levels"
Parameter value : A positive integer. This determines the number of different resolution levels for the target and source images during registration. If the number of resolution levels is not specified, one level is used by default.
If more than one resolution level is required, the registration is first run with a blurred and/or down sampled version of the target and source images. A blurred and down sampled version of an input image represents structures at a coarser scale and starting the registration at a larger scale increases the likelihood of registration success.
The transformation estimated at the first coarse scale is then used as a starting point for the subsequent (finer) scale and so on. The degree of blurring and the resampled voxel sizes for each image are specified by further parameters (see below).
The resolution levels are numbered in reverse order with respect to the order in which they are carried out, e.g. for three resolution levels, level number 3 (coarsest) is run first and level number 1 (finest) is optimised last.
Parameter name : "Resolution level"
Parameter value : A number to indicate that following parameters are restricted to a particular image resolution level. For example, if 3 resolution levels are specified, then the values that can be used for the "Resolution level" are 1, 2 or 3.
This is an optional parameter that affects certain other registration parameters, allowing them to be specified individually for each resolution level. The parameters that can be specified in this way are those that control the blurring and resampling of the images, the number of iterations during optimisation and the length and number of steps used. These parameters are described below.
Specifying a resolution level with a line such as
Resolution level = 2
ties all the affected parameters to the specified resolution level until the next appearance of a similar line for a different resolution level.
Parameter name : "Target blurring (in mm)" "Source blurring (in mm)"
Parameter value : A floating point number. These parameters determine the size of the Gaussian kernel used to blur the source and target images. A value of zero indicates that no blurring should be done.
The degree of blurring can be specified separately for each resolution level using the "Resolution level" parameter as described above. If a blurring parameter is only specified once, without specifying a resolution level, then the value is assumed to relate to resolution level number 1 (the final level). The values for assigned to the remaining levels are obtained by successive doubling of the specified value.
Parameter name : "Target resolution (in mm)" "Source resolution (in mm)"
Parameter value : Floating point number(s). These parameters determine the voxel size of the resampled images during registration. A value of zero indicates that the images should not be resampled. If a single number is specified, the resampled voxel size is isotropic, e.g.:
  Target resolution (in mm) = 2
Alternatively, giving multiple values allows anisotropic resampling to be carried out, e.g., for a 3-D image:
  Target resolution (in mm) = 2 2 3
The resampling resolutions can be specified separately for each resolution level using the "Resolution level" parameter as described above. If a resolution parameter is specified only once, without specifying a resolution level, then the value is assumed to relate to resolution level number 1 (the final level) with the values for any other levels obtained by successive doubling of the specified value.
Parameter name : "No. of iterations"
Parameter value : A number to specify the number of iterations to use during optimisation. This is used as a stopping condition. The optimisation may stop before the number specified if the similarity metric changes by a negligible amount between iterations (see the `Epsilon' parameter)
Different numbers of iterations can be specified for each resolution level using the "Resolution level" parameter as described above. Specifying the number of iterations once, without specifying a resolution level, means that the same number of iterations is used for all resolution levels.
Parameter name : "Length of steps"
Parameter value : A positive floating point number to determine the amount by which the parameters are incremented when optimising the transformation parameters.
A different step length can be specified for each resolution level using the "Resolution level" parameter as described above. If a single value is given, without specifying a particular resolution level, then the value is assigned to resolution level 1 (final level) and the values assigned to the remaining levels are obtained by successive doubling of the specified value.
Parameter name : "No. of steps"
Parameter value : A positive integer. It is possible to run the optimisation in a `coarse-to-fine' manner. This starts by using large parameter steps (see `Length of steps' above) and estimating the transformation parameters, the parameter step is then halved and the optimisation is continued. The 'No. of steps' parameter determines the number of step sizes used. For example, if `Length of steps' is set to 8 and 'No. of steps' is set to 3, the optimisation will first use a step length of 8 and this is followed by step lengths of 4 and 2.
This parameter can be separately specified for each resolution level using the "Resolution level" parameter as described above. If a single value is given, without specifying a particular resolution level, then the value is applied to all resolution levels.

nreg

top

Usage:
  nreg [target] [source] <options>

  where <options> is one or more of the following:

  <-parin file>        Read parameter from file
  <-parout file>       Write parameter to file
  <-dofin  file>       Read transformation from file
  <-dofout file>       Write transformation to file
  <-Rx1 value>         Region of interest in both images
  <-Ry1 value>         Region of interest in both images
  <-Rz1 value>         Region of interest in both images
  <-Rx2 value>         Region of interest in both images
  <-Ry2 value>         Region of interest in both images
  <-Rz2 value>         Region of interest in both images
  <-Tx1 value>         Region of interest in target image
  <-Ty1 value>         Region of interest in target image
  <-Tz1 value>         Region of interest in target image
  <-Tx2 value>         Region of interest in target image
  <-Ty2 value>         Region of interest in target image
  <-Tz2 value>         Region of interest in target image
  <-Sx1 value>         Region of interest in source image
  <-Sy1 value>         Region of interest in source image
  <-Sz1 value>         Region of interest in source image
  <-Sx2 value>         Region of interest in source image
  <-Sy2 value>         Region of interest in source image
  <-Sz2 value>         Region of interest in source image
  <-Tp  value>         Padding value in target image
  <-ds  value>         Initial control point spacing
  <-debug>             Enable debugging information
Notes:
Carry out a non-rigid registration for two images. The resulting non-rigid transformation is represented by a free-form deformation (FFD) where the transformation parameters are represented using a lattice of control point vectors.
The mandatory arguments are the file names of two images, the first is treated as a `target' image and the second is treated as a `source' image. The transformation that is estimated maps locations in the target to locations in the source. This can be achieved by this simple example:
  nreg a.nii.gz b.nii.gz -dofout nreg-b-a.dof
In this example, the estimated FFD transformation is written to the file nreg-b-a.dof.
The -dofin flag can be used to give a initial estimate for the transformation. This is used as a starting point for the registration. The initial estimate could be, for example, estimated by an earlier affine registration step:
  nreg a.nii.gz b.nii.gz -dofout nreg-b-a.dof -dofin areg-b-a.dof
The -parin flag allows a parameter file to be specified. This file contains a list of parameter names and their corresponding values for use during the registration. Specifying a parameter file is optional; if no file is given, default parameter values are used. The parameters listed in a specified file do not need to be exhaustive, i.e. only those parameters the user wishes to set need to be listed. See the separate notes on registration parameters below.
The -parout flag is used to specify a file in which to write the parameters used during the registration. This is useful if there is a need to record these parameters. It is possible to identify the default parameters used during registration by specifying a `-parout' file without specifying a `-parin' file. The file specified is written at the outset of the registration process.
The -Tp flag can be used to specify a padding value within the target image. If used, all voxels in the target with a value less than or equal to the padding value are ignored. This restricts the registration to a region of interest consisting of the unpadded voxels. A padding value can also be specified in a parameter file.
The -debug flag can be used to capture the data used by the registration during its intermediate stages. For example, if pre-processing steps such as blurring or resampling are specified by the registration parameters, then the pre-processed images are saved during the registration. If more than one image resolution is used during registration, the intermediate images and transformation files are also saved.
The flags -Rx1, -Rx2, etc. can be used to restrict the registration to a region of interest in both of the images. Replacing `R' with `T' or `S' restricts the region of interest to the target or source images. An example is the following:
  nreg a.nii.gz b.nii.gz -dofout nreg-b-a.dof -Tx1 20 -Tx2 100
where the registration is restricted to a target region corresponding to slices perpendicular to the (image) x-axis. Eighty slices are used beginning with the twentieth.
Registration parameters:
The registration parameter file contains specifications for a set of parameters in the format
    <parameter name\> = \<parameter value\>
Lines that start with a `#' character are ignored when the parameter file is read and can be used to insert comments into the file. All parameters are optional and only need to be specified if the default values are to be overridden. To identify the default values for the parameters, the -parout command line option can be used as described above. For an example parameter file see nreg.par.
Parameter name : "Padding value"
Parameter value : A number used to determine if voxels in the target image are used during registration. All voxels with an intensity less than or equal to the padding value are ignored.
Parameter name : "Interpolation mode"
Parameter value : One of the following options:
    NN
    Linear
    CSpline
    BSpline
    Sinc
This determines how the source image is interpolated during registration. NN represents nearest nearest neighbour interpolation.
Parameter name : "Similarity measure"
Parameter value : This can be chosen from the following list, the meanings of the abbreviations is written on the right.
    SSD	    Sum of squared differences
    CC	    Cross correlation
    CR_XY   Correlation ratio of the target given the source
    CR_YX   Correlation ratio of the source given the target
    JE	    Joint entropy
    MI	    Mutual information
    NMI	    Normalised mutual information
    LC	    Label consistency
    K	    Kappa coefficient
The LC and K metrics are intended for label images and should be used in conjunction with the NN interpolator. The metrics requiring least computation are those that do not require a joint histogram to be constructed, these are SSD, CC and LC.
Parameter name : "No. of bins"
Parameter value : A Number to determine the number of bins when constructing the joint histogram for the target and source. The joint histogram is used to calculate the similarity metric for the images based on the current transformation estimate. This parameter is only used if a similarity metric is used that requires a joint histogram.
Setting the number of bins to zero creates a histogram with one bin for each of the intensity values in the images. If no value is specified the default value of 64 bins is used.
Parameter name : "Epsilon"
Parameter value : A floating point number to determine the stopping point for the iterations of the optimisation. For example, if a value of 0.00001 is set, the registration stops when the similarity between the images changes by less than 0.00001 between successive iterations.
Parameter name : "Optimization method"
Parameter value : This can be chosen from the following list:
    GradientDescent
    SteepestGradientDescent
    DownhillDescent
    ConjugateGradientDescent
Each choice determines the method used to optimise the transformation parameters during registration.
Parameter name : "No. of resolution levels"
Parameter value : A positive integer. The resolution levels refer to the use of different spacings of control points in FFD transformations that are optimised within a multi-resolution approach. This method begins by estimating a transformation using a FFD with a relatively large control point spacing. This initial transformation aims to capture the larger scale differences between the images. The resulting FFD is then subdivided, generating a new FFD with half the control point spacing. The new FFD is then used as a starting point for a second optimisation step that captures a finer level of detail. The number of iterations of this process is determined by the number of resolution levels chosen by the user. If the number of resolution levels is not specified, one level is used by default.
For each resolution level, it is possible to specify a range of other parameters that relate to the registration. These parameters can be used to set the voxel resolution and blurring of the images being registered, and also to set the step length, iterations and number of steps during optimisation. These are described in more detail below.
The resolution levels are numbered in reverse order with respect to the order in which they are carried out, e.g. for three resolution levels, level number 3 (coarsest) is run first and level number 1 (finest) is optimised last.
Parameter name : "Control point spacing in X" "Control point spacing in Y" "Control point spacing in Z"
Parameter value : Numbers to set the control point spacing during registration. If more than one resolution level is required, the values set for these parameters determine the control point spacing for the initial (largest scale) FFD that is optimised. The control point spacings for subsequent levels are obtained by successively halving the given values. For example, the following parameters:
No. of resolution levels = 2 Control point spacing in X = 5 Control point spacing in Y = 5 Control point spacing in Z = 10
will result in a FFD with a control point spacing of 5, 5 and 10 (mm) being optimised in the first stage. This is then subdivided to give a FFD with a spacing of 2.5, 2.5 and 5 (mm) for the second stage.
Parameter name : "Resolution level"
Parameter value : A number to indicate that following parameters are restricted to a particular image resolution level. For example, if 3 resolution levels are specified, then the values that can be used for the "Resolution level" are 1, 2 or 3.
This is an optional parameter that affects certain other registration parameters, allowing them to be specified individually for each resolution level. The parameters that can be specified in this way are those that control the blurring and resampling of the images, the number of iterations during optimisation and the length and number of steps used. These parameters are described below.
Specifying a resolution level with a line such as
  Resolution level = 2
ties all the affected parameters to the specified resolution level until the next appearance of a similar line for a different resolution level.
Parameter name : "Target blurring (in mm)" "Source blurring (in mm)"
Parameter value : A floating point number. These parameters determine the size of the Gaussian kernel used to blur the source and target images. A value of zero indicates that no blurring should be done.
The degree of blurring can be specified separately for each resolution level using the "Resolution level" parameter as described above. If a blurring parameter is only specified once, without specifying a resolution level, then the value is assumed to relate to resolution level number 1 (the final level). The values for assigned to the remaining levels are obtained by successive doubling of the specified value.
Parameter name : "Target resolution (in mm)" "Source resolution (in mm)"
Parameter value : Floating point number(s). These parameters determine the voxel size of the resampled images during registration. A value of zero indicates that the images should not be resampled. If a single number is specified, the resampled voxel size is isotropic, e.g.:
  Target resolution (in mm) = 2
Alternatively, giving multiple values allows anisotropic resampling to be carried out, e.g., for a 3-D image:
  Target resolution (in mm) = 2 2 3
The resampling resolutions can be specified separately for each resolution level using the "Resolution level" parameter as described above. If a resolution parameter is specified only once, without specifying a resolution level, then the value is assumed to relate to resolution level number 1 (the final level) with the values for any other levels obtained by successive doubling of the specified value.
Parameter name : "No. of iterations"
Parameter value : A number to specify the number of iterations to use during optimisation. This is used as a stopping condition. The optimisation may stop before the number specified if the similarity metric changes by a negligible amount between iterations (see the `Epsilon' parameter)
Different numbers of iterations can be specified for each resolution level using the "Resolution level" parameter as described above. Specifying the number of iterations once, without specifying a resolution level, means that the same number of iterations is used for all resolution levels.
Parameter name : "Length of steps"
Parameter value : A positive floating point number to determine the amount by which the parameters are incremented when optimising the transformation parameters.
A different step length can be specified for each resolution level using the "Resolution level" parameter as described above. If a single value is given, without specifying a particular resolution level, then the value is assigned to resolution level 1 (final level) and the values assigned to the remaining levels are obtained by successive doubling of the specified value.
Parameter name : "No. of steps"
Parameter value : A positive integer. It is possible to run the optimisation in a `coarse-to-fine' manner. This starts by using large parameter steps (see `Length of steps' above) and estimating the transformation parameters, the parameter step is then halved and the optimisation is continued. The 'No. of steps' parameter determines the number of step sizes used. For example, if `Length of steps' is set to 8 and 'No. of steps' is set to 3, the optimisation will first use a step length of 8 and this is followed by step lengths of 4 and 2.
This parameter can be separately specified for each resolution level using the "Resolution level" parameter as described above. If a single value is given, without specifying a particular resolution level, then the value is applied to all resolution levels.
Parameter name : "Lambda1" "Lambda2" "Lambda3"
Parameter value : Floating point numbers. These three parameters represent weighting values for different types of regularisation penalty terms that can be added to the similarity metric during registration. Assigning higher values for each weighting value results in more regularity in the resulting FFD displacement fields.
If unspecified the default value for each parameter is zero. The values for each of Lambda1, Lambda2 and Lambda3 are used to weight penalty terms for smoothness, volume preservation and topology preservation respectively.

Example parameter file for use with nreg

top

An example parameter file for use with nreg. The general registration parameters are given first, followed by the non-rigid registration parameters that are the same for all resolution levels. Finally, parameters specific to each resolution level are given in separate groups.
#
# Registration parameters
#

No. of resolution levels          = 3

No. of bins                       = 64
Epsilon                           = 0.0001
Padding value                     = -1
Similarity measure                = NMI
Interpolation mode                = Linear
Optimization method               = GradientDescent

#
# Non-rigid registration parameters
#

Lambda1                           = 0
Lambda2                           = 0
Lambda3                           = 0
Control point spacing in X        = 40
Control point spacing in Y        = 40
Control point spacing in Z        = 40
Subdivision                       = True

#
# Registration parameters for resolution level 1
#

Resolution level                  = 1
Target blurring (in mm)           = 1.5
Target resolution (in mm)         = 3 3 3
Source blurring (in mm)           = 1.5
Source resolution (in mm)         = 3 3 3
No. of iterations                 = 10
No. of steps                      = 4
Length of steps                   = 5

#
# Registration parameters for resolution level 2
#

Resolution level                  = 2
Target blurring (in mm)           = 3
Target resolution (in mm)         = 6 6 6
Source blurring (in mm)           = 3
Source resolution (in mm)         = 6 6 6
No. of iterations                 = 10
No. of steps                      = 4
Length of steps                   = 10

#
# Registration parameters for resolution level 3
#

Resolution level                  = 3
Target blurring (in mm)           = 6
Target resolution (in mm)         = 12 12 12
Source blurring (in mm)           = 6
Source resolution (in mm)         = 12 12 12
No. of iterations                 = 10
No. of steps                      = 4
Length of steps                   = 20


prreg

top

Usage:
  prreg [target] [source] <-dofout file>
Notes:
Estimate a rigid transformation between two sets of landmark points. The point sets need to be in VTK format and are assumed to contain equal numbers of corresponding points. E.g.
  prreg a.vtk b.vtk -dofout prreg-a-b.vtk
The resulting transformation maps locations in the target point set (a.vtk) to locations in the source point set (b.vtk).
The registration uses a closed form optimisation that is based on singular value decomposition applied to a matrix derived from the point locations. This method finds the least squares fit for the distance between corresponding points.
The accuracy of the transformation, measured by root-mean-square RMS distance between corresponding points, is calculated and written to standard out. If the -dofout flag is not used, the transformation is estimated in order to give the accuracy but it is not written to a file.

pareg

top

Usage:
  pareg [target] [source] <options>

  Where options are:
  <-dofout    file>    Final transformation estimate
  <-dofin     file>    Start transformation estimate
Notes:
Estimate an affine transformation between two sets of landmark points. The point sets need to be in VTK format and are assumed to contain equal numbers of corresponding points. E.g.
  pareg a.vtk b.vtk -dofin prreg-a-b.vtk -dofout pareg-a-b.vtk
Gives the affine transformation pareg-a-b.vtk based on an initial rigid estimate given by prreg-a-b.vtk. The resulting transformation maps locations in the target point set (a.vtk) to locations in the source point set (b.vtk).
The registration uses a conjugate gradient descent to optimise the affine transformation parameters so that the sum of squared distances between corresponding points is minimal.
The accuracy of the transformation, measured by root-mean-square RMS distance between corresponding points, is calculated and written to standard out. If the -dofout flag is not used, the transformation is estimated in order to give the accuracy but it is not written to a file.

pnreg

top

Usage:
  pareg [target] [source] <options>

  <-dofout file>       Final transformation estimate
  <-dofin  file>       Start transformation estimate
  <-ds spacing>        Control point spacing
Notes:
Estimate an non-rigid transformation between two sets of landmark points. The non-rigid transformation is represented by a free-form deformation (FFD). The point sets need to be in VTK format and are assumed to contain equal numbers of corresponding points. E.g.
  pnreg a.vtk b.vtk -dofin pareg-a-b.vtk -dofout pnreg-a-b.vtk -ds 10
estimates the non-rigid FFD pnreg-a-b.vtk based on an initial affine estimate given by pareg-a-b.vtk. The lattice of control points within the output FFD has a spacing of 10mm and covers the bounding box of the target points. The resulting transformation maps locations in the target point set (a.vtk) to locations in the source point set (b.vtk).
The registration optimises the control point vectors of the FFD so that the sum of squared distances between corresponding points is minimal.
The accuracy of the transformation, measured by root-mean-square RMS distance between corresponding points, is calculated and written to standard out. If the -dofout flag is not used, the transformation is estimated in order to give the accuracy but it is not written to a file.

srreg

top

Usage:
  srreg [target] [source] <options>

  where <options> is one or more of the following:

  <-locator>          Locator: 0 = cell locator,
                               1 = point locator, (default)
                               2 = kd-tree locator
  <-dofin name>       Name of input file
  <-dofout name>      Name of output file
  <-epsilon>          Value for espilon (default=0.01)
  <-clean>            Clean polydata (default OFF)
  <-symmetric>        Use symmetric distance (default OFF)
  <-ignoreedges>      Ignores edges in ICP (default OFF)
  <-invert>           Save the inverse transformation (default OFF)
  <-iterations>       Number of iterations (default 100)
Notes:
Run a rigid surface registration for a pair of input meshes. The meshes provided need to be in VTK format. There is no restriction on the points contained in the input meshes, i.e. they do not need to be in correspondence.
During registration, however, two sets of corresponding points are estimated from the meshes by finding, for each target point, the closest location in the source surface. These point sets are then registered using a landmark-based rigid registration (see prreg). The resulting transformation is then used to transform the target mesh and the process is iterated.
A stopping condition for this process is determined by the maximum number of iterations, 100 iterations are used by default but this can be varied using the `-iterations' flag.
Another stopping condition is met when `epsilon', the difference between the root-mean square error for corresponding points for successive iterations, falls below a specified value. By default, registration halts when the difference between successive iterations is less than 0.01 and the value used can be varied using the -epsilon flag.
An input transformation estimate can be specified with the `-dofin' flag and the resulting transformation estimate can be written to a file using the `-dofout' flag. An example call might be:
srreg mesh-a.vtk mesh-b.vtk -dofout srreg-b-a.vtk -epsilon 0.001
The resulting transformation maps locations in the target mesh to locations in the source mesh.
By default, a point locator is used when estimating the corresponding point sets (`-locator 1') - this uses the nearest vertex in the source mesh for each target vertex. Specifying a cell locator (`-locator 0') results in the identification of the nearest source locations from within the faces (cells) of the source mesh. A kd-tree locator (`-locator 2') gives the same result as a point locator but uses a more efficient search method, which can be useful for large datasets.
If the `-symmetric' flag is used, the corresponding point sets are estimated using both the nearest source locations to each target point and the nearest target locations for each source point.
The `-invert' flag results in the inverse transformation being written to the file specified by dofout, i.e. the transformation that maps source mesh locations to the target mesh.
The `-ignoreedges' flag is used for open meshes where a subset of the edges can be defined as boundary edges. If specified, the boundary edges are identified and are not used during the registration. This flag is not appropriate for closed meshes, for example spheres or topologically equivalent structures.
The `-clean' flag results in the removal of duplicate or redundant vertices and degenerate faces from the input meshes.

sareg

top

Usage:
  sareg [target] [source] <options>

  where <options> is one or more of the following:

  <-locator>          Locator: 0 = cell locator,
                               1 = point locator, (default)
                               2 = kd-tree locator
  <-dofin name>       Name of input file
  <-dofout name>      Name of output file
  <-epsilon>          Value for espilon (default=0.01)
  <-clean>            Clean polydata (default OFF)
  <-symmetric>        Use symmetric distance (default OFF)
  <-ignoreedges>      Ignores edges in ICP (default OFF)
  <-invert>           Save the inverse transformation (default OFF)
  <-iterations>       Number of iterations (default 100)
Notes:
Run an affine surface registration for a pair of input meshes. The meshes provided need to be in VTK format. There is no restriction on the points contained in the input meshes, i.e. they do not need to be in correspondence.
During registration, however, two sets of corresponding points are estimated from the meshes by finding, for each target point, the closest location in the source surface. These point sets are then registered using a landmark-based affine registration (see pareg). The resulting transformation is then used to transform the target mesh and the process is iterated.
A stopping condition for this process is determined by the maximum number of iterations, 100 iterations are used by default but this can be varied using the `-iterations' flag.
Another stopping condition is met when `epsilon', the difference between the root-mean square error for corresponding points for successive iterations, falls below a specified value. By default, registration halts when the difference between successive iterations is less than 0.01 and the value used can be varied using the -epsilon flag.
An input transformation estimate can be specified with the `-dofin' flag and the resulting transformation estimate can be written to a file using the `-dofout' flag. An example call might be:
  sareg mesh-a.vtk mesh-b.vtk -dofin srreg-b-a.vtk -dofout sareg-b-a.vtk
The resulting transformation maps locations in the target mesh to locations in the source mesh.
By default, a point locator is used when estimating the corresponding point sets (`-locator 1') - this uses the nearest vertex in the source mesh for each target vertex. Specifying a cell locator (`-locator 0') results in the identification of the nearest source locations from within the faces (cells) of the source mesh. A kd-tree locator (`-locator 2') gives the same result as a point locator but uses a more efficient search method, which can be useful for large datasets.
If the `-symmetric' flag is used, the corresponding point sets are estimated using both the nearest source locations to each target point and the nearest target locations for each source point.
The `-invert' flag results in the inverse transformation being written to the file specified by dofout, i.e. the transformation that maps source mesh locations to the target mesh.
The `-ignoreedges' flag is used for open meshes where a subset of the edges can be defined as boundary edges. If specified, the boundary edges are identified and are not used during the registration. This flag is not appropriate for closed meshes, for example spheres or topologically equivalent structures.
The `-clean' flag results in the removal of duplicate or redundant vertices and degenerate faces from the input meshes.

snreg

top

Usage:
  snreg [target] [source] <options>

  where <options> is one or more of the following:

  <-locator>          Locator: 0 = cell locator
                               1 = point locator (default)
                               2 = kd-tree locator
  <-dofin name>       Name of input file
  <-dofout name>      Name of output file
  <-epsilon>          Value for espilon (default=0.01)
  <-symmetric>        Use symmetric distance (default OFF)
  <-ignoreedges>      Ignores edges in ICP (default OFF)
  <-iterations>       Number of iterations (default 100)
  <-ds spacing>       Control point spacing
Notes:
Run a non-rigid surface registration for a pair of input meshes. The non-rigid transformation is modelled using a free-form deformation (FFD). The meshes provided need to be in VTK format. There is no restriction on the points contained in the input meshes, i.e. they do not need to be in correspondence.
During registration, however, two sets of corresponding points are estimated from the meshes by finding, for each target point, the closest location in the source surface. These point sets are then registered using a landmark-based non-rigid registration (see pnreg). The resulting transformation is then used to transform the target mesh and the process is iterated.
A stopping condition for this process is determined by the maximum number of iterations, 100 iterations are used by default but this can be varied using the `-iterations' flag.
Another stopping condition is met when `epsilon', the difference between the root-mean square error for corresponding points for successive iterations, falls below a specified value. By default, registration halts when the difference between successive iterations is less than 0.01 and the value used can be varied using the -epsilon flag.
An input transformation estimate can be specified with the `-dofin' flag and the resulting transformation estimate can be written to a file using the `-dofout' flag. The `-ds' flag determines the control point spacing of the FFD transformation. An example call might be:
  snreg mesh-a.vtk mesh-b.vtk -dofin sareg-b-a.vtk -dofout snreg-b-a.vtk -ds 10
The resulting transformation maps locations in the target mesh to locations in the source mesh and is represented by a FFD with a 10mm control point spacing.
By default, a point locator is used when estimating the corresponding point sets (`-locator 1') - this uses the nearest vertex in the source mesh for each target vertex. Specifying a cell locator (`-locator 0') results in the identification of the nearest source locations from within the faces (cells) of the source mesh. A kd-tree locator (`-locator 2') gives the same result as a point locator but uses a more efficient search method, which can be useful for large datasets.
If the `-symmetric' flag is used, the corresponding point sets are estimated using both the nearest source locations to each target point and the nearest target locations for each source point.
The `-ignoreedges' flag is used for open meshes where a subset of the edges can be defined as boundary edges. If specified, the boundary edges are identified and are not used during the registration. This flag is not appropriate for closed meshes, for example spheres or topologically equivalent structures.

transformation

top

Usage:
  transformation [source] [output] <options>

  where <options> is one or more of the following:

  <-dofin file>      Transformation
  <-target file>     Target image
  <-Rx1 value>       Region of interest
  <-Ry1 value>       Region of interest
  <-Rz1 value>       Region of interest
  <-Rx2 value>       Region of interest
  <-Ry2 value>       Region of interest
  <-Rz2 value>       Region of interest
  <-Tx1 value>       Region of interest in target image
  <-Ty1 value>       Region of interest in target image
  <-Tz1 value>       Region of interest in target image
  <-Tx2 value>       Region of interest in target image
  <-Ty2 value>       Region of interest in target image
  <-Tz2 value>       Region of interest in target image
  <-Sx1 value>       Region of interest in source image
  <-Sy1 value>       Region of interest in source image
  <-Sz1 value>       Region of interest in source image
  <-Sx2 value>       Region of interest in source image
  <-Sy2 value>       Region of interest in source image
  <-Sz2 value>       Region of interest in source image
  <-Tp value>        Target padding value
  <-Sp value>        Source padding value
  <-invert>          Invert transformation
  <-linear>          Linear interpolation
  <-bspline>         B-spline interpolation
  <-cspline>         Cubic spline interpolation
  <-sinc>            Sinc interpolation
Notes:
Transform one image (the source) onto the voxel lattice of a second image (the target) using a transformation estimate. A typical set of command line arguments might be as follows:
  transformation a.nii.gz out.nii.gz -dofin tr-a-b.dof -target b.nii.gz -linear
In this example the image being transformed is a.nii.gz, the voxel lattice of the resulting image (out.nii.gz) will match that of the target image (b.nii.gz).
The transformation given, tr-a-b.dof, is used to transform the source intensities to the target but it should be noted that this transformation maps locations in the target image to locations in the source image. The intensity at each voxel of out.nii.gz is `pulled-back' from the corresponding source location.
If no file is given for the transformation, a default identity transformation is used. I.e. it is assumed that the target and source images share the same world coordinate system (although they need not share the same voxel lattice).
An interpolation method (`-linear' in the above example) is usually required because the source locations corresponding to target voxels may not coincide with the source voxel lattice. If no interpolation scheme is specified, nearest neighbour interpolation is used by default.
If no target image is specified, the voxel lattice of the source is used as a default.
Specifying a region of interest can be achieved by using the flags -Rx1, -Rx2, etc (replacing `R' with `T' or `S' if the region of interest is specific to the target or source images). An example could be:
  transformation a.nii.gz out.nii.gz -dofin tr-a-b.dof -target b.nii.gz -Rz1 50 -Rz2 60
In this case, the voxel lattice for out.nii.gz will contain 10 z-slices, these correspond to the ten slices in the target image starting with the 50th.
A padding value can be used to restrict the target voxel locations at which the transformation is estimated. In this case the padding value is assigned directly to the corresponding output voxels without calculating the transformation, for example:
  transformation a.nii.gz out.nii.gz -dofin tr-a-b.dof -target b.nii.gz -Tp -1 -linear
In this example, all voxels in out.nii.gz will be assigned a value of -1 where the intensity in target image (b.nii.gz) is less than or equal to -1.
The invert flag can be used if the direction of the transformation is to be reversed. For example, using the same images and transformation from the examples above:
  transformation b.nii.gz out.nii.gz -dofin tr-a-b.dof -target a.nii.gz -invert
This will transform the image b.nii.gz onto the voxel lattice of a.nii.gz.

jacobian

top

Usage:
  jacobian [input] [output] [ffd]

  where <options> is one or more of the following:

  <-total>                 Total jacobian (default)
  <-local>                 Local jacobian only
  <-global>                Global jacobian only
  <-relative>              Local jacobian divided by global Jacobian
  <-padding value>         Padding value
Notes:
Generate a map of Jacobian determinants for a given free-form deformation transformation (FFD). The Jacobian determinants can be used as a measure of the volume change induced by the transformation. These can be regions of expansion (>1), contraction (<1) and volume preservation (=1).
The transformation for which the Jacobian values are calculated is specified by the [ffd] argument. The locations at which the Jacobians are calculated are on the voxel lattice of the image specified by the [input] argument. The resulting Jacobian determinant values are written to an image specified by the [output] argument, i.e. the [input] and [output] images share the same voxel lattice.
The [input] image needs to be appropriate for the transformation. For example, if the transformation is a result of a registration step between a pair of images, then the target image used during the registration may be used as the [input] image for ffdjacobian. This is due to the transformation being defined with respect to the target voxel lattice (see nreg).
The `-padding' flag can be used to restrict the number of voxels over which the calculations are carried out. For example, if the image a.nii.gz has a value of -1 for all voxels outside a region of interest, then a typical call might be:
  ffdjacobian a.nii.gz jac-ffd-b-a.nii.gz ffd-b-a.nii.gz -padding -1
where ffd-b-a.nii.gz represents the result of non-rigidly registering a source image b.nii.gz to the target image a.nii.gz.
By default, the total Jacobian is calculated for the FFD, this represents the volume change induced by both the global affine component and the local non-rigid component of the FFD transformation. The global and local Jacobian determinants can be obtained separately by using the `-global' and `-local' flags respectively. The `-relative' flag produces estimates of the local Jacobian expressed as a fraction of the global Jacobian.

atlas

top

Usage:
  atlas [output] [input1..inputN] <options>

  where <options> is one or more of the following:
  <-scale factor>  Scaling factor (0 means no normalisation)
Notes:
Generate an atlas image based on averaging a set of input images.
The averaging is carried out on a per-voxel basis so the input images need to occupy the same voxel lattice. One way to achieve this is through a set of registration and transformation steps.
For example, if images a.nii.gz, b.nii.gz, c.nii.gz are to be atlased in the space of a target or reference image r.nii.gz, the process might be started with an affine registration step:
  areg r.nii.gz a.nii.gz -dofout areg-a-r.dof
  areg r.nii.gz b.nii.gz -dofout areg-b-r.dof
  areg r.nii.gz c.nii.gz -dofout areg-c-r.dof
the source images can then be transformed so that they are resampled onto the lattice of the reference image:
  transformation a.nii.gz tr-a.nii.gz -dofin areg-a-r.dof -target r.nii.gz
  transformation b.nii.gz tr-b.nii.gz -dofin areg-b-r.dof -target r.nii.gz
  transformation c.nii.gz tr-c.nii.gz -dofin areg-c-r.dof -target r.nii.gz
now the transformed images may be averaged to produce an atlas:
  atlas atlas-abc.nii.gz tr-a.nii.gz tr-b.nii.gz tr-c.nii.gz
If many images are to be averaged then it is possible to use the `*' symbol as a wild card if they share the same name format, e.g.:
  atlas atlas-many-images.nii.gz tr-*.nii.gz
The `-scale' flag allows for variations in the intensity ranges of the input images to be accommodated. If it used to specify a factor, then, prior to averaging, each image's intensities are linearly scaled to have mean zero and standard deviation one. After averaging, the resulting values are multiplied by the factor specified with the `-scale' flag.

dof2flirt

top

Usage:
  dof2flirt [dofin] [target] [source] [matrix_out.raw] <options>
  where <options> can be one or more of the following:
  <-info>           Print transformation info
  <-print>          Print matrix to screen
Notes:
Convert a transformation (.dof) file to the FSL flirt format. The flirt format is represented by a matrix that transforms target world locations (measured in mm) to source world locations. The format assumes that the origin of each image is represented by the centre of the voxel with lattice index (0,0,0). This means that, as well as the transformation file to be converted, [dofin], the target and source images also need to be given in the argument list. The resulting matrix is written out to [matrix_out.raw].

dof2image

top

Usage:
  dof2image [image] [dof] [dx] [dy] [dz]
Notes:
Calculate the x, y and z components of the displacements of the transformation represented by [dof]. These displacements are calculated at the voxel locations of the input [image]. The components of resulting displacements are written to three separate images with names specified by the arguments [dx], [dy] and [dz].

dof2mat

top

Usage:
  dof2mat [doffile] [-matout matrixfile] [-invert]
Notes:
Convert a transformation represented by the file [doffile] to the IRTK project matrix format. The output is represented a homogeneous transformation matrix. E.g.:
  dof2mat areg-a-b.dof -matout areg-a-b.mat
If the '-matout' argument is not used, the homogeneous matrix is written to standard out.
If the '-invert' is used, the transformation is inverted prior to conversion.

dofinvert

top

Usage:
  dofinvert [dofin] [dofout]
Notes:
Invert an affine transformation, [dofin], and write the result to [dofout].

flirt2dof

top

Usage:
  flirt2dof [matrix_in.raw] [target] [source] [dofout] <options>
Notes:
Convert a transformation from the FSL flirt format to DOF format. The flirt format is represented by a matrix that transforms target world locations (measured in mm) to source world locations. The format assumes that the origin of each image is represented by the centre of the voxel with lattice index (0,0,0). This means that, as well as the transformation file to be converted, [matrix_in.raw], the target and source images also need to be given in the argument list. The resulting DOF file is written out to [dofout].

info

top

Usage:
  info [image] [-real] [-grey] [-byte]
Notes:
Returns general information about an image, most of this information is obtained from the image header. The flags are used to control how the voxel intensity data are interpreted: `-real' treats the data as floating point values, `-grey' treats them as 2 byte integers and `-byte' treats them as single byte integers.
The fields returned by info include the following:
The NIFTI format also has the following additional fields:

convert

top

Usage:
  convert [in] [out] <options>

     where <options can be one or more of the following:
         <-real|-grey|-byte>       Output voxel type
         <-minmax value value>     Output min and max intensity
     The following input formats are supported:
         .pgm
         generic 2D/3D byte, short, float
         .rrep .gipl .vtk .unc
     The following output formats are supported:
         .gipl .vtk .unc .nii .gipl.gz .nii.gz
Notes:
`convert' allows images to be converted between different formats. E.g.
  convert old.hdr new.nii
converts an Analyze image to a NIFTI image. It is possible to compress the output image in the same step by appending a `gz' suffix:
  convert old.hdr new.nii.gz
The output data type can be set by the appropriate flags, e.g. a binary mask image using integer shorts can be converted to byte format by:
  convert mask.nii.gz byteMask.nii.gz -byte
If floating point calculations are to be applied, an image can be converted to this format by:
  convert image.nii.gz image.nii.gz -real
In this example, the output image over-writes the input image.
Note that formats consisting of a single file e.g. gipl or NIFTI, can have a `gz' suffix when used as input or output. Images in Analyze format have separate header and data files (`hdr' and `img'). When setting an Analyze image as output (deprecated), it is not possible to compress the data (`.img') file in the same step.

threshold

top

Usage:
  threshold [input] [output] [threshold]
Notes:
Generate a binary image based on thresholding the intensities of the input image. E.g.
  threshold input.nii.gz output.nii.gz 50
means output.nii.gz will have a value of one for all voxels where input.nii.gz is greater than 50. All other voxels in input will have an intensity of zero.
This command interprets input data and writes output data as two byte integers.

binarize

top

Usage:
  binarize [in] [out] [threshold] [value1] [value2]
Notes:
Generate a binary image based on thresholding the intensities of the input image. This performs a similar function to the `threshold' application except that the output image will have user set values instead of zero and one. E.g.
  binarize input.nii.gz output.nii.gz  0  -10  10
will create output.nii.gz that has a value of ten for all voxels where the corresponding input intensity is positive and a value of -10 for all other voxels.

mcubes

top

Usage:
  mcubes [image] [polydata] [threshold] <options>

  where options can be selected from the following:

  <-decimate>
  <-smooth>
  <-normals on|off>
  <-gradients on|off>
  <-blur sigma>
  <-isotropic>
  <-size x y z>
  <-ascii>
Notes:
Apply the marching cubes algorithm to an image in order to produce a mesh representation. The mesh represents a selected iso-intensity surface within the image and is produced in VTK format.
A typical application for mcubes may be to generate a mesh representation for a structure given a binary (0/1) mask for the structure. For example:
  mcubes mask.nii.gz surf.vtk 0.5 
generates a surface based that estimates the 0.5 iso-surface within the image.
If a discrete binary image is used, the resulting mesh may contain a significant number of irregularities. A smoother result may be required and this can be achieved using either of the `-blur' or `-smooth' flags.
If the `-blur' flag is specified, the input image is first blurred using a Gaussian kernel with a standard deviation given after the flag, e.g.:
  mcubes mask.nii.gz surf.vtk 0.5 -blur 1
The iso-surface is estimated after the blurring step.
If the `-smooth' flag is used, the mesh is smoothed directly after it has been generated by the marching cubes algorithm.
By default, the normal vectors at each vertex location in the mesh are calculated and included in the output file. This can be set explicitly by using `-normals on' at the command line or prevented by using `-normals off'.
Selection of whether the gradient of the input image is associated with the vertex in the mesh can be controlled by using `-gradient on' or `-gradient off' at the command line. By default these are not included in the output.
If the input image contains anisotropic voxels, it is possible to resample it prior to extracting the surface using the `-isotropic' flag. The voxel dimensions of the resulting image will correspond to the minimum dimension of the input image voxels. It is possible to separately specify the voxel dimensions at the resampling stage by using the `-size' option followed by three numbers representing the voxel size in mm.
By default, the output is written in VTK binary format. This can be overridden by using the `-ascii' flag.

padding

top

Usage:
  padding [imageA] [mask] [output] [maskPaddingValue] [outputPaddingValue]
Notes:
Pads a region in an image with a chosen value. This can be done to restrict the region of interest within the image to the unpadded voxels. For example if scan.nii.gz represents a head scan for a subject and brainMask.nii.gz represents a binary mask for the brain (with a value of one for brain and zero elsewhere), then
  padding scan.nii.gz brainMask.nii.gz scan_pad.nii.gz 0 -1
generates the image scan_pad.nii.gz which is identical to scan.nii.gz within the brain region but has a value of -1 outside the brain.

blur

top

Usage:
  blur [in] [out] [sigma]
Notes:
Apply Gaussian blurring to input image [in] and write the result to output image [out]. The standard deviation of the kernel used to blur the image is given by the [sigma] parameter which is measured in mm. Higher values of sigma result in a higher degree of blurring. An example:
  blur a.nii.gz a-blur.nii.gz 2

dilation

top

Usage:
  dilation [in] [out] <options>
  Where <options> are one or more of the following:
	  <-iterations n>    Number of iterations
Notes:
Apply the morphological dilation operator to the input image and write the result to an output image. For example, if in.nii.gz represents a binary image where background is zero and foreground is one, then the call
  dilation in.nii.gz out.nii.gz
produces out.nii.gz which contains an enlarged set of input foreground voxels. The dilation operator converts to foreground any background voxels that were adjacent to a foreground voxel. Adjacency in this case means within the 26-neighbourhood for 3-D images and within the 8-neighbourhood for 2-D images.
Repeated dilations can be achieved by using the -iterations flag.
The operator can also be applied to grey-level images (non-binary) but the effect is beyond the scope of these notes.

erosion

top

Usage:
  erosion [in] [out] <options>
  Where <options> are one or more of the following:
	  <-iterations n>    Number of iterations
Notes:
Apply the morphological erosion operator to the input image and write the result to an output image. For example, if in.nii.gz represents a binary image where background is zero and foreground is one, then the call
  erosion in.nii.gz out.nii.gz
produces out.nii.gz which contains a reduced set of input foreground voxels. The erosion operator converts to background any foreground voxels that were adjacent to a background voxel. Adjacency in this case means within the 26-neighbourhood for 3-D images and within the 8-neighbourhood for 2-D images.
Repeated erosions can be achieved by using the -iterations flag.
The operator can also be applied to grey-level images (non-binary) but the effect is beyond the scope of these notes.

closing

top

Usage:
  closing [in] [out] <options>
  Where <options> are one or more of the following:
	  <-iterations n>    Number of iterations
Notes:
Produces the result of applying a dilation operator followed by an erosion operator to the image. When applied to a binary image this tends to remove small `holes' within the foreground voxels.
See notes on `erosion' and `dilation'.

opening

top

Usage:
  opening [in] [out] <options>
  Where <options> are one or more of the following:
	  <-iterations n>    Number of iterations
Notes:
Produces the result of applying an erosion operator followed by a dilation operator to the image. When applied to a binary image this tends to remove small regions of foreground voxels.
See notes on `erosion and `dilation'.

reflect

top

Usage:
  reflect [in] [out] [-x/-y/-z]
Notes:
Reflects the image data matrix along the specified axis:
  reflect first.nii.gz second.nii.gz -y
Will result in two images with image data related by a reflection in the y = 0 plane (x-z plane).
This command interprets input data and writes output data as two byte integers.

region

top

Usage:
  region [in] [out] <-Rx1 x1> <-Ry1 y1> <-Rz1 z1> <-Rx2 x2> <-Ry2 y2> <-Rz2 z2>
Notes:
Extract a region from input image [in] and write the result to output image [out]. The bounds for x are given by the optional parameters -Rx1 and -Rx2, with the bounds for y and z similarly defined. The bounds specify a region with respect to the voxel lattice (or image coordinates) of the input image. Indices for the voxel lattice are indexed from zero. The following example:
  region a.nii.gz a-crop.nii.gz -Ry1 20 -Ry2 50
will generate an image formed by taking 30 slices perpendicular to the y-dimension from the input voxel lattice, starting with the slice at index 20 (i.e. the 21st slice). The bounds for x and z are unspecified in this example, which results in an output image with the same x and z dimensions as the input image.

resample

top

Usage:
  resample [in] [out] <options>
  Where <options> are one or more of the following:
         <-size x y z>      New voxel size in mm (default: 1 1 1)
         <-linear>          Linear interpolation
         <-bspline>         B-spline interpolation
         <-cspline>         Cubic spline interpolation
         <-sinc>            Truncated sinc interpolation
         <-padding value>   Background padding (default: MIN_SHRT)
                            Only linear interpolation for padding!
Notes:
Create a new image with a different voxel spacing. The fields of view for the input and output images are the same. The difference between the voxel spacings on the new and old voxel lattices means that an interpolation scheme is required as the new image's voxels are unlikely to coincide with those in the old image.
For example, if input.nii.gz is an image with isotropic 2mm voxels,
  resample input.nii.gz output.nii.gz -size 3 3 3 -bspline
applies B-Spline based interpolation to the data in input.nii.gz to generate a new image with 3mm isotropically spaced voxels.
  resample input.nii.gz output.nii.gz -size 3 3 3 -bspline -padding 0
applies B-Spline interpolation only in regions where the intensity is greater than zero. Less computationally expensive linear interpolation is used elsewhere.
This command interprets input data and writes output data as two byte integers.

rescale

top

Usage:
  rescale [in] [out] [min] [max]
Notes:
The intensities in the input image are multiplied and a shift is added so that the new minimum and maximum values match those given on the command line.
This command interprets input data and writes output data as two byte integers.