AFNI program: 3dmask_tool

Output of -help

-------------------------------------------------------------------------
3dmask_tool         - for combining/dilating/eroding/filling masks

This program can be used to:
   1. combine masks, with a specified overlap fraction
   2. dilate and/or erode a mask or combination of masks
   3. fill holes in masks

The outline of operations is as follows.

   - read all input volumes
      - optionally dilate/erode inputs (with any needed zero-padding)
   - restrict voxels to the fraction of overlap
   - optionally dilate/erode combination (with zero-padding)
   - optionally fill any holes
   - write result

Note : all volumes across inputs are combined into a single output volume

Note : a hole is defined as a fully connected set of zero voxels that
       does not contain an edge voxel.  For any voxel in such a set, it
       is not possible to find a path of voxels to reach an edge.

       Such paths are evaluated using 6 face neighbors, no diagonals.

----------------------------------------
examples:

   a. dilate a mask by 5 levels

      3dmask_tool -input mask_anat.FT+tlrc -prefix ma.dilate \
                  -dilate_input 5

   b. dilate and then erode, which connects areas that are close

      3dmask_tool -input mask_anat.FT+tlrc -prefix ma.close.edges \
                  -dilate_input 5 -5

   b2. dilate and erode after combining many masks

      3dmask_tool -input mask_anat.*+tlrc.HEAD -prefix ma.close.result \
                  -dilate_result 5 -5

   c1. compute an intersection mask, this time with EPI masks

      3dmask_tool -input mask_epi_anat.*+tlrc.HEAD -prefix mask_inter \
                  -frac 1.0

   c2. compute a mask of 70% overlap

      3dmask_tool -input mask_epi_anat.*+tlrc.HEAD \
                  -prefix group_mask_olap.7 -frac 0.7

   c3. simply count the voxels that overlap

      3dmask_tool -input mask_epi_anat.*+tlrc.HEAD \
                  -prefix mask.counts -count

   d. fill holes

      3dmask_tool -input mask_anat.FT+tlrc -prefix ma.filled \
                  -fill_holes

   e. fill holes per slice

      3dmask_tool -input mask_anat.FT+tlrc -prefix ma.filled.xy \
                  -fill_holes -fill_dirs xy

   f. read many masks, dilate and erode, restrict to 70%, and fill holes

      3dmask_tool -input mask_anat.*+tlrc.HEAD -prefix ma.fill.7 \
                  -dilate_input 5 -5 -frac 0.7 -fill_holes

----------------------------------------
informational command arguments (execute option and quit):

    -help                   : show this help
    -hist                   : show program history
    -ver                    : show program version

