alignlinear

• purpose
• usage
• examples
• comments
• error messages
• see also

Purpose:

Usage:

• 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

options:

• [-t1 threshold-standard-file ]
• [-t2 threshold-reslice-file ]
• [-b1 FWHM-x FWHM-y FWHM-z] (standard file)
• [-b2 FWHM-x FWHM-y FWHM-z] (reslice file)
• [-p1 partitions_in_standard_file]
• [-p2 partitions_in_reslice_file]
• [-f initialization-file]
• [-f initialization-file]
• [-g termination-file [overwrite?(y/n)]]
• [-s initial-sampling final-sampling sampling-decrement-ratio ]
• [-c convergence-threshold ]
• [-r repeated-iterations ]
• [-h halt-after-(N)-iterations-without-improvement]
• [-a alternate-strategy-after-(M)-iterations-without-improvement]
• [-z] enable pre-alignment interpolation
• [-v] enable verbose mode
• [-x cost-function]

  Cost functions:

  • 1. standard deviation of ratio image
  • 2. least squares

where the following definitions apply:

standard-file

the name of the file that you want the other file resliced to match (.img or .hdr suffix optional)

reslice-file

the name of the file you want to reslice (.img or .hdr suffix optional)

air-out

the exact name of the output file (cannot contain '.img' or '.hdr' and will not be modified by the program).

threshold-standard-file

defines a minimum voxel value for the standard file. Voxels in the standard file below this value are excluded from analysis when computing the cost function and its derivatives in the forward direction. The value should always be an integer less than the maximum possible voxel value.

threshold-reslice-file

defines a minimum voxel value for the reslice file. Voxels in the reslice file below this value are excluded from analysis when computing the cost function and its derivatives in the reverse direction. The value should always be an integer less than the maximum possible voxel value.

partitions-in-standard-file

defines the number of partitions used for segmenting the standard file when computing the standard deviation of the ratio image in the forward direction. If this value is less than 1, no forward direction computation is performed. A value of 256 is typically used for intermodality registration if the standard file is an MRI study. A value of zero is typically used for intermodality registration if the standard file is a PET study. For intramodality registration, the default value of 1 is appropriate.

partitions-in-reslice-file

defines the number of partitions used for segmenting the standard file when computing the standard deviation of the ratio image in the reverse direction. If this value is less than 1, no reverse direction computation is performed. A value of 256 is typically used for intermodality registration if the reslice file is an MRI study. A value of zero is typically used for intermodality registration if the reslice file is a PET study. For intramodality registration, the default value of 1 is appropriate.

FWHM-x FWHM-y FWHM-z (standard-file)

if this option is used, smoothing filters are applied along the x, y and z axes of the standard file 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.

FWHM-x FWHM-y FWHM-z (reslice-file)

if this option is used, smoothing filters are applied along the x, y and z axes of the reslice file 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.

initialization-file

the name of an ASCII file containing 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°ree; 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.

termination-file

the name of an ASCII file to be created containing 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.

overwrite?(y/n)

'y' if you want any preexisting file with the same name as your termination file to be overwritten.

initial-sampling

controls how densely data is sampled during the first iterative cycle of the algorithm. 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. Avoid multiples of two when choosing sampling parameters. If any of your matrix dimensions are divisible by two, the sampling will become spatially biased until the sampling density reaches one, at which point the algorithm will have to iteratively overcome the earlier bias at the maximal sampling density. If your matrix dimensions are divisible by three, you will have a similar problem with sampling densities that are multiples of three.

final-sampling

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. In such cases, you may want to choose a final_sampling that is greater than one. Iterations will cease if the new sampling density is less than the final_sampling density specified here.

sampling-decrement-ratio

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.

convergence-threshold

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.

repeated-iterations

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.

halt-after-(N)-iterations-without-improvement

controls the maximum number of iterations without any observed improvement in the cost function. If greater than or equal to the "repeated_iterations" variable above, 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.

alternate-strategy-after-(M)-iterations-without-improvement

similar to the preceeding option except that it does not force termination of the current sampling density, but rather tries to split the difference between the locations in parameter space at the current sampling. If greater than or equal to the "halt-after-(N)-iterations-without-improvement" or the "repeated-interations" variables above, this value has no effect.

pre-alignment interpolation

