AFNI program: suma

Output of -help


Usage:  
 Mode 0: Just type suma to see some toy surface and play
         with the interface. Some surfaces are generated
         using T. Lewiner's MarchingCubes library. 
         Use '.' and ',' keys to cycle through surfaces.

 Mode 1: Using a spec file to specify surfaces
                suma -spec <Spec file> 
                     [-sv <SurfVol>] [-ah AfniHost]

 Mode 2: Just show me the money
                suma <-i SomeSurface> 
                     [-sv <SurfVol>] [-ah AfniHost]


 Mode 1:
   -spec <Spec file>: File containing surface specification. 
                      This file is typically generated by 
                      @SUMA_Make_Spec_FS (for FreeSurfer surfaces) or 
                      @SUMA_Make_Spec_SF (for SureFit surfaces). 
                      The Spec file should be located in the directory 
                      containing the surfaces.
   [-sv <SurfVol>]: Anatomical volume used in creating the surface 
                    and registerd to the current experiment's anatomical 
                    volume (using @SUMA_AlignToExperiment). 
                    This parameter is optional, but linking to AFNI is 
                    not possible without it.If you find the need for it 
                    (as some have), you can specify the SurfVol in the 
                    specfile. You can do so by adding the field 
                    SurfaceVolume to each surface in the spec file. 
                    In this manner, you can have different surfaces using
                    different surface volumes.
   [-ah AfniHost]: Name (or IP address) of the computer running AFNI. 
                     This parameter is optional, the default is localhost.
                     When both AFNI and SUMA are on the same computer, 
                     communication is through shared memory. 
                     You can turn that off by explicitly setting AfniHost
                     to 127.0.0.1
   [-niml]: Start listening for NIML-formatted elements.

 Mode 2: Using -t_TYPE or -t* options to specify surfaces on command line.
         -sv, -ah, -niml and -dev are still applicable here. This mode 
         is meant to simplify the quick viewing of a surface model.
                suma [-i_TYPE surface] [-t* surface] 
         Surfaces specified on command line are place in a group
         called 'DefGroup'.
         If you specify nothing on command line, you will have a random
         surface created for you. Some of these surfaces are generated
         using Thomas Lewiner's sample volumes for creating isosurfaces.
         See suma -sources for a complete reference.

 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.

 Modes 1 & 2: You can mix the two modes for loading surfaces but the -sv
              option may not be properly applied.
              If you mix these modes, you will have two groups of
              surfaces loaded into SUMA. You can switch between them
              using the 'Switch Group' button in the viewer controller.

   [-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

   [-visuals] Shows the available glxvisuals and exits.
   [-version] Shows the current version number.
   [-environment] Shows a list of all environment variables, 
                  their default setting and your current setting.
                  The output can be used as a new .sumarc file.
                  Since it takes into consideration your own settings
                  this command can be used to update your .sumarc 
                  regularly with a csh command like this:

           suma -environment > ~/sumarc && \
             cp ~/.sumarc ~/.sumarc-bak ; \
             mv ~/sumarc ~/.sumarc


   -np PORT_OFFSET: Provide a port offset to allow multiple instances of
                    AFNI <--> SUMA, AFNI <--> 3dGroupIncorr, or any other
                    programs that communicate together to operate on the same
                    machine. 
                    All ports are assigned numbers relative to PORT_OFFSET.
         The same PORT_OFFSET value must be used on all programs
           that are to talk together. PORT_OFFSET is an integer in
           the inclusive range [1025 to 65500]. 
         When you want to use multiple instances of communicating programs, 
           be sure the PORT_OFFSETS you use differ by about 50 or you may
           still have port conflicts. A BETTER approach is to use -npb below.
   -npq PORT_OFFSET: Like -np, but more quiet in the face of adversity.
   -npb PORT_OFFSET_BLOC: Simliar to -np, except it is easier to use.
                          PORT_OFFSET_BLOC is an integer between 0 and
                          MAX_BLOC. MAX_BLOC is around 4000 for now, but
                          it might decrease as we use up more ports in AFNI.
                          You should be safe for the next 10 years if you 
                          stay under 2000.
                          Using this function reduces your chances of causing
                          port conflicts.

         See also afni and suma options: -list_ports and -port_number for 
            information about port number assignments.

         You can also provide a port offset with the environment variable
            AFNI_PORT_OFFSET. Using -np overrides AFNI_PORT_OFFSET.

   -max_port_bloc: Print the current value of MAX_BLOC and exit.
                   Remember this value can get smaller with future releases.
                   Stay under 2000.
   -max_port_bloc_quiet: Spit MAX_BLOC value only and exit.
   -num_assigned_ports: Print the number of assigned ports used by AFNI 
                        then quit.
   -num_assigned_ports_quiet: Do it quietly.

     Port Handling Examples:
     -----------------------
         Say you want to run three instances of AFNI <--> SUMA.
         For the first you just do: 
            suma -niml -spec ... -sv ...  &
            afni -niml &
         Then for the second instance pick an offset bloc, say 1 and run
            suma -niml -npb 1 -spec ... -sv ...  &
            afni -niml -npb 1 &
         And for yet another instance:
            suma -niml -npb 2 -spec ... -sv ...  &
            afni -niml -npb 2 &
         etc.

         Since you can launch many instances of communicating programs now,
            you need to know wich SUMA window, say, is talking to which AFNI.
            To sort this out, the titlebars now show the number of the bloc 
            of ports they are using. When the bloc is set either via 
            environment variables AFNI_PORT_OFFSET or AFNI_PORT_BLOC, or  
            with one of the -np* options, window title bars change from 
            [A] to [A#] with # being the resultant bloc number.
         In the examples above, both AFNI and SUMA windows will show [A2]
            when -npb is 2.

   [-list_ports]  List all port assignments and quit
   [-port_number PORT_NAME]: Give port number for PORT_NAME and quit
   [-port_number_quiet PORT_NAME]: Same as -port_number but writes out 
                                    number only
   [-dev]: Allow access to options that are not well polished for
           mass consuption.
   [-update_env] Performs the set operations detailed under -environment
   [-default_env] Output hard coded default environment values, ignoring
                  user settings.
   [-latest_news] Shows the latest news for the current 
                  version of the entire SUMA package.
   [-all_latest_news] Shows the history of latest news.
   [-progs] Lists all the programs in the SUMA package.
   [-motif_ver] Displays the linked version of Motif.
   [-sources] Lists code sources used in parts of SUMA.
   [-help_nido] Help message for displayable objects of type NIDO

   For help on interacting with SUMA, press 'ctrl+h' with the mouse 
   pointer inside SUMA's window.
   For more help: http://afni.nimh.nih.gov/pub/dist/edu/latest/suma/suma.pdf

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

   
Compile Date:
   May 31 2013



    Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov 
This page auto-generated on Mon Jun 3 08:38:24 EDT 2013