----------------------------------------
optional command arguments:

    -count                  : count the voxels that overlap

        Instead of created a binary 0/1 mask dataset, create one with.
        counts of voxel overlap, i.e each voxel will contain the number
        of masks that it is set in.

    -datum TYPE             : specify data type for output

            e.g: -datum short
            default: -datum byte

        Valid TYPEs are 'byte', 'short' and 'float'.

    -dilate_inputs D1 D2 ... : dilate inputs at the given levels

            e.g. -dilate_inputs 3
            e.g. -dilate_inputs -4
            e.g. -dilate_inputs 8 -8
            default: no dilation

        Use this option to dilate and/or erode datasets as they are read.

        Dilations are across the 18 voxel neighbors that share either a
        face or an edge (i.e. of the 26 neighbors in a 3x3x3 box, it is
        all but the outer 8 corners).
        
        An erosion is specified by a negative dilation.
        
        One can apply a list of dilations and erosions, though there
        should be no reason to apply more than one of each.
        
        Note: use -dilate_result for dilations on the combined masks.

    -dilate_result D1 D2 ... : dilate combined mask at the given levels

            e.g. -dilate_result 3
            e.g. -dilate_result -4
            e.g. -dilate_result 8 -8
            default: no dilation

        Use this option to dilate and/or erode the result of combining
        masks that exceed the -frac cutoff.

        See -dilate_inputs for details of the operation.

    -frac LIMIT             : specify required overlap threshold

            e.g. -frac 0    (same as -union)
            e.g. -frac 1.0  (same as -inter)
            e.g. -frac 0.6
            e.g. -frac 17
            default: union (-frac 0)

        When combining masks (across datasets and sub-bricks), use this
        option to restrict the result to a certain fraction of the set of
        volumes (or to a certain number of volumes if LIMIT > 1).

        For example, assume there are 7 volumes across 3 datasets.  Then
        at each voxel, count the number of masks it is in over the 7
        volumes of input.

            LIMIT = 0       : union, counts > 0 survive
            LIMIT = 1.0     : intersection, counts = 7 survive
            LIMIT = 0.6     : 60% fraction, counts >= 5 survive
            LIMIT = 5       : count limit, counts >= 5 survive  

        See also -inter and -union.

    -inter                  : intersection, this means -frac 1.0
    -union                  : union, this means -frac 0

    -fill_holes             : fill holes within the combined mask

        This option can be used to fill holes in the resulting mask, i.e.
        after all other processing has been done.

        A hole is defined as a connected set of voxels that is surrounded
        by non-zero voxels, and which contains no volume edge voxel, i.e.
        there is no connected voxels at a volume edge (edge of a volume
        meaning any part of any of the 6 volume faces).

        To put it one more way, a zero voxel is part of a hole if there
        is no path of zero voxels (in 3D space) to a volume face/edge.
        Such a path can be curved.

        Here, connections are via the 6 faces only, meaning a voxel could
        be consider to be part of a hole even if there were a diagonal
        path to an edge.  Please pester me if that is not desirable.

    -fill_dirs DIRS         : fill holes only in the given directions

            e.g. -fill_dirs xy
            e.g. -fill_dirs RA
            e.g. -fill_dirs XZ

        This option is for use with -fill holes.

        By default, a hole is a connected set of zero voxels that does
        not have a path to a volume edge.  By specifying fill DIRS, the
        filling is done restricted to only those axis directions.

        For example, to fill holes once slice at a time (in a sagittal
        dataset say, with orientation ASL), one could use any one of the
        options:

            -fill_dirs xy
            -fill_dirs YX
            -fill_dirs AS
            -fill_dirs ip
            -fill_dirs APSI

        DIRS should be a single string that specifies 1-3 of the axes
        using {x,y,z} labels (i.e. dataset axis order), or using the
        labels in {R,L,A,P,I,S}.  Such labels are case-insensitive.

    -input DSET1 ...       : specify the set of inputs (taken as masks)
                           : (-inputs is historically allowed)

            e.g. -input group_mask.nii
            e.g. -input mask_epi_anat.*+tlrc.HEAD
            e.g. -input amygdala_subj*+tlrc.HEAD
            e.g. -input ~/abin/MNI152_2009_template_SSW.nii.gz'[0]'

        Use this option to specify the input datasets to process.  Any
        non-zero voxel will be consider part of that volume's mask.

        An input dataset is allowed to have multiple sub-bricks.
        All volumes across all input datasets are combined to create
        a single volume of output.

    -NN1            : specify NN connection level: 1, 2 or 3
    -NN2            : specify NN connection level: 1, 2 or 3
    -NN3            : specify NN connection level: 1, 2 or 3

            e.g. -NN1
            default: -NN2

        Use this option to specify the nearest neighbor level, one of
        1, 2 or 3.  This defines which voxels are neighbors when
        dilating or eroding.  The default is NN2.

           NN1  : face neighbors         (6   first  neighbors)
           NN2  : face or edge neighbors (+12 second neighbors)
           NN3  : face, edge or diagonal (+8  third  neighbors (27-1))

    -prefix PREFIX          : specify a prefix for the output dataset

            e.g. -prefix intersect_mask
            default: -prefix combined_mask

        The resulting mask dataset will be named using the given prefix.

    -quiet                  : limit text output to errors

        Restrict text output.  This option is equivalent to '-verb 0'.

        See also -verb.

    -verb LEVEL             : specify verbosity level

        The default level is 1, while 0 is considered 'quiet'.
        The maximum level is currently 3, but most people don't care.

-------------------------------
R. Reynolds         April, 2012
----------------------------------------------------------------------
This page auto-generated on Thu Apr 18 14:45:41 EDT 2024