AFNI program: SurfMeasures

Output of -help


SurfMeasures - compute measures from the surface dataset(s)

  usage: SurfMeasures [options] -spec SPEC_FILE -out OUTFILE

    This program is meant to read in a surface or surface pair,
    and to output and user-requested measures over the surfaces.
    The surfaces must be specified in the SPEC_FILE.

 ** Use the 'inspec' command for getting information about the
    surfaces in a spec file.

    The output will be a 1D format text file, with one column
    (or possibly 3) per user-specified measure function.  Some
    functions require only 1 surface, some require 2.

    Current functions (applied with '-func') include:

        ang_norms    : angular difference between normals
        ang_ns_A     : angular diff between segment and first norm
        ang_ns_B     : angular diff between segment and second norm
        coord_A      : xyz coordinates of node on first surface
        coord_B      : xyz coordinates of node on second surface
        n_area_A     : associated node area on first surface
        n_area_B     : associated node area on second surface
        n_avearea_A  : for each node, average area of triangles (surf A)
        n_avearea_B  : for each node, average area of triangles (surf B)
        n_ntri       : for each node, number of associated triangles
        node_vol     : associated node volume between surfs
        node_volg    : associated node volume between surfs via Gauss' theorem
        nodes        : node number
        norm_A       : vector of normal at node on first surface
        norm_B       : vector of normal at node on second surface
        thick        : distance between surfaces along segment

------------------------------------------------------------

  examples:

    1. For each node on the surface smoothwm in the spec file,
       fred.spec, output the node number (the default action),
       the xyz coordinates, and the area associated with the
       node (1/3 of the total area of triangles having that node
       as a vertex).

        SurfMeasures                                   \
            -spec       fred1.spec                     \
            -sv         fred_anat+orig                 \
            -surf_A     smoothwm                       \
            -func       coord_A                        \
            -func       n_area_A                       \
            -out_1D     fred1_areas.1D                   

    2. For each node of the surface pair smoothwm and pial,
       display the:
         o  node index
         o  node's area from the first surface
         o  node's area from the second surface
         o  node's resulting volume
         o  thickness at that node (segment distance)
         o  coordinates of the first segment node
         o  coordinates of the second segment node

         Additionally, display total surface areas, minimum and
         maximum thicknesses, and total volume for the
         cortical ribbon (the sum of node volumes).

        SurfMeasures                                   \
            -spec       fred2.spec                     \
            -sv         fred_anat+orig                 \
            -surf_A     smoothwm                       \
            -surf_B     pial                           \
            -func       n_area_A                       \
            -func       n_area_B                       \
            -func       node_volg                      \
            -func       thick                          \
            -func       coord_A                        \
            -func       coord_B                        \
            -info_area                                 \
            -info_thick                                \
            -info_vol                                  \
            -out        fred2_vol.niml.dset              

    3. For each node of the surface pair, display the:
         o  node index
         o  angular diff between the first and second norms
         o  angular diff between the segment and first norm
         o  angular diff between the segment and second norm
         o  the normal vectors for the first surface nodes
         o  the normal vectors for the second surface nodes
         o  angular diff between the segment and second norm

        SurfMeasures                                   \
            -spec       fred2.spec                     \
            -surf_A     smoothwm                       \
            -surf_B     pial                           \
            -func       ang_norms                      \
            -func       ang_ns_A                       \
            -func       ang_ns_B                       \
            -func       norm_A                         \
            -func       norm_B                         \
            -out        fred2_norm_angles                

    4. Similar to #3, but output extra debug info, and in
       particular, info regarding node 5000.

        SurfMeasures                                   \
            -spec       fred2.spec                     \
            -sv         fred_anat+orig                 \
            -surf_A     smoothwm                       \
            -surf_B     pial                           \
            -func       ang_norms                      \
            -func       ang_ns_A                       \
            -func       ang_ns_B                       \
            -debug      2                              \
            -dnode      5000                           \
            -out        fred2_norm_angles.1D             

    5. For each node, output the  volume, thickness
       and areas, but restrict the nodes to the list contained in
       column 0 of file sdata.1D.  Furthermore, restrict those 
       nodes to the mask inferred by the given '-cmask' option.

        SurfMeasures                                                   \
            -spec       fred2.spec                           \
            -sv         fred_anat+orig                       \
            -surf_A     smoothwm                             \
            -surf_B     pial                                 \
            -func       node_volg                            \
            -func       thick                                \
            -func       n_area_A                             \
            -func       n_area_B                             \
            -nodes_1D   'sdata.1D[0]'                        \
            -cmask      '-a sdata.1D[2] -expr step(a-1000)'  \
            -out        fred2_masked.1D                        

------------------------------------------------------------

  REQUIRED COMMAND ARGUMENTS:

    -spec SPEC_FILE       : SUMA spec file

        e.g. -spec fred2.spec

        The surface specification file contains a list of
        related surfaces.  In order for a surface to be
        processed by this program, it must exist in the spec
        file.

    -surf_A SURF_NAME     : surface name (in spec file)
    -surf_B SURF_NAME     : surface name (in spec file)

        e.g. -surf_A smoothwm
        e.g. -surf_A lh.smoothwm
        e.g. -surf_B lh.pial

        This is used to specify which surface(s) will be used
        by the program.  The 'A' and 'B' correspond to other
        program options (e.g. the 'A' in n_area_A).

        The '-surf_B' parameter is required only when the user
        wishes to input two surfaces.

        Any surface name provided must be unique in the spec
        file, and must match the name of the surface data file
        (e.g. lh.smoothwm.asc).

    -out_1D OUT_FILE.1D   : 1D output filename

        e.g. -out_1D pickle_norm_info.1D

        This option is used to specify the name of the output
        file.  The output file will be in the 1D ascii format,
        with 2 rows of comments for column headers, and 1 row
        for each node index.

        There will be 1 or 3 columns per '-func' option, with
        a default of 1 for "nodes".

        Consider using the newer -out instead of -out_1D


    -out OUT_DSET   : Output into surface dataset OUT_DSET

        e.g. -out pickle_norm_info.niml.dset

        The dset format is determined from the extension of
        OUT_DSET. Default is NIML format.
        You are better off using -out and non-1D format datasets
        because non-1D datasets are better handled by 3dcalc

        You can use both -out and -out_1D, but why?

