AFNI program: 3dUndump

Usage: 3dUndump [options] infile ...
Assembles a 3D dataset from an ASCII list of coordinates and
(optionally) values.

Options:
  -prefix ppp  = 'ppp' is the prefix for the output dataset
                   [default = undump].
  -master mmm  = 'mmm' is the master dataset, whose geometry
    *OR*           will determine the geometry of the output.
  -dimen I J K = Sets the dimensions of the output dataset to
                   be I by J by K voxels.  (Each I, J, and K
                   must be >= 1.)  This option can be used to
                   create a dataset of a specific size for test
                   purposes, when no suitable master exists.
          ** N.B.: Exactly one of -master or -dimen must be given.
  -mask kkk    = This option specifies a mask dataset 'kkk', which
                   will control which voxels are allowed to get
                   values set.  If the mask is present, only
                   voxels that are nonzero in the mask can be
                   set in the new dataset.
                   * A mask can be created with program 3dAutomask.
                   * Combining a mask with sphere insertion makes
                     a lot of sense (to me, at least).
  -datum type  = 'type' determines the voxel data type of the
                   output, which may be byte, short, or float
                   [default = short].
  -dval vvv    = 'vvv' is the default value stored in each
                   input voxel that does not have a value
                   supplied in the input file [default = 1].
  -fval fff    = 'fff' is the fill value, used for each voxel
                   in the output dataset that is NOT listed
                   in the input file [default = 0].
  -ijk         = Coordinates in the input file are (i,j,k) index
       *OR*        triples, as might be output by 3dmaskdump.
  -xyz         = Coordinates in the input file are (x,y,z)
                   spatial coordinates, in mm.  If neither
                   -ijk or -xyz is given, the default is -ijk.
          ** N.B.: -xyz can only be used with -master. If -dimen
                   is used to specify the size of the output dataset,
                   (x,y,z) coordinates are not defined (until you
                   use 3drefit to define the spatial structure).
  -srad rrr    = Specifies that a sphere of radius 'rrr' will be
                   filled about each input (x,y,z) or (i,j,k) voxel.
                   If the radius is not given, or is 0, then each
                   input data line sets the value in only one voxel.
                   * If '-master' is used, then 'rrr' is in mm.
                   * If '-dimen' is used, then 'rrr' is in voxels.
  -orient code = Specifies the coordinate order used by -xyz.
                   The code must be 3 letters, one each from the pairs
                   {R,L} {A,P} {I,S}.  The first letter gives the
                   orientation of the x-axis, the second the orientation
                   of the y-axis, the third the z-axis:
                     R = right-to-left         L = left-to-right
                     A = anterior-to-posterior P = posterior-to-anterior
                     I = inferior-to-superior  S = superior-to-inferior
                   If -orient isn't used, then the coordinate order of the
                   -master dataset is used to interpret (x,y,z) inputs.
          ** N.B.: If -dimen is used (which implies -ijk), then the
                   only use of -orient is to specify the axes ordering
                   of the output dataset.  If -master is used instead,
                   the output dataset's axes ordering is the same as the
                   -master dataset's, regardless of -orient.
  -head_only   =  A 'secret' option for creating only the .HEAD file which
                  gets exploited by the AFNI matlab library function
                  New_HEAD.m

Input File Format:
 The input file(s) are ASCII files, with one voxel specification per
 line.  A voxel specification is 3 numbers (-ijk or -xyz coordinates),
 with an optional 4th number giving the voxel value.  For example:

   1 2 3 
   3 2 1 5
   5.3 6.2 3.7
   // this line illustrates a comment

 The first line puts a voxel (with value given by -dval) at point
 (1,2,3).  The second line puts a voxel (with value 5) at point (3,2,1).
 The third line puts a voxel (with value given by -dval) at point
 (5.3,6.2,3.7).  If -ijk is in effect, and fractional coordinates
 are given, they will be rounded to the nearest integers; for example,
 the third line would be equivalent to (i,j,k) = (5,6,4).

Notes:
* This program creates a 1 sub-brick file.  You can 'glue' multiple
   files together using 3dbucket or 3dTcat to make multi-brick datasets.

* If one input filename is '-', then stdin will be used for input.

* If no input files are given, an 'empty' dataset is created.
   For example, to create an all zero dataset with 1 million voxels:
     3dUndump -dimen 100 100 100 -prefix AllZero

* By default, the output dataset is of type '-fim', unless the -master
   dataset is an anat type. You can change the output type using 3drefit.

* You could use program 1dcat to extract specific columns from a
   multi-column rectangular file (e.g., to get a specific sub-brick
   from the output of 3dmaskdump), and use the output of 1dcat as input
   to this program.

* [19 Feb 2004] The -mask and -srad options were added this day.
   Also, a fifth value on an input line, if present, is taken as a
   sphere radius to be used for that input point only.  Thus, input
      3.3 4.4 5.5 6.6 7.7
   means to put the value 6.6 into a sphere of radius 7.7 mm centered
   about (x,y,z)=(3.3,4.4,5.5).

* [10 Nov 2008] Commas (',') inside an input line are converted to
   spaces (' ') before the line is interpreted.  This feature is for
   convenience for people writing files in CSV (Comma Separated Values)
   format.

* [31 Dec 2008] Inputs of 'NaN' are explicitly converted to zero, and
  a warning message is printed.  AFNI programs do not deal with NaN
  floating point values!

-- RWCox -- October 2000

++ Compile date = Mar 13 2009