-1Dmatrix_save and -1Dmatrix_apply
RW Cox — July 2007
The option -1Dmatrix_save is present in program 3dvolreg, 3dWarpDrive, and 3dAllineate.
It instructs the program to save the base-to-input transformation matrix for each
registered sub-brick into a text file, which will have 12 numbers per row, and one row per
sub-brick. An example (with 2 rows):
# 3dvolreg matrices (DICOM-to-DICOM, row-by-row):
1 0.000906864 -0.000222938 -0.0564219 -0.000908728 0.999963 -0.00850925 -0.660097 0.000215214 0.00850945 0.999964 0.579968
1 0.000346147 -0.000353107 -0.0735129 -0.00034904 0.999966 -0.00822638 -0.435146 0.000350247 0.0082265 0.999966 0.0866295
Such a file can be used later with the -1Dmatrix_apply in program
3dAllineate to transform datasets directly (skipping the estimation of the matrix,
which is the prime function of this program).
When using the -1Dmatrix_save option, the preferred prefix for the
output filename is ".aff12.1D".
If the filename argument given after the option does not end in the
string ".1D", then ".aff12.1D" will be appended when forming
the output filename.
The program cat_matvec can be used to manipulate such matrix files. If you have a multiline .aff12.1D file, you can pre- or post-multiply it by another single matrix.
Suppose you have an EPI time series file that you want to register within itself
(to compensate for subject movements), and also to register to a structural
volume. 3dvolreg is good for the first registration, and 3dAllineate is good
for the second one. However, it isn't generally desirable to resample the EPI
dataset twice, as this will artificially blur the dataset a little. Instead,
you can register the dataset with 3dvolreg, not writing out the result but saving
the matrices that would be used for the resampling. Then compute the single matrix
that would register the EPI to the structural volume with 3dAllineate, again not
saving the resulting dataset but saving only the matrix. Combining these two
sets of matrices leads to the matrix collection to align the EPI time series to
the structural image. A script to do the above is given below:
3dTstat -mean -prefix v2_bar v2_EPI+orig
3dAllineate -base astrip+orig -1Dmatrix_save as_to_vb.aff12.1D \
-input v2_bar+orig -EPI
3dvolreg -prefix NULL -1Dmatrix_save vb_to_v2.aff12.1D -base v2_bar+orig \
-input v2_EPI+orig -cubic
cat_matvec as_to_vb.aff12.1D vb_to_v2.aff12.1D > as_to_v2.aff12.1D
3dAllineate -master astrip+orig -mast_dxyz 2.0 \
-1Dmatrix_apply as_to_v2.aff12.1D -input v2_EPI+orig\
-final quintic -prefix v2_reg
The datasets are
The processing steps are
- v2_EPI+orig = EPI time series (from scanner)
- v2_bar+orig = average EPI volume (from 3dTstat); used as the
base for registering v2_EPI+orig and as the source for
registering to astrip+orig
- astrip+orig = 3dSkullStrip-ed T1-weighted structural image
(what you want everything to be lined up with)
You might ask why not just use 3dAllineate to register v2_EPI+orig directly
to astrip+orig, sub-brick by sub-brick. The answer is that using a general
affine transform for intra-EPI registration tends to produce worse results than
a rigid transformation — the small differences in stretching parameters between
time points is counter-productive and disturbing. The above procedure combines the
strengths of 3dvolreg for what it is good at (intra-EPI registration) and 3dAllineate
for what it is good at (inter-modality registration).
- Compute the average EPI volume using program 3dTstat.
- The first 3dAllineate run saves file as_to_vb.aff12.1D, which contains
the alignment matrix from the base astrip+orig to the input average
- Note the use of the -EPI
flag to prevent stretching in the slice direction.
- The 3dvolreg run saves file vb_to_v2.aff12.1D,
containing the matrices for transforming v2_bar+orig to each sub-brick
- Note the use of '-prefix NULL' to avoid
the output of any aligned dataset. In 3dvolreg and 3dWarpDrive,
if no '-prefix' option is given, then a default output
dataset filename is used. Using 'NULL' for the output prefix
will (in these programs) suppress dataset output.
- 3dAllineate will not produce an output dataset if there is
no '-prefix' option. For compatibility, 3dAllineate
will also accept '-prefix NULL' as a signal not to
write an output dataset.
- The cat_matvec program computes the transformations from astrip+orig
coordinates to v2_EPI+orig coordinates, one row for each sub-brick.
Each transformation is first the transformation from astrip+orig
to v2_bar+orig (from as_to_vb.aff12.1D) followed by the
transformation from v2_bar+orig to v2_EPI+orig) (from
- The final 3dAllineate run applies the matrices from cat_matvec to the
v2_EPI+orig sub-bricks, and produces the EPI time series registered
within itself and also to the anatomy.
- The matrices saved by -1Dmatrix_save are, in all 3 programs, the
base-to-input transformations. This is what 3dAllineate needs as
input for the -1Dmatrix_apply option.
- If you output a 3dvolreg dataset, the matrices saved in its header
under the attribute names VOLREG_MATVEC_00* are the input-to-base
matrices — the inverse of the -1Dmatrix_save matrices.
- If you output a 3dWarpDrive dataset, the matrices saved in its header
under the attribute names WARPDRIVE_MATVEC_FOR_00* are the
base-to-input matrices and those under the names
WARPDRIVE_MATVEC_INV_00* are the input-to-base matrices.
- If you output a 3dAllineate dataset, the matrices saved under the attribute
names ALLINEATE_MATVEC_B2S_00* are the base-to-input (input≡source)
matrices, and the attributes ALLINEATE_MATVEC_S2B_00* are the
- All these matrices apply to 3-vectors stored in DICOM (RAI) coordinates.
- You can also save and apply the transformation parameters (shifts, angles, scalings,
and shears) in 3dAllineate using the -1Dparam_save
options. However, since 3dvolreg and 3dWarpDrive do not provide compatible parameter
outputs, this option is less desirable. Also, when using
must be taken that the parameters input mean the same thing as in the run when
-1Dparam_save was used:
the same -base dataset must be used, and
if -EPI was used, then that flag must be supplied again and the new
-input dataset must be stored in the same orientation as the
original -input dataset. These complications are one reason why the
matrix save/restore options were developed.
- You could try to do EPI-to-structural alignment using the 3dAllineate options
-warpfreeze, -replacemeth ls,
However, I've not had such luck with this combination of options, and more
work is needed.