AFNI program: 3dBlurInMask

Usage: 3dBlurInMask [options]
Blurs a dataset spatially inside a mask.  That's all.  Experimental.

OPTIONS
-------
 -input  ddd = This required 'option' specifies the dataset
               that will be smoothed and output.
 -FWHM   f   = Add this amount of smoothness to the dataset.
              **N.B.: This is also a required 'option'.
 -mask   mmm = Mask dataset, if desired.  Blurring will
               occur only within the mask.  Voxels NOT in
               the mask will be set to zero in the output.
 -Mmask  mmm = Multi-mask dataset -- each distinct nonzero
               value in dataset 'mmm' will be treated as
               a separate mask for blurring purposes.
              **N.B.: 'mmm' must be byte- or short-valued!
 -automask   = Create an automask from the input dataset.
              **N.B.: only 1 masking option can be used!
 -preserve   = Normally, voxels not in the mask will be
               set to zero in the output.  If you want the
               original values in the dataset to be preserved
               in the output, use this option.
 -prefix ppp = Prefix for output dataset will be 'ppp'.
              **N.B.: Output dataset is always in float format.
 -quiet      = Don't be verbose with the progress reports.
 -float      = Save dataset as floats, no matter what the
               input data type is.
              **N.B.: If the input dataset is unscaled shorts, then
                      the default is to save the output in short
                      format as well.  In EVERY other case, the
                      program saves the output as floats. Thus,
                      the ONLY purpose of the '-float' option is to
                      force an all-shorts input dataset to be saved
                      as all-floats after blurring.

NOTES
-----
 * If you don't provide a mask, then all voxels will be included
     in the blurring.  (But then why are you using this program?)
 * Note that voxels inside the mask that are not contiguous with
     any other voxels inside the mask will not be modified at all!
 * Works iteratively, similarly to 3dBlurToFWHM, but without
     the extensive overhead of monitoring the smoothness.
 * But this program will be faster than 3dBlurToFWHM, and probably
     slower than 3dmerge.
 * Since the blurring is done iteratively, rather than all-at-once as
     in 3dmerge, the results will be slightly different than 3dmerge's,
     even if no mask is used here (3dmerge, of course, doesn't take a mask).
 * If the original FWHM of the dataset was 'S' and you input a value
     'F' with the '-FWHM' option, then the output dataset's smoothness
     will be about sqrt(S*S+F*F).  The number of iterations will be
     about (F*F/d*d) where d=grid spacing; this means that a large value
     of F might take a lot of CPU time!
 * The spatial smoothness of a 3D+time dataset can be estimated with a
     command similar to the following:
          3dFWHMx -detrend -mask mmm+orig -input ddd+orig
 * The minimum number of voxels in the mask is 9
 * Isolated voxels will be removed from the mask!

 =========================================================================
* This binary version of 3dBlurInMask is NOT compiled using OpenMP, a
   semi-automatic parallelizer software toolkit, which splits the work
   across multiple CPUs/cores on the same shared memory computer.
* However, the source code is modified for OpenMP, and can be compiled
   with an OpenMP-capable compiler, such as gcc 4.2, Intel's icc, and
   Sun Studio.
* If you wish to compile this program with OpenMP, see the man page for
   your C compiler, and (if needed) consult the AFNI message board, and

++ Compile date = Nov  5 2009