AFNI program: 3dmaskdump

Output of -help

Usage: 3dmaskdump [options] dataset dataset ...
Writes to an ASCII file values from the input datasets
which satisfy the mask criteria given in the options.
If no options are given, then all voxels are included.
This might result in a GIGANTIC output file.
Options:
  -mask mset   Means to use the dataset 'mset' as a mask:
                 Only voxels with nonzero values in 'mset'
                 will be printed from 'dataset'.  Note
                 that the mask dataset and the input dataset
                 must have the same number of voxels.
  -mrange a b  Means to further restrict the voxels from
                 'mset' so that only those mask values
                 between 'a' and 'b' (inclusive) will
                 be used.  If this option is not given,
                 all nonzero values from 'mset' are used.
                 Note that if a voxel is zero in 'mset', then
                 it won't be included, even if a < 0 < b.
  -index       Means to write out the dataset index values.
  -noijk       Means not to write out the i,j,k values.
  -xyz         Means to write the x,y,z coordinates from
                 the 1st input dataset at the start of each
                 output line.  These coordinates are in
                 the 'RAI' (DICOM) order.
  -o fname     Means to write output to file 'fname'.
                 [default = stdout, which you won't like]

  -cmask 'opts' Means to execute the options enclosed in single
                  quotes as a 3dcalc-like program, and produce
                  produce a mask from the resulting 3D brick.
       Examples:
        -cmask '-a fred+orig[7] -b zork+orig[3] -expr step(a-b)'
                  produces a mask that is nonzero only where
                  the 7th sub-brick of fred+orig is larger than
                  the 3rd sub-brick of zork+orig.
        -cmask '-a fred+orig -expr 1-bool(k-7)'
                  produces a mask that is nonzero only in the
                  7th slice (k=7); combined with -mask, you
                  could use this to extract just selected voxels
                  from particular slice(s).
       Notes: * You can use both -mask and -cmask in the same
                  run - in this case, only voxels present in
                  both masks will be dumped.
              * Only single sub-brick calculations can be
                  used in the 3dcalc-like calculations -
                  if you input a multi-brick dataset here,
                  without using a sub-brick index, then only
                  its 0th sub-brick will be used.
              * Do not use quotes inside the 'opts' string!

  -xbox x y z   Means to put a 'mask' down at the dataset (not DICOM)
                  coordinates of 'x y z' mm.
       Notes: * By default, this box is 1 voxel wide in each direction,
                  rounding to the closest voxel center to the given single
                  coordinate.
                  Alternatively, one can specify a range of coordinates
                  using colon ':' as a separator; for example:
                    -xbox 22:27 31:33 44
                  means a box from (x,y,z)=(22,31,44) to (27,33,44).
                  Use of the colon makes the range strict, meaning voxels
                  outside the exact range will be omitted.  Since 44 is
                  not specified with a range, the closest z coordinate
                  to 44 is used, while the x and y coordinates are strict.
              * Dataset coordinates are NOT the coordinates you
                 typically see in AFNI's main controller top left corner.
                 Those coordinates are typically in either RAI/DICOM order
                 or in LPI/SPM order and should be used with -dbox and
                 -nbox, respectively.

  -dbox x y z   Means the same as -xbox, but the coordinates are in
                  RAI/DICOM order (+x=Left, +y=Posterior, +z=Superior).
                  If your AFNI environment variable AFNI_ORIENT is set to
                  RAI, these coordinates correspond to those you'd enter
                  into the 'Jump to (xyz)' control in AFNI, and to
                  those output by 3dclust.
            NOTE: It is possible to make AFNI and/or 3dclust output 
                  coordinates in an order different from the one specified 
                  by AFNI_ORIENT, but you'd have to work hard on that. 
                  In any case, the order is almost always specified along 
                  with the coordinates. If you see RAI/DICOM, then use 
                  -dbox. If you see LPI/SPM then use -nbox. 

  -nbox x y z   Means the same as -xbox, but the coordinates are in
                  LPI/SPM or 'neuroscience' order where the signs of the
                  x and y coordinates are reversed relative to RAI/DICOM.
                  (+x=Right, +y=Anterior, +z=Superior)

  -ibox i j k   Means to put a 'mask' down at the voxel indexes
                  given by 'i j k'.  By default, this picks out
                  just 1 voxel.  Again, you can use a ':' to specify
                  a range (now in voxels) of locations.
       Notes: * Boxes are cumulative; that is, if you specify more
                  than 1 box, you'll get more than one region.
              * If a -mask and/or -cmask option is used, then
                  the INTERSECTION of the boxes with these masks
                  determines which voxels are output; that is,
                  a voxel must be inside some box AND inside the
                  mask in order to be selected for output.
              * If boxes select more than 1 voxel, the output lines
                  are NOT necessarily in the order of the options on
                  the command line.
              * Coordinates (for -xbox, -dbox, and -nbox) are relative
                  to the first dataset on the command line.
              * It may be helpful to slightly pad boxes, to be sure they
                contain the desired voxel centers.

  -xball x y z r  Means to put a ball (sphere) mask down at dataset
                    coordinates (x,y,z) with radius r.
  -dball x y z r  Same, but (x,y,z) are in RAI/DICOM order.
  -nball x y z r  Same, but (x,y,z) are in LPI/SPM order.
       Notes: * The combined (set UNION) of all ball and/or box masks
                is created first.  Then, if a -mask and/or -cmask
                option was used, then the ball+box mask will be
                INTERSECTED with the existing mask.
              * Balls not centered over voxels, or those applied to
                anisotropic volumes may not appear symmetric.
              * Consider slight padding to handle truncation.

  -nozero       Means to skip output of any voxel where all the
                  data values are zero.

  -n_rand N_RAND Means to keep only N_RAND randomly selected
                 voxels from what would have been the output.

  -n_randseed SEED  Seed the random number generator with SEED,
                    instead of the default seed of 1234

  -niml name    Means to output data in the XML/NIML format that
                  is compatible with input back to AFNI via
                  the READ_NIML_FILE command.
              * 'name' is the 'target_name' for the NIML header
                  field, which is the name that will be assigned
                  to the dataset when it is sent into AFNI.
              * Also implies '-noijk' and '-xyz' and '-nozero'.

  -quiet        Means not to print progress messages to stderr.

Inputs after the last option are datasets whose values you
want to be dumped out.  These datasets (and the mask) can
use the sub-brick selection mechanism (described in the
output of '3dcalc -help') to choose which values you get.

Each selected voxel gets one line of output:
  i j k val val val ....
where (i,j,k) = 3D index of voxel in the dataset arrays,
and val = the actual voxel value.  Note that if you want
the mask value to be output, you have to include that
dataset in the dataset input list again, after you use
it in the '-mask' option.

* To eliminate the 'i j k' columns, use the '-noijk' option.
* To add spatial coordinate columns, use the '-xyz' option.

N.B.: This program doesn't work with complex-valued datasets!

INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.

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