in contrast to AIR 1.0, this new algorithm in AIR 2.0 does not apply prealignment interpolation of the files to cubic voxels by default. If you want prealignment interpolation, it can be enabled using this flag. Using prealignment interpolation will slow down the algorithm if you have thick slices, but may result in a more robust algorithm. If your voxels are already cubic, prealignment interpolation has no effect.

verbose mode

information about every iteration will be printed to the screen if you use the -v option. If you run a lot of registrations and leave screen scrolling enabled with this option, you will eventually fill up the disk and the system will grind to a halt.

cost-function

determines which cost function is used for aligning the images. This should be a number from the corresponding menu:

1. standard deviation of ratio images

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 effected.

2. least squares

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.

menu-model

specifies the spatial model to be used to align the images. This should be a number from the corresponding menu:

6. rigid body 6 parameter model

Used for intra-subject registration when all voxel sizes are known accurately

7. global rescale 7 parameter model

Not too useful for biological data

9. traditional 9 parameter model (std must be on AC-PC line)

This is the typical (as opposed to literal) Talairach model, provided that the standard file has been properly oriented using the Talairach rules.

12. affine 12 parameter model

This is the preferred model for intersubject registration

15. perspective 15 parameter model

The perspective distortions are probably not worth the extra computational cost in most cases.

23. 2-D rigid body 3 parameter model

Analogous to the 6 parameter 3D model

24. 2-D global rescale 4 parameter model

Analogous to the 7 parameter 3D model. Might be useful for aligning photos of distant objects taken from various distances.

25. 2-D affine/fixed determinant 5 parameter model

This model allows for nonrigid distortion so long as total area is preserved. This may be a useful model for realigning data from serial tissue sections.

26. 2-D affine 6 parameter model

Analogous to the 12 parameter 3D model.

Examples:

• This will derive a .air file for aligning PET study pet2 to match PET study pet1. Thresholds of 55 will be set for each study, the standard deviation of ratio images cost function will be employed, a six parameter spatial model will be used and the algorithm will stop after eight iterations at each sampling density (using the default samplings of 81, 27, 9, 3, and 1). The total number of iterations will be the only applicable stopping criteria since the -h and -a flags have been effectively disabled by setting them equal to the -r flag and the -c flag has been disabled by setting it to zero.

Comments:

• The most common problem with the use of this algorithm is inappropriate selection of the thresholds. If you are using an eight bit version of AIR, a PET data threshold around 55 works well. For MRI data, a threshold around 10 is often but not always appropriate. For a sixteen bit verson of AIR, a PET threshold around 14000 may be about right if the image uses the full dynamic range, but a proportionately lower threshold will be needed if only part of the range is utilized. MRI data often only uses 12 of the available 16 bits, so appropriate values typically will be in the 160-2560 range for 16 bit versions of AIR. It is best to look at the images to pick a threshold that excludes nonbrain regions.
• When choosing a spatial model, do not assume that more is better. While you can use a 15 parameter model to perform intrasubject registration, the results will be slower. Furthermore, unless there truly is some element of nonrigid-body distortion of the images, the extra parameters that you derive will be errors. If you know that your scanner systematically introduces some sort of linear distortion, the best approach would be to understand the distortion and systematically remove it before registration. However, if this is not practical, use of a model with more freedom does represent a reasonable alternative.

Error messages: (alphabetical by case)

A positive decimal number must follow -c

• self explanatory

A positive integer must follow -a

• self explanatory

A positive integer must follow -h

• self explanatory

A positive integer must follow -r

• self explanatory

A termination file name must follow -g

• you must supply a valid file name after this argument

A valid cost function number from the menu must follow -x

• you must supply one of the cost function integers listed in the menu

A valid model number from the menu must follow -m

• you must supply one of the model integers listed in the menu

An initialization parameter file name must follow -f

• you must supply the name of a valid initialization file after this argument

An integer must follow -t1 or -t2

• self explanatory

Argument after -a cannot start with - ; it must be a positive integer

• self explanatory

Argument after -c cannot start with - ; it must be a positive decimal number

• self explanatory

Argument after -f cannot start with - ; it must be an initialization parameter file name

• you must supply the name of a valid initialization file after -f

Argument after -g cannot start with -; it must be a termination file name

• you must supply a valid name for a termination file

Argument after -h cannot start with - ; it must be a positive integer

• self explanatory