------------------------------------------------------------

  ALPHABETICAL LISTING OF OPTIONS:

    -cmask COMMAND        : restrict nodes with a mask

        e.g.     -cmask '-a sdata.1D[2] -expr step(a-1000)'

        This option will produce a mask to be applied to the
        list of surface nodes.  The total mask size, including
        zero entries, must match the number of nodes.  If a
        specific node list is provided via the '-nodes_1D'
        option, then the mask size should match the length of
        the provided node list.
        
        Consider the provided example using the file sdata.1D.
        If a surface has 100000 nodes (and no '-nodes_1D' option
        is used), then there must be 100000 values in column 2
        of the file sdata.1D.

        Alternately, if the '-nodes_1D' option is used, giving
        a list of 42 nodes, then the mask length should also be
        42 (regardless of 0 entries).

        See '-nodes_1D' for more information.

    -debug LEVEL          : display extra run-time info

        e.g.     -debug 2
        default: -debug 0

        Valid debug levels are from 0 to 5.

    -dnode NODE           : display extra info for node NODE

        e.g. -dnode 5000

        This option can be used to display extra information
        about node NODE during surface evaluation.

    -func FUNCTION        : request output for FUNCTION

        e.g. -func thick

        This option is used to request output for the given
        FUNCTION (measure).  Some measures produce one column
        of output (e.g. thick or ang_norms), and some produce
        three (e.g. coord_A).  These options, in the order they
        are given, determine the structure of the output file.

        Current functions include:

            ang_norms    : angular difference between normals
            ang_ns_A     : angular diff between segment and first norm
            ang_ns_B     : angular diff between segment and second norm
            coord_A      : xyz coordinates of node on first surface
            coord_B      : xyz coordinates of node on second surface
            n_area_A     : associated node area on first surface
            n_area_B     : associated node area on second surface
            n_avearea_A  : for each node, average area of triangles (surf A)
            n_avearea_B  : for each node, average area of triangles (surf B)
            n_ntri       : for each node, number of associated triangles
            node_vol     : associated node volume between surfs
            node_volg    : associated node volume between surfs via Gauss' theorem
            nodes        : node number
            norm_A       : vector of normal at node on first surface
            norm_B       : vector of normal at node on second surface
            thick        : distance between surfaces along segment

          Note that with node_vol, the node volumes can be a little
          biased. It is recommended you use -node_volg instead.

          You can also use -func ALL to get everything output.
          You should not use other -func options with -func ALL

    -help                 : show this help menu

    -hist                 : display program revision history

        This option is used to provide a history of changes
        to the program, along with version numbers.

  NOTE: the following '-info_XXXX' options are used to display
        pieces of 'aggregate' information about the surface(s).

    -info_all             : display all final info

        This is a short-cut to get all '-info_XXXX' options.

    -info_area            : display info on surface area(s)

        Display the total area of each triangulated surface.

    -info_norms           : display info about the normals

        For 1 or 2 surfaces, this will give (if possible) the
        average angular difference between:

            o the normals of the surfaces
            o the connecting segment and the first normal
            o the connecting segment and the second normal

    -info_thick           : display min and max thickness

        For 2 surfaces, this is used to display the minimum and
        maximum distances between the surfaces, along each of
        the connecting segments.

    -info_vol             : display info about the volume

        For 2 surfaces, display the total computed volume.
        Note that this node-wise volume computation is an
        approximation, and tends to run ~10 % high.

        ** for more accuracy, use -info_volg **

    -info_volg             : display info about the volume
                             which is estimated with Gauss'
                             theorem.

    -nodes_1D NODELIST.1D : request output for only these nodes

        e.g.  -nodes_1D node_index_list.1D
        e.g.  -nodes_1D sdata.1D'[0]'

        The NODELIST file should contain a list of node indices.
        Output from the program would then be restricted to the
        nodes in the list.
        
        For instance, suppose that the file BA_04.1D contains
        a list of surface nodes that are located in Broadman's
        Area 4.  To get output from the nodes in that area, use:
        
            -nodes_1D BA_04.1D
        
        For another example, suppose that the file sdata.1D has
        node indices in column 0, and Broadman's Area indices in
        column 3.  To restrict output to the nodes in Broadman's
        area 4, use the pair of options:
        
            -nodes_1D 'sdata.1D[0]'                     \
            -cmask '-a sdata.1D[3] -expr (1-bool(a-4))' 

    -sv SURF_VOLUME       : specify an associated AFNI volume

        e.g. -sv fred_anat+orig

        If there is any need to know the orientation of the
        surface, a surface volume dataset may be provided.

    -ver                  : show version information

        Show version and compile date.

------------------------------------------------------------

  Author: R. Reynolds  - version 1.11 (October 6, 2004)
This page auto-generated on Thu Oct 31 09:45:34 PM EDT 2024