alignlinear


Purpose:

This is a general linear intramodality registration tool (within or across subjects, 2D or 3D). The user can specify any of a variety of models, including rigid-body, affine, or perspective.

The program will generate a .air file that can be used to reslice the specified reslice data set to match the specified standard data set.


Usage:

alignlinear standard-file reslice-file air-out -m model-menu-number [options]

Model Menu:

3-D models:
6. rigid body 6 parameter model
7. global rescale 7 parameter model
9. traditional 9 parameter model (std must be on AC-PC line)
12. affine 12 parameter model
15. perspective 15 parameter model
2-D models (constrained to in-plane, no interpolation):
23. 2-D rigid body 3 parameter model
24. 2-D global rescale 4 parameter model
25. 2-D affine/fixed determinant 5 parameter model
26. 2-D affine 6 parameter model
28. 2-D perspective 8 parameter model AIR 5.0

options:

[-b1 FWHM_x FWHM_y FWHM_z] (standard file)
smooths standard-file
[-b2 FWHM_x FWHM_y FWHM_z] (reslice file)
smooths reslice-file
[-c convergence-threshold]
changes default convergence threshold
[-d] AIR 5.0
forces use of static partitioning, reverting to default behavior of AIR 3.0x
[-e1 mask]
masks standard-file
[-e2 mask]
masks reslice-file
[-f initialization-file]
changes default spatial initialization
[-fs scaling-initialization-file]
changes default intensity initialization
[-g termination-file [overwrite?(y/n)]]
saves final parameters as ASCII file
[-gs scaling-termination-file [overwrite?(y/n)]]
saves final intensity scaling parameter
[-h halt-after-(N)-iterations-without-improvement]
changes default iterations without improvement
[-j] AIR 5.0
uses currently unvalidated method for overcoming non-positive definite Hessian matrices
[-p1 partitions]
segments standard-file into designated number of partitions
[-p2 partitions]
segments reslice-file into designated number of partitions
[-q]
assumes non-interaction of spatial parameter derivatives (reduces likelihood of non-positive definite Hessian matrices)
[-r repeated-iterations]
changes default repeated interations
[-s initial-sampling final-sampling sampling-decrement-ratio]
changes default sampling
[-t1 threshold]
changes default threshold for standard-file
[-t2 threshold]
changes default threshold for reslice-file
[-v]
enables verbose reporting of interim results
[-w ...] AIR 5.0
deprecated and no longer supported since .air files can be used directly for initialization of align_warp
[-x cost-function]
cost function from the menu:
  1. standard deviation of ratio image
  2. least squares
  3. least squares with intensity rescaling
