7.1.174. 3dWarpDrive

Link to classic view

Usage: 3dWarpDrive [options] dataset Warp a dataset to match another one (the base).

This program is a generalization of 3dvolreg. It tries to find a spatial transformation that warps a given dataset to match an

input dataset (given by the -base option). It will be slow.

* Also see the script align_epi_anat.py for a more general * ** alignment procedure, which does not require that the two ** ** datasets be defined on the same 3D grid. ** ** align_epi_anat.py uses program 3dAllineate, which can ** * also do nonlinear (polynomial) warping for registration. *

Transform Defining Options: [exactly one of these must be used]

-shift_only = 3 parameters (shifts)
-shift_rotate = 6 parameters (shifts + angles)
-shift_rotate_scale = 9 parameters (shifts + angles + scale factors)
-affine_general = 12 parameters (3 shifts + 3x3 matrix)

-bilinear_general = 39 parameters (3 + 3x3 + 3x3x3)

N.B.: At this time, the image intensity is NOT
adjusted for the Jacobian of the transformation.

N.B.: -bilinear_general is not yet implemented.

Other Options:

-linear }
-cubic } = Chooses spatial interpolation method.
-NN } = [default = linear; inaccurate but fast]

-quintic } [for accuracy, try ‘-cubic -final quintic’]

-base bbb = Load dataset ‘bbb’ as the base to which the
input dataset will be matched. [This is a mandatory option]
-verb = Print out lots of information along the way.
-prefix ppp = Sets the prefix of the output dataset.
If ‘ppp’ is ‘NULL’, no output dataset is written.
-input ddd = You can put the input dataset anywhere in the
command line option list by using the ‘-input’ option, instead of always putting it last.
-summ sss = Save summary of calculations into text file ‘sss’.
(N.B.: If ‘sss’ is ‘-‘, summary goes to stdout.)

Technical Options:

-maxite m = Allow up to ‘m’ iterations for convergence.
-delta d = Distance, in voxel size, used to compute
image derivatives using finite differences. [Default=1.0]
-weight wset = Set the weighting applied to each voxel
proportional to the brick specified here. [Default=computed by program from base]
-thresh t = Set the convergence parameter to be RMS ‘t’ voxels
movement between iterations. [Default=0.03]
-twopass = Do the parameter estimation in two passes,
coarse-but-fast first, then fine-but-slow second (much like the same option in program 3dvolreg). This is useful if large-ish warping is needed to align the volumes.
-final ‘mode’ = Set the final warp to be interpolated using ‘mode’
instead of the spatial interpolation method used to find the warp parameters.
-parfix n v = Fix the n’th parameter of the warp model to
the value ‘v’. More than one -parfix option can be used, to fix multiple parameters.
-1Dfile ename = Write out the warping parameters to the file
named ‘ename’. Each sub-brick of the input dataset gets one line in this file. Each parameter in the model gets one column.
-float = Write output dataset in float format, even if
input dataset is short or byte.
-coarserot = Initialize shift+rotation parameters by a
brute force coarse search, as in the similar 3dvolreg option.
-1Dmatrix_save ff = Save base-to-input transformation matrices
in file ‘ff’ (1 row per sub-brick in the input dataset). If ‘ff’ does NOT end in ‘.1D’, then the program will append ‘.aff12.1D’ to ‘ff’ to make the output filename.
*N.B.: This matrix is the coordinate transformation from base

to input DICOM coordinates. To get the inverse matrix (input-to-base), use the cat_matvec program, as in

cat_matvec fred.aff12.1D -I

AFFINE TRANSFORMATIONS:

The options below control how the affine tranformations (-shift_rotate, -shift_rotate_scale, -affine_general) are structured in terms of 3x3 matrices:

-SDU or -SUD }= Set the order of the matrix multiplication
-DSU or -DUS }= for the affine transformations:
-USD or -UDS }= S = triangular shear (params #10-12)
D = diagonal scaling matrix (params #7-9) U = rotation matrix (params #4-6)

Default order is ‘-SDU’, which means that the U matrix is applied first, then the D matrix, then the S matrix.

-Supper }= Set the S matrix to be upper or lower
-Slower }= triangular [Default=lower triangular]
-ashift OR }= Apply the shift parameters (#1-3) after OR
-bshift }= before the matrix transformation. [Default=after]

The matrices are specified in DICOM-ordered (x=-R+L,y=-A+P,z=-I+S) coordinates as:

[U] = [Rotate_y(param#6)] [Rotate_x(param#5)] [Rotate_z(param #4)]
(angles are in degrees)

[D] = diag( param#7 , param#8 , param#9 )

[ 1 0 0 ] [ 1 param#10 param#11 ]
[S] = [ param#10 1 0 ] OR [ 0 1 param#12 ]
[ param#11 param#12 1 ] [ 0 0 1 ]

For example, the default (-SDU/-ashift/-Slower) has the warp specified as [x]_warped = [S] [D] [U] [x]_in + [shift]. The shift vector comprises parameters #1, #2, and #3.

The goal of the program is to find the warp parameters such that
I([x]_warped) = s * J([x]_in)

as closely as possible in a weighted least squares sense, where ‘s’ is a scaling factor (an extra, invisible, parameter), J(x) is the base image, I(x) is the input image, and the weight image is a blurred copy of J(x).

Using ‘-parfix’, you can specify that some of these parameters are fixed. For example, ‘-shift_rotate_scale’ is equivalent ‘-affine_general -parfix 10 0 -parfix 11 0 -parfix 12 0’. Don’t attempt to use the ‘-parfix’ option unless you understand this example!

RWCox - November 2004

++ Compile date = Dec 16 2015

Table Of Contents

This Page