Usage: cat_matvec [-MATRIX | -ONELINE] matvec_spec matvec_spec ...
Catenates 3D rotation+shift matrix+vector transformations.
Each matvec_spec is of the form
mfile [-opkey]
'mfile' specifies the matrix, and can take 4(ish) forms:
=== FORM 1 ===
mfile is the name of an ASCII file with 12 numbers arranged
in 3 lines:
u11 u12 u13 v1
u21 u22 u23 v2
u31 u32 u33 v3
where each 'uij' and 'vi' is a number. The 3x3 matrix [uij]
is the matrix of the transform, and the 3-vector [vi] is the
shift. The transform is [xnew] = [uij]*[xold] + [vi].
=== FORM 1a === [added 24 Jul 2007]
mfile is the name of an ASCII file with multiple rows, each
containing 12 numbers in the order
u11 u12 u13 v1 u21 u22 u23 v2 u31 u32 u33 v3
The filename must end in the characters '.aff12.1D', as output
by the '-1Dmatrix_save' option in 3dAllineate and 3dvolreg.
Each row of this file is treated as a separate matrix, and
multiple matrices will be computed.
** N.B.: At most ONE input matrix can be in this format! **
=== FORM 2 ===
mfile is of the form 'dataset::attribute', where 'dataset'
is the name of an AFNI dataset, and 'attribute' is the name
of an attribute in the dataset's header that contains a
matrix+vector. Examples:
'fred+orig::VOLREG_MATVEC_000000' = fred+orig from 3dvolreg
'fred+acpc::WARP_DATA' = fred+acpc warped in AFNI
'fred+orig::WARPDRIVE_MATVEC_FOR_000000' = fred+orig from 3dWarpDrive
'fred+orig::ROTATE_MATVEC_000000' = fred+orig from 3drotate
For matrices to turn voxel coordinates to dicom:
'fred+orig::IJK_TO_CARD_DICOM'
'fred+orig::IJK_TO_DICOM_REAL'
Note that both of VOLREG_MATVEC_ and ROTATE_MATVEC_ are usually
accompanied with VOLREG_CENTER_OLD and VOLREG_CENTER_BASE or
ROTATE_CENTER_OLD and ROTATE_CENTER_BASE attributes.
These center attributes are automatically taken into account in
cat_matvec's output.
=== FORM 3 ===
mfile is of the form
'MATRIX(u11,u12,u13,v1,u21,u22,u23,v2,u31,u32,u33,v3)'
directly giving all 12 numbers on the command line. You will
need the 'forward single quotes' around this argument.
=== FORM 4 ===
mfile is of the form
'-rotate xI yR zA'
where 'x', 'y', and 'z' are angles in degrees, specifying rotations
about the I, R, and A axes respectively. The letters 'I', 'R', 'A'
specify the axes, and can be altered as in program 3drotate.
(The 'quotes' are mandatory here because the argument contains spaces.)
=== COMPUTATIONS ===
If [U] [v] are the matrix/vector for the first mfile, and
[A] [b] are the matrix/vector for the second mfile, then
the catenated transformation is
matrix = [A][U] vector = [A][v] + [b]
That is, the second mfile transformation follows the first.
** Thus, the order of matrix multiplication is exactly the **
** opposite of the order of the inputs on the command line! **
The optional 'opkey' (operation key) following each mfile
starts with a '-', and then is a set of letters telling how
to treat the input. The opkeys currently defined are:
-I = invert the transformation:
-1 -1
[xold] = [uij] [xnew] - [uij] [vi]
-P = Do a polar decomposition on the 3x3 matrix part
of the mfile. This would result in an orthogonal
matrix (rotation only, no scaling) Q that is closest,
in the Frobenius distance sense, to the input matrix A.
Note: if A = R * S * E, where R, S and E are the Rotation,
Scale, and shEar matrices, respctively, Q does not
necessarily equal R because of interaction; Each of R,
S and E affects most of the columns in matrix A.
-IP = -I followed by -P
-S = square root of the matrix
Note: Not all matrices have square roots!
The square root of a matrix will do 'half' the transformation.
One application: 3dLRflip + 3dAllineate to register a volume
to its mirror image, then apply half the transformation to
bring it into vertical alignment.
The transformation resulting by catenating the transformations
is written to stdout in the same 3x4 ASCII file format. This can
be used as input to '3drotate -matvec_dicom' (provided [uij] is a
proper orthogonal matrix), or to '3dWarp -matvec_xxx'.
-MATRIX: indicates that the resulting matrix will
be written to stdout in the 'MATRIX(...)' format (FORM 3).
This feature could be used, with clever scripting, to input
a matrix directly on the command line to program 3dWarp.
-ONELINE: option indicates that the resulting matrix
will simply be written as 12 numbers on one line.
-4x4: Output matrix in augmented form (last row is 0 0 0 1)
This option does not work with -MATRIX or -ONELINE
N.B.: If only 9 numbers can be read from an mfile, then those
values form the [uij] matrix, and the vector is set to zero.
N.B.: If form 1a (.aff12.1D) is used to compute multiple matrices,
then the output matrices are written to stdout, one matrix