[-z]
turns on pre-alignment interpolation to cubic voxels
where the following definitions apply:
air-out [mandatory]
the exact name of the .air transformation parameter output file (cannot contain '.img' or '.hdr').
convergence-threshold [-c]
controls how small the predicted change in the cost function must be in order to meet the convergence criteria. Setting this value too large will result in convergence while the images are still misregistered; setting it too small may lead to a failure to converge.
cost-function [-x]
the number of the cost function selected from the following menu:
1. Standard deviation of ratio images cost function
This cost function has the advantage of being independent of image intensity, so image intensities can be poorly matched and the registration will not be adversely affected. This is the only model that allows multiple partitions as required for intermodality registration.
2. Least squares cost function
This cost function assumes that the image intensities are scaled identically. Least squares is computationally simpler and therefore faster than the standard deviation of ratio images, but may be inaccurate if the image intensities are poorly matched.
3. Least squares with global rescaling cost function
This cost function is identical to the least squares cost function except that an intensity scaling term is added to the model.
final-sampling [-s ...]
controls how densely data is sampled during the final iterative cycle of the algorithm. If your data is oversampled, the time spent sampling very densely may not provide any significant improvement in accuracy. Iterations will cease if the new sampling density is less than the final_sampling density specified here. The final sampling will be even more sparse than indicated by this value if the initial-sampling divided repeatedly by the sampling-decrement-ratio does not give a value equal to this number.
FWHM-x FWHM-y FWHM-z [-b1] [-b2]
if this option is used, smoothing filters are applied along the x, y and z axes of the standard file (-b1) or reslice file (-b2) before performing registration. The FWHM value specifies the full width at half maximum of the Gaussian smoothing filter to be applied along each dimension. The filters have units of millimeters (or whatever units you use to specify voxel sizes in your .hdr files). All three dimensions must be specified. If you give a value of zero, no smoothing will be applied along the corresponding dimension.
halt-after-(N)-iterations-without-improvement [-h]
controls the maximum number of iterations without any observed improvement in the cost function. If greater than or equal to repeated-iterations, this value has no effect. At lower values, it can help you escape from situations where you are bouncing back and forth between two or three locations in parameter space without making any real progress. This sort of thing usually only happens at superficial sampling densities.
initial-sampling [-s ...]
controls how densely data is sampled during the first iterative cycle of the algorithm for each order of polynomial. Large values generally speed up the registration process because gross misregistration can be detected with fairly superficial sampling of the data. However, choosing an excessively large value can be counterproductive if the algorithm falls into an infinite loop or is led far from the true value by nonrepresentative sampling.
initialization-file [-f]
the name of an ASCII file containing spatial transformation initialization parameters. These parameters can be used to control the starting position for automated registration, a feature that is useful if the initial misregistration is extreme (e.g., > 45° of rotational misregistration) or if the default registration leads to an obviously incorrect result. The format for the rigid-body initialization file is discussed under file types. Rigid-body initialization files are created most easily using the program manualreslice. Different spatial models require different numbers and types of parameters in the initialization file. Note that some cost functions may also allow an intensity parameter initialization file.
mask [-e1] [-e2]
this file is applied to the standard file (-e1) or reslice file (-e2) as a mask. The file must match the corresponding file's dimensions, and voxels that are zero in this file will be treated as if they were zero in the corresponding file when computing the cost function. Mask files can be binary or regular files.
model-menu-number [mandatory]
the number of the spatial transformation model selected from the following menu:
  • 3D models
    6. rigid-body 6 parameter model
    used for intrasubject registration when all voxel sizes are accurately known
    7. global rescaling 7 parameter model
    provides the so-called 'Procrustes' fit used in some morphometric contexts
    9. traditional 9 parameter model (standard must be on AC-PC line)
    the usual 9 parameter implementation of the Talairach model, not to be confused with the formal 13 parameter transformation originally described by Talairach and colleagues
    12. affine 12 parameter model
    generally the recommended model for intersubject registration (the resulting .air file can also be used to initialize polynomial warping with align_warp) or for intrasubject registration when voxel sizes are uncertain
    15. perspective 15 parameter model
    provides perspective deformation that allows parallel lines to intersect
  • 2D models
    23. 2D rigid-body 3 parameter model
    analogous to the 6 parameter 3D model
    24. 2D global rescale 4 parameter model
    analogous to the 7 parameter 3D model
    25. 2D affine/fixed determinant 5 parameter model
    allows for linear non-rigid distortions that preserve total area; potentially useful for data from serial tissue sections
    26. 2D affine 6 parameter model
    analogous to the 12 parameter 3D model
    28. 2D perspective 8 parameter model
    analogous to the 3D 15 parameter model; appropriate for photographs with perspective distortions AIR 5.0
