warp_reslice - Applies deformation field and linear transformation

1997 Ulrik Kjems, DSP/IMM, Technical University of Denmark, uk@imm.dtu.dk

Use:

  warp_reslice [-i infolevel] [-n | -l | -p sx sy sz] [-d dx dy dz] [-c cx cy cz]   
          [-a E2_airfile ] [-b E2_ascii_transfile] [-e E2_matrix_string ] 
          [-g E1_matrix_string ] [-o E1_ascii_transfile]
          [-j inputvol] [-f displacement_vector_field] [-t templateexample] 
          [-k sx sy sz] [-m cmx cmy cmz ]  outputvol

Applies a 3D deformation field to a volume and combines the non-linear
warp with a linear transformation matrix (as produced by the e.g. the
AIR registration package, see http://bishopw.loni.ucla.edu

This is a general purpose volume data reslice program.
For non-linear registration of PET using MR scans of each individual
subject, the following setup is assumed:


       6 par              12 par                nonlinear          Post
       linear             linear                warp               translation/scale

  PET   -->   Subject MRI   -->   Template MRI  -->   Template MRI   -->   Aligned PET
     \____________________________/          \___________/    \___________/
                 |                                |                   |                  
            12 parameter linear           Displacement field        Translation
            transformation                

The PET image(s) is registered with the corresponding MR scan using a 6
parameter rigid body reorientation. The subject MR scan is then
aligned to the Talairach (or whatever) template MR scan, using a two
step procedure: First the subject MR is aligned to the template using
a 12 parameter linear affine transformation (translation, rotation and
scale in any 3 directions). The nonlinear warp transforms the 12
parameter resliced subject MR to match the template.

This program is able to perform the entire reslice operation, given a
transformation matrix and the volume of displacement vectors.

The deformation field is represented as a 4 dim. volume, with the last
(outer) index being 0, 1 or 2 for X, Y or Z coordinate of the
displacement vector. The displacements are stored in units of
cm's. The template volume covers the same field of view as the
template volume but may be in lower resolution by any integral factor
in each 3 dimensions (i.e. as produced by compute_warp).

The program will resample the input volume 'inputvol' over a field of view
that may be different from the field of view covered by the displacement field.

Define the following coordinates (measured in image indices, first voxel is (0,0,0))

Subject PET:                             p = (px, py, pz, 1)
12 parameter normalized MR:              m = (mx, my, mz, 1)
Template:                                t = (tx, ty, tz, 1)
Aligned PET:                             u = (ux, uy, uz, 1)
Displacement field vector                F(t) = (F1(t), F2(t), F3(t), 0)
12 par. AIR transformation 4x4 matrix    E2
Output translation 4x4 matrix            E1

The program generates the following coordinate shift:

  p = E2*m
  m = t/t(4) + F(t)
  t = E1*u

Note that if you do not wish to apply a deformation field but only the matrix
transformation E1 or E2 you do not need to specify any information regarding
the template volume. You will need to specify the total dimensions and voxel
size of the output volume.

If you do wish to apply a deformation field, you will need to specify the
template size and voxel size, since the displacement field covers the
same field of view as the template file.

Options:
--------
-i level         silent, std, info or debug for control amount of output

-n               Use nearest neighbor interpolation. 

-l               Use trilinear interpolation. 

-p sx sy sz      Use sinc interpolation using a kernel size of sx * sy * sz. 
                 A Hann weigthing filter is applied.

-a airfile       Reads in a binary .air file as generated by alignlinear. 
                 The program checks for differences in endian architechture.
                 The matrix is for cubic template voxels as output by the 
                 AIR alignlinear program.
                 This is the E2 matrix. 

-b asciitransf2  Read in a 3x4 or 4x4 transformation matrix from an ascii file.
                 This is the E2 matrix. 
-o asciitransf1  Read in a 3x4 or 4x4 transformation matrix from an ascii file.
                 This is the E1 matrix. 

-g matrixstring  Get the 3x4 or 4x4 E1 transformation matrix directly from this 
                 string. The matrix E1 is transversed row by row. The matrix
                 defines the relationship between homogeneous volume index 
                 coordinates in the input volume and in the 12 parameter 
                 normalized volume:

                    E1 * output volume coordinates = template index coordinates
                    E2 * template index coordinates = reslice index coordinates
                 Note that this is different from the .air convention where the
                 template coordinates refer to cubic voxel sizes. 
                 
-e matrixstring  Get the 3x4 or 4x4 E2 transformation matrix directly from this 
                 string. Like -g above.
-j inputvol      Use this file as the source file for reslicing. If no 
                 inputvol is given, the airfile is searched for the name 
                 of the reslice file. 

-f dispfield     Volume containing the displacment vectors. If not specified,
                 zero vectors will be applied.

-t templateex    This is the name of a file which defines voxel spacing of the 
                 template volume. Use this volume to get the pixel size
                 for reslicing (instead of using standard file from air file).
                 This will override any naming of the template file given in 
                 the .air file (-a option)

-m cmx cmy cmz   Specify the template voxel spacing here (overriding any other defs). 

-k sx sy sz      In stead of naming a template file, you can specify the template 
                 dimensions here (overriding other defs).


Options controlling reslicing of output file:
---------------------------------------------

-d dx dy dz      Downsample the image by these factors in the x, y 
                 and z directions. This is when you want to resample the file 
                 over the same field of view as is covered by the template 
                 and the displacement map. 

-z sx sy sz      Use these volume dimensions for the output volume. Voxel spacing 
                 adjusted accordingly so that the same field of view as the 
                 template is covered, unless -c specified as well) 

-c cx cy cz      Use this voxel spacing for the output volume. (dimension adjusted 
                 accordingly unless -z specified also)


-h               Display this help

All volio.h file and data formats are supported.

warp_reslice -h produces above information