Usage: 3dvolreg [options] dataset
* Registers each 3D sub-brick from the input dataset to the base brick.
'dataset' may contain a sub-brick selector list.
* This program is written to be fast, and is limited to rigid body
(6 parameter) transformations.
-->> Also see the script align_epi_anat.py for a more general
alignment procedure, which does not require that the base
and source datasets be defined on the same 3D grid.
-->> Program 3dQwarp can do nonlinear warping of one dataset
to match another.
-->> datasets. Script @2dwarper.Allin can do nonlinear
warping in 2D to align 2 datasets on a slice-wise basis
(no out-of-slice movements; each slice registered separately).
OPTIONS:
-verbose Print progress reports. Use twice for LOTS of output.
-Fourier Perform the alignments using Fourier interpolation.
-heptic Use heptic polynomial interpolation.
-quintic Use quintic polynomial interpolation.
-cubic Use cubic polynomial interpolation.
-linear Use linear interpolation.
-->> OLD Default = Fourier [slowest and most accurate interpolator]
-->> NEW Default = Heptic [7th order polynomials]
-clipit Clips the values in each output sub-brick to be in the same
range as the corresponding input volume.
The interpolation schemes can produce values outside
the input range, which is sometimes annoying.
[16 Apr 2002: -clipit is now the default]
-noclip Turns off -clipit
-zpad n Zeropad around the edges by 'n' voxels during rotations
(these edge values will be stripped off in the output)
N.B.: Unlike to3d, in this program '-zpad' adds zeros in
all directions.
N.B.: The environment variable AFNI_ROTA_ZPAD can be used
to set a nonzero default value for this parameter.
N.B.: [22 May 2019] The default value for zero padding
is now set to 4 voxels on each of the 6 planes.
-prefix fname Use 'fname' for the output dataset prefix.
The program tries not to overwrite an existing dataset.
Default = 'volreg'.
N.B.: If the prefix is 'NULL', no output dataset will be written.
-float Force output dataset to be written in floating point format.
N.B.: If the input dataset has scale factors attached to ANY
sub-bricks, then the output will always be written in
float format!
-base n Sets the base brick to be the 'n'th sub-brick
from the input dataset (indexing starts at 0).
Default = 0 (first sub-brick).
-base 'bset[n]' Sets the base brick to be the 'n'th sub-brick
from the dataset specified by 'bset', as in
-base 'elvis+orig[4]'
The quotes are needed because the '[]' characters
are special to the command line shell.
-dfile dname Save the motion parameters in file 'dname'.
The output is in 9 ASCII formatted columns:
n roll pitch yaw dS dL dP rmsold rmsnew
where: n = sub-brick index
roll = rotation about the I-S axis }
pitch = rotation about the R-L axis } degrees CCW
yaw = rotation about the A-P axis }
dS = displacement in the Superior direction }
dL = displacement in the Left direction } mm
dP = displacement in the Posterior direction }
rmsold = RMS difference between input brick and base brick
rmsnew = RMS difference between output brick and base brick
N.B.: If the '-dfile' option is not given, the parameters aren't saved.
N.B.: The motion parameters are those needed to bring the sub-brick
back into alignment with the base. In 3drotate, it is as if
the following options were applied to each input sub-brick:
-rotate 'roll'I 'pitch'R 'yaw'A -ashift 'dS'S 'dL'L 'dP'P
** roll = shaking head 'no' left-right
** pitch = nodding head 'yes' up-down
** yaw = wobbling head sideways (ear toward shoulder)
-1Dfile ename Save the motion parameters ONLY in file 'ename'.
The output is in 6 ASCII formatted columns:
roll pitch yaw dS dL dP
This file can be used in FIM as an 'ort', to detrend
the data against correlation with the movements.
This type of analysis can be useful in removing
errors made in the interpolation.
-1Dmatrix_save ff = Save the matrix transformation from base to input
coordinates 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
*N.B.: This matrix is the inverse of the matrix stored in
the output dataset VOLREG_MATVEC_* attributes.
The base-to-input convention followed with this
option corresponds to the convention in 3dAllineate.
*N.B.: 3dvolreg does not have a '-1Dmatrix_apply' option.
See 3dAllineate for this function. Also confer with
program cat_matvec.
-rotcom Write the fragmentary 3drotate commands needed to
perform the realignments to stdout; for example:
3drotate -rotate 7.2I 3.2R -5.7A -ashift 2.7S -3.8L 4.9P
The purpose of this is to make it easier to shift other
datasets using exactly the same parameters.
-maxdisp = Print the maximum displacement (in mm) for brain voxels.
('Brain' here is defined by the same algorithm as used
in the command '3dAutomask -clfrac 0.33'; the displacement
for each non-interior point in this mask is calculated.)
If '-verbose' is given, the max displacement will be
printed to the screen for each sub-brick; otherwise,
just the overall maximum displacement will get output.
** This displacement is relative to the base volume.
[-maxdisp is now turned on by default]
-nomaxdisp = Do NOT calculate and print the maximum displacement.
[maybe it offends you in some theological sense?]
[maybe you have some real 'need for speed'?]
-maxdisp1D mm = Do '-maxdisp' and also write the max displacement for each
sub-brick into file 'mm' in 1D (columnar) format.
You may find that graphing this file (cf. 1dplot)
is a useful diagnostic tool for your FMRI datasets.
[the 'mm' filename can be '-', which means stdout]
** The program also outputs the maximum change (delta) in
displacement between 2 successive time points, into the
file with name 'mm_delt'. This output can let you see
when there is a sudden head jerk, for example. [22 Jun 2015]
-savedisp sss = Save 3 3D+time datasets with the x,y,z displacements at each
voxel at each time point. The prefix for the x displacement
dataset will be the string 'sss' with '_DX' appended, etc.
This option is intended for use with various processing
scripts now under construction, and is probably otherwise
completely useless.
-tshift ii If the input dataset is 3D+time and has slice-dependent
time-offsets (cf. the output of 3dinfo -v), then this
option tells 3dvolreg to time shift it to the average
slice time-offset prior to doing the spatial registration.
The integer 'ii' is the number of time points at the
beginning to ignore in the time shifting. The results
should like running program 3dTshift first, then running
3dvolreg -- this is primarily a convenience option.
N.B.: If the base brick is taken from this dataset, as in
'-base 4', then it will be the time shifted brick.
If for some bizarre reason this is undesirable, you
could use '-base this+orig[4]' instead.
-rotparent rset
Specifies that AFTER the registration algorithm finds the best
transformation for each sub-brick of the input, an additional
rotation+translation should be performed before computing the
final output dataset; this extra transformation is taken from
the first 3dvolreg transformation found in dataset 'rset'.
-gridparent gset
Specifies that the output dataset of 3dvolreg should be shifted to
match the grid of dataset 'gset'. Can only be used with -rotparent.
This dataset should be one this is properly aligned with 'rset' when
overlaid in AFNI.
* If 'gset' has a different number of slices than the input dataset,
then the output dataset will be zero-padded in the slice direction
to match 'gset'.
* These options are intended to be used to align datasets between sessions:
S1 = SPGR from session 1 E1 = EPI from session 1
S2 = SPGR from session 2 E2 = EPI from session 2
3dvolreg -twopass -twodup -base S1+orig -prefix S2reg S2+orig
3dvolreg -rotparent S2reg+orig -gridparent E1+orig -prefix E2reg \
-base 4 E2+orig
Each sub-brick in E2 is registered to sub-brick E2+orig[4], then the
rotation from S2 to S2reg is also applied, which shifting+padding
applied to properly overlap with E1.
* A similar effect could be done by using commands
3dvolreg -twopass -twodup -base S1+orig -prefix S2reg S2+orig
3dvolreg -prefix E2tmp -base 4 E2+orig
3drotate -rotparent S2reg+orig -gridparent E1+orig -prefix E2reg E2tmp+orig
The principal difference is that the latter method results in E2
being interpolated twice to make E2reg: once in the 3dvolreg run to
produce E2tmp, then again when E2tmp is rotated to make E2reg. Using
3dvolreg with the -rotparent and -gridparent options simply skips the
intermediate interpolation.
*** Please read file README.registration for more ***
*** information on the use of 3dvolreg and 3drotate ***
Algorithm: Iterated linearized weighted least squares to make each
sub-brick as like as possible to the base brick.
This method is useful for finding SMALL MOTIONS ONLY.
See program 3drotate for the volume shift/rotate algorithm.
The following options can be used to control the iterations:
-maxite m = Allow up to 'm' iterations for convergence
[default = 23].
-x_thresh x = Iterations converge when maximum movement
is less than 'x' voxels [default=0.010000],
-rot_thresh r = And when maximum rotation is less than
'r' degrees [default=0.020000].
-delta d = Distance, in voxel size, used to compute
image derivatives using finite differences
[default=0.700000].
-final mode = Do the final interpolation using the method
defined by 'mode', which is one of the
strings 'NN', 'cubic', 'quintic', 'heptic',
or 'Fourier' or 'linear'
[default=mode used to estimate parameters].
-weight 'wset[n]' = Set the weighting applied to each voxel
proportional to the brick specified here
[default=smoothed base brick].
N.B.: if no weight is given, and -twopass is
engaged, then the first pass weight is the
blurred sum of the base brick and the first
data brick to be registered.
-edging ee = Set the size of the region around the edges of
the base volume where the default weight will
be set to zero. If 'ee' is a plain number,
then it is a voxel count, giving the thickness
along each face of the 3D brick. If 'ee' is
of the form '5%', then it is a fraction of
of each brick size. For example, '5%' of
a 256x256x124 volume means that 13 voxels
on each side of the xy-axes will get zero
weight, and 6 along the z-axis. If this
option is not used, then 'ee' is read from
the environment variable AFNI_VOLREG_EDGING.
If that variable is not set, then 5% is used.
N.B.: This option has NO effect if the -weight
option is used.
N.B.: The largest % value allowed is 25%.
-twopass = Do two passes of the registration algorithm:
(1) with smoothed base and data bricks, with
linear interpolation, to get a crude
alignment, then
(2) with the input base and data bricks, to
get a fine alignment.
This method is useful when aligning high-
resolution datasets that may need to be
moved more than a few voxels to be aligned.
-twoblur bb = 'bb' is the blurring factor for pass 1 of
the -twopass registration. This should be
a number >= 2.0 (which is the default).
Larger values would be reasonable if pass 1
has to move the input dataset a long ways.
Use '-verbose -verbose' to check on the
iterative progress of the passes.
N.B.: when using -twopass, and you expect the
data bricks to move a long ways, you might
want to use '-heptic' rather than
the default '-Fourier', since you can get
wraparound from Fourier interpolation.
-twodup = If this option is set, along with -twopass,
then the output dataset will have its
xyz-axes origins reset to those of the
base dataset. This is equivalent to using
'3drefit -duporigin' on the output dataset.
-sinit = When using -twopass registration on volumes
whose magnitude differs significantly, the
least squares fitting procedure is started
by doing a zero-th pass estimate of the
scale difference between the bricks.
Use this option to turn this feature OFF.
-coarse del num = When doing the first pass, the first step is
to do a number of coarse shifts in order to
find a starting point for the iterations.
'del' is the size of these steps, in voxels;
'num' is the number of these steps along
each direction (+x,-x,+y,-y,+z,-z). The
default values are del=10 and num=2. If
you don't want this step performed, set
num=0. Note that the amount of computation
grows as num**3, so don't increase num
past 4, or the program will run forever!
N.B.: The 'del' parameter cannot be larger than
10% of the smallest dimension of the input
dataset.
-coarserot Also do a coarse search in angle for the
starting point of the first pass.
-nocoarserot Don't search angles coarsely.
[-coarserot is now the default - RWCox]
-wtinp = Use sub-brick[0] of the input dataset as the
weight brick in the final registration pass.
N.B.: * This program can consume VERY large quantities of memory.
(Rule of thumb: 40 bytes per input voxel.)
Use of '-verbose -verbose' will show the amount of workspace,
and the steps used in each iteration.
* ALWAYS check the results visually to make sure that the program
wasn't trapped in a 'false optimum'.
* The default rotation threshold is reasonable for 64x64 images.
You may want to decrease it proportionally for larger datasets.
* -twopass resets the -maxite parameter to 66; if you want to use
a different value, use -maxite AFTER the -twopass option.
* The -twopass option can be slow; several CPU minutes for a
256x256x124 volume is a typical run time.
* After registering high-resolution anatomicals, you may need to
set their origins in 3D space to match. This can be done using
the '-duporigin' option to program 3drefit, or by using the
'-twodup' option to this program.
++ Compile date = Oct 31 2024 {AFNI_24.3.06:linux_ubuntu_24_64}
