AFNI program: 3dSurfMaskDump

3dSurfMaskDump - dump ascii dataset values corresponding to a surface

This program is used to display AFNI dataset values that
correspond to a surface.  The surface points are mapped to xyz
coordinates, according to the SURF_VOL (surface volume) AFNI
dataset.  These coordinates are then matched to voxels in other
AFNI datasets.  So given any other AFNI dataset, this program
can output all of the sub-brick values that correspond to each
of the suface locations.  The user also has options to mask
regions for output.

Different mappings are allowed from the surface(s) to the grid
parent dataset.  The mapping function is a required parameter to
the program.

The current mapping functions are:

    ave       : for each node pair (from 2 surfaces), output the
                average of all voxel values along that line
                segment
    mask      : each node in the surface is mapped to one voxel
    midpoint  : for each node pair (from 2 surfaces), output the
                dataset value at their midpoint (in xyz space)

  usage: 3dSurfMaskDump [options] -spec SPEC_FILE -sv SURF_VOL \
                    -grid_parent AFNI_DSET -map_func MAP_FUNC

  examples:

    3dSurfMaskDump                       \
       -spec         fred.spec                \
       -sv           fred_anat+orig           \
       -grid_parent  fred_anat+orig           \
       -map_func     mask                     \

    3dSurfMaskDump                       \
       -spec         fred.spec                               \
       -sv           fred_anat+orig                          \
       -grid_parent 'fred_epi+orig[0]'                       \
       -map_func     mask                                    \
       -cmask       '-a fred_func+orig[2] -expr step(a-0.6)' \
       -debug        2                                       \
       -output       fred_surf_vals.txt

    3dSurfMaskDump                       \
       -spec         fred.spec                               \
       -sv           fred_anat+orig                          \
       -grid_parent  fred_anat+orig                          \
       -map_func     ave                                     \
       -m2_steps     10                                      \
       -m2_index     nodes                                   \
       -cmask       '-a fred_func+orig[2] -expr step(a-0.6)' \
       -output       fred_surf_ave.txt


  REQUIRED COMMAND ARGUMENTS:

    -spec SPEC_FILE        : SUMA spec file

        e.g. -spec fred.spec

        The surface specification file contains the list of
        mappable surfaces that are used.

        See @SUMA_Make_Spec_FS and @SUMA_Make_Spec_SF.

    -sv SURFACE_VOLUME     : AFNI dataset

        e.g. -sv fred_anat+orig

        This is the AFNI dataset that the surface is mapped to.
        This dataset is used for the intial surface node to xyz
        coordinate mapping, in the Dicomm orientation.

    -grid_parent AFNI_DSET : AFNI dataset

        e.g. -grid_parent fred_function+orig

        This dataset is used as a grid and orientation master
        for the output.  Output coordinates are based upon
        this dataset.

    -map_func MAP_FUNC     : surface to dataset function

        e.g. -map_func ave
        e.g. -map_func ave -m2_steps 10
        e.g. -map_func ave -m2_steps 10 -m2_index nodes
        e.g. -map_func mask
        e.g. -map_func midpoint

        Given one or more surfaces, there are many ways to
        select voxel locations, and to select corresponding
        values for the output dataset.  Some of the functions
        will have separate options.

        The current mapping functions are:

          ave      : Given 2 related surfaces, for each node
                     pair, output the average of the dataset
                     values located along the segment joining
                     those nodes.

                  -m2_steps NUM_STEPS :

                     The -m2_steps option may be added here, to
                     specify the number of points to use in the
                     average.  The default and minimum is 2.

                     e.g.  -map_func ave -m2_steps 10
                     default: -m2_steps 2

                  -m2_index TYPE :

                     The -m2_index options is used to specify
                     whether the average is taken by indexing
                     over distict nodes or over distict voxels.

                     For instance, when taking the average along
                     one node pair segment using 10 node steps,
                     perhaps 3 of those nodes may occupy one
                     particular voxel.  In this case, does the
                     user want the voxel counted only once, or 3
                     times?  Each case makes sense.
                     
                     Note that this will only make sense when
                     used along with the '-m2_steps' option.
                     
                     Possible values are "nodes", "voxels".
                     The default value is voxels.  So each voxel
                     along a segment will be counted only once.
                     
                     e.g.  -m2_index nodes
                     e.g.  -m2_index voxels
                     default: -m2_index voxels

          mask     : For each surface xyz location, output the
                     dataset values of each sub-brick.

          midpoint : Given 2 related surfaces, for each node
                     pair, output the dataset value with xyz
                     coordinates at the midpoint of the nodes.

  options:

    -cmask MASK_COMMAND    : (optional) command for dataset mask

        e.g. -cmask '-a fred_func+orig[2] -expr step(a-0.8)'

        This option will produce a mask to be applied to the
        output dataset.  Note that this mask should form a
        single sub-brick.

        This option follows the style of 3dmaskdump (since the
        code for it was, uh, borrowed from there (thanks Bob!)).

        See '3dmaskdump -help' for more information.

    -debug LEVEL           :  (optional) verbose output

        e.g. -debug 2

        This option is used to print out status information 
        during the execution of the program.  Current levels are
        from 0 to 4.

    -help                  : show this help

        If you can't get help here, please get help somewhere.

    -outfile OUTPUT_FILE   : specify a file for the output

        e.g. -outfile some_output_file
        e.g. -outfile mask_values_over_dataset.txt
        e.g. -outfile stderr
        default: write to stdout

        This is where the user will specify which file they want
        the output to be written to.  Note that the output file
        should not yet exist.

        Two special (valid) cases are stdout and stderr, either
        of which may be specified.

    -noscale               : no scale factor in output dataset

        If the output dataset is an integer type (byte, shorts
        or ints), then the output dataset may end up with a
        scale factor attached (see 3dcalc -help).  With this
        option, the output dataset will not be scaled.

    -version               : show version information

        Show version and compile date.


  Author: R. Reynolds  - version 2.3 (July 21, 2003)

                (many thanks to Z. Saad and R.W. Cox)