5.2. SUMA Viewer

5.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 showing smoothed white matter surfaces AFNI slice viewer AFNI Controller
../_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.
  1. 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

    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.

  2. 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.
  3. 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.
  4. 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

    • 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

  5. Cardinal views (along coordinate directions)

    • Ctrl+Left/Right: Views along LR axis

    • Ctrl+Up/Down: Views along SI axis

    • Ctrl+shift+Up/Down: Views along AP axis

    • Resetting the view point

      • Press Home(fn+left arrow macs) to get back to the original vantage point.
      • view->save and view->load to save load views
  6. 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.
  7. 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.
  8. 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.

    • 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

  9. 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
  10. 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.
  11. Viewing datasets

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

    • 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

        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.
  12. Mapping Parameters Table (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.

  13. 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 surface-based dataset applies to volumetric and connectivity data.

5.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.:

5.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.


    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.


    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.
  1. 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.
  1. 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.

  1. 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.

5.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

  1. Looking 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:

  • Open a new SUMA controller with Ctrl+n
  • Switch states till you get to the matrix (. (period))
  • Select a connection, either by clicking on an edge or its corresponding cell in the matrix.

Graph display, with slices in background at 50% transparency (link).


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.

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.

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.

5.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.

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

5.2.6. ECOG Grid Viewing


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

5.2.7. Mouse & Keyboard

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

5.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 come 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

Turn OFF: 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 dataset from lh.1D.col below the function from AFNI

Use Switch Dset to get a list of available planes

Prefixes fg: and bg: denote 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.

5.2.9. Alignment of Surfaces with Volumes


Explain alignment of surfaces with volumes.

5.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 announing 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.