overwrite?(y/n) [-g ...] [-gs ...]
'y' allows any preexisting file with the same name as the argument it follows (termination-file or scaling-termination-file ) to be overwritten.
partitions [-p1] [-p2]
defines the number of partitions used for segmenting the standard file in the forward direction (-p1) or for segmenting the reslice file in the reverse direction (-p2) when using the standard deviation of the ratio image as a cost function. If this value is zero, no forward direction (-p1 0) or reverse direction (-p2 0) computation is performed. A value of 256 is typically used for intermodality registration when the corresponding file is an MRI study. For MRI-PET registration, the number of partitions corresponding to the PET study should be set to zero. When registering two dissimilar MR images, both data sets can be assigned 256 partitions. For intramodality registration, the default value of 1 is appropriate.
only the ratio image cost function allows more than one partition
AIR 5.0Note that AIR now uses dynamic partitioning by default. Instead of dividing the theoretical range of voxel intensities into the designated number of partitions, the actual range of voxel intensities is divided into this number of partitions. This assures that when the dynamic range of the data is restricted, the voxels do not all end up occupying far fewer partitions than requested. The -d flag forces the use of static partitioning as in AIR 3.0x.
repeated-iterations [-r]
controls the maximum number of iterations permitted at each sampling density. If this number is made too low, it will lead to inaccurate results and/or slow down the overall performance of the algorithm by preventing you from making use of information that could have been derived more quickly at the prematurely aborted, more superficial sampling.
reslice-file [mandatory]
the name of the file you want registered to the standard-file (.img or .hdr suffix optional)
sampling-decrement-ratio [-s ...]
determines the number of intermediate iterative cycles of the algorithm. The current sampling is divided by this ratio with each cycle to determine the new sampling.
scaling-initialization-file[-fs]
the name of an ASCII file containing a single parameter that initializes intensity scaling
scaling-termination-file [-gs]
the name of an ASCII file to be created containing the intensity scaling parameter identified as optimal by the algorithm. Combined with a spatial transformation initialization file, this parameter can be used to restart the algorithm at the same location in parameter space where it left off. In addition, the scaling parameter can be used as an intensity normalization factor for subsequent statistical analysis of the registered data or as input to reslice to create a final image that is intensity corrected as well as spatially corrrected.
standard-file [mandatory]
the name of the file that you want the other file resliced to match (.img or .hdr suffix optional).
termination-file [-g]
the name of an ASCII file to be created containing spatial transformation termination parameters. These parameters can then be used as initialization parameters to restart the algorithm at the same location in parameter space where it left off (using the same spatial model). This allows you to switch cost functions or to vary smoothing, among other things. Different spatial models create incompatible files. Note that some cost functions may also allow an intensity parameter termination file.
threshold [-t1] [-t2]
defines a minimum voxel value for the standard file (-t1) or reslice file (-t2). Voxels in the corresponding file with intensities below this value are excluded from analysis when computing the cost function and its derivatives. The value should always be an integer less than the maximum voxel value in the corresponding file.

Examples:

alignlinear pet1 pet2 pet2.airpet1 -m 6 -t1 55 -t2 55 -x 1 -r 8 -c 0.0 -h 8 -a 8

Comments:


Error messages: (alphabetical by case)

See also: Generic error messages
-b1 must be followed by three non-negative numbers
-b2 must be followed by three non-negative numbers
-c must be followed by a positive number
-h must be followed by a non-negative integer
-m must be followed by a spatial transformation model from the menu
-p1 must be followed by an unsigned integer
-p2 must be followed by an unsigned integer
-r must be followed by an unsigned integer
-s must be followed by three positive integers
-t1 must be followed by an integer
-t2 must be followed by an integer
-x must be followed by a valid cost function number from the menu
A scaling initialization file (____) can only be used with the scaled least squares cost function (-x 3)
A scaling termination file (____) can only be created with the scaled least squares cost function (-x 3)
A termination parameter file name must follow -g or -gs
An image file name must follow -e1 or -e2
An initialization parameter file name must follow -f or -fs
Cannot have two output files with the name: ____
Either the standard file or the reslice file must have at least 1 partition
Final sampling (2nd argument after -s) cannot be larger than initial sampling (1st argument after -s)
Name of output .air file cannot contain .hdr or .img
Only the ratio image uniformity cost function allows use of more than one partition per file
Sampling decrement ratio (3rd argument after -s) must be larger than 1
Unable to parse ____
Unable to parse argument ____, which was expected to begin with a '-'
You must specify a spatial transformation model using the -m argument

See also:


Modified: July 21, 2002
© 2001-2002   Roger P. Woods, M.D.(rwoods@ucla.edu)