AFNI program: 3dNwarpCat

Output of -help

Usage: 3dNwarpCat [options] warp1 warp2 ...
------
 * This program catenates (composes) 3D warps defined on a grid,
   OR via a matrix.
  ++ All transformations are from DICOM xyz (in mm) to DICOM xyz.

 * Matrix warps are in files that end in '.1D' or in '.txt'.  A matrix
   warp file should have 12 numbers in it, as output (for example), by
   '3dAllineate -1Dmatrix_save'.
  ++ The matrix (affine) warp can have either 12 numbers on one row,
     or be in the 3x4 format.
  ++ The 12-numbers-on-one-row format is preferred, and is the format
     output by the '-1Dmatrix_save' option in 3dvolreg and 3dAllineate.
  ++ The matrix warp is a transformation of coordinates, not voxels,
     and its use presumes the correctness of the voxel-to-coordinate
     transformation stored in the header of the datasets involved.

 * Nonlinear warps are in dataset files (AFNI .HEAD/.BRIK or NIfTI .nii)
   with 3 sub-bricks giving the DICOM order xyz grid displacements in mm.
  ++ Note that it is not required that the xyz order of voxel storage be in
     DICOM order, just that the displacements be in DICOM order (and sign).
  ++ However, it is important that the warp dataset coordinate order be
     properly specified in the dataset header, since warps are applied
     based on coordinates, not on voxels.
  ++ Also note again that displacements are in mm, NOT in voxel.
  ++ You can 'edit' the warp on the command line by using the 'FAC:'
     scaling prefix, described later. This input editing could be used
     to change the sign of the xyz displacements, if needed.

 * If all the input warps are matrices, then the output is a matrix
   and will be written to the file 'prefix.aff12.1D'.
  ++ Unless the prefix already contains the string '.1D', in which case
     the filename is just the prefix.
  ++ If 'prefix' is just 'stdout', then the output matrix is written
     to standard output.
  ++ In any of these cases, the output format is 12 numbers in one row.

 * If any of the input warps are datasets, they must all be defined on
   the same 3D grid!
  ++ And of course, then the output will be a dataset on the same grid.
  ++ However, you can expand the grid using the '-expad' option.

 * The order of operations in the final (output) warp is, for the
   case of 3 input warps:

     OUTPUT(x) = warp3( warp2( warp1(x) ) )

   That is, warp1 is applied first, then warp2, et cetera.
   The 3D x coordinates are taken from each grid location in the
   first dataset defined on a grid.

 * For example, if you aligned a dataset to a template with @auto_tlrc,
   then further refined the alignment with 3dQwarp, you would do something
   like this:
       warp1 is the output of 3dQwarp
       warp2 is the matrix from @auto_tlrc
       This is the proper order, since the desired warp takes template xyz
       to original dataset xyz, and we have
         3dQwarp warp:      takes template xyz to affinely aligned xyz, and
         @auto_tlrc matrix: takes affinely aligned xyz to original xyz

   3dNwarpCat -prefix Fred_total_WARP -warp1 Fred_WARP+tlrc.HEAD -warp2 Fred.Xat.1D 

   The dataset Fred_total_WARP+tlrc.HEAD could then be used to transform original
   datasets directly to the final template space, as in

   3dNwarpApply -prefix Wilma_warped        \
                -nwarp Fred_total_WARP+tlrc \
                -source Wilma+orig          \
                -master Fred_total_WARP+tlrc

 * If you wish to invert a warp before it is used here, supply its
   input name in the form of
     INV(warpfilename)
   To produce the inverse of the warp in the example above:

   3dNwarpCat -prefix Fred_total_WARPINV        \
              -warp2 'INV(Fred_WARP+tlrc.HEAD)' \
              -warp1 'INV(Fred.Xat.1D)' 

   Note the order of the warps is reversed, in addition to the use of 'INV()'.

 * The final warp may also be inverted simply by adding the '-iwarp' option, as in

   3dNwarpCat -prefix Fred_total_WARPINV -iwarp -warp1 Fred_WARP+tlrc.HEAD -warp2 Fred.Xat.1D 

 * Other functions you can apply to modify a 3D dataset warp are:
    SQRT(datasetname) to get the square root of a warp
    SQRTINV(datasetname) to get the inverse square root of a warp
   However, you can't do more complex expressions, such as 'SQRT(SQRT(warp))'.
   If you think you need something so rococo, use 3dNwarpCalc.  Or think again.

 * You can also manufacture a 3D warp from a 1-brick dataset with displacements
   in a single direction.  For example:
      AP:0.44:disp+tlrc.HEAD  (note there are no blanks here!)
   means to take the 1-brick dataset disp+tlrc.HEAD, scale the values inside
   by 0.44, then load them into the y-direction displacements of a 3-brick 3D
   warp, and fill the other 2 directions with zeros.  The prefixes you can use
   here for the 1-brick to 3-brick displacement trick are
     RL: for x-displacements (Right-to-Left)
     AP: for y-displacements (Anterior-to-Posterior)
     IS: for z-displacements (Inferior-to-Superior)
     VEC:a,b,c: for displacements in the vector direction (a,b,c),
                which vector will be scaled to be unit length.
     Following the prefix's colon, you can put in a scale factor followed
     by another colon (as in '0.44:' in the example above).  Then the name
     of the dataset with the 1D displacements follows.
 * You might reasonably ask of what possible value is this peculiar format?
   This was implemented to use Bz fieldmaps for correction of EPI datasets,
   which are distorted only along the phase-encoding direction.  This format
   for specifying the input dataset (the fieldmap) is built to make the
   scripting a little easier.  Its principal use is in the program 3dNwarpApply.

 * You can scale the displacements in a 3D warp file via the 'FAC:' prefix, as in
     FAC:0.6,0.4,-0.2:fred_WARP.nii
   which will scale the x-displacements by 0.6, the y-displacements by 0.4, and
   the z-displacments by -0.2.

 * Finally, you can input a warp catenation string directly as in the '-nwarp'
   option of 3dNwarpApply, as in

   3dNwarpCat -prefix Fred_total_WARP 'Fred_WARP+tlrc.HEAD Fred.Xat.1D' 