Argument after -m cannot start with - ; it must be a valid model number from the menu

• self explanatory

Argument after -r cannot start with - ; it must be a positive integer

• self explanatory

Argument after -x cannot start with -; it must be a valid cost function number from the menu

• self explanatory

Attempt to save .air file ____ failed.

• The .air file could not be saved. Do you have write permission on the disk? Is the disk full?

Failure in smoothing routine

• The smoothing routine ran out of RAM. Try smoothing the file externally using gsmooth and then run this program on the smoothed result without the -b option.

File '____' exists, no permission to overwrite

• You have not granted overwrite permission for the termination file that follows the -g flag and a file already exists with the name that you have specified. If you want to give overwrite permission, add 'y' after the file name in the command line.

First three arguments cannot begin with a -

• Self explanatory

Name of output .air file cannot contain ____ or ____

• This protects you from accidentally overwriting image data with a .air file. Choose a new name that does not contain the specified suffixes.

Name of termination file cannot contain ____ or ____

• This protects you from accidentally overwriting image data with a termination file. Choose a new name that does not contain the specified suffixes.

Sorry, flag -____ is not defined for this program

• You have specified a flag that is not defined. Review the defined flags and respecify.

Sorry, model ____ is not defined

• The spatial model you have selected does not exist. Review the menu of implemented models.

Sorry, you have selected an unimplemented model for this cost function, please try again

• The spatial model you have requested is not implemented for all cost functions. Choose an alternative model or cost function.

Sorry, you have selected an unimplemented model, please try again

• The spatial model you have selected does not exist. Review the menu of implemented models.

Standard (____) and reslice (____) files both have only a single plane of data. You must use a 2D model in this situation

• Select a 2D model (all 2D model numbers start with the digit '2').

Standard file (____) has ____ planes and reslice file (____) has ____ planes

• For 2D models, you must have an identical number of planes in the two image sets being registered. Data from any given plane of the reslice file is always mapped to data on the corresponding plane of the standard file.

The initialization file only provided ____ parameters, 12 parameters are required for the affine model (up to 16 parameters can be specified, but parameters 13-16 must be 0 0 0 1

• You can review and modify the initialization file with your favorite text editor.

The initialization file only provided ____ parameters, 15 parameters are required for the perspective model (up to 16 parameters can be specified

• You can review and modify the initialization file with your favorite text editor.

The initialization file only provided ____ parameters, ____ are required for this model

• You can review and modify the initialization file with your favorite text editor.

The initialization file only provided ____ parameters, ____ are required for this model

• You can review and modify the initialization file with your favorite text editor.

The number of planes in the standard and reslice files must be identical for 2D alignment models

• Self explanatory.

The sixteenth parameter for the perspective model must be non-zero

• You can review and modify the initialization file with your favorite text editor.

Three arguments that follow -s cannot start with - ; they must be positive integers

• Self-explanatory

Three integers must follow -s

• Self-explanatory

Three positive numbers must follow -b1 or -b2

• Self-explanatory

WARNING: File '____' will be overwritten by the output of this program

• Type control-C immediately to abort program if you don't want to overwrite this file

WARNING: The initialization file contained more parameters (____) than required (____)

• You can review and modify the initialization file with your favorite text editor.

WARNING: the voxel z_size differs for the two files that you are aligning using a 2D in-plane model

• The registration may run without problem, but the resulting .air file may generate subsequent difficulties.

When the initialization file specifies >12 parameters for the affine model, parameters 13-16 must be 0 0 0 1

• self-explanatory

You have requested an unimplemented cost function

• Choose a diffent cost function from the menu

You must use a 2D model in this situation

• Choose a 2D model from the menu.

final_sampling (2nd argument after -s) cannot be > initial_sampling (1st argument after -s)

• respecify arguments accordingly

sampling_decrement_ratio (3rd argument after -s) must be > 1

• respecify argument accordingly

threshold ____ is not in range of possible pixel values

• Choose a value less than 255 if you are using 8 bits/pixel on a SPARCstation

unable to create termination file '____'

• Do you have write permission and free space in the specified directory?

unable to open initialization file '____'

• Check to see that the file exists and that you have read permission

unable to parse arguments,argument ____ was expected to begin with a -

• review command line looking for an extra argument.

See also:

• alignpettomri
• alignpettopet
• alignmritopet
• reslice