1dApar2mat


Usage: 1dApar2mat dx dy dz a1 a2 a3 sx sy sz hx hy hz

* This program computes the affine transformation matrix
  from the set of 3dAllineate parameters.

* The result is printed to stdout, and can be captured
  by Unix shell redirection (e.g., '|', '>', '>>', etc.).
  See the EXAMPLE, far below.

* One use for 1dApar2mat is to take a set of parameters
  from '3dAllineate -1Dparam_save', alter them in some way,
  and re-compute the corresponding matrix. For example,
  compute the full affine transform with 12 parameters,
  but then omit the final 6 parameters to see what the
  'pure' shift+rotation matrix looks like.

* The 12 parameters are, in the order used on the 1dApar2mat command line
  (the same order as output by 3dAllineate):
   x-shift         in mm
   y-shift         in mm
   z-shift         in mm
   z-angle (roll)  in degrees (not radians!)
   x-angle (pitch) in degrees
   y-angle (yaw)   in degrees
   x-scale         unitless factor, in [0.10,10.0]
   y-scale         unitless factor, in [0.10,10.0]
   z-scale         unitless factor, in [0.10,10.0]
   y/x-shear       unitless factor, in [-0.3333,0.3333]
   z/x-shear       unitless factor, in [-0.3333,0.3333]
   z/y-shear       unitless factor, in [-0.3333,0.3333]

* Parameters omitted from the end of the command line get their
  default values (0 except for scales, which default to 1).

* At least 1 parameter must be given, or you get this help message :)
  The minimum command line is
   1dApar2mat 0
  which will output the identity matrix.

* Legal scale and shear factors have limited ranges, as
  described above. An input value outside the given range
  will be reset to the default value for that factor (1 or 0).

* UNUSUAL SPECIAL CASES:
   If you used 3dAllineate with any of the options described
   under 'CHANGING THE ORDER OF MATRIX APPLICATION' or you
   used the '-EPI' option, then the order of parameters inside
   3dAllineate will no longer be the same as the parameter order
   in 1dApar2mat. In such a situation, the matrix output by
   this program will NOT agree with that output by 3dAllineate
   for the same set of parameter numbers :(

* EXAMPLE:
   1dApar2mat 0 1 2 3 4 5
  to get a rotation matrix with some shifts; the output is:
  # mat44 1dApar2mat 0 1 2 3 4 5 :
        0.994511      0.058208     -0.086943       0.000000
       -0.052208      0.996197      0.069756       1.000000
        0.090673     -0.064834      0.993768       2.000000
  If you wish to capture this matrix all on one line, you can
  combine various Unix shell and command tricks/tools, as in
   echo `1dApar2mat 0 1 2 3 4 5 | tail -3` > Fred.aff12.1D
  This 12-numbers-in-one-line is the format output by '-1Dmatrix_save'
  in 3dAllineate and 3dvolreg.

* FANCY EXAMPLE:
  Tricksy command line stuff to compute the inverse of a matrix
    set fred = `1dApar2mat 0 0 0 3 4 5 1 1 1 0.2 0.1 0.2 | tail -3`
    cat_matvec `echo $fred | sed -e 's/ /,/g' -e 's/^/MATRIX('/`')' -I

* ALSO SEE: Programs cat_matvec and 1dmatcalc for doing
            simple matrix arithmetic on such files.

* OPTIONS: This program has no options. Love it or leave it :)

* AUTHOR: Zhark the Most Affine and Sublime - April 2019