:orphan: .. _ahelp_suma: **** suma **** .. contents:: :local: | .. code-block:: none 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 [-sv ] [-ah AfniHost] Mode 2: Just show me the money suma <-i SomeSurface> [-sv ] [-ah AfniHost] Mode 1: -spec : 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. As with option -i, you can load template spec files with symbolic notation trickery as in: suma -spec MNI_N27 which will load the all the surfaces from template MNI_N27 at the original FreeSurfer mesh density. The string following -spec is formatted in the following manner: HEMI:TEMPLATE:DENSITY where: HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh', 'rh', 'lr', or 'both' which is the default if you do not specify a hemisphere. TEMPLATE: Specify the template name. For now, choose from MNI_N27 if you want surfaces from the MNI_N27 volume, or TT_N27 for the Talairach version. Those templates must be installed under this directory: /home/afniHQ/.afni/data/ If you have no surface templates there, download one of: https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI152_2009.tgz and untar them under directory /home/afniHQ/.afni/data/ DENSITY: Use if you want to load standard-mesh versions of the template surfaces. Note that only ld20, ld60, ld120, and ld141 are in the current distributed templates. You can create other densities if you wish with MapIcosahedron, but follow the same naming convention to enable SUMA to find them. This parameter is optional. The order in which you specify HEMI, TEMPLATE, and DENSITY, does not matter. For template surfaces, the -sv option is provided automatically, so you can have SUMA talking to AFNI with something like: suma -spec MNI_N27:ld60 & afni -niml /home/afniHQ/.afni/data/suma_MNI_N27 [-sv ]: 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 communications with NIML-formatted elements. Environment variable SUMA_START_NIML can also be used to start listening. [-noniml]: Do not start listening for communications with NIML-formatted elements, even if env. SUMA_START_NIML is set to YES 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 displayable objects: -cdset CDSET: Load and display a CIFTI dataset -gdset GDSET: Load and display a graph dataset -tract TRACT: Load and display a tractography dataset -vol VOL: Load and display a volume 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. stl: STL format, ascii or binary. This format of no use for much of the surface-based analyses. Objects are defined as a soup of triangles with no information about which edges they share. STL is only useful for taking surface models to some 3D printing software. 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. obj: OBJ file format for triangular meshes only. The following primitives are preserved: v (vertices), f (faces, triangles only), and p (points) 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. You can also specify multiple surfaces after -i option. This makes it possible to use wildcards on the command line for reading in a bunch of surfaces at once. -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. More variants for option -i: ----------------------------- You can also load standard-mesh spheres that are formed in memory with the following notation -i ldNUM: Where NUM is the parameter controlling the mesh density exactly as the parameter -ld linDepth does in CreateIcosahedron. For example: suma -i ld60 create on the fly a surface that is identical to the one produced by: CreateIcosahedron -ld 60 -tosphere -i rdNUM: Same as -i ldNUM but with NUM specifying the equivalent of parameter -rd recDepth in CreateIcosahedron. To keep the option confusing enough, you can also use -i to load template surfaces. For example: suma -i lh:MNI_N27:ld60:smoothwm will load the left hemisphere smoothwm surface for template MNI_N27 at standard mesh density ld60. The string following -i is formatted thusly: HEMI:TEMPLATE:DENSITY:SURF where: HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh' or 'rh'. You must specify a hemisphere with option -i because it is supposed to load one surface at a time. You can load multiple surfaces with -spec which also supports these features. TEMPLATE: Specify the template name. For now, choose from MNI_N27 if you want to use the FreeSurfer reconstructed surfaces from the MNI_N27 volume, or TT_N27 Those templates must be installed under this directory: /home/afniHQ/.afni/data/ If you have no surface templates there, download https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz and/or https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz and/or https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI152_2009.tgz and untar them under directory /home/afniHQ/.afni/data/ DENSITY: Use if you want to load standard-mesh versions of the template surfaces. Note that only ld20, ld60, ld120, and ld141 are in the current distributed templates. You can create other densities if you wish with MapIcosahedron, but follow the same naming convention to enable SUMA to find them. SURF: Which surface do you want. The string matching is partial, as long as the match is unique. So for example something like: suma -i l:MNI_N27:ld60:smooth is more than enough to get you the ld60 MNI_N27 left hemisphere smoothwm surface. The order in which you specify HEMI, TEMPLATE, DENSITY, and SURF, does not matter. For template surfaces, the -sv option is provided automatically, so you can have SUMA talking to AFNI with something like: suma -i l:MNI_N27:ld60:smooth & afni -niml /home/afniHQ/.afni/data/suma_MNI_N27 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. 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. 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) -h: Mini help, at time, same as -help in many cases. -help: The entire help output -HELP: Extreme help, same as -help in majority of cases. -h_view: Open help in text editor. AFNI will try to find a GUI editor -hview : 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. -hweb : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_find WORD: Look for lines in this programs's -help output that match (approximately) WORD. -h_raw: Help string unedited -h_spx: Help string in sphinx loveliness, but do not try to autoformat -h_aspx: Help string in sphinx with autoformatting of options, etc. -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. [-visuals] Shows the available glxvisuals and exits. [-brethren_windows] For Testing Only. Show a listing of windows possibly related to AFNI and SUMA. [-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 [-drive_com DRIVE_SUMA_COM]: Drive suma with command DRIVE_SUMA_COM, which has the same syntax that you would use for DriveSuma. For instance: suma -i ld120 -drive_com '-com surf_cont -view_surf_cont y' or suma -drive_com '-com viewer_cont -key 'F12' -com kill_suma' You can use repeated instances of -drive_com to have a series of commands that get executed in the order in which they appear on the command line. [-clippingPlaneVerbose []] Give verbose output in clipping plane mode. The default verbosity is 1, meaning it only tells when an action toggles a state or selects a plane. A higher verbosity integer (current maximum 2) gives more detailed information about what is happening. -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: Similar 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. -help_clipping_planes: Clipping planes to view 3D region of interest. -help_interactive: Write the help for interactive usage into file Mouse_Keyboard_Controls.txt -help_sphinx_interactive HOUT: Write the help for interactive usage into SPHINX formatted file HOUTSee DriveSuma's -write_*_help options for more -test_help_string_edit: Show example of help string editing and quit -test_help_string_edit_web: Like its prefix, but nicer for webpage. [-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. [-fake_cmap]: Use X11 to render cmap. This is only needed to get colorbar to appear when the frame is automatically captured by SUMA for making documentation. This option has no other use. [-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: https://afni.nimh.nih.gov/pub/dist/edu/latest/suma/suma.pdf If you can't get help here, please get help somewhere. Compile Date: Oct 13 2022 Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov Peter D. Lauren SSCC/NIMH/NIH laurenpd@mail.nih.gov