OPTIONS
-------
 -interp iii == 'iii' is the interpolation mode:
                ++ Modes allowed are a subset of those in 3dAllineate:
                     linear  quintic  wsinc5
                ++ The default interpolation mode is 'wsinc5'.
                ++ 'linear' is much faster but less accurate.
                ++ 'quintic' is between 'linear' and 'wsinc5',
                   in both accuracy and speed.

 -verb       == print (to stderr) various fun messages along the road.

 -prefix ppp == prefix name for the output dataset that holds the warp.
 -space sss  == attach string 'sss' to the output dataset as its atlas
                space marker.

 -warp1 ww1  == alternative way to specify warp#1
 -warp2 ww2  == alternative way to specify warp#2 (etc.)
                ++ If you use any '-warpX' option for X=1..99, then
                   any addition warps specified after all command
                   line options appear AFTER these enumerated warps.
                   That is, '-warp1 A+tlrc -warp2 B+tlrc C+tlrc'
                   is like using '-warp3 C+tlrc'.
                ++ At most 99 warps can be used.  If you need more,
                   PLEASE back away from the computer slowly, and
                   get professional counseling.

 -iwarp      == Invert the final warp before output.

 -expad PP   == Pad the nonlinear warps by 'PP' voxels in all directions.
                The warp displacements are extended by linear extrapolation
                from the faces of the input grid.

AUTHOR -- RWCox -- March 2013

 =========================================================================
* This binary version of 3dNwarpCat is compiled using OpenMP, a semi-
   automatic parallelizer software toolkit, which splits the work across
   multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
   by a network (e.g., OpenMP doesn't work across cluster nodes).
* For some implementation and compilation details, please see
   https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
   your system. You can control this value by setting environment variable
   OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
   using all CPUs available.
   ++ However, on some systems, it seems to be necessary to set variable
      OMP_NUM_THREADS explicitly, or you only get one CPU.
   ++ On other systems with many CPUS, you probably want to limit the CPU
      count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
   since OpenMP queries this variable BEFORE the program actually starts.
   ++ You can't usefully set this variable in your ~/.afnirc file or on the
      command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
   it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 1.
* The maximum number of CPUs that will be used is now set to .... 1.
 =========================================================================

++ Compile date = Oct 31 2024 {AFNI_24.3.06:linux_ubuntu_24_64}
This page auto-generated on Thu Oct 31 09:42:22 PM EDT 2024