6.2. SUMA Viewer

6.2.1. Surface Viewing

This is a walk through the basics of surface navigation. To follow along you will need the suma_demo directory installed.

To begin we go into the demo directory and launch suma and afni with the following commands:

cd suma_demo/afni
afni -niml &
tcsh run_suma &


The script run_suma does little more than launch suma with the command:

suma  -spec ../SurfData/SUMA/std.DemoSubj_both.spec        \
      -sv DemoSubj_SurfVol_Alnd_Exp+orig

You should have AFNI up by now, and SUMA soon after, seeing the following pieces:

SUMA viewer:
smoothed WM surfaces
AFNI slice viewer:
anat with overlay
AFNI controller:
control overlay display
../_images/surfview.0000.jpg ../_images/surfview.0001.jpg ../_images/surfview.0002.jpg

Quick Tour

  1. Talking to AFNI

    Press the t in the suma window to talk to afni. This sends anatomically correct surfaces to AFNI.

    You should be seeing surface contours atop the slices; the contours are the intersection of the surface with the slice.

    AFNI slice view with anatomically correct surfaces


    You should also see boxes representing the nodes that are within +/-1/2 slice from the center of the slice in view. Colors and node box visibility can be changed to suit your desires from the Control Surface button in AFNI.

  2. Navigating through the volume in AFNI

    Check to make sure you have an excellent alignment between volume and surface. Also make sure surface adequately represents areas of the brain that are difficult to segment:

    • occipital cortex

    • inferior frontal and inferior temporal regions

    The surface may look good in suma, but it might not actually match anatomy in some places – this is why you check surfaces in the AFNI display.

    The Surface Volume and the surfaces must be in nearly perfect alignment.

    1. If you have an improper alignment, it should be addressed here and now. This should not happen for FreeSurfer and SureFit/Caret surfaces created in the standard fashion with @SUMA_Make_Spec_FS or @SUMA_Make_Spec_Caret, say. Problems might come up when you attempt to align data across days with @SUMA_AlignToExperiment. See also Align_Surf_Vol

    2. Watch for error messages and warnings to come up in the shell as all the surfaces are read in. These messages should be examined once per subject since they do not change unless the surface’s geometry or topology is changed.

    3. Viewed without the volume underal, it is extremely difficult to tell if surface models with no topological defects accurately represent the cortical surface.

  3. Rotating the surface

    Use Button 1 drag: keep it down while moving the mouse left to right. This rotates the surface about the screen’s Y-axis (dotted green if screen axes are displayed). Let go of button-1 (usually the left button).

    Repeat the left-click and drag, and move the mouse up and down in order to rotate about the X-axis; and move the mouse in various directions for rotations mimicking those of a trackball interface.

    Also try up/down, left/right arrow keys.

    • Arrow keys rotate by increments specified by the unix environment variable SUMA_ArrowRotAngle in degrees.

    • You can set SUMA environment variables in file ~/.sumarc. See also option -update_env in suma.

  4. Prying & Z rotating the hemispheres

    Use Ctrl+button-1, drag: move the mouse horizontally while button 1 is pressed and ctrl is down will pry hemispheres apart for better visualization. The prying behavior is different for spherical and flattened surfaces. Better try it than read about it. See also F10

    Prying anatomically correct surfaces


    Prying flat surfaces


    Use Ctrl+button-1 double click: undo prying.

    Use Shift+button-1 drag: Rotate surfaces about screen’s Z-axis. This option is useful for positioning flat surfaces when displayed one at a time. In most other circumstances, it leads to confusion.

    Use Shift+button 1 double click: Undo Z rotation.

  5. Translating surfaces

    • Button-2 drag: keep it down while moving the mouse to translate surface along screen X and Y axes or any combinations of the two.

    • Also try Shift+arrow keys.

  6. Zooming in/out

    • Both Buttons 1&2 or Shift+button2: while pressing buttons, move mouse down or up to zoom in and out, respectively.

    • Also try keyboard buttons Z and z for zooming in and out, respectively.

  7. Picking a Node or a Facet

    • Button 3: press over a location on a surface to pick the closest facet and node to the location of the pointer.

    • The closest node is highlighted with a blue sphere

    • The closest facet is highlighted with a gray triangle


      The little crosshair that could

    • Note the information written to the shell regarding the properties of the picked Node and Facet.

    • When connected to AFNI (after having pressed t), watch the AFNI crosshair jump to the corresponding location in the volume.

    • Conversely, position the crosshair in AFNI (a left click there) at a position close to the surface and watch the crosshari relocate in SUMA.

    • You can swap buttons 1 & 3’s functions using the environment variable SUMA_SwapButtons_1_3

  8. Cardinal views (along coordinate directions)

  9. Momentum feature

    • Press m to toggle momentum on. Click the left mouse button and release it as you are dragging the mouse. It should feel like you’re throwing the surface.

  10. Lots more!

    • Function keys modify various aspects of the display

      • Those may be usurped by OS X, see Keyboard Setup or try key modifiers to get them to work.

      • See SUMA‘s help or Keyboard Controls for all interactive options.

  11. Recording your images

    • Press r in the viewer to record the current scene. The image is captured in an AFNI flavored window. Successive record commands get saved in the same viewer.


      The record viewer acquires a GUI interface the moment it has more than one image in it. The interface is the same as that in AFNI. If you want to save a single captured image to disk, use ‘Alt+Right Click’ in the recorder window to pop a save menu which allows you to enter prefix of the image and more.

      When more than one image are captured in the recorder, you have numerous options to control the recording process. Consider turning off Disp->Save One to record multiple images in one pass. This changes the save button from Sav1.jpg to Save.jpg. If you’ve read this far, you should stop reading and try it for yourself.


      This was a post-bac

    • Press r on the colorbar of the surface controller records an image of the colorbar.

    • Press R to record continuously from the viewer. Doing so puts the viewer in Recording Mode where any operation that causes a change in the rendered image is directly captured in the recorder.

      • Identical consecutive images are rejected

      • Images caused by window expose events are ignored

      • If you let the recorder run continuously with very large images, you might quickly run out of memory on your computer.

    • Use Ctrl+r to capture the image directly to disk intead of to the recorder.

    • Similarly, Ctrl+R records continuously to disk

    • You can save/load viewer setting used to create a figure with File->Save View / File->Load View

  12. Viewing a group of surfaces

    • Use . (period) to switch to the next viewing state (pial then inflated, …)

    • Use , (comma) to switch to the previous vieweing state

    • Navigate on any of the surfaces and watch AFNI’s crosshair track the surface

    • Use SPACE to toggle between the current state and the state of the Local Domain Parent

  13. Viewing multiple surfaces concurrently

    • Ctrl+n opens a new SUMA controller (up to 10 allowed, more possible, but ridiculous).

    • Swith states in any of the viewers

    • all viewers are still connected to AFNI (if any are)

    • See the SUMA controller for controlling the link between viewers.

  14. Viewing datasets

    • Open the surface controller (Ctrl+s if you forgot), and press Load Dset.


      The controller of surfaces

    • From the available options, select one of v2s.lh.TS.niml.dset, or v2s.rh.TS.niml.dset.

      • One of the two should be available to you depending on which hemisphere is currently in focus. Contralateral dataset, if sanely named, gets automatically loaded onto the contralateral hemisphere.

      • To graph the time series, at the cross hair press g in SUMA. The graph window is wedded to the hemisphere in focus. You will need to press g on the contralateral hemisphere to get a graph for that hemisphere too.

      • Select other nodes or Right-Click+Drag

      • Press Freeze on graph window to preserve current graph. Clicking on other nodes will start a new graph


        For more help on graph window usage, including for instance how to save the time series, type ctrl+h with the graphing window in focus. (link)

      • Now let’s look at a delay dataset (computed with 3ddelay). Press Load Dset and load one of v2s.lh.DEL.niml.dset or v2s.rh.DEL.niml.dset. SUMA will colorize the loaded dataset thereby creating a color plane for it, and will display it on the top of the pre-existing color planes.

      • We begin by describing the right side block Dset Mapping which is used to colorize a dataset. Many of the options mimic those in AFNI’s Define Overlay controls.


        Many features are not mentioned here, use BHelp or WHelp interactively or the online help for the controller you are using, here the surface controller.

      • From the Dset Mapping block on the right side of the interface


        Dset colormapping GUI.

        Should it look different, consider the more updated documentation here

      • Select column Corr. Coef. for the Threshold

      • Press v button to apply thresholding.

      • Use the scale to set the threshold. Nodes whose cross correlation value does not pass the threshold will not get colored.

      • Note p (uncorrected), and q values (FDR) below the slider. FDR values are per-hemisphere


        • For simplicity, we mapped a statistical dataset onto the surface (see script run_3dVol2Surf under suma_demo/afni). This resulted in statistical parameters being averaged with being normalized.

        • A better approach would be to map the time series, and then perform the statistical computation. See script run_3dVol2Surf for examples.

  15. Mapping Parameters Table

    This is located below the I, T, B selectors.

    • Used for setting the clipping ranges.

    • Clipping is only done for color mapping. Actual data values do not change.

    • See detailed help here.

    • Note that a Left click on the ‘I’ locks ranges from automatic resetting when you choose a different dataset column for I. A right click on ‘I’ resets values to full range in data.

    • For color mapping controls see Col, New, Cmp, etc.

    • Bored? Try Bias for a change.

      The colormap is rendered as a surface, and shares some of the functions of SUMA’s viewer. You have keyboard controls when the mouse is over the colorbar. More info here and there.

  16. Interactive clustering

    • Left click on Clst to activate/deactivate clustering. Cluster table is output to the shell. Clicking on a node shows its cluster label in the viewer.

    • For more information, resort to the help for the Surface Controller and Plane Layering.


Most of what was done for a surface-based dataset applies to volumetric and connectivity data.

6.2.2. Volume Viewing

We present a brief example of viewing volumes in SUMA. This particular case is one of looking at: probabilistic tractography results (which are volumes), along with the target network that we input (also volumes). We’ll load in the FA map from the DTI fits and view it as slices for locating us in space. Finally, we can load in the dset of structural connectivity for further information (labels, graph connection and connectivity matrix viewing), but in this example we won’t use it much, actually. Commands of note will be highlighted with dashed ellipsoids (ell) for ease of finding.

  1. To load in the appropriate data sets into suma, we use the following commandline call from within the FATCAT_DEMO/DTI/ directory (assuming that you have run the scripts therein, you can follow along at home). We are loading in most data as volumes (to be viewed as either surfaces or slices), with the *.dset file accompanying:

    suma                                       \
        -vol o.NETS_AND_000_PAIRMAP+orig[0]    \
        -vol DT_FA+orig                        \
        -vol ../ROI_ICMAP_GMI+orig[0]          \
        -gdset o.NETS_AND_000.niml.dset

    The following image is what we get (you may have different defaults for some minor characteristics on your own machine, but this is basically what should appear):



    Volumes by default are viewed as slices, and in grayscale, so we mostly see the FA map and not the PAIRMAP of tract results nor the target ROI map. That default can be changed via environment variable SUMA_VO_InitSlices in your .sumarc file. If you have a volume rendered in 3D at this stage, turn that off with the v button. The dset is represented as a graph, showing the centers-of-mass of the target ROIs with yellow spheres, and the locations of tractographic bundles on lines, colored by a matrix property in the dset.

  2. To really get going, let’s open up the controller, using either “View -> Object Controller” or just the shortcut “CTRL + s” while the SUMA viewer is foremost on the screen. Now we have the viewer and the controller:



    Each data object (here, volume or dset) will have its own control panel, which we can toggle through using the small up/down triangle “Switch” at the top of the panel (magenta ell.). But first, we need to tell SUMA to prepare each panel, which we can most easily do by hitting the “All Objs.” button (orange ell.). After this, you can try toggling through each control panel, if you wish. (NB: this useful button appeared in Jan, 2015, so if you don’t see, please update your AFNI/SUMA distribution!)

  3. Toggle to the PAIRMAP file using the switches at the top, seeing the correct file name, in this case o.NETS_AND_000_PAIRMAP+orig[0] (magenta ell):



    This zeroth brick contains a mask of all the WM ROIs found between any pair of targets in the image. Right now, it’s being shown as slices, so it’s hard to appreciate. Let’s view these results as the surface of the volume.

    Firstly, turn off the slice viewing, by unchecking the slice viewers, if they currently are highlighted (green ell.). Then, turn on the surface viewing for the volume, by highlighting the ‘v’ in the “Volume Rendering Controls” (blue ell). Additionally, in this same part of the panel, you can adjust the density of surface rendering points, by changing the number in the ‘Ns’ box; this parameter is now set to the maximum number of slices in the volume. Increasing the number beyond this value does not help much, decreasing the number speeds up the rendering at the cost of more artifacts.

  4. What you should see now is a big, gray mass of tract volume, as in the SUMA Viewer window here:



    To change the colorscheme of the PAIRMAP (though, it is just a binary mask in this case), we can go to the ‘Cmp’ button in the Controller panel (magenta ell).

  5. Right-click on the ‘Cmp’ button, which opens up a list of colormaps:



    and you can scroll through the list until you find something nice and visually pleasing, for example:



    Ok, so that completes viewing that volume.

  6. Now, let’s say we want to turn off the viewing of the dset data. First, use the top arrows by the ‘Switch’ to go to the appropriate Control panel, until you see something that says “GMATRIX_DOlink…” at the top (magenta ell). NB for dsets: the label here is not the filename in this case, but I think that what is shown is a string inside the file– seeing ‘MATRIX’ should help identify it:



    To not see any graph stuff, we’ll just raise the threshold for the colorbar from ‘0’ (green ell) all the way to the top. Doing so (blue ell in next figure), results in a farwell to labels and edges:



    If you have no use for the dset at this time, you also didn’t have to load it into the SUMA viewer, either.

  7. Ok, quickly now, let’s practice again by viewing the target ROI network as surfaces. So, toggle to the panel with that volume’s filename (here, “../ROI_ICMAP_GMI+orig”), and turn off the Slice viewing and turn on the volume viewing, as done above, resulting in a panel and viewer that look like the following (I’ve just highlighted the locations from above where we had adjusted viewing controls):



  8. Again, we can make the volumes have a non-grayscale colormap for viewing. In this case, each target ROI has a separate integer, so a nice colorscheme could be the “ROI_i*” ones, or here I’ll pick “Spectrum:red_to_blue+gap” from the ‘Cmp’ list (green ell in the following) for no particular reason:



  9. And that’s pretty much that! You can view the results from different angles, and note that you can select voxels rendered in 3D much like you can select voxels on slices, tracts, etc.:





6.2.3. Tract Viewing

This is a walk through the basics of tract navigation. To follow along you will need the FATCAT Visualization directory installed.

Quick Tour

  1. A first look at the tracts

    To begin we go into the demo directory and launch suma and afni with the following commands:

    afni -niml -npb 12 -yesplugouts -layout demo_layout             \
                mprage+orig.HEAD DTI/*.HEAD ROI_ICMAP_GMI+orig.HEAD &
    suma -dev -npb 12 -niml -vol mprage+orig.                       \
                -tract DTI/o.WB_000.niml.tract  &


    The script Do_06_VISdti_SUMA_visual_ex1.tcsh contains the same commands used above. You might want to chek out the help for option -npb.

    You should have AFNI up by now, and SUMA soon after.








    Right-click on the tracts to select a location along them. The crosshair should mark the location along the tract where you clicked. The selection would make AFNI jump to the same mm location if the two programs are talking. To make them talk, press t in the suma windowto get them talking and try the selections again.

    Left- middle-mouse buttons operate as they do for surface viewing.

    Open the tract controller via View‣ Object Controllers or Ctrl+s. Select locations anew and examine controller update coordinates and selection information.

  2. InstaTract, or interactive mask selection

    Create a mask by clicking on Masks in the tract controller. This creates a masking sphere and only tracts going through it are displayed.



    To move the sphere right-double click on it to place SUMA in Mask Manipulation Mode which is indicated by displaying the ball as a mesh.


    SUMA in mask manipulation mode


    Selection of voxel while in mask manipulation mode repositions mask at selected voxel.


    Selecting a location on the tracts will make the ball jump to that location. Clicking on the slices or surfaces whenever present, will position the mask at the selected voxel, or surface node. If you select while dragging, the selection is only made on the type of object on which you began the selection. For instance, if you select a location on the tracts and start dragging without releasing the right-mouse button, the ball will track along non-masked tracts that fall under your pointer, even if you go over surfaces or slices that are closer to your viewpoint.

    Tracts that fall outside of the mask are hidden by default. You can also choose to display them in gray scale or in dimmed colors by manipulating the hiding option.


    Hidden tracts shown in gray.


    Hidden tracts shown in dimmed color


    The mask should also be visibile in AFNI. Clicking in AFNI will make the mask move in SUMA also.


    Crosshair movements in AFNI while SUMA is in mask manipulation mode will reposition the ball at the selected voxel’s center (link).

    You can manipulate the size of the mask with Ctrl+Scroll (go slow!) or with the masks controller interface mentioned below.



    To turn off ‘Mask Manipulation Mode’, right-double click in open air, or on the ball itself.

    Another click on Masks will also open the masks controller, which allows for complex masking configurations. Check out the mask controller’s link for information on how to manipluate the mask in detail.

  3. Looking at tracts within blobs making up one ROI

    Here we are showing those tracts that go through any of the ROIs in the DMN per the results of deterministic tracking in 3dTrackID that were generated in script Do_05_RUNdti_DET_tracking.tcsh of FATCAT_Demo.

    This example is from the second part of demo script Do_06_VISdti_SUMA_visual_ex1.tcsh. Close the old AFNI & SUMA windows and launch new ones with the following commands:

    @Quiet_Talkers -npb_val 12
    afni                                                                \
        -npb 12                                                         \
        -niml -yesplugouts -layout demo_layout                          \
         mprage+orig.HEAD                                               \
         DTI/*.HEAD ROI_ICMAP_GMI+orig.HEAD &
    plugout_drive                                                       \
        -npb 12                                                         \
        -com 'SET_FUNCTION o.NETS_OR_000_INDIMAP+orig 0 0'              \
        -com 'SET_THRESHOLD 0'                                          \
        -com 'SET_ANATOMY mprage+orig'                                  \
        -com 'SET_DICOM_XYZ 18 7 -10'                                   \
    suma                                                                \
        -npb 12                                                         \
        -niml -onestate                                                 \
        -vol mprage+orig.                                               \
        -i Net_000.gii                                                  \
        -tract DTI/o.NETS_OR_000.niml.tract &
    DriveSuma                                                           \
        -npb 12                                                         \
        -com surf_cont -surf_label Net_000.gii                          \
        -switch_cmap amber_monochrome -Dim 1.0                          \
        -com viewer_cont -key '.' -key 't'


    The suma command now includes a set of surfaces representing the ROIs. Those were created with program IsoSurface in script Do_05_RUNdti_DET_tracking.tcsh of FATCAT_Demo.




    Colors indicate the number of tracts passing through a voxel (link). Search for INDIMAP in the help for program 3dTrackID.




  1. By default, points along the tracts are colored based on their local orientation. You can also color them based on the orientation of their midpoint with Switch Dset ‣ o.NETS_OR_000_MID accessible from the tract controller. You can also color by bundle with Switch Dset ‣ o.NETS_OR_000_BUN, however there is only one bundle in this set of tracts because there is only one ROI involved - all the blobs are part of the same ROI in this example.


    Tract coloring by direction at mid tract


    Tract coloring by bundle. All tacts are part of the same bundle here.


  2. If you’re feeling adventurous, open the controllers for the surface forming the ROIs by selecting a point on the surface (the controller is created automatically once the controller notebook is open), and on a point of the volume to create the volume controller. For the image blow, I hid the surface with Drw, hid the sagittal slice from the volume controller, set the transparency to 8, then turned on the 3D rendering with v.



  3. Whole brain tractography results with surfaces.

    This example is based on script Do_09_VISdti_SUMA_visual_ex2.tcsh of FATCAT_Demo. You can run it to launch the demo automatically, or do it the hard way with:

    @Quiet_Talkers -npb_val 12
    suma                                       \
        -npb 12 -niml                          \
        -spec SUMA/std.60.FATCAT_both.spec     \
        -sv mprage+orig                        \
        -vol mprage+orig.                      \
        -tract DTI/o.WB_000.niml.tract &

    The command uses the same data used in the Do_06 script, and in paragraph 1 of the quick tour above, except that we are also showing the cortical surfaces loaded via option -spec.

    Open the object controllers for volume, tracts, and surfaces. Select a tract and create a tract mask. As mentioned earlier, the mask can be positioned on the surfaces, just as you would position it on the tracts or the slices. However the surfaces obstruct the view and tracts are not visible. You could make them transparent (press o twice in SUMA) but that may not be ideal. Another option is to pry the surfaces apart with ctrl+click and drag, left right, and/or up down. You can now position the mask on the pried surfaces and have the same masking effect. When the surfaces are pried apart, a doppleganger of the mask is shown on the displaced surfaces, and the mask ball is shown in the anatomically correct location.

    Walk along the corpus callosum, for instance, and watch tracts follow along. When talking to AFNI, correspondence between pried surfaces and locations in the volume is maintained throughout.


    You can position the mask on the surface but few of the tracts are visible this way. (link)


    Surface pried open and viewer opacity turned off with two more o. clicks (link). You can continue to position the mask on the pried surfaces.


    Turning on 50% transparency for all objects by clicking o twice - not thrice - helps, but not that cool (link).



    For more on prying, see Prying Brains Apart and the F10 key.

  4. For more anatomical connectivity excitement, follow along with remaining demos in script Do_09_VISdti_SUMA_visual_ex2.tcsh and remaining Do_*VIS* scripts of FATCAT_Demo.

6.2.4. Graph Viewing

This is a walk through the basics of graph (connectivity matrix) navigation. To follow along you will need the FATCAT Visualization directory installed.

For starters, we need to go into the demo directory and launch suma and afni with the following commands:

@Quiet_Talkers -npb_val 12


afni                                                     \
    -npb 12 -niml -yesplugouts -layout demo_layout       \
    *.HEAD DTI/*.HEAD &

cd DTI/

suma                                                     \
    -npb 12 -niml                                        \
    -onestate                                            \
    -i ../SUMA/std.60.lh.smoothwm.gii                    \
    -i ../SUMA/std.60.rh.smoothwm.gii                    \
    -i ../Net_000.gii                                    \
    -sv ../mprage+orig                                   \
    -vol ../mprage+orig.                                 \
    -gdset o.NETS_AND_MINIP_000.niml.dset &

cd -

DriveSuma                                                \
    -npb 12                                              \
    -com viewer_cont -key 't'                            \
    -com surf_cont -view_surf_cont y


The script Do_09_VISdti_SUMA_visual_ex2.tcsh contains the same commands used above. New options to ponder for your amusement here include -onestate, and -gdset. Also, program DriveSuma is used to control suma by mimicking user input.For more driving good times, see also @DO.examples, @DriveSuma, and @DriveAfni.

Quick Tour

Let’s look at the connectivity matrices between DMN ROIs.

A connectivity matrix is considered a graph dataset in SUMA and can be rendered as a set of nodes connected by edges, or as a matrix. The dual forms can be rendered simultaneously this way:

The edges (cells) carry the connection values. Open the graph controller with Ctrl+n to get information about a particular connection, and do all the kinds of colorization controls that are available for surface datasets and volumes.

Selecting an edge highlights the cell in the matrix and vice versa.

Selecting a node (label, or ball in 3D graph mode, label in matrix mode) will only show connections to that node.


Connections to node N000:R3 only in 3D graph rendering


Connections to node N000:R3 in matrix rendering


The set of controls on the lower left side is particular to graph datasets. Explore as curiosity moves you, the BHelp button comes in handy here but the help messages are still a work in progress. Complain away!

Of note is the Bundles button, try it, it is cool.


Representing edges by corresponding bundles


Note that as with all AFNI datasets, you can have multiple sub-bricks, here matrices of course. You can navigate between them using the sub-brick selectors (I, T, B) on the right side of the controller.

So far, no thresholding was applied, so go ahead and try it out.

6.2.5. Displayable Objects


Show directions: for example, show surface based normals, explain how you can hide some, etc. Link to other demos. For now, see the following for some inspiration:

  1. Interactive loading of displayable objects: Ctrl+Alt+s

  2. Demo script illustrating variety of DOs: @DO.examples


    Output of script @DO.examples showing text, textures and geometric objects displayed simultaneously.

  3. This AFNI message board posting explaining how to show principal orientations in a volume.


    Display of voxelwise diffusion directions

6.2.6. ECOG Grid Viewing


Show example of grid viewing. Until that is done, take a look at script @ElectroGrid

6.2.7. Mouse & Keyboard

This section includes help for mouse (pointer) and keyboard driven interactions with SUMA.

Keyboard Controls

On MACs, Alt is the Apple/Command key.

If it is commandeered by the OS, and you can’t get it back, then try the alt/option key instead.

On Linux, Turn NumLock OFF, otherwise certain mouse or

keyboard combinations do not work as intended.

a: attenuation by background, toggle. See also Plane Layering

B: Backface/Frontface/Noface culling, toggle.

b: background color, toggle. See also Plane Layering

c: load a node color file.

Ctrl+d: Open draw ROI controller, and put cursor in drawing mode.

D: Attch to the current dataset ‘parent’ a dot product

transform. The ‘child’ (transformed) dataset is created by calculating the dot product between each node time series and the time series of the current node. Each time you ‘shift+ctrl+click (drag too if you like)’ on the surface, with the child dataset in view, the dot product is recalculated. You can save the resultant datasets with ‘ctrl+W’ key (see below). Dset names are automatically formed. To stop the interactive dot product computations, switch back to the parent dset and press ‘D’ again. If the parent dataset is properly detrended and each time series is normalized so that its stdev is 1.0 then the dot product is the cross correlation coefficient. Detrending and normalization can be carried out with:

3dDetrend -polort 4 -normalize

-prefix dt.TS.niml.dset v2s.TS.niml.dset

You can get a good feel for what this ‘D’ does by running


That script will download and setup demo data for resting-state correlations. In particular, script @RunSingleSurfInstaCorr of the demo illustrates the ‘D’ feature.

F: Flip light position between +z and -z.

f: functional overlay, toggle.

g: graph data.

Open a graphing window for the dataset currently selected. The graphing window updates with each new node selection. A graphing window can be opened for each dataset, and all graphs will update unless ‘1 Only’ is set in Surface Controller. For complex data its magnitude is plotted instead. Use ‘ctrl+h’ in graph window for more help.

H: Highlight nodes inside a specified box.

Does not update other viewers Paints into existing colors Highlight is wiped out with new colors.

Ctrl+h: help message

J: Set the selected FaceSet on Surface Object

in Focus. Does not update in other viewers or in AFNI.

j: Set the cross hair to a certain node on SO in Focus.

Append/prepend L or R to switch hemispheres. Does update in other viewers if linked by index and AFNI if connected

Ctrl+j: Set the cross hair’s XYZ location.

Does update in other viewers if linked by XYZ and AFNI if connected

Alt+j: Set the Focus node.

Cross hair’s XYZ remain unchanged. Does not update in other viewers or in AFNI

L: Light’s XYZ coordinates.

Default setting is 0.0 0.0 1.0

Ctrl+L: Brighten specular and diffuse lights by a factor of 1/0.8

l: look at point

Alt+l: look at cross hair

Ctrl+l: Dim specular and diffuse lights by a factor of 0.8

Alt+Ctrl+M: Dumps memory trace to file

called malldump.NNN where NNN is the smallest number between 001 and 999 that has not been used.

m: momentum, toggle

O: Increase opacity of all surfaces in viewer by 4 levels.

Transparency levels accessible are: 0 (opaque), 25%, 50%, 75%, 100% (invisible)

Ctrl+O: Increase opacity of selected object by 4 levels.

o: Decrease opacity of all surfaces in viewer by 4 levels.

Ctrl+o: Decrease opacity of selected object by 4 levels.

Alt+o: Set new center of rotation.

Enter nothing to go back to default.

Ctrl+n: Open a new surface viewer window.

p: Viewer rendering mode

(Fill, Line, Points, Hide), switch.

Ctrl+p: Selected object rendering mode

(Fill, Line, Points, Hide), switch.

Alt+p: Cycle between restrictions of where DO node-based
objects are displayed. Available modes are:

All: No restrictions n3Crosshair: Crosshair node + 3 neighboring layers n2Crosshair: Crosshair node + 2 neighboring layers n1Crosshair: Crosshair node only None: Show nothing.

See also -do_draw_mask option in DriveSuma

** DO stands for displayable objects, see also

Ctrl+Alt+s below.

** For the moment, ‘Alt+p’ only applies to segment

and sphere DOs that are node based. If you need it applied to other DOs, let me know.

P: Reset viewer and all surfaces to Fill

rendering mode.

r: record current image

in an a la AFNI image viewer. Identical images are rejected. If you just save one image, the recording window has no visible controls for saving the image. Either take another picture, or use ‘Shift+right click’ to get a menu.

Ctrl+r: Record current image directly to disk.

Images are saved with a date stamp of the format PREFIX.X.yymmdd_hhmmss.MMM.jpg where:

PREFIX controlled with SUMA_AutoRecordPrefix.

See environment variable SUMA_AutoRecordPrefix for controlling prefix and output image type (suma -update_env).

X The character indicating which viewer is recording (you can

record from multiple viewers at once.

yy, mm, dd, hh, mm, ss for year, month, day, hours, minutes,

and seconds, respectively. MMM is a millisecond marker to avoid overwriting files. Unlike the other recording mode (with the ‘R’ key), there is no rejection of identical images

This option is useful for saving a large number of images without running out of memory in the recorder GUI.

Your current PREFIX is: ./SUMA_Recordings/autorecord.jpg

Alt+r: Increase the image oversampling factor.

By increasing this factor, you can create images at a resolution higher than that of the SUMA window. This is done by subdividing the scene into NxN sections and rendering each section separately. The NxN renderings are saved in the image recorder. After you save the images to disk, you can stitch them using imcat (a la AFNI montage).

Note that each section is still rendered at

the resolution of the SUMA window. So the bigger the window the more resolution per section. However, you cannot exceed a certain limit on the number of pixels in the final image. This limitation is due to the graphics card on your system. SUMA will take care not to exceed this limit.

Ctrl+R: Toggle continuous jpeg saving to disk.

Naming of output images is automatic, same as in Ctrl+r. See help for Ctrl+r above for more info.

R: Toggle continuous recording

to an a la AFNI image viewer. Identical images are rejected.

Ctrl+s: Open controller for surface in Focus.

Ctrl+Alt+s: Input filename containing displayable objects (a.k.a. DOs).

Files are of 1D format with a necessary comment at the top to indicate the type of objects in the file. Note 1: Repeatedly loading files with the same name will replace currently loaded versions. Note 2: Node-based (Types 3 and 4) objects will follow a node when its coordinates change. Note 3: See also ‘Alt+p’ for restricting which node-based objects get displayed.

Type 1: Segments between (x0,y0,z0) and (x1,y1,z1)

1st line must be ‘#segments’ (without quotes), or ‘#oriented_segments’ (slower to render). One can also use #node-based_segments or #node-based_oriented_segments and use a node index in place of (x,y,z) triplets. Remainder of file is N rows, each defining a segment (or a vector) between two points. Column content depends on the number of columns in the file:

For node-based:

2 cols: n0 n1 3 cols: n0 n1 th

with th being line thickness

6 cols: n0 n1 c0 c1 c2 c3

with c0..3 being the RGBA values between 0 and 1.0

7 cols: n0 n1 c0 c1 c2 c3 th 8 cols: n0 n1 c0 c1 c2 c3 th st

with st being a stippling, or dashing for some, flag. Use integers between 1 and 5 for a variety of syles.

For coordinate-based

6 cols: x0 y0 z0 x1 y1 z1 7 cols: x0 y0 z0 x1 y1 z1 th

with th being line thickness

10 cols: x0 y0 z0 x1 y1 z1 c0 c1 c2 c3

with c0..3 being the RGBA values between 0 and 1.0

11 cols: x0 y0 z0 x1 y1 z1 c0 c1 c2 c3 th 12 cols: x0 y0 z0 x1 y1 z1 c0 c1 c2 c3 th st

with st defined above.

Type 2: Directions, a variant of segments and oriented segments.

1st line must be ‘#directions’ (without quotes). Remainder of file is N rows, each defining a direction. Column content depends on the number of columns in the file:

3 cols: dx dy dz

with dx dy dz defining the direction. The triplet need not be of unti norm though that would affect the default coloring scheme detailed below. The segment drawn has origin 0, 0, 0

4 cols: dx dy dz mag

with mag being a scaling factor for the direction. mag is 1 by default.

5 cols: dx dy dz mag th

with th being the thickness of the line. Default is 1

6 cols: ox oy oz dx dy dz

Specify the origin of the segment in o1, o2, o3. Default is origin 0, 0, 0 for all

7 cols: o1 o2 o3 dx dy dz mag

Add individual scaling factors to case above Segment is from origin to origin+mag*direction

8 cols: o1 o2 o3 dx dy dz mag th

Add thickness to case with 7 columns

9 cols: dx dy dz mag th c0 c1 c2 c3

Add colors for each segment, with origin at 0,0,0

11 cols: ox oy oz dx dy dz mag c0 c1 c2 c3 12 cols: ox oy oz dx dy dz mag th c0 c1 c2 c3

Type 3: Spheres centered at (ox, oy, oz)

1st line must be ‘#spheres’ (without quotes). Remainder of file is N rows, each defining a sphere. Column content depends on the number of columns in the file: 3 cols: ox oy oz 4 cols: ox oy oz rd

with rd being the radius of the sphere

5 cols: ox oy oz rd st

with st being the style of the sphere’s rendering. Choose from:

0: points 1: Lines 2: Filled

7 cols: ox oy oz c0 c1 c2 c3

with c0..3 being the RGBA values between 0 and 1.0

8 cols: ox oy oz c0 c1 c2 c3 rd 9 cols: ox oy oz c0 c1 c2 c3 rd st

Type 4: Points at (ox, oy, oz)

1st line must be ‘#points’ (without quotes). Remainder of file is N rows, each defining a point. Column content depends on the number of columns in the file: 3 cols: ox oy oz 4 cols: ox oy oz sz

with sz being the size of the point

7 cols: ox oy oz c0 c1 c2 c3

with c0..3 being the RGBA values between 0 and 1.0

8 cols: ox oy oz c0 c1 c2 c3 sz

Type 5: Vectors (vx, vy, vz) at surface nodes

1st line must be ‘#node-based_vectors’ (without quotes) or ‘#node-based_ball-vectors’ (slower to render). Remainder of file is N rows, each defining a a vector at a particular node of the current surface. Column content depends on the number of columns in the file: 3 cols: vx, vy, vz

node index ‘n’ is implicit equal to row index. Vector ‘v’ is from coordinates of node ‘n’ to coordinates of node ‘n’ + ‘v’

4 cols: n, vx, vy, vz

Here the node index ‘n’ is explicit. You can have multiple vectors per node, one on each row.

5 cols: n, vx, vy, vz, gn

with gn being a vector gain factor

8 cols: n, vx, vy, vz, c0 c1 c2 c3

with with c0..3 being the RGBA values between 0 and 1.0

9 cols: n, vx, vy, vz, c0 c1 c2 c3 gn

Type 6: Spheres centered at nodes n of the current surface

1st line must be ‘#node-based_spheres’ (without quotes). Remainder of file is N rows, each defining a sphere. Column content depends on the number of columns in the file, see Type 2 for more details: 1 cols: n 2 cols: n rd 3 cols: n rd st 5 cols: n c0 c1 c2 c3 6 cols: n c0 c1 c2 c3 rd 7 cols: n c0 c1 c2 c3 rd st

Type 7: Planes defined with: ax + by + cz + d = 0.

1st line must be ‘#planes’ (without quotes). Remainder of file is N rows, each defining a plane. Column content depends on the number of columns in the file: 7 cols: a b c d cx cy cz

with the plane’s equation being: ax + by + cz + d = 0 cx,cy,cz is the center of the plane’s representation. Yes, d is not of much use here.

There are no node-based planes at the moment. They are a little inefficient to reproduce with each redraw. Complain if you need them.

Type 8: Another class of displayble objects is described in

the output of suma -help_nido and the demonstration script @DO.examples. This new class allows for displaying text and figures in both screen and world space.

Alt+s: Switch mouse buttons 1 and 3.

t: talk to AFNI, toggle.

Ctrl+t: Force a resend of

surfaces to AFNI.

T: Start listening for niml connections

Ctrl+u: Open SUMA controller.

w: Whereami window of little use at the moment.

Ctrl+W: Write items stowed in SUMA’s save list.

This is used to write temporary dsets that are created on the fly in SUMA. Such sets include those created via the ‘D’ option above, or the results sent by 3dGroupInCorr

W: Write ascii files containing the NodeList,

the FaceSetList and the nodecolors of the surface in focus.

Z: Zoom in

z: Zoom out

[: Show/Hide left hemisphere.

]: Show/Hide right hemisphere.

Window title shows which hemispheres are shown


or :–:

8: Set the number of smoothing iterations

to be applied to the foreground colors. This setting will be applied to all subsequent color sets.

*: Smooth node colors by averaging with neighbors.

The smoothing is only applied to the current colors, and will be not be applied to new color sets.


. (think </>): Switch to next/previous view state.

Viewing angle is reset only when switching to a state with flat surfaces.

See state for more on the meaning of states for different object types.

SPACE: Toggle between Mapping Reference and Current view state. Viewing angle is reset only when switching to a state with flat surfaces.

L-R arrows: rotate about screen’s Y axis

U-D arrows: rotate about screen’s X axis

Shift+L-R arrows: translate along screen’s

X axis

Shift+U-D arrows arrows: translate along screen’s

Y axis

Ctrl+L-R arrows: LR cardinal views

Ctrl+U-D arrows: IS cardinal views

Ctrl+Shift+U-D arrows: AP cardinal views

Ctrl+Shift+L-R arrows: rotate CCW and CW about Z screen axis

Alt+L-R arrows: Move selected node to neighboring nodes

in the direction of the screen’s X axis. The default is to move one node at a time. You can alter this setting with the environment variable: SUMA_KeyNodeJump in your ~/.sumarc file.

Alt+U-D arrows: Same as Alt+L-R but in the direction

of the screen’s Y axis

F1: screen axis (X-Red, Y-Green), toggle.

F2: surface axis (X-Red, Y-Green, Z-Blue),


F3: cross hair, toggle.

F4: node/voxel/edge/cell/tract/tie selection highlight, toggle.

F5: FaceSet/Slice selection highlight, toggle.

F6: Viewer background color, toggle.

F7: Switch between color mixing modes.

ORIG: Col = ( 1 - opacity ) * OldCol + opacity * NewCol MOD1: Col = ( 1 - opacity ) * OldCol + NewCol

F8: Viewing mode (Perspective or Orthographic Projection), toggle.

F9: Labels at cross hair, toggle.

F10: Toggle prying axis between surfaces’ Z and Y axes.

F11: Change object rendering order.

This order will affect the resultant image in the few instances where alpha transparency is used. The order can be specified for only three types of objects for now: graphs, surfaces, and volumes. If you want to render graphs first, followed by volumes then surfaces then set SUMA_ObjectDisplayOrder to something like: ‘graph,vol,surf’, or ‘GVS’

F12: Time 20 scene renderings.

HOME: reset zoom and recenter surfaces.

rest view angle for flat surfaces only.

ESCAPE: close the surface viewer window.

Shift+ESCAPE: close all surface viewer windows.

Mouse Controls

On MACs, Alt is the Apple/Command key.

If it is commandeered by the OS, and you can’t get it back, then try the alt/option key instead.

On Linux, Turn NumLock OFF, otherwise certain mouse or

keyboard combinations do not work as intended.

Button 1-Motion: For 3D scenes, rotation as if you were

using a trackball. For matrix displays, Button 1-Motion causes translation because rotations are of little use in matrix display mode.

Pure vertical motion is equivalent to using the up/down arrow keys.

Pure horizontal motion is equivalent to using the left/right arrow keys.

Of course, the advantage to using the mouse is a continuous range of rotation angles and simultaneous rotations about the screen’s X & Y axis.

Shift+Button 1-Motion: Rotate surfaces about the Z

axis. This is useful at times for reorienting flat maps.

Shift+Button 1-DoubleClick: Undo Z rotation

Ctrl+Button 1-Motion: Pry open two hemispheres

so that you can see medial or lateral walls better from one angle. Prying is disabled for flat surfaces and with spheres the effect is to rotate each sphere about the Y axis passing through its center. Also, prying is only enabled when the state you are viewing contains two surfaces, one on the left and one on the right. in 3D views, left right mouse movement cause a rotation about the front or rear I/S axis. Up down movements cause a shift along the left/right direction. You can select nodes (Button 3) on pried surfaces and still have AFNI jump to the proper location, and vice versa. However for the moment, you cannot draw in pried mode. If you attempt to draw, the surfaces are put back together. To make best use of this option, you want to have env. variable SUMA_LHunify = YES (see your ~/.sumarc for help)

Button 1-DoubleClick: Reset to Home vieweing angle, zooming is

left unchanged. See also ‘HOME’ key

Ctrl+Button 1-DoubleClick: Undo surface prying.

Button 2-Motion: Translation for 3D scenes. Rotation for

matrix displays.

Shift+Button2-Motion or Button 1+2-Motion:

Zoom in/out

Button 3-Press: Node/Voxel/Edge/etc. picking.

In ROI mode, initiates a path to new node in DrawROI mode. Picking of graph edges/nodes can get difficut when surfaces are also displayed. To help with that, see Alt+Button 3-Press next.

Also see Selecting Objects below.

Alt+Button 3-Press: Graph edge/node picking in the presence

of surfaces. Intersections with surfaces are ignored.

Shift+Alt+Button 3-Press: Same as Alt+Button 3, but also display

pick buffer. This is mostly for debugging or for understanding why selection is behaving strangely.

Shift+Button 3-Press: Shows an image of the selection buffer for debugging purposes. In Draw ROI Mode, the selection buffer is not displayed and the effect of the click is to select a node, but not to include it in the ROI.

Ctrl+Button 3-Press: Yoke intensity selection to index of

selected node*K. This is only possible if the currently visualized dataset has K times many sub-bricks as the surface has nodes. K is an integer.

Shift+Ctrl+Button 3-Press: Pick and initiate call in Dot xform

mode, or to GroupInCorr

Button 3-DoubleClick: If double clicking on a tract mask, select

the tract mask and turn the viewer into Mask Manipulation Mode. In this mode, the mask is shown as a wiremesh, and selections on any object will move the mask to that location. New tract/masks intersections are computed at the new location. To leave Mask Manipulation Mode, double click with button 3 either on the mask or in an area void of any objects. If double clicking with a graph object in focus and only connections from one node are shown, then revert to showing all graph connections. Without this, you can loose all other clickables if a certain node is not connected to anything.

Button 3-Motion: continuous picking whenever surface are present.

No calls for dot product (InstaCorr) or GroupInCorr, while dragging. Continuous picking of graph edges/nodes if no surfaces are displayed.

See Continuous Selection below

Alt+Button 3-Motion: Continuous picking of graph edges/nodes.

Intersections with surfaces are ignored.

Ctrl+Button 3-Motion: continous yoking of intensity selection to

selected node*K.

Shift+Ctrl+Button 3-Motion: Continuous picking and calls

for dot product (InstaCorr) or GroupInCorr, while dragging.

Scroll or Wheel: Zoom in/out

Shift+Scroll or Shift+Wheel: change selected slice if current selected

object is a volume.

Ctrl+Scroll or Ctrl+Wheel: change the size of the currently selected

tract mask. This only works when you’re in mask manipulation mode.

Selecting Objects

Selections are done with the right-mouse click unless you request otherwise.

The selection of an object triggers a multitude of actions:

  • When talking to AFNI, a selection prompts AFNI to also jump to the corresponding location. SUMA can also talk to other programs such asHalloSuma

  • The controller for that object is popped to the top of the stack in the controllers notebook, and the crosshair information in the controller gets updated.

  • Other open SUMA controllers are made to jump to the corresponding locations. Use the SUMA controller (Ctrl+u) to setup how different controllers are locked together.

  • When in drawing ROIs mode a selection adds to the ROI being drawn. See Drawing ROIs for details, assuming it is written by now!

  • If you have ‘click callbacks’ initiated, a selection combined with the proper keyboard modifiers initiates a callback. An example of this would be the surface-based instacorr or the variety of instacorr features in AFNI and/or 3dGroupInCorr. The following command can download and install demo material for InstaCorr excitement:

    @Install_InstaCorr_Demo -mini
  • If you are in Mask Manipulation Mode Selections will make the tract mask jump to the selection location.

Picking behavior depends on the object being selected as follows:

1- Node picking on surfaces: Selection of a node on the surface involves finding intersected triangles, identifying the closest intersected triangle, and then indentifying the closest node within it. The crosshair is centered at the location of intersection and marked with a yellow sphere. The closest node in the triangle is marked with a small (tiny some say) blue sphere, and the triangle is highlighted with a gray line contour. Highlighting can be toggled with F3 for crosshair, F4 for selected node, and F5 for the triangle



2- Voxel picking in volumes: You can select voxels on rendered slices as long as the voxels are not thresholded out of view. They maybe too dark to see but still be selectable if their value exceeds that of the threshold.

Selecting a voxel also highlights the slice. You can turn off the highlight rectangle with F5.

Note that you can also select from the 3D rendered volume and when 3D rendering is turned on. In that case, no slice highlighting is done.

3- Edge/cell selection in graphs: Right click on an edge, matrix cell, or bundle reprenting the edge and the connection is rendered white. Because the graphs can be bidirectional, clicking on an edge between [n1, n2] with the click location closest to n1 would select edge n1–>n2, while clicking closer to n2 gets you edge n2–>n1. This also happens when you click on a bundle representation of the edge. The selected connection is highlighted in white and the highlighting can be toggled with the F4

Selecting an edge on the 3D graph is reflected on the dual representation in matrix form by highlighting the equivalent cell, and vice versa.

Selecting a node on the 3D graph, by clicking on the ball representing the node, or the node’s name highlights only the connections to that node. The same type of selection can be made by clicking on a row or column’s label in the matrix representation form.

When graphs are represented along with volumes and surfaces, picking an edge can get tricky. In that case, use Alt+Button 3 instead.

4- Tract selection: Right click on a tract - the hairline - for selecting a location along the tract. What’s more to say ?

Continuous Selection

You can select and drag and sweep through numerous locations. The main thing to keep in mind is that when you have a multitute of object types, such as tracts, voxels, surfaces, etc. SUMA locks the selection to the object type selected at the beginning of the sweep. So, if you begin the selection on a surface and drag, then the selections during the sweep are restricted to surfaces only.

Viewer Menus


Save View: Save viewer’s display settings.

Load View: Load and apply display settings.

Close: Close this viewer.

Exit SUMA if this is the only viewer.


SUMA Controller: Open SUMA controller interface.

Surface Controller: Open selected surface’s

controller interface.

Viewer Controller: Open viewer’s controller interface.

Cross Hair: Toggle cross hair display.

Node in Focus: Toggle highlight of selected node.

Selected Faceset: Toggle highlight of selected faceset.


Draw ROI: Open Draw ROI controller, also with Ctrl+d.


Usage: Opens window with this message.

Message Log: Opens window that will

contain errors and warnings typically output to screen.

SUMA Global: Output debugging information

about some of SUMA’s global structure’s variables.

Viewer Struct: Output debugging info on

a viewer’s structure.

Surface Struct: Output debugging info on

the selected surface’s struct.

InOut Notify: Turn on/off function in/out tracing.

MemTrace: Turn on memory tracing.

Once turned on, this can’t be turned off.

SUMA’s env.

Below is a list of all of SUMA’s environment variables and their default values. You can query the value of a variable as SUMA sees it with:

suma -Vname=

with ‘name’ replaced by the environment variable’s name.

e.gcommand:suma -VSUMA_ArrowRotAngle=

Always update your environment variable list with:

suma -update_env

List of Variables

SUMA_ArrowRotAngle (env): Incremental arrow rotation angle in degrees

default value: SUMA_ArrowRotAngle = 5

SUMA_ColorPattern (env): Color pattern (AFNI, EURO, PRINT, DEFAULT)

default value: SUMA_ColorPattern = EURO

SUMA_SwapButtons_1_3 (env): Swap mouse buttons 1 and 3

default value: SUMA_SwapButtons_1_3 = NO

SUMA_BackgroundColor (env): Background color r g b. No space between values

default value: SUMA_BackgroundColor = 0.0,0.0,0.0

SUMA_ROIColorMap (env): ROI color map (bgyr64, roi64, roi128, roi256)

default value: SUMA_ROIColorMap = ROI_i256

SUMA_NumConvSmooth (env): Number of smoothing operations to run on convexity data

default value: SUMA_NumConvSmooth = 5

SUMA_ConvColorMap (env): Colormap for convexity (gray02, gray_i02, ngray20, bgyr64, etc.)

default value: SUMA_ConvColorMap = gray02

SUMA_ConvBrightFactor (env): Brightness factor for convexity

default value: SUMA_ConvBrightFactor = 0.5

SUMA_NumForeSmoothing (env): Number of smoothing operations to run on mixed foregroung color plane

before mixing with background

default value: SUMA_NumForeSmoothing = 0

SUMA_NumFinalSmoothing (env): Number of smoothing operations to run on final set of mixed colors.

This would be the mixed foreground and background colors

default value: SUMA_NumFinalSmoothing = 0

SUMA_ColorMixingMode (env): Setup the color mixing mode (ORIG, MOD1)

default value: SUMA_ColorMixingMode = ORIG

SUMA_AFNI_TCP_PORT (env): ** OBSOLETE: Port for communicating with AFNI

Listening ports are derived from SUMA_AFNI_TCP_PORT Listening port i SUMA_AFNI_TCP_PORT + i (i > 0)

default value: SUMA_AFNI_TCP_PORT = 0

SUMA_WarnBeforeClose (env): Warn before closing with the Escape key (YES/NO)

default value: SUMA_WarnBeforeClose = YES

SUMA_MaskZero (env): Mask node values

0 ? YES/NO

default value: SUMA_MaskZero = YES

SUMA_AbsThreshold (env): Threshold if Val < thr (NO) or | Val | < | Thr | (YES)

default value: SUMA_AbsThreshold = YES

SUMA_ThresholdScalePower (env): Threshold scale precision. 2 is the minimum allowed.

This value might be overriden in SUMA.

default value: SUMA_ThresholdScalePower = 2

SUMA_CenterOnPatch (env): Center of Rotation is based on nodes used in the mesh and not

on all the nodes in NodeList

default value: SUMA_CenterOnPatch = NO

SUMA_UseCrossTicks (env): Use cross ticks on axis ?

default value: SUMA_UseCrossTicks = NO

SUMA_1D_Transpose_Warn (env): Warn if 1D file looks like it needs a transpose

default value: SUMA_1D_Transpose_Warn = YES

SUMA_AdjustMouseMotionWithZoom (env): Adjust roation and translation factor of mouse with changes

in zoom levels

default value: SUMA_AdjustMouseMotionWithZoom = YES

SUMA_ViewOrthographicProjection (env): Use orthographic projection

default value: SUMA_ViewOrthographicProjection = NO

SUMA_KeyZoomGain (env): Percent gain for zooming in and out with the ‘z’ and ‘Z’ keys.

Typical range from 0 to 50

default value: SUMA_KeyZoomGain = 5

SUMA_FOV_Original (env): Original FOV. Set between 1.0 and 100.0

Default is 30.0, -1 == auto

default value: SUMA_FOV_Original = -1

SUMA_Position_Original (env): Original windows size and width in pixels

Allowed values are:



‘X Y’ Sets only the position to top left corner

‘X Y Xwidth Ywidth’ Set also width of window

default value: SUMA_Position_Original = TopLeft

SUMA_Light0Color (env): light0 color

default value: SUMA_Light0Color = 1.0,1.0,1.0

SUMA_AmbientLight (env): Ambient light

default value: SUMA_AmbientLight = 1.0,1.0,1.0

SUMA_AllowDsetReplacement (env): Allow for replacement of pre-loaded dsets

default value: SUMA_AllowDsetReplacement = YES

SUMA_AlwaysAssignSurface (env): Allow a dataset to be assigned to a surface, even if domain of dset is specified and different for the surface.

default value: SUMA_AlwaysAssignSurface = YES

SUMA_ShareGrandChildrenOverlays (env): Allow for surfaces with same DomainGrandParentID to share overlays

default value: SUMA_ShareGrandChildrenOverlays = NO

SUMA_SnapshotOverSampling (env): Increase the resolution of images recorded with ‘r’ button.

Increase is done by taking multiple shots that once stitched together form a high-resolution image. The maximum resolution is set by the GL_MAX_VIEWPORT_DIMS of your graphics card. I have 4096 pixels. If you exceed this number, SUMA will make adjustments automatically. Assemble images with program imcat.

default value: SUMA_SnapshotOverSampling = 1

SUMA_NoDuplicatesInRecorder (env): Ignore consecutive duplicate images in recorder

default value: SUMA_NoDuplicatesInRecorder = YES

SUMA_START_NIML (env): start NIML (can’t do this for more than one suma at a time!)

default value: SUMA_START_NIML = YES

SUMA_AllowFilenameDsetMatch (env): Allow (YES) datasets with the same filename but differing ID

to be considered the same. This is only useful with SUMA_AllowDsetReplacement

default value: SUMA_AllowFilenameDsetMatch = YES

SUMA_FreezeFOVAcrossStates (env): Freeze zoom across states

default value: SUMA_FreezeFOVAcrossStates = NO

SUMA_DsetColorMap (env): Dset color map

default value: SUMA_DsetColorMap = Spectrum:red_to_blue

SUMA_ShowOneOnly (env): Show only selected dset in suma’s surface controller.

default value: SUMA_ShowOneOnly = YES

SUMA_GraphHidden (env): Update graphs, even SUMA_ShowOneOnly (or suma’s ‘1 Only’) is turned on.

default value: SUMA_GraphHidden = YES

SUMA_ColorMapRotationFraction (env): Fraction of colormap to rotate with up/down arrow keys.

default value: SUMA_ColorMapRotationFraction = 0.05

SUMA_SurfContFontSize (env): Size of surface controller font.

Values are SMALL, BIG (old style).

default value: SUMA_SurfContFontSize = SMALL

SUMA_StartUpLocation (env): Where to position SUMA window when first opened.
Values are POINTER (at the mouse pointer’s location)

DEFAULT (let the window manager decide)

default value: SUMA_StartUpLocation = DEFAULT

SUMA_KeyNodeJump (env): Numer of nodes to jump with the ‘alt+arrow’ keys.

Valid range from 1 to 10

default value: SUMA_KeyNodeJump = 1

SUMA_DriveSumaMaxWait (env): Numer of seconds to wait for SUMA to respond to DriveSuma.

Valid range from 0 to 60000, see also env SUMA_DriveSumaMaxCloseWait

default value: SUMA_DriveSumaMaxWait = 300.0

SUMA_LEFT_FILE_DSET_IDENTIFIER (env): String to use in creating left hemisphere dataset wildcards.

default value: SUMA_LEFT_FILE_DSET_IDENTIFIER = lh.dset

SUMA_RIGHT_FILE_DSET_IDENTIFIER (env): String to use in creating left hemisphere dataset wildcards.

default value: SUMA_RIGHT_FILE_DSET_IDENTIFIER = rh.dset

SUMA_LEFT_FILE_ROI_IDENTIFIER (env): String to use in creating left hemisphere roi wildcards.

default value: SUMA_LEFT_FILE_ROI_IDENTIFIER = lh.roi

SUMA_RIGHT_FILE_ROI_IDENTIFIER (env): String to use in creating right hemisphere roi wildcards.

default value: SUMA_RIGHT_FILE_ROI_IDENTIFIER = rh.roi

SUMA_LEFT_FILE_OTHER_IDENTIFIER (env): String to use in creating left hemisphere roi wildcards.


SUMA_RIGHT_FILE_OTHER_IDENTIFIER (env): String to use in creating right hemisphere roi wildcards.


SUMA_ConvexityDsetOpacity (env): Initial Convexity Datasest opacity.

default value: SUMA_ConvexityDsetOpacity = 0.85

SUMA_ShowLabelDsetAtStartup (env): Display mode of Label Datasest specified in spec file at startup.

‘YES’ or ‘Col’: Shows it in color

‘Con’: Shows only contours (see also env SUMA_ContourThickness).

‘C&C’: Shows both colors and contours

‘XXX’or ‘No’: Does not show it.

default value: SUMA_ShowLabelDsetAtStartup = XXX

SUMA_ShowLabelsAtCrossHair (env): Show label at cross hair in viewer You can toggle the display at such labels with F9

default value: SUMA_ShowLabelsAtCrossHair = YES

SUMA_LabelDsetOpacity (env): Initial Label Datasest opacity.

default value: SUMA_LabelDsetOpacity = 0.2

SUMA_AttemptTalkRecover (env): Attempt to recover from AFNI <–> SUMA disconnection bug.

default value: SUMA_AttemptTalkRecover = Yes

SUMA_CmapsDir (env): Name of directory containing user’s own SUMA color maps (*.cmap)

default value: SUMA_CmapsDir = None

SUMA_RetinoAngle_DsetColorMap (env): Name of color map for datasets of retinotopy angles. These would be produced by 3dRetinoPhase

default value: SUMA_RetinoAngle_DsetColorMap = rgybr20

SUMA_VFR_DsetColorMap (env): Name of color map for VFR datasets produced by SurfRetinoMap

default value: SUMA_VFR_DsetColorMap = afni_n2

SUMA_NodeCoordsUnits (env): Coordinate units of surface nodes. Choose from ‘mm’ or ‘cm’ A bad choice can make the surfaces render with many artifacts.

default value: SUMA_NodeCoordsUnits = mm

SUMA_DoNotSendStates (env): Which anatomically correct surf. states should not NOT be sent to AFNI? This is mostly for deciding whether one of ‘white’ or ‘smoothwm’ FreeSurfer states should not be sent to AFNI. The default is to let them all go. You can specify multiple states with a , delimited list (no spaces!). By default nothing is excluded.

default value: SUMA_DoNotSendStates = N/A

SUMA_AutoRecordPrefix (env): Prefix for autorecord (suma’s Ctrl+R) files. FreeSurfer states should not be sent to AFNI. Add a path if you want the files to endup in a particular directory. You can also add an extension to prefix to specify the output type. Choose from .jpg, .ppm, or .1D . The fallback type is .jpg

default value: SUMA_AutoRecordPrefix = ./SUMA_Recordings/autorecord.jpg

SUMA_CrossHairLabelFont (env): Font for cross hair label in SUMA viewer Choose one of: f8 f9 tr10 tr24 he10 he12 he18

default value: SUMA_CrossHairLabelFont = f9

SUMA_IxT_LinkMode (env): Linking mode of I and T sub-brick selectors Choose one of: None, Same, Stat

default value: SUMA_IxT_LinkMode = Stat

SUMA_ArrowFieldSelectorTrigger (env): Minimum Number of sub-bricks to trigger use of arrow field for sub-brick selectors.

default value: SUMA_ArrowFieldSelectorTrigger = 200

SUMA_Sym_I_Range (env): Use symmetric Intensity range at startup? Valid options are:

YES or NO: For your preference if no decision is made by the software FYES or FNO: To force your preference and keep software from deciding

default value: SUMA_Sym_I_Range = YES

SUMA_Auto_I_Range (env): Set auto Intensity range by default (YES or NO)

default value: SUMA_Auto_I_Range = NO

SUMA_Auto_B_Range (env): Set auto Brightness range by default (YES or NO)

default value: SUMA_Auto_B_Range = NO

SUMA_ContourThickness (env): Set thickness of dataset contours

default value: SUMA_ContourThickness = 1.0

SUMA_LHunify (env): Merge separated left/right states for inflated/spherical/etc. surfaces Choose from YES or NO

default value: SUMA_LHunify = YES

SUMA_SameSurfCont (env): Put surface controllers in same window Choose from YES or NO

default value: SUMA_SameSurfCont = YES

SUMA_WindowOffset (env): Adjust offset of Surface Viewers as they are first open Choose from AUTO or provide two X Y offsets.

default value: SUMA_WindowOffset = Auto

SUMA_LockViewers (env): Lock views across viewers Choose from YES or NO.

default value: SUMA_LockViewers = YES

SUMA_VO_ColorMap (env): Set colormap for volumes, choose any of the standard list

default value: SUMA_VO_ColorMap = bw20

SUMA_VO_Reorient (env): Force reorienting of read volume. To force reorientation, Choose from RAI, LPI, RAS. etc… Use NO to avoid reorientation. This env. is for debugging purposes.

default value: SUMA_VO_Reorient = NO

SUMA_DriveSumaMaxCloseWait (env): Set maximum waiting time for proper detection of closed stream This is to avoid DriveSuma’s: Failed to detect closed stream … complaint which results in a forced stream closing. Time unit is in seconds. See also env SUMA_DriveSumaMaxWait

default value: SUMA_DriveSumaMaxCloseWait = 5

SUMA_ObjectDisplayOrder (env): Set order in which object types are rendered. This order will affect the resultant image in the few instances where alpha transparency is used. The order can be specified for only three types of objects for now: graphs, surfaces, and volumes. If you want to render graphs first, followed by volumes then surfaces then set SUMA_ObjectDisplayOrder to something like: ‘graph,vol,surf’. Do not include spaces between the type names.

default value: SUMA_ObjectDisplayOrder = vol,surf,graph

SUMA_Dset_Font (env): Font for datasets in SUMA viewer Choose one of: f8 f9 tr10 tr24 he10 he12 he18

default value: SUMA_Dset_Font = f9

SUMA_Dset_NodeConnections (env): Method for representing connections to a certain node in a graph dataset. Choose one of: Edge, Color, Radius, C&R, XXX

default value: SUMA_Dset_NodeConnections = Edge

SUMA_VO_InitSlices (env): Set which slices should be shown when a volume is first loaded. You can set parameters for each of the Ax, Sa, and Co planes, and the volume rendering. Each plane gets its own string formatted as such: PL:SL:MON:INC where:

PL is the plane (Ax, Co, Sa, or Vr)

SL is the slice number, you can also set the number as

a fraction of the number of slices in the volume.

MON is the number of montage slices

INC is the increment between montage slices. You can use

fractions for this parameter also.

If you want to set parameters for a certain plane, but do not want to see it, prepend the plane name with ‘h’ (for hide) as in ‘hAx’ Note that for Vr, there are no SL, MON, and INC qualifiers Also, SUMA will force the display of at least one plane because otherwise you have no way of opening a volume controller Example: ‘Ax:0.5:3:10,Co:123:2:50,Vr’

default value: SUMA_VO_InitSlices = Ax:0.5,Sa:0.5:2:0.5,hCo:0.5

SUMA_VrSelectable (env): Allow selection of voxels on 3D rendering. Choose one of: YES or NO

default value: SUMA_VrSelectable = YES

SUMA_HomeAfterPrying (env): Perform ‘Home’ call in SUMA after each prying. If YES, objects are repositioned to stay in the middle of the viewer as you pry the surfaces apart. This behavior is desired in general, unless you don’t like the initial positioning in the first place. Choose from YES or NO

default value: SUMA_HomeAfterPrying = YES

SUMA_SUMA_TESSCON_AutoScale (env): Assume surface in TESSCON units if range is extreme If YES, surfaces with a big difference between max and min dims are scaled by 319.7. Don’t set this env to YES unless this jibber jabber means. Choose from YES or NO

default value: SUMA_SUMA_TESSCON_AutoScale = NO

SUMA_CountProcs_Verb (env): Turn on verbose mode for function count_procs() that checks for recursive calls to a program. Do not keep this env set to YES unless you are debugging.

default value: SUMA_CountProcs_Verb = NO

SUMA_Transparency_Step (env): Number of transparency levels to jump with each ‘o’ key press Choose one of 1, 2, 4, or 8

default value: SUMA_Transparency_Step = 4

SUMA_AutoLoad_Matching_Dset (env): If YES, then automatically load datasets with names matching those the surface just read. For example, if you load a surface named PATH/TOY.gii, for instance, and there exists a file called PATH/TOY.niml.dset then that file is automatically loaded onto surface TOY.gii. This would work for all surface types (e.g. TOY.ply) and dataset types (e.g. TOY.1D.dset) Choose from YES or NO

default value: SUMA_AutoLoad_Matching_Dset = YES

SUMA_Classic_Label_Colors (env): Colorize labeled datasets without attempting to make colors match what would be displayed in AFNI (YES or NO). Set to YES to match old style colorization preceding the addition of this variable

default value: SUMA_Classic_Label_Colors = NO

SUMA_Range_Multiplier (env): Multiplier for range of thresholding scale.

default value: SUMA_Range_Multiplier = 1.0

SUMA_pval_at_switch (env): Default p value to adopt when switching to a new sub-brick. Negative values mean leave the threshold alone when switching.

default value: SUMA_pval_at_switch = -1.0

SUMA_DriveSumaQuiet (env): If YES, then reduce messages to only errors while driving suma Choose from YES or NO

default value: SUMA_DriveSumaQuiet = NO

SUMA_SHOWPOPUPS (env): If YES, then show popup message windows in suma Choose from YES or NO

default value: SUMA_SHOWPOPUPS = NO

Current Version Info:

Compile Date:

Dec 19 2018

Colormap Keyboard Controls

With the cursor over the colormap, the following keyboard initiated actions are available.

f: flip color map

See also Up/Down keys.

Ctrl+h: this help message

r: record image of colormap.

w: write colormap to ascii file.

Z: Zoom in.

Maximum zoom in shows 2 colors in the map

z: Zoom out.

Minimum zoom in shows all colors in the map

U-D arrows arrows: rotate colormap up/down by fraction of

number of colors in color map. Fraction a number between 0 and 0.5 and set via the environment variable SUMA_ColorMapRotationFraction. See suma -environment for complete list of variables.

Ctrl+U-D arrows: rotate colormap up/down by one color

Shift+U-D arrows: move colormap up/down

HOME: Reset zoom, translation and rotation parameters

6.2.8. Color Mixing

Color Plane Grouping

Colorized Dsets are organized into layered color planes. Two commonly used planes are:

  • Surface Convexity (usually in gray scale)

  • AFNI Function (usually in color)

Planes are assigned to two groups:

  • Background planes (like Convexity)

  • Foreground planes (like AFNI Function)

Many other planes can be added to either group. Color planes of the same group are mixed together: Planes are stacked based on their order and opacity. Opacity of 1st plane in a group does not affect color mixing. There are 2 modes for mixing colors. See F7 key in SUMA.



Layering fore- & background planes

To demonstrate the layering of foreground and background planes, start with a view of an inflated surface with some color overlay such as you would get from talking to AFNI. Requires suma_demo:



Turn foreground plane(s) off by pressing f once. Now all you see is the background plane(s):



Turn background planes off by pressing b once. Now all you see is “No Color” color on all nodes:



Turn foreground plane(s) back on with f. Now you have foreground without background:



Turn background plane(s) back on with b. Now you have foreground atop background. You can still see the background underneath the foreground – this is due to the background brightness attenuation of the foreground colors.

Toggle background intensity attenuation off and on with a and see the effect on the resultant maps:





Playing with color plane opacity

Continuing with the demo surfaces and pre-existing color planes (datasets)...

Open surface controller with ctrl+s or View->Surface Controller. To turn OFF, press 1.

Load in color plane lh.1D.col using Load Col or c:

  • This is an RGB Dset, so color mapping controls are hidden

  • Plane is placed atop of the foreground group

  • Its opacity is 1 so it will obsucure the functional data



Background attenuation is not affected by plane’s opacity. Try turning it on and off again with a:



Now lower the opacity of lh.1D.col with Opa, and watch the colors from the planes below start to show through:





Playing with color plane order

Continuing with the examples above, with inflated view and function from AFNI displayed on the surfaces…

We will push the dataset from lh.1D.col below the function overlay sent from AFNI.

  • Use Switch Dset to get a list of available planes

  • Prefixes fg: and bg: denote the plane’s group membership

  • Select lh.1D.col and lower its order with the Ord button

  • Select FuncAfni_0 and play with its opacity

  • Note: You can’t make a plane change its group membership, yet.

You can’t delete a loaded color plane yet, but you can reload it if it changes on disk, or you can hide it with Dsp.

Turn 1 ON if you just want to see the selected plane with no blending business from other planes. The plane displayed would be the one whose label is shown in the surface controller.


  • Find a way to flip between the mapping from AFNI and the mapping (done with 3dVol2Surf on the command line with script run_3dVol2Surf.)

  • Appreciate the differences between the two mappings.

6.2.9. Alignment of Surfaces with Volumes


Explain alignment of surfaces with volumes.

6.2.10. The Spec File

The Spec file contains information about surfaces that will be available to a program.

  • Information is specified in the format: field = value

  • The = sign must be preceded and followed by a space character.

  • # delimit comment lines, empty lines and tabs are ignored.

  • In addition to fields, there is also the NewSurface tag which is used to announce a new surface.

  • Unrecognized text will cause the program parsing a Spec file to complain and exit.

  • See programs quickspec and inspec for manipulations of spec files.

  • Here is a sample spec file:

    # delimits comments
    # define the group
       Group = DemoSubj
    # define various States
       StateDef = smoothwm
       StateDef = pial
       StateDef = inflated
       SurfaceFormat = ASCII
       SurfaceType = FreeSurfer
       FreeSurferSurface =
       LocalDomainParent = SAME
       SurfaceState = smoothwm
       EmbedDimension = 3
       SurfaceFormat = ASCII
       SurfaceType = FreeSurfer
       FreeSurferSurface = lh.pial.asc
       LocalDomainParent =
       SurfaceState = pial
       EmbedDimension = 3
       SurfaceFormat = ASCII
       SurfaceType = FreeSurfer
       FreeSurferSurface = lh.inflated.asc
       LocalDomainParent = lh.smoothwm.asc
       SurfaceState = inflated
       EmbedDimension = 3
       SurfaceFormat = ASCII
       SurfaceType = FreeSurfer
       FreeSurferSurface = lh.sphere.asc
       LocalDomainParent = lh.smoothwm.asc
       SurfaceState = sphere
       EmbedDimension = 3
  • Fields of the Spec File:

    • Group: Usually the Subject’s ID. In the current SUMA version, you can only have one group per spec file. All surfaces read by SUMA must belong to a group.

    • NewSurface: A tag announcing the beginning of a set of fields for a new surface.

    • SurfaceName or FreeSurferSurface: Name of the surface file.

    • SurfaceFormat: ASCII or BINARY

    • SurfaceType: FreeSurfer, Caret, BrainVoyager, Ply, etc.

    • SurfaceState: Surfaces can be in different states such as inflated, flattened, etc. The label of a state is arbitrary and can be defined by the user. The set of available states must be defined with StateDef at the beginning of the Spec file.

    • StateDef: Used to define the various states. This must be placed before any of the surfaces are specified.

    • Anatomical: Used to indicate whether surface is anatomically correct (Y) or not (N). Anatomically correct surfaces are sent to AFNI.

    • LocalDomainParent: Name of a surface whose mesh is shared by other surfaces in the spec file.

      • The default for FreeSurfer surfaces is the smoothed gray matter/ white matter boundary. For SureFit it is the fiducial surface. Use SAME when the LocalDomainParent for a surface is the surface itself.

    • EmbedDimension: Embedding Dimension of the surface, 2 for surfaces in the flattened state, 3 for other.