AFNI program: SurfDist

Output of -help


Usage: SurfDist  [OPTIONS] <SURFACE> <NODEPAIRS>
       Output shortest distance between NODEPAIRS along
       the nesh of SURFACE, or the Euclidian distance.

Mandatory options:
  <SURFACE> : Surface on which distances are computed.
              (For option's syntax, see 
              'Specifying input surfaces' section below).
  <NODEPAIRS> : Specifying node pairs can be done in two ways

     <FROM_TO_NODES>: A dataset of two columns where each row
               specifies a node pair.
               (For option's syntax, see 
              'SUMA dataset input options' section below).
   or
     <-from_node START>: Specify one starting node.
     <TO_NODES>: Specify one column of 'To' node indices.
                 Node pairs are between START and each node
                 in TO_NODES.
               (For option's syntax, see 
              'SUMA dataset input options' section below).

Optional stuff:
  -node_path_do PATH_DO: Output the shortest path between
                         each node pair as a SUMA Displayable
                         object.
  -Euclidian: Calculate Euclidian distance, rather than graph distance.
  -Graph: Calculate distance along the mesh (default).

  example 1:
     echo make a toy surface
     CreateIcosahedron
     echo Create some nodepairs
     echo 2 344 > nodelist.1D
     echo 416 489 >> nodelist.1D
     echo 415 412 >> nodelist.1D
     echo 123 32414 >> nodelist.1D
     echo Get distances and write out results in a 1D file
     SurfDist -i CreateIco_surf.asc \
              -input nodelist.1D \
              -node_path_do node_path   > example.1D
     echo 'The internode distances are in this file:'
     cat example.1D
     echo 'And you can visualize the paths this way:'
     suma -niml &
     DriveSuma -com show_surf -label ico \
                       -i_fs CreateIco_surf.asc \
               -com viewer_cont -load_do node_path.1D.do

  example 2: (for tcsh)
     echo Say one has a filled ROI called: Area.niml.roi on 
     echo a surface called lh.smoothwm.asc.
     set apref = Area
     set surf = lh.smoothwm.asc
     echo Create a dataset from this ROI with:
     ROI2dataset -prefix ${apref} -input ${apref}.niml.roi
     echo Get the nodes column forming the area
     ConvertDset -i ${apref}.niml.dset'[i]' -o_1D_stdout \
                              > ${apref}Nodes.1D 
     echo Calculate distance from node 85329 to each of ${apref}Nodes.1D
     SurfDist  -from_node 85329 -input ${apref}Nodes.1D \
               -i ${surf}   > ${apref}Dists.1D
     echo Combine node indices and distances from node  85329
     1dcat ${apref}Nodes.1D ${apref}Dists.1D'[2]' \
                                  > welt.1D.dset 
     echo Now load welt.1D.dset and overlay on surface
     echo Distances are in the second column
     echo 'And you can visualize the distances this way:'
     suma -niml &
     sleep 4
     DriveSuma -com show_surf -label oke \
                       -i_fs ${surf} \
               -com  pause hit enter when surface is ready \
               -com surf_cont -load_dset welt.1D.dset \
                              -I_sb 1 -T_sb 1 -T_val 0.0 

  example 3:
     echo make a toy surface
     CreateIcosahedron
     echo Create some nodepairs
     echo 2 344 > nodelist.1D
     echo 416 489 >> nodelist.1D
     echo 415 412 >> nodelist.1D
     echo 123 32414 >> nodelist.1D
     echo Get Euclidian distances and write out results to file
     SurfDist -i CreateIco_surf.asc \
              -input nodelist.1D \
              -Euclidian   > example3.1D
 Specifying input surfaces using -i or -i_TYPE options: 
    -i_TYPE inSurf specifies the input surface,
            TYPE is one of the following:
       fs: FreeSurfer surface. 
           If surface name has .asc it is assumed to be
           in ASCII format. Otherwise it is assumed to be
           in BINARY_BE (Big Endian) format.
           Patches in Binary format cannot be read at the moment.
       sf: SureFit surface. 
           You must specify the .coord followed by the .topo file.
       vec (or 1D): Simple ascii matrix format. 
            You must specify the coord (NodeList) file followed by 
            the topo (FaceSetList) file.
            coord contains 3 floats per line, representing 
            X Y Z vertex coordinates.
            topo contains 3 ints per line, representing 
            v1 v2 v3 triangle vertices.
       ply: PLY format, ascii or binary.
            Only vertex and triangulation info is preserved.
       mni: MNI .obj format, ascii only.
            Only vertex, triangulation, and node normals info is preserved.
       byu: BYU format, ascii.
            Polygons with more than 3 edges are turned into
            triangles.
       bv: BrainVoyager format. 
           Only vertex and triangulation info is preserved.
       dx: OpenDX ascii mesh format.
           Only vertex and triangulation info is preserved.
           Requires presence of 3 objects, the one of class 
           'field' should contain 2 components 'positions'
           and 'connections' that point to the two objects
           containing node coordinates and topology, respectively.
       gii: GIFTI XML surface format.
 Note that if the surface filename has the proper extension, 
 it is enough to use the -i option and let the programs guess
 the type from the extension.
     -onestate: Make all -i_* surfaces have the same state, i.e.
                they all appear at the same time in the viewer.
                By default, each -i_* surface has its own state. 
                For -onestate to take effect, it must precede all -i
                options with on the command line. 
     -anatomical: Label all -i surfaces as anatomically correct.
                Again, this option should precede the -i_* options.
 Specifying surfaces using -t* options: 
   -tn TYPE NAME: specify surface type and name.
                  See below for help on the parameters.
   -tsn TYPE STATE NAME: specify surface type state and name.
        TYPE: Choose from the following (case sensitive):
           1D: 1D format
           FS: FreeSurfer ascii format
           PLY: ply format
           MNI: MNI obj ascii format
           BYU: byu format
           SF: Caret/SureFit format
           BV: BrainVoyager format
           GII: GIFTI format
        NAME: Name of surface file. 
           For SF and 1D formats, NAME is composed of two names
           the coord file followed by the topo file
        STATE: State of the surface.
           Default is S1, S2.... for each surface.
 Specifying a Surface Volume:
    -sv SurfaceVolume [VolParam for sf surfaces]
       If you supply a surface volume, the coordinates of the input surface.
        are modified to SUMA's convention and aligned with SurfaceVolume.
        You must also specify a VolParam file for SureFit surfaces.
 Specifying a surface specification (spec) file:
    -spec SPEC: specify the name of the SPEC file.
 Specifying a surface using -surf_? method:
    -surf_A SURFACE: specify the name of the first
            surface to load. If the program requires
            or allows multiple surfaces, use -surf_B
            ... -surf_Z .
            You need not use _A if only one surface is
            expected.
            SURFACE is the name of the surface as specified
            in the SPEC file. The use of -surf_ option 
            requires the use of -spec option.

  SUMA dataset input options:
      -input DSET: Read DSET1 as input.
                   In programs accepting multiple input datasets
                   you can use -input DSET1 -input DSET2 or 
                   input DSET1 DSET2 ...
       NOTE: Selecting subsets of a dataset:
             Much like in AFNI, you can select subsets of a dataset
             by adding qualifiers to DSET.
           Append #SEL# to select certain nodes.
           Append [SEL] to select certain columns.
           Append {SEL} to select certain rows.
           The format of SEL is the same as in AFNI, see section:
           'INPUT DATASET NAMES' in 3dcalc -help for details.
           Append [i] to get the node index column from
                      a niml formatted dataset.
           *  SUMA does not preserve the selection order 
              for any of the selectors.
              For example:
              dset[44,10..20] is the same as dset[10..20,44]
              Also, duplicate values are not supported.
              so dset[13, 13] is the same as dset[13].
              I am not proud of these limitations, someday I'll get
              around to fixing them.



 SUMA mask options:
      -n_mask INDEXMASK: Apply operations to nodes listed in
                            INDEXMASK  only. INDEXMASK is a 1D file.
      -b_mask BINARYMASK: Similar to -n_mask, except that the BINARYMASK
                          1D file contains 1 for nodes to filter and
                          0 for nodes to be ignored.
                          The number of rows in filter_binary_mask must be
                          equal to the number of nodes forming the
                          surface.
      -c_mask EXPR: Masking based on the result of EXPR. 
                    Use like afni's -cmask options. 
                    See explanation in 3dmaskdump -help 
                    and examples in output of 3dVol2Surf -help
      NOTE: Unless stated otherwise, if n_mask, b_mask and c_mask 
            are used simultaneously, the resultant mask is the intersection
            (AND operation) of all masks.


   [-novolreg]: Ignore any Rotate, Volreg, Tagalign, 
                or WarpDrive transformations present in 
                the Surface Volume.
   [-noxform]: Same as -novolreg
   [-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname
                to be ENVvalue. Quotes are necessary.
             Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'"
                See also options -update_env, -environment, etc
                in the output of 'suma -help'
  Common Debugging Options:
   [-trace]: Turns on In/Out debug and Memory tracing.
             For speeding up the tracing log, I recommend 
             you redirect stdout to a file when using this option.
             For example, if you were running suma you would use:
             suma -spec lh.spec -sv ... > TraceFile
             This option replaces the old -iodbg and -memdbg.
   [-TRACE]: Turns on extreme tracing.
   [-nomall]: Turn off memory tracing.
   [-yesmall]: Turn on memory tracing (default).
  NOTE: For programs that output results to stdout
    (that is to your shell/screen), the debugging info
    might get mixed up with your results.


Global Options (available to all AFNI/SUMA programs)
   -overwrite: Overwrite existing output dataset.
               Equivalent to setting env. AFNI_DECONFLICT=OVERWRITE
   -ok_1D_text: Zero out uncommented text in 1D file.
                Equivalent to setting env. AFNI_1D_ZERO_TEXT=YES
   -Dname=val: Set environment variable 'name' to value 'val'
             For example: -DAFNI_1D_ZERO_TEXT=YES
   -Vname=: Print value of environment variable 'name' to stdout and quit.
            This is more reliable that the shell's env query because it would
            include envs set in .afnirc files and .sumarc files for SUMA
            programs.
             For example: -VAFNI_1D_ZERO_TEXT=
   -all_opts: Try to identify all options for the program from the
              output of its -help option. Some options might be missed
              and others misidentified. Use this output for hints only.
   -h_find WORD: Look for lines in this programs's -help output that match
                 (approximately) WORD.
   -h_view: Open help in text editor. AFNI will try to find a GUI editor
            on your machine. You can control which it should use by
            setting environment variable AFNI_GUI_EDITOR.
   -h_web: Open help in web browser. AFNI will try to find a browser
            on your machine. You can control which it should use by
            setting environment variable AFNI_GUI_EDITOR.
   -skip_afnirc: Do not read the afni resource (like ~/.afnirc) file.
   -pad_to_node NODE: Output a full dset from node 0 to MAX_NODE-1
                   ** Instead of directly setting NODE to an integer you 
                      can set NODE to something like:
                   ld120 (or rd17) which sets NODE to be the maximum 
                      node index on an Icosahedron with -ld 120. See 
                      CreateIcosahedron for details.
                   d:DSET.niml.dset which sets NODE to the maximum node found
                      in dataset DSET.niml.dset.
                   ** This option is for surface-based datasets only.
                      Some programs may not heed it, so check the output if
                      you are not sure.
   -pif SOMETHING: Does absolutely nothing but provide for a convenient
                   way to tag a process and find it in the output of ps -a
   -echo_edu: Echos the entire command line to stdout (without -echo_edu)
              for edification purposes



Compile Date:
   May 10 2013

       Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov     
This page auto-generated on Sat May 11 16:36:57 EDT 2013