-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.

Example Application:
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 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).

Miscellany: