3dWarpDrive¶
Overview¶
Warp a dataset to match another one (the base).
Usage: 3dWarpDrive [options] dataset
* 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.
* Here, the spatial transformation is defined by a matrix; thus,
it is an affine warp.
* Program 3dAllineate can also compute such an affine transformation,
and it has more options for how the base and input (source) datasets
are to be matched. Thus, the usefulness of the older 3dWarpDrive
program is now limited. For future work, consider using 3dAllineate.
Note other more modern+specific programs for alignment to consider:
* For nonlinear spatial warping, see program 3dQwarp, as well as its
useful wrappers, such as sswarper2, @animal_warper, etc.
* For a more general affine alignment procedure, consider 3dAllineate;
that program does not require the two datasets be on the same grid.
* For affine EPI-anatomical alignment (and other affine alignments),
consider align_epi_anat.py (which is a wrapper for 3dAllineate), which
does not require the two datasets be defined on the same 3D grid.
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)
NB: At this time, the image intensity is NOT adjusted for the
Jacobian of the transformation.
NB: -bilinear_general is not yet implemented. AND WILL NEVER BE.
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.
-setup_mask SS = Option to control preliminary mask opts during
alignment setup. User can provide a keyword that
controls behavior within mri_warp3D_align's setup,
specifically for making a mask. Allowed keywords
are:
default : use default behavior
erode_off : no mask erosion+dilation
erode_2d_min_dim : do slicewise erosion+dilation;
the chosen sliceplane is the
one perpendicular to the axis
that has the minimum matrix
dimension
The default mask setup behavior is to: do mask
erosion+dilation in 3D when the input matrix
dimensions are each >1; and _no_ erosion+dilation
when any matrix dimension is 1 (since the mask would
disappear).
-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.
NB: 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 transformations
(-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 = Sep 14 2026 {AFNI_26.2.08:linux_ubuntu_24_64}
