6.3. SUMA Controllers

6.3.1. Overview

GUI controllers make up three groups:

  • SUMA Controller To control aspects common to all the SUMA viewers.

  • Viewer Controller: To control aspects particular to one viewer. This baby is practically nonexistent at this stage.

  • Object Controllers: To control how certain objects and the data defined over them are displayed. In modern SUMA versions, it is best that all controllers are collected in the same controller notebook. Example controllers include the Surface Controller, the Tract Controller, the Volume Controller etc.

6.3.2. Global Controller

Suma Controller

The suma controller is for controlling parameters common to across viewers and objects.You can launch the Suma Controller with: ctrl+u or View‣Suma Controller

SUMA/media/SumaCont.auto.ALL.jpg

(link)

Lock:

Set the crosshair lock between viewers.

- No Lock: Crosshair only moves in viewer where you clicked.

i Node index Lock: Crosshair jumps to the same node index on related surfaces (or objects) in other viewers. Linking in this case is topology based.

c Coordinate Lock: Crosshair jumps to the same XYZ mm coordinate in other viewers. Linking in this case is geometry based).

View:

Lock the view point of all viewers. Depress toggle button to link view point across viewers.

  • Surface rotation and translation in one viewer is reflected in all linked viewers.

  • Liking is NOT done across viewers that are displaying objects of different embedding dimensions such as 3D and 2D surfaces.

All:

Set the crosshair lock between viewers.

- No Lock: Crosshair only moves in viewer where you clicked.

i Node index Lock: Crosshair jumps to the same node index on related surfaces (or objects) in other viewers. Linking in this case is topology based.

c Coordinate Lock: Crosshair jumps to the same XYZ mm coordinate in other viewers. Linking in this case is geometry based).

Viewer: Opens a new viewer

Opens a new Surface viewer window.

BHelp: Press this button then click on a button/label/menu for more help.

Click the hand on any button or label, menu, etc. to get a little help. See also WHelp!

Close: Close SUMA controller

Close SUMA controller window. Current settings are preserved when controller is reopened.

done: Click twice in 5 seconds to close everything and quit SUMA.

Click twice in 5 seconds to quit application. All viewer windows will be closed, nothing is saved, SUMA will terminate, and there maybe no one left at this computer.

6.3.3. Object Controllers

Controller Notebook

Many of the displayable objects, particularly those that can carry data, have an object controller. Historically there was only surface-controllers (hence the Ctrl+s for the shortcut) but now volumes, tracts, and graphs also have their own controllers.

The easiest way to open a controller is to select an object and open its controller with ctrl+s, or View ‣ Object Controller. Once a controller is open, selecting other objects automatically creates their own controller.

All object controllers are grouped in one notebook window as shown in Object Controller. If you don’t have all your object controllers opening in the same notebook and your SUMA version is current, make sure environment variable SUMA_SameSurfCont is set to YES in your .sumarc file.

../_images/object_controller_notebook_gray.jpg

Object Controller Notebook: Holder of all controllers. Grayed out area will be different for different object types. (link)

Once you select an object, its controller is popped to the top. You can also use the Switch to get at the controller for an object that you don’t want to select or that is simply out of reach (invisible).

Disp. Cont.

A few controls for the object controller notebook.

Close: Close controller. Settings are not

lost. You can bring it back with Ctrl+s key.

BHelp: Obtain context specific help by

clicking on this button then clicking on the context for which you want information.

WHelp: Obtain web-based context specific

help by clicking on this button then clicking on the context for which you want information.

All Objs: Initialize controllers for

all objects that have one. This is particularly useful when a particular may not be visible under the default settings.

Switch: Switch between controller

notebook pages. You can use the arrows to cycle between pages or set the page number directly.

Surface Cont.

The surface controller is for controlling the way surfaces and datasets defined over them are displayed. The same controller is shared by a family of surfaces and all the datasets displayed on them. Left and Right surfaces have separate controllers though in most cases actions on one hemisphere’s controller are automatically mirrored on the contralateral side. The surface controller is initialized by the currently selected surface - the one said to be in focus. You can launch the Surface Controller with: ctrl+s or View‣Object Controller

../_images/SurfCont.auto.ALL.jpg

(link)

Surface Properties

Block providing information about selected surface.

../_images/SurfCont.auto.Surface_Properties.jpg

(link) ..

more: More info on Surface

Opens a dialog with detailed information about the object in geek speak.

Drw: Choose the rendering (drawing) mode for this surface.

Choose the rendering mode for this surface.

Viewer: Surface’s rendering mode is set by the viewer’s setting which can be changed with the ‘p’ option.

Fill: Shaded rendering mode.

Line: Mesh rendering mode.

Points: Points rendering mode.

Trn: Choose the transparency for this surface.

Set the transparency for this surface to one of the following options.

Viewer: Surface’s transparency is set by the viewer’s setting which can be changed with the o, O options.

0 : No transparency, opaque.

16: Maximum transparency, invisibile

Dsets: Show/Hide Dataset (previously Color Plane) controllers

Show/Hide Dataset (previously Color Plane) controllers

Crosshair Information

../_images/SurfCont.auto.Xhair_Info.jpg

(link) ..

Xhr: Crosshair coordinates.

Set/Get crosshair location in mm RAI on this controller’s selected object. Entering new coordinates makes the crosshair jump to that location (like ‘ctrl+j’). Use ‘alt+l’ to center the cross hair in your viewer.

Node: Node index

Index of node in focus (1) and RAI coordinates of that node (2).

1- The index is of the node in focus on this controller’s surface. Nodes in focus are highlighted by the blue sphere in the crosshair. This cell is editable; manually entering a new node’s index will put that node in focus and send the crosshair to its location (like ‘j’). Use ‘alt+l’ to center the cross hair in your viewer.

2- The RAI coordinates are those of the surface node after all spatial transformations have been applied to the surface. Those transformations do not include visualization transformations applied in the viewer

Tri: 1- Triangle index, 2- Nodes forming tiangle

1- Triangle (faceset) index of triangle in focus on this on this controller’s surface. Triangle in focus is highlighted in gray, and entering a new triangle’s index will set a new triangle in focus (like ‘J’).

2- Indices of nodes forming triangle.

Val: Data Values at node in focus

Data values at node in focus. Intensity, Threshold, and Brightness show the triplets of values at the selected node that correspond to the dataset column choices in I, T, and B selectors.

Lbl: Color at node in focus

Labels available at the selected datum. If nothing is available, datum color is displayed.

Dset Controls

../_images/SurfCont.auto.Dset_Controls.jpg

(link) ..

Lbl+Par: Label of Dset

Label of dataset currently selected. Note that for some objects, like surfaces, what you’re viewing at any moment maybe a blend of multiple datasets. See color mixing for details.

Ord: Order of Dset’s colorplane.

Order of Dset’s colorplane in the stack of all colorplanes of the parent surface. The datset with highest order number is on top of the stack. Separate stacks exist for foreground (fg:) and background planes (bg:).

See Color Mixing for details on how colors are merged.

Opa: Opacity of Dset’s colorplane.

Opacity of Dset’s colorplane. Opaque planes have an opacity of 1, transparent planes have an opacity of 0. Opacities are used when mixing planes within the same group foreground (fg:) or background(bg:).

Opacity values are not applied to the first plane in a group. Consequently, if you have just one plane to work with, opacity value is meaningless.

Color mixing can be done in two ways, use F7 to toggle between mixing modes.

Dim: Dimming factor to apply to colormap or color datasets.

Dimming factor to apply to colormap before mapping the intensity (I) data. The colormap, if displayed on the right, is not visibly affected by Dim but the colors mapped onto the surface, voxel grid, tracts, etc. are. For RGB Dsets (e.g. .col files, or tract colors), Dim is applied to the RGB colors directly.

Decreasing Dim is useful when the colors are too saturated for lighting to reflect the object terrain. When in doubt, just press the button and see what happens.

Dsp: Choose the rendering mode for this dataset.

Choose the viewing mode for this dataset.

Col: Colours, only.

Con: Contours (slower), only.

C&C: Colours and Contours (slower), only.

XXX: Unfortunately nothing, only.

There is one contour created for each color in the colormap. You’d want to use colormaps with few colors to get a contour of use. Contours are not created if colormap has panes of unequal sizes.

1: Show ONLY ONE selected Dset. Foreground only.

If ON, view only the selected Dset’s colors. No mixing of colors in the foreground stack is done.

If OFF, then mix the color planes in the foreground stack.

This option makes it easy to view one Dset’s colors at a time without having to worry about color mixing, opacity, and stacking order.

Needless to say, options such as ‘Ord:’ and ‘Opa:’ in this panel are of little use when this button is ON.

Switch_Dset: Switch between datasets

Switch between datasets.

Load_Dset: Load a new dataset

Load a new dataset (Dset). Datasets can be of 3 formats:

1- NIML (.niml.dset) :This format is internal to AFNI/SUMA.

2- GIFTI (.gii.dset):The format to end all formats.

3- 1D (.1D.dset) :Simple ASCII tabular format supporting numerical values only.

Each row i contains Nj data values per node.Since this format has no headerassociated with it, it makessome assumption about the datain the columns.

You can choose from 3 options: (see below for nomenclature)

  • Each column has Ni values where Ni = N_Node. In this case, it is assumed that row i has values for node i on the surface.

  • If Ni is not equal to N_Node then SUMA will check to see if column 0 (Col_0) is all integers with values v satisfying: 0 <= v < N_Node . If that is the case then column 0 contains the node indices. The values in row j of Dset are for the node indexed Col_0[j]. In the sample 1D Dset shown below assuming N_Node > 58, SUMA will consider the 1st column to contain node indices. In that case the values -12.1 and 0.9 are for node 58 on the surface.

  • Lastly, if Col_0 fails the node index test, then SUMA considers the data in row i to be associated with node i.

If you’re confused, try creating some toy datasets like the one below and load them into SUMA.

Sample 1D Dset (Call it pickle.1D.dset):

25 22.7 1.2 58 -12.1 0.9

Nomenclature and conventions:
  • N_Node is the number of nodes forming the surface.

  • Indexing always starts at 0. In the example, value v at row 0, column 1 is v = 22.7 .

  • A Dset has Ni rows and Nj columns. In other terms, Ni is the number of values per node and Nj is the number of nodes for which data are specified in Dset. Ni = 2, Nj = 3 in the example.

Load_Col: Load a new color plane

Load a new color plane. A color plane is a 1D text file with each row formatted as such

n r g b

where n is the node index, r, g, and b are the red, green and blue color values, respectively. Color values must be between 0 and 1.0. A sample file would be: test.1D.col with content:

0    0.1 0.2 1
1    0   1   0.8
4    1   1   1
7    1   0   1
14   0.7 0.3 0

Dset Color Mapping

../_images/SurfCont.auto.Dset_Mapping.jpg

(link) ..

IxT: Set I, T selection linking modes.

Switch between methods for the automatic linking of I, T selectors.

None: Do nothing.

Same: Set the T selector to match the I selection.

Stat: Switch T selector to match an I selection with an obvious statistic. Matching is based on labels.

You can set your preference using environment variable

SUMA_IxT_LinkMode

I: Select Intensity (I) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for an Intensity (I)measure.

Values in (I) are the ones that get colored by the colormap,however, no coloring is done if the ‘v’ button on the right isturned off.

The (I) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (I). A right-click on ‘I’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the numberof sub-bricks (columns) you have in your dataset. If the numberexceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: View (ON)/Hide Dset node colors

View (ON)/Hide Dset node colors

T: Select Threshold (T) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for a Threshold (T) measure.

T values are the ones used to determine if a datum gets colored based on its (I) value.

A datum n is not colored if:

T(n) < Tscale

or if ‘|T|’ option below is turned ON:

T(n) | < Tscale .

Thresholding is not applied when the ‘v’ button on the right is turned off.

The (T) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (T). A right-click on ‘T’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the number of sub-bricks (columns) you have in your dataset. If the number exceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: Apply (ON)/Ignore thresholding

Apply (ON)/Ignore thresholding

B: Select Brightness (B) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for color Brightness (B) modulation.

The (B) values are the ones used to control the brightness of a datum’s color.

Brightness modulation is controlled by ranges in the ‘B’ cells of the table below.

Brightness modulation is not applied when the ‘v’ button on the right is turned off.

The (B) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (B). A right-click on ‘B’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the numberof sub-bricks (columns) you have in your dataset. If the numberexceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: View (ON)/Ignore brightness modulation

View (ON)/Ignore brightness modulation

ThrVal[0]: Threshold Value (append ‘p’ to set by p value, ‘%’ to set by percentile)

Set/Get the threshold value. When statistical parameters are set under T, you can append a ‘p’ to set by the p value, as in 0.001p.

For percentile thresholding, append a ‘%’ to the value, such as 25%

bar: Colorbar for ‘I’ values

Colorbar used for colorizing values in ‘I’ sub-brick. Colorization depends on the settings under the I, Range Setting, among other things. Threshold settings determine whether or not a certain value will get displayed at all.

Use ctrl+h over the colorbar for help on manipulating the displayed map.

scale: Set the threshold for ‘T’ values

Set threshold value to determine which nodes/voxels/edges will get coloredVoxels for which the value in the ‘T’ sub-brick is below that of the threshold will not get colored.

pval: Nominal p-value per node; FDR q-value

Shows the estimated significance (p-value) of the threshold above, if possible.

  • If not possible, will display as ‘[N/A]’ instead.

  • p’s that display as 1.2-7 should be interpreted as 1.2 x 10^(-7)

  • p-value here is significance PER NODE/VOXEL/etc.

  • If FDR curves are pre-computed in the dataset’s header, then the False Discovery Rate q-value will also be shown.

  • You can add FDR curves to a dataset with ‘3drefit -addFDR’.

SetRangeTable: Clipping ranges

Used for setting the clipping ranges. Clipping is only done for color mapping. Actual data values do not change.

SetRangeTable.r01: Intensity clipping range (append ‘%’ for percentiles, see BHelp)

Intensity clipping range rules:

Values in the intensity data that are less than Min are colored by the first (bottom) color of the colormap.

Values larger than Max are mapped to the top color.

Intermediate values are mapped according to the ‘Col’ menu below.

You can set the range as a percentile of the dataset’s values by appending ‘%’ to the percentile for Min and/or Max such as 5% or 90%. Note that the percentile always gets replaced by the actual value in the dataset.

A left-click on ‘I’ locks ranges from automatic resetting, and the locked range applies to the current Dset only. A locked range is indicated with the reverse video mode.

A right-click resets values to the default range (usually 2% to 98%) in the dataset.

SetRangeTable.r02: Brightness modulation clipping range

Values in the brightness (B) column are clipped to the Min to Max range in this row before calculating their modulation factor per the values in the next table row.

You can set the range as a percentile of the dataset’s values by appending ‘%’ to the percentile for Min and/or Max such as 8% or 75%. Note that the percentile always gets replaced by the actual value in the dataset.

A left-click locks ranges in this row from automatic resetting, and a locked range is applied to the current Dset only. A locked range is indicated with the reverse video mode.

A right-click resets values to the default range (usually 2% to 98%) for the dataset.

SetRangeTable.r03: Brightness modulation factor range

Brightness modulation factor range. Brightness modulation values, after clipping per the values in the row above, are scaled to fit the range specified here.

Col: Switch between color mapping modes.

Switch between modes for mapping values to the color map.

The bottom color of the map C0 maps to the minimum value in the I range row, and the top color to the maximum value. Colors for values in between the minimum and maximum of I range, the following methods apply

Int: Interpolate linearly between colors in colormap to find color at

icol=((V-Vmin)/Vrange * Ncol)

NN : Use the nearest color in the colormap. The index into the colormap of Ncol colors is given by

icol=floor((V-Vmin)/Vrange * Ncol)

with icol clipped to the range 0 to Ncol-1

Dir: Use intensity values as indices into the colormap. In Dir mode, the intensity clipping range is of no use.

icol=floor(V) with clipping to the range 0 to Ncol-1

Bias: Coordinate bias direction

Coordinate bias direction.

-: No bias thank you

x: X coord bias

y: Y coord bias

z: Z coord bias

n: bias along node’s normal

See more info in Bhelp for ‘C’ table entry above.

This option will produce ‘Extremely Cool’[1] images. [1] Chuck E. Weiss (Slow River/Rykodisc) 1999.

Cmp: Switch between available color maps.

Switch between available color maps. If the number of colormaps is too large for the menu button, right click over the ‘Cmp’ label and a chooser with a slider bar will appear.

More help is available via ctrl+h while mouse is over the colormap.

New: Load new colormap

Load new colormap. Loaded map will replace a pre-existing one with the same name.

See ScaleToMap -help for details on the format of colormap file. The formats are described in the section for the option -cmapfile.

A sample colormap would be:

0 0 1
1 1 1
1 0 0

saved into a cmap file called cmap_test.1D.cmap See also envs SUMA_CmapsDir, SUMA_RetinoAngle_DsetColorMap and SUMA_VFR_DsetColorMap

abs_T: Absolute threshold ON/OFF

Toggle Absolute thresholding.

OFF: Mask color for datum (nodes, edges, voxels, etc.) that have:

T(n) < Tscale

ON: Mask color for datum that have:

T(n) | < Tscale

where:

Tscale is the value set by the threshold scale.

T(n) is the datum value in the selected threshold column (T). This value is seen in the second cell of the ‘Value’ table on the left side.

sym_I: Intensity range symmetry about 0

Toggle Intensity range symmetry about 0.

ON : Intensity clipping range is forced to go from -val to val. This allows you to mimic AFNI’s ranging mode.

OFF: Intensity clipping range can be set to your liking.

shw_0: Color masking of nodes with intensity = 0

Toggle color masking of nodes with intensity = 0

ON : 0 intensities are mapped to the colormap as any other values.

OFF: 0 intensities are masked, a la AFNI

Clst: Clusterizing options

Used for setting the clustering parameters.

Clst.c01: Connectedness criterion

Minimum distance between nodes. Nodes closer than the minimum distance are in same cluster. If you want to distance to be in number of edges (N) separating nodes, set the minimum distance to -N. This parameter is the same as -rmm in the program SurfClust

RangeTable: Full range of values in Dset

Full range of values in Dset

RangeTable.r01: Range of values in intensity (I) column

Range of values in intensity (I) column

RangeTable.r02: Range of values in threshold (T) column

Range of values in threshold (T) column

RangeTable.r03: Range of values in brightness (B) column

Range of values in brightness (B) column

RangeTable.c01: Minimum value in Dset column

Minimum value in Dset column

RangeTable.c02: Node index at minimum

Node index at minimum. Right click in cell to have crosshair jump to node’s index. Same as ‘ctrl+j’ or an entry in the ‘Node’ cell under Xhair Info block.

RangeTable.c03: Maximum value in Dset column

Maximum value in Dset column

RangeTable.c04: Node index at maximum

Node index at maximum. Right click in cell to have crosshair jump to node’s index. Same as ‘ctrl+j’ or an entry in the ‘Node’ cell under Xhair Info block.

Network/Tracts Cont.

The tract controller is for controlling the way tracts and values defined over them are displayed. Each network of tracts gets its own controller. You can launch the Tract Controller with: ctrl+s or View‣Object Controller

../_images/TractCont.auto.ALL.jpg

(link)

Tract Properties

Name and number of bundles, tracts, and points making up the selected network of tracts.

../_images/TractCont.auto.Tract_Properties.jpg

(link) ..

more: More info on network of tracts

Opens a dialog with detailed information about the object in geek speak.

Information at crosshair

../_images/TractCont.auto.Xhair_Info.jpg

(link) ..

Xhr: Crosshair coordinates.

Set/Get crosshair location in mm RAI on this controller’s selected object. Entering new coordinates makes the crosshair jump to that location (like ‘ctrl+j’). Use ‘alt+l’ to center the cross hair in your viewer.

Ind: Point index in whole network

Set/Get the 1D index of the selected elementary tract datum: the infinitesimal point.

BTP: Bundle index in network, Tract index in bundle, Point index in tract

Set/Get the triplet of indices for the selection on the displayed tracts.

The 1st index is that of the selected bundle in the network

The second is for the selected tract in that bundle

The third is the index of the point selected along that tract.

Val: Data values at tract point in focus

Data values at point in focus. At the moment, Intensity, Threshold, and Brightness show the RGB values for the point selected. Eventually, they would represent the triplets of values at the point that correspond to the dataset column choices in I, T, B.

Lbl: Label at selected point

Labels at selected point. For now, nothing more than a regurgitation of BTP

Coloring Controls

Controls the final coloration of the tracts based on the tract datasets available. What’s a tract dataset you say? It is a dataset defined over the collection of points that define the tracts of a network. And where do we get these sets? Nowhere at the moment. For now they are generated internally and they are only of the RGB variety. This will change in the future, when you would be able to drive a flying car and have arbitrary sets much like on surfaces or volumes.

../_images/TractCont.auto.Coloring_Controls.jpg

(link) ..

Lbl: Label of dataset displayed on tracts

Label of dataset currently selected. Note that for some objects, like surfaces, what you’re viewing at any moment maybe a blend of multiple datasets. See color mixing for details.

Dim: Dimming factor to apply to colormap or color datasets.

Dimming factor to apply to colormap before mapping the intensity (I) data. The colormap, if displayed on the right, is not visibly affected by Dim but the colors mapped onto the surface, voxel grid, tracts, etc. are. For RGB Dsets (e.g. .col files, or tract colors), Dim is applied to the RGB colors directly.

Decreasing Dim is useful when the colors are too saturated for lighting to reflect the object terrain. When in doubt, just press the button and see what happens.

Ord: Order of Dset’s colorplane.

Order of this tract’s dataset colorplane in the stack of all colorplanes available. The datset with highest order number is on top of the stack. See color plane grouping for details on how colors are merged.

1: Show ONLY selected set.

If ON, view only the selected Dset’s colors.

If OFF, then mix the color planes in the datasets stack.

This option makes it easy to view one Dset’s colors at a time without having to worry about color mixing, opacity, and stacking order.

Needless to say, options such as ‘Ord:’ and ‘Opa:’ in this panel are of little use when this button is ON.

Opa: Opacity of Dset’s colorplane.

Opacity of Dset’s colorplane. Opaque planes have an opacity of 1, transparent planes have an opacity of 0.

Opacity values are not applied to the first plane in a group. Consequently, if you have just one plane to work with, or you have 1 ON, the opacity value is meaningless.

Color mixing can be done in two ways, use F7 to toggle between mixing modes.

Ln: Line drawing style

Choose the line drawing style.

Digits specify number of pixels to mask out of each 16 pixels

1 : One pixel/16 off, almost solid

15: 15/16 pixels off, almost invisible

HDE: Hide all the tracts

SLD: No stippling, solid line.

Masks: Create/Switch to Masks controller

Opens controller for masks. At the first click, this button creates a new interactive tract mask and activates menu items such as Gry. A ball of a mask is added to the interface, and only tracts that go through it are displayed.

../_images/MaskButtonInController.jpg

(link)

Clicking on Masks after the initialization brings up the Mask Controller. See mask manipulation mode for details on how to move the mask around.

Hde: Choose how masked tracts are displayed.

That’s not the name of the button, but its default value. This menu controls how tracts that fall outside of the masks are displayed:

Hde: Hide ‘em masked tracts

Gry: Gray ‘em masked tracts (gray color set by Gry arrow field)

One: A coding mistake that ended up looking cool. Each tract not in the mask is colored by one color extracted from the set of colors for the whole network.

Ign: Ignore ‘em good for nothing masks, show tracts in all their unabashed glory

Gry: Gray level (0–100) of tracts outside of mask (only for Msk –> Gry)

Set the gray level for masked tracts. 0 for black, 100 for white

This arrow field only has an effect when ‘Msk’ menu is set to ‘Gry’

Switch_Dset: Switch between datasets

Select the dataset to which the Coloring Controls are being applied. For now you have three free RGB datasets per network that are created by SUMA. In the first one each node of a tract is colored based on the local orientation, with red, green, and blue values reflecting the X,Y, and Z components of the unit direction vector. In the second dataset all nodes of a tract are assigned the color of the middle node of that tract. In the third dataset, all nodes of a tract are colored based on the bundle in which that tract resides.The number of colors in such a dataset depend on the total number of bundles in the entire network.

Mask Manipulation Mode

To move the mask interactively, right-double click on it to place SUMA in Mask Manipulation Mode which is indicated by displaying the moveable mask in mesh mode (see help in SUMA, (ctrl+h), section Button 3-DoubleClick for details.). Selecting a location on the tracts, the slices, or surfaces, will make the mask jump to that location. The mask should also be visibile in AFNI (if SUMA is launched with -dev option), and clicking in AFNI will make the mask move in SUMA also.

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

../_images/MaskManipulationMode_OFF.jpg

Mask manipulation OFF.

../_images/MaskManipulationMode_ON.jpg

Mask manipulation ON.

../_images/blank.jpg

Network tracts mask controller

The mask controller is used for manipulating masks for network tractsYou can launch the Mask Controller from the tract controller by clicking on Masks twice.

../_images/MaskController.02.jpg

(link) ..

Create/delete masks and setup masking expression

../_images/MaskCont.auto.Masks.jpg

(link) ..

Mask_Eval: Evaluate mask expression

A boolean expression evaluated per tract to determine whether or not a tract should be displayed. Each mask is assigned a letter from ‘a’ to ‘z’ and has an entry in the table below. Symbols for the OR operator are ‘|’ or ‘+’ while those for AND are ‘&’ or ‘*’. The ‘|’ is for the NOT operation. By default, the expression is blank, as indicated by ‘-’, and the operation is an OR of all the masks.

Tract Tinting:

Tracts that go through any of the masks are displayed and they keep their own color, as shown in the figure below to the left.

Say we now want to show tracts that go through both masks b and c or through mask a. The expression to evaluate at each tract would be: ‘( b & c ) | a’. Note that for the expression to take effect, you need to have the v button selected.

../_images/MaskedTracts.01.jpg

Tracts going through any of the three masks.

../_images/MaskedTracts.02.jpg

Tracts evaluating to true per expression: ‘( b & c ) | a’. (link)

../_images/MaskController.02.jpg

Mask Controller.

../_images/blank.jpg

When using the the Mask Eval expression, the color of tracts that go though a set of regions is equal to the alpha weighted average of the colors of those regions. This can be seen in the figure on the right side above.

The colors of a tract is given by:

Ct = sum(AiCi)/sum(Ai)

for all ROIs i the tract intersects.

For example, say a tract goes through a blue region of color [0 0 1] with alpha of 0.5 (A ~ 5 in column A), and a red region of color [1 0 0] (alpha is 1.0, or in the table = 9). The tracts that go through both ROIs will be colored (1.0*([1 0 0]+0.5*([0 0 1])/1.5, which is purple. Similar averaging goes on if tracts go through more than 2 regions. Tracts that go though one region will get that region’s color.

Now, if you set alpha to 0 for a certain ROI, then that ROI does add to the tint of tracts that go thourough it at all. And for a tract that goes through that region only, it retains its original colors. See image on the right side.

../_images/Masks.02.jpg

Tracts going through any of 2 masks ‘a|b’, with ‘Mask Eval’ ON. (link)

../_images/Masks.03.jpg

Tracts going through ‘a|b’ but with alpha of ROI ‘a’ - the blue one - set to 0. Tracts going through the blue ROI are not tinted by it at all. (link)

../_images/Masks.00.jpg

Mask Controller settings for image to the left. (link)

../_images/blank.jpg

v: Enable (ON)/Disable Mask expression evaluation

Enable (ON)/Disable Mask expression evaluation

Tract_Length: Mask based on tract length

Set Min Max length for tract masking. Use can scroll (mouse wheel) in Min and Max cells to change the value. The ‘v’ button must be selected for masking to take effect.

v: Enable (ON)/Disable Tract Length masking

Enable (ON)/Disable Tract Length masking

Table: Add new mask

Add one more row for a mask ROI

Table.c01: Variable

Variable symbol. Choose from ‘a’ to ‘z’

Table.c02: Label

String label of ROI

Table.c03: Type (‘box’ or ‘sphere’)

Type of mask. For the moment, this string can only be one of ‘box’ or ‘sphere’.

Table.c04: Center X,Y,Z

Set/Get coordinates in mm RAI of the center of the mask

You can right click in cell to get back to the original center.

You can also reposition the mask interactively in the SUMA viewer by selecting something, if you are in Mask Manipulation Mode.

Table.c05: Size Sx,Sy,Sz

Set/Get size along three dimensions of mask. You can enter a single value if the all three dimensions are equal.

Right click in cell to get back to the original size.

Resizing in SUMA viewer can be done with Ctrl+scroll if you are in Mask Manipulation Mode.

You can also change values by scrolling with mouse pointer over the cell.

Table.c06: Color R G B (A)

Color of mask in RGB triplets between 0 and 1.0. You can also specify colors using the shorthands of:

‘b’ or ‘blue’

‘g’ or ‘green’

‘p’ or ‘pink’

‘r’ or ‘red’

‘w’ or ‘white’

‘y’ or ‘yellow’

The final color depends also on the dim factor ‘D’

Table.c07: A

Alpha of mask color. The Alpha value controls the contribution of an ROI’scolor to the tracts that pass through it. This tinting process is only used when ‘Mask Eval’ is in use, and when A is > 0. See the help for ‘Mask Eval’ for information on how tinting works.

You can also change values by scrolling with mouse pointer over the cell.

Table.c08: T

Transparency of mask. A value of 0 renders a mask opaque. Consider using lower D values to avoid color saturation of rendered masks.

You can also change values by scrolling with mouse pointer over the cell.

Table.c09: D

Dimming factor for color. Saturated colors may not look nice when rendered, so consider using the D parameter to dim a color’s brightness without having to so directly in the color column. Setting D to 6 for example will scale a color by a factor of 6/9, so a saturated red of [1 0 0] becomes [0.67 0 0 ]. This makes masks render better when not in transparent mode T = 0.

You can also change values by scrolling with mouse pointer over the cell.

Load_Masks: Load the masks

Load a set of masks previously saved by my neighboring button. The save operation also preserves the Mask Eval expression.

Reloading a mask file will replace current masks.

Save_Masks: Save the masks

Save current set of masks for future loading by my neighborly button.

Volume Cont.

The volume controller is for controlling the way volumes are rendered. Each volume gets its own controller. You can use the switch button above to switch between them. The volume controller is initialized by the volume of the last selected voxel.

After you have selected a voxel, you can launch the Volume Controller with: ctrl+s or View‣Object Controller

../_images/VolCont.auto.ALL.jpg

(link) ..

Volume Properties

Block providing information about selected volume.

../_images/VolCont.auto.Volume_Properties.jpg

(link) ..

more: More info on Volume

Opens a dialog with detailed information about the object in geek speak.

Information at crosshair

../_images/VolCont.auto.Xhair_Info.jpg

(link) ..

Xhr: Crosshair coordinates.

Set/Get crosshair location in mm RAI on this controller’s selected object. Entering new coordinates makes the crosshair jump to that location (like ‘ctrl+j’). Use ‘alt+l’ to center the cross hair in your viewer.

Ind: Voxel 1D index in volume

Set/Get the 1D index of the selected elementary surface datum: the voxel.

IJK: Voxel 3D indices in volume

Triplet of indices (I) of selected voxel. The mm RAI coordinate X = M I with M being the matrix transforming voxel indices to voxel coordinates.

Val: Data Values at voxel in focus

Data values at voxel in focus. Intensity, Threshold, and Brightness show the triplets of values at the selected voxel that correspond to the volume column choices in I, T, and B selectors.

Lbl: Label at voxel in focus

Labels available at the selected datum. If nothing is available, datum color is displayed.

Set up which and how many slices are displayed

../_images/VolCont.auto.Slice_Controls.jpg

(link)

Ax: Select axial slice(s) to render (use BHelp for details)

Select axial slice(s) to render. If the dataset is oblique, that would be the slice that is closest to the axial plane. Move slider bar or enter slice number directly in adjoining field. To show a stack of axial slices set the second text field to N:S where N is the number of slices in the stack and S is the spacing in number of slices between consecutive slices. The stack is centered on the chosen slice number. So when N > 1 and even, the ‘selected’ slice is not rendered. In that case, set N to the next odd number to see it. To hide/show all displayed axial slices, use right-side toggle button.

Sa: Select sagittal slice(s) to render (use BHelp for details)

Select sagittal slice(s) to render. If the dataset is oblique, that would be the slice that is closest to the sagittal plane. Move slider bar or enter slice number directly in adjoining field. To show a stack of sagittal slices set the second text field to N:S where N is the number of slices in the stack and S is the spacing in number of slices between consecutive slices. The stack is centered on the chosen slice number. So when N > 1 and even, the ‘selected’ slice is not rendered. In that case, set N to the next odd number to see it. To hide/show all displayed sagittal slices, use right-side toggle button.

Co: Select coronal slice(s) to render (use BHelp for details)

Select coronal slice(s) to render. If the dataset is oblique, that would be the slice that is closest to the coronal plane. Move slider bar or enter slice number directly in adjoining field. To show a stack of coronal slices set the second text field to N:S where N is the number of slices in the stack and S is the spacing in number of slices between consecutive slices. The stack is centered on the chosen slice number. So when N > 1 and even, the ‘selected’ slice is not rendered. In that case, set N to the next odd number to see it. To hide/show all displayed coronal slices, use right-side toggle button.

Trn: Choose the transparency for these slices.

Set the transparency level for this set of slices to one of the following options:

Viewer: Surface’s transparency is set by the viewer’s setting which can be changed with the o, O options.

Only Cheesecloth transparency is allowed in this setting.

A : Alpha blending. May look good, but not always accurate.

0 : No transparency, opaque.

16: Maximum transparency, invisibile

Slices_At_+: Make slices jump to crosshair location

Make slices jump to crosshair location

Set the parameters for 3D rendering

../_images/VolCont.auto.Volume_Rendering_Controls.jpg

(link)

Ns: Volume Rendering Settings (use BHelp for details)

Set the number of slices used to render the volume. Volume rendering is done by slicing the volume from the far end along your vieweing direction to the front, blending successive images along the way. The more slices you use the better the result, something comparable to the maximum number of voxels in any of the directions would be a good start. Of course, the more slices, the slower the rendering.

Blending is affected by Avl and Ath settings.

v: View (ON)/Hide VrF

View (ON)/Hide Volume Rendering

Dset Controls

../_images/VolCont.auto.Dset_Controls.jpg

(link)

Lbl: Label of Volume Dset

Label of dataset currently selected. Note that for some objects, like surfaces, what you’re viewing at any moment maybe a blend of multiple datasets. See color mixing for details.

Dim: Dimming factor to apply to colormap or color datasets.

Dimming factor to apply to colormap before mapping the intensity (I) data. The colormap, if displayed on the right, is not visibly affected by Dim but the colors mapped onto the surface, voxel grid, tracts, etc. are. For RGB Dsets (e.g. .col files, or tract colors), Dim is applied to the RGB colors directly.

Decreasing Dim is useful when the colors are too saturated for lighting to reflect the object terrain. When in doubt, just press the button and see what happens.

Avl: Choose method for computing color alpha value for voxels.

Choose the method for assigning an alpha value (A) to a voxel’s color.

Avg : A = average of R, G, B values

Max : A = maximum of R, G, B values

Min : A = minimum of R, G, B values

I : A is based on I selection. I range parameters apply

T : A is based on T selection. Full range is used.

B : A is based on B selection. B range parameters apply

XXX: A is set to 0, nothing will show.

Ath: Threshold for voxel alpha value.

Alpha threshold of Dset’s rendered slices. When datasets’ voxels get colored, they get an Alpha (A) value in addition to the R, G, B values. A is computed based on the setting of the ‘Avl’ menu. Voxels (or more precisely, their openGL realization) with Alpha lower than this value will not get rendered. This is another way to ‘threshold’ a rendered volume, and is comparable to thresholding with the slider bar if using a monochromatic increasingly monotonic colormap with ‘Avl’ set to one of Max, Min, or Avg. Note that thresholding with the slider bar sets A for thresholded voxels to 0.0 regardless of the setting for ‘Avl’. Thresholding with Ath is faster than using the slider bar because it does not require recreating the whole texture.

Dset Color Mapping

../_images/VolCont.auto.Dset_Mapping.jpg

(link) ..

IxT: Set I, T selection linking modes.

Switch between methods for the automatic linking of I, T selectors.

None: Do nothing.

Same: Set the T selector to match the I selection.

Stat: Switch T selector to match an I selection with an obvious statistic. Matching is based on labels.

You can set your preference using environment variable

SUMA_IxT_LinkMode

I: Select Intensity (I) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for an Intensity (I)measure.

Values in (I) are the ones that get colored by the colormap,however, no coloring is done if the ‘v’ button on the right isturned off.

The (I) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (I). A right-click on ‘I’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the numberof sub-bricks (columns) you have in your dataset. If the numberexceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: View (ON)/Hide volume voxel colors

View (ON)/Hide Dset voxel colors

T: Select Threshold (T) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for a Threshold (T) measure.

T values are the ones used to determine if a datum gets colored based on its (I) value.

A datum n is not colored if:

T(n) < Tscale

or if ‘|T|’ option below is turned ON:

T(n) | < Tscale .

Thresholding is not applied when the ‘v’ button on the right is turned off.

The (T) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (T). A right-click on ‘T’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the number of sub-bricks (columns) you have in your dataset. If the number exceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: Apply (ON)/Ignore thresholding

Apply (ON)/Ignore thresholding

B: Select Brightness (B) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for color Brightness (B) modulation.

The (B) values are the ones used to control the brightness of a datum’s color.

Brightness modulation is controlled by ranges in the ‘B’ cells of the table below.

Brightness modulation is not applied when the ‘v’ button on the right is turned off.

The (B) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (B). A right-click on ‘B’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the numberof sub-bricks (columns) you have in your dataset. If the numberexceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: View (ON)/Ignore brightness modulation

View (ON)/Ignore brightness modulation

ThrVal[0]: Threshold Value (append ‘p’ to set by p value, ‘%’ to set by percentile)

Set/Get the threshold value. When statistical parameters are set under T, you can append a ‘p’ to set by the p value, as in 0.001p.

For percentile thresholding, append a ‘%’ to the value, such as 25%

bar: Colorbar for ‘I’ values

Colorbar used for colorizing values in ‘I’ sub-brick. Colorization depends on the settings under the I, Range Setting, among other things. Threshold settings determine whether or not a certain value will get displayed at all.

Use ctrl+h over the colorbar for help on manipulating the displayed map.

scale: Set the threshold for ‘T’ values

Set threshold value to determine which nodes/voxels/edges will get coloredVoxels for which the value in the ‘T’ sub-brick is below that of the threshold will not get colored.

pval: Nominal p-value per node; FDR q-value

Shows the estimated significance (p-value) of the threshold above, if possible.

  • If not possible, will display as ‘[N/A]’ instead.

  • p’s that display as 1.2-7 should be interpreted as 1.2 x 10^(-7)

  • p-value here is significance PER NODE/VOXEL/etc.

  • If FDR curves are pre-computed in the dataset’s header, then the False Discovery Rate q-value will also be shown.

  • You can add FDR curves to a dataset with ‘3drefit -addFDR’.

SetRangeTable: Clipping ranges

Used for setting the clipping ranges. Clipping is only done for color mapping. Actual data values do not change.

SetRangeTable.r01: Intensity clipping range (append ‘%’ for percentiles, see BHelp)

Intensity clipping range rules:

Values in the intensity data that are less than Min are colored by the first (bottom) color of the colormap.

Values larger than Max are mapped to the top color.

Intermediate values are mapped according to the ‘Col’ menu below.

You can set the range as a percentile of the dataset’s values by appending ‘%’ to the percentile for Min and/or Max such as 5% or 90%. Note that the percentile always gets replaced by the actual value in the dataset.

A left-click on ‘I’ locks ranges from automatic resetting, and the locked range applies to the current Dset only. A locked range is indicated with the reverse video mode.

A right-click resets values to the default range (usually 2% to 98%) in the dataset.

SetRangeTable.r02: Brightness modulation clipping range

Values in the brightness (B) column are clipped to the Min to Max range in this row before calculating their modulation factor per the values in the next table row.

You can set the range as a percentile of the dataset’s values by appending ‘%’ to the percentile for Min and/or Max such as 8% or 75%. Note that the percentile always gets replaced by the actual value in the dataset.

A left-click locks ranges in this row from automatic resetting, and a locked range is applied to the current Dset only. A locked range is indicated with the reverse video mode.

A right-click resets values to the default range (usually 2% to 98%) for the dataset.

SetRangeTable.r03: Brightness modulation factor range

Brightness modulation factor range. Brightness modulation values, after clipping per the values in the row above, are scaled to fit the range specified here.

Col: Switch between color mapping modes.

Switch between modes for mapping values to the color map.

The bottom color of the map C0 maps to the minimum value in the I range row, and the top color to the maximum value. Colors for values in between the minimum and maximum of I range, the following methods apply

Int: Interpolate linearly between colors in colormap to find color at

icol=((V-Vmin)/Vrange * Ncol)

NN : Use the nearest color in the colormap. The index into the colormap of Ncol colors is given by

icol=floor((V-Vmin)/Vrange * Ncol)

with icol clipped to the range 0 to Ncol-1

Dir: Use intensity values as indices into the colormap. In Dir mode, the intensity clipping range is of no use.

icol=floor(V) with clipping to the range 0 to Ncol-1

Cmp: Switch between available color maps.

Switch between available color maps. If the number of colormaps is too large for the menu button, right click over the ‘Cmp’ label and a chooser with a slider bar will appear.

More help is available via ctrl+h while mouse is over the colormap.

New: Load new colormap

Load new colormap. Loaded map will replace a pre-existing one with the same name.

See ScaleToMap -help for details on the format of colormap file. The formats are described in the section for the option -cmapfile.

A sample colormap would be:

0 0 1
1 1 1
1 0 0

saved into a cmap file called cmap_test.1D.cmap See also envs SUMA_CmapsDir, SUMA_RetinoAngle_DsetColorMap and SUMA_VFR_DsetColorMap

abs_T: Absolute threshold ON/OFF

Toggle Absolute thresholding.

OFF: Mask color for datum (nodes, edges, voxels, etc.) that have:

T(n) < Tscale

ON: Mask color for datum that have:

T(n) | < Tscale

where:

Tscale is the value set by the threshold scale.

T(n) is the datum value in the selected threshold column (T). This value is seen in the second cell of the ‘Value’ table on the left side.

sym_I: Intensity range symmetry about 0

Toggle Intensity range symmetry about 0.

ON : Intensity clipping range is forced to go from -val to val. This allows you to mimic AFNI’s ranging mode.

OFF: Intensity clipping range can be set to your liking.

shw_0: Color masking of nodes with intensity = 0

Toggle color masking of nodes with intensity = 0

ON : 0 intensities are mapped to the colormap as any other values.

OFF: 0 intensities are masked, a la AFNI

RangeTable: Full range of values in Dset

Full range of values in Dset

RangeTable.r01: Range of values in intensity (I) column

Range of values in intensity (I) column

RangeTable.r02: Range of values in threshold (T) column

Range of values in threshold (T) column

RangeTable.r03: Range of values in brightness (B) column

Range of values in brightness (B) column

RangeTable.c01: Minimum value in Dset column

Minimum value in Dset column

RangeTable.c02: Node index at minimum

Node index at minimum. Right click in cell to have crosshair jump to node’s index. Same as ‘ctrl+j’ or an entry in the ‘Node’ cell under Xhair Info block.

RangeTable.c03: Maximum value in Dset column

Maximum value in Dset column

RangeTable.c04: Node index at maximum

Node index at maximum. Right click in cell to have crosshair jump to node’s index. Same as ‘ctrl+j’ or an entry in the ‘Node’ cell under Xhair Info block.

Graph Cont.

The graph controller is for controlling the way graphs (matrices) are rendered. Each graph gets its own controller. You can use the switch button above to switch between them. The graph controller is initialized by the graph of the last selected edge/cell.

After you have selected an edge, you can launch the Graph Controller with: ctrl+s or View‣Object Controller

../_images/GraphCont.auto.ALL.jpg

(link)

Properties of graph dset

../_images/GraphCont.auto.Graph_Dset_Properties.jpg

(link) ..

more: More info on Graph Dset

Opens a dialog with detailed information about the object in geek speak.

Crosshair Information

../_images/GraphCont.auto.Xhair_Info.jpg

(link) ..

Xhr: Crosshair coordinates.

Set/Get crosshair location in mm RAI on this controller’s selected object. Entering new coordinates makes the crosshair jump to that location (like ‘ctrl+j’). Use ‘alt+l’ to center the cross hair in your viewer.

Edge: 1- Edge index, 2- Nodes forming (directed) edge

1- Edge/Cell Index: Get/Set index of edge/cell in focus on this controller’s graph. This number is the 1D index of the edge/cell in the graph/matrix. Consider it the equivalent of a voxel 1D index in a volume, or a node in a surface dataset. Entering a new edge’s index will put that edge in focus and send the crosshair to its center (like j). Use alt+l to center the cross hair in your viewer.

Note that an edge can be formed by a pair of identical nodes - think matrix diagonal.

2- Nodes Forming Directed Edge/Cell: For a cell, this would its pair of row and column indices into the matrix. For a graph, this would be the indices of the nodes forming the directed edge.

Node: Closest Node index

Index of the node closest to the selection location on the edge’s representation.

NOTE that a node is also an edge that starts and ends at the samenode. Think diagonal elements of a connectivity matrix.

Val: Data Values at Edge in Focus

Data values at edge in focus. Intensity, Threshold, and Brightness show the triplets of values at the selected edge that correspond to the graph/matrix choices.in I, T, and B selectors.

Lbl: Label of edge in focus

Labels from the selected graph dataset at the edge in focus. If no labels are available, edge color is displayed.

Control appearance of 3D graphs and matrices

../_images/GraphCont.auto.GDset_Controls.jpg

(link) ..

Dim: Dimming factor to apply to colormap or color datasets.

Dimming factor to apply to colormap before mapping the intensity (I) data. The colormap, if displayed on the right, is not visibly affected by Dim but the colors mapped onto the surface, voxel grid, tracts, etc. are. For RGB Dsets (e.g. .col files, or tract colors), Dim is applied to the RGB colors directly.

Decreasing Dim is useful when the colors are too saturated for lighting to reflect the object terrain. When in doubt, just press the button and see what happens.

Bundles: Show bundles instead of edges if possible.

Show bundles instead of edges between nodes if the graph dataset contains such information. For the moment, only 3dProbTrackID creates such data.

../_images/Graph3D.jpg

Graph shown in 3D. Edges represented by straight lines.

../_images/Graph3D_Bundles.jpg

Graph shown in 3D. Edges represented by bundles derived from. tractography with 3dTrackID. See FATCAT Visualization for details.

../_images/blank.jpg

Figures were generated using FATCAT Visualization output with:

suma -vol mprage+orig. -gdset DTI/o.NETS_AND_000.niml.dset &

Bundle colors reflect the value of the edge connecting the two nodes

Selection is identical to when edges are represented by straight lines.

CN: How to display connection to selected graph node.

When a node, rather than an edge is selected, choose how connections to it are displayed.

Edg: Show connections to selected node with edges, either straight lines or with bundles.

Col: Show connections to selected node by changing the colors of the connecting nodes, based on edge value. Edges are not displayed. the idea here is to reduce the clutter of the display, while still allowing you to visualize connection strength to one node at a time.

Rad: Show connections to selected node by changing the radius of the connecting nodes, based on edge value. Edges are not displayed in this mode also.

CaR: Both Col and Rad

XXX: Do nothing special, keep showing whole graph, even when selecting a graph node.

Rd: Choose the sizing option for graph nodes.

Choose the radius sizing for nodes of this graph dataset.

Const: All nodes have a radius of 1 x Gain.

Val: Nodes size equals its dset value x Gain. A node’s dsetvalue is that of the edge connecting the node to itself

XXX: Show no balls.

Gn: Gain factor to apply to node radius.

Gain to apply to node radius. This multiplier is always applied to whatever radius value the node gets, whether is it constant or data derived.

Br: Choose the partition ratio of matrix.

Choose the partition ratio of the matrix border. This option only applies to the matrix display of the graph.

XX: No partition.

5: Border is 1/5 of cell width.

10: Border is 1/10 of cell width.

20: Border is 1/20 of cell width.

30: Border is 1/30 of cell width.

40: Border is 1/40 of cell width.

Fo: Choose the font for graph node labels.

Choose the font size for labels of nodes.

8: 8x13.

9: 9x15.

TR10: Times New Roman 10.

HE10: Helvetica 10.

HE12: Helvetica 12.

HE18: Helvetica 18.

TR24: Times New Roman 24.

XXX: Show no text.

Cl: Choose the coloring option for graph nodes.

Choose the colorization method for nodes of this dataset.

White: Alle weiss.

Black: Tutti nero.

Red: Sve crveno.

Green: Killon akhdar.

Blue: Tous bleu.

Yellow: Todos amarillo.

Gray50: Not there yet.

Val: Nodes color is based its dset value and the chosen colormap

Sh: Choose the shading options for node labels.

Choose the variants for how labels are handled.

T : Text shown unless more than 50% occluded.

Ts: Foreground text bright, occluded text shaded

B : Text shown with background box unless more than 50% occluded

Bs: Foreground text with background, occluded text shaded

Ta: All text shown, occlusions be damned.

Ba: All text shown with background, damn the torpedoes.

U: Show Unconnected graph nodes.

Show graph nodes even if unconnected to other nodes.

Th: Choose the thickness option for graph edges.

Choose the thickness for edges of this graph dataset.

Const: All nodes have a radius of 1 x Gain.

Val: Edge size equals its dset value x Gain

Gn: Gain factor to apply to edge thickness.

Gain to apply to edge thickness. This multiplier is always applied to whatever thickness value the edge gets, whether is it constant or data derived.

St: Choose the stippling option for graph edges.

Choose the stippling for edges of this graph dataset.

1 : One pixel/16 off, almost solid

15: 15/16 pixels off, almost invisible

Val: Set stippling based on the dset value

XXX: No stippling, solid line.

Control mapping of edge/cell values to color map

../_images/GraphCont.auto.GDset_Mapping.jpg

(link) ..

IxT: Set I, T selection linking modes.

Switch between methods for the automatic linking of I, T selectors.

None: Do nothing.

Same: Set the T selector to match the I selection.

Stat: Switch T selector to match an I selection with an obvious statistic. Matching is based on labels.

You can set your preference using environment variable

SUMA_IxT_LinkMode

I: Select Intensity (I) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for an Intensity (I)measure.

Values in (I) are the ones that get colored by the colormap,however, no coloring is done if the ‘v’ button on the right isturned off.

The (I) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (I). A right-click on ‘I’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the numberof sub-bricks (columns) you have in your dataset. If the numberexceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: View (ON)/Hide graph edge colors

View (ON)/Hide Dset edge colors

T: Select Threshold (T) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for a Threshold (T) measure.

T values are the ones used to determine if a datum gets colored based on its (I) value.

A datum n is not colored if:

T(n) < Tscale

or if ‘|T|’ option below is turned ON:

T(n) | < Tscale .

Thresholding is not applied when the ‘v’ button on the right is turned off.

The (T) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (T). A right-click on ‘T’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the number of sub-bricks (columns) you have in your dataset. If the number exceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: Apply (ON)/Ignore thresholding

Apply (ON)/Ignore thresholding

B: Select Brightness (B) column, aka sub-brick.

Use this menu to select which column (sub-brick) in the dataset (Dset) should be used for color Brightness (B) modulation.

The (B) values are the ones used to control the brightness of a datum’s color.

Brightness modulation is controlled by ranges in the ‘B’ cells of the table below.

Brightness modulation is not applied when the ‘v’ button on the right is turned off.

The (B) value for the selected datum (n) is shown in the ‘Val’ tableof the ‘Xhair Info’ section on the left. The value is also shown in the SUMA viewer

You can use a different type of selector to set (B). A right-click on ‘B’ opens a list widget, which is better when you have many columns from which to choose.

The style of this selector can also change depending on the numberof sub-bricks (columns) you have in your dataset. If the numberexceeds a threshold specified by the environment variable SUMA_ArrowFieldSelectorTrigger

v: View (ON)/Ignore brightness modulation

View (ON)/Ignore brightness modulation

ThrVal[0]: Threshold Value (append ‘p’ to set by p value, ‘%’ to set by percentile)

Set/Get the threshold value. When statistical parameters are set under T, you can append a ‘p’ to set by the p value, as in 0.001p.

For percentile thresholding, append a ‘%’ to the value, such as 25%

bar: Colorbar for ‘I’ values

Colorbar used for colorizing values in ‘I’ sub-brick. Colorization depends on the settings under the I, Range Setting, among other things. Threshold settings determine whether or not a certain value will get displayed at all.

Use ctrl+h over the colorbar for help on manipulating the displayed map.

scale: Set the threshold for ‘T’ values

Set threshold value to determine which nodes/voxels/edges will get coloredVoxels for which the value in the ‘T’ sub-brick is below that of the threshold will not get colored.

pval: Nominal p-value per node; FDR q-value

Shows the estimated significance (p-value) of the threshold above, if possible.

  • If not possible, will display as ‘[N/A]’ instead.

  • p’s that display as 1.2-7 should be interpreted as 1.2 x 10^(-7)

  • p-value here is significance PER NODE/VOXEL/etc.

  • If FDR curves are pre-computed in the dataset’s header, then the False Discovery Rate q-value will also be shown.

  • You can add FDR curves to a dataset with ‘3drefit -addFDR’.

SetRangeTable: Clipping ranges

Used for setting the clipping ranges. Clipping is only done for color mapping. Actual data values do not change.

SetRangeTable.r01: Intensity clipping range (append ‘%’ for percentiles, see BHelp)

Intensity clipping range rules:

Values in the intensity data that are less than Min are colored by the first (bottom) color of the colormap.

Values larger than Max are mapped to the top color.

Intermediate values are mapped according to the ‘Col’ menu below.

You can set the range as a percentile of the dataset’s values by appending ‘%’ to the percentile for Min and/or Max such as 5% or 90%. Note that the percentile always gets replaced by the actual value in the dataset.

A left-click on ‘I’ locks ranges from automatic resetting, and the locked range applies to the current Dset only. A locked range is indicated with the reverse video mode.

A right-click resets values to the default range (usually 2% to 98%) in the dataset.

SetRangeTable.r02: Brightness modulation clipping range

Values in the brightness (B) column are clipped to the Min to Max range in this row before calculating their modulation factor per the values in the next table row.

You can set the range as a percentile of the dataset’s values by appending ‘%’ to the percentile for Min and/or Max such as 8% or 75%. Note that the percentile always gets replaced by the actual value in the dataset.

A left-click locks ranges in this row from automatic resetting, and a locked range is applied to the current Dset only. A locked range is indicated with the reverse video mode.

A right-click resets values to the default range (usually 2% to 98%) for the dataset.

SetRangeTable.r03: Brightness modulation factor range

Brightness modulation factor range. Brightness modulation values, after clipping per the values in the row above, are scaled to fit the range specified here.

Col: Switch between color mapping modes.

Switch between modes for mapping values to the color map.

The bottom color of the map C0 maps to the minimum value in the I range row, and the top color to the maximum value. Colors for values in between the minimum and maximum of I range, the following methods apply

Int: Interpolate linearly between colors in colormap to find color at

icol=((V-Vmin)/Vrange * Ncol)

NN : Use the nearest color in the colormap. The index into the colormap of Ncol colors is given by

icol=floor((V-Vmin)/Vrange * Ncol)

with icol clipped to the range 0 to Ncol-1

Dir: Use intensity values as indices into the colormap. In Dir mode, the intensity clipping range is of no use.

icol=floor(V) with clipping to the range 0 to Ncol-1

Cmp: Switch between available color maps.

Switch between available color maps. If the number of colormaps is too large for the menu button, right click over the ‘Cmp’ label and a chooser with a slider bar will appear.

More help is available via ctrl+h while mouse is over the colormap.

New: Load new colormap

Load new colormap. Loaded map will replace a pre-existing one with the same name.

See ScaleToMap -help for details on the format of colormap file. The formats are described in the section for the option -cmapfile.

A sample colormap would be:

0 0 1
1 1 1
1 0 0

saved into a cmap file called cmap_test.1D.cmap See also envs SUMA_CmapsDir, SUMA_RetinoAngle_DsetColorMap and SUMA_VFR_DsetColorMap

abs_T: Absolute threshold ON/OFF

Toggle Absolute thresholding.

OFF: Mask color for datum (nodes, edges, voxels, etc.) that have:

T(n) < Tscale

ON: Mask color for datum that have:

T(n) | < Tscale

where:

Tscale is the value set by the threshold scale.

T(n) is the datum value in the selected threshold column (T). This value is seen in the second cell of the ‘Value’ table on the left side.

sym_I: Intensity range symmetry about 0

Toggle Intensity range symmetry about 0.

ON : Intensity clipping range is forced to go from -val to val. This allows you to mimic AFNI’s ranging mode.

OFF: Intensity clipping range can be set to your liking.

shw_0: Color masking of nodes with intensity = 0

Toggle color masking of nodes with intensity = 0

ON : 0 intensities are mapped to the colormap as any other values.

OFF: 0 intensities are masked, a la AFNI

RangeTable: Full range of values in Dset

Full range of values in Dset

RangeTable.r01: Range of values in intensity (I) column

Range of values in intensity (I) column

RangeTable.r02: Range of values in threshold (T) column

Range of values in threshold (T) column

RangeTable.r03: Range of values in brightness (B) column

Range of values in brightness (B) column

RangeTable.c01: Minimum value in Dset column

Minimum value in Dset column

RangeTable.c02: Edge index at minimum

Edge index at minimum. Right click in cell to have crosshair jump to edge’s index. Same as ‘ctrl+j’ or an entry in the ‘Edge’ cell under Xhair Info block.

RangeTable.c03: Maximum value in Dset column

Maximum value in Dset column

RangeTable.c04: Edge index at maximum

Edge index at maximum. Right click in cell to have crosshair jump to edge’s index. Same as ‘ctrl+j’ or an entry in the ‘Edge’ cell under Xhair Info block.

ROI Cont.

The ROI controller is for drawing ROIs on surfaces.

You can launch the Draw ROI Controller with: ctrl+d or Tools‣Draw ROI

../_images/ROICont.auto.ALL.jpg

(link)

ROI

Controls for drawing ROIs.

../_images/ROICont.auto.ROI.jpg

(link)

Draw: Toggles ROI drawing mode

Toggles ROI drawing mode. If turned on, then drawing is enabled and the cursor changes to a target. To draw, use the right mouse button. If you want to pick a node without causing a drawing action, use shift+right button.

After the draw ROI window is open, you can toggle this button via ctrl+d also.

Cont.: Toggles showing ROI contours

Toggles ROI contour drawing If turned on, then contours are drawn around filled ROIs. Contours will float over other displayed datasets

Pen: Toggles Pen drawing mode

Toggles Pen drawing mode If turned on, the cursor changes shape to a pen. In the pen mode, drawing is done with button 1. This is for coherence with AFNI’s pen drawing mode, which is meant to work pleasantly with a stylus directly on the screen. In pen mode, you draw with the left mouse button and move the surface with the right button. To pick a node, use shift+left button. Pen mode only works when Draw Mode is enabled.

Afni: Toggles Link to Afni

Toggles Afni Link for ROI drawing. If turned on, then ROIs drawn on the surface are sent to AFNI. Surface ROIs that are sent to AFNI are turned into volume ROIs (VOIs) on the fly and displayed in a functional volume with the same colormap used in SUMA. The mapping from the surface domain (ROI) to the volume domain (VOI) is done by intersection of the first with the latter. The volume used for the VOI has the same resolution (grid) as the Surface Volume (-sv option) used when launching SUMA. The color map used for ROIs is set by the environment variable SUMA_ROIColorMap.

Dist: Report length of drawn segments?

Report length of drawn segments?

—–: No distance calculations.

trace: Calculate distance along last traced segment. all: In addition to output from ‘trace’, calculate the shortest distance between the first and last node of the trace.

The results are output to the Message Log window (Help –> Message Log) with the following information:

n0, n1: Indices of first and last node forming the traced path.

N_n: Number of nodes forming the trace.

lt: Trace length calculated as the sum of the distances from node to node. This length is a slight overestimation of the geodesic length. Units for all distances is the same as the units for surface coordinates. Usually and hopefully in mm.

lt_c: Trace length corrected by a scaling factor from [1] to better approximate geodesic distances. Factor is 2/(1+sqrt(2)). Do not use this factor when N_n is small. Think of the extreme case when N_n is 2.

sd: Shortest distance on the mesh (graph) between n0 and n1 using Dijkstra’s algorithm.

sd_c: Corrected shortest distance as for lt_c.

Note 1: sd and sd_c take some time to compute. That is why they are only calculated when you select ‘all’.

Note 2: The output is formatted to be cut and pasted into a .1D file for ease of processing. You can include all the comment lines that start with ‘#’. But you cannot combine entries from the output obtained using ‘all’ option with those from ‘trace’ since they produce different numbers of values.

[1] Fischl et al, Neuroimage 9, 195-207 1999, Cortical Surface-Based Analysis.

Label: Label of ROI being drawn

Label of ROI being drawn. It is very advisable that you use different labels for different ROIs. If you don’t, you won’t be able to differentiate between them afterwards.

Value: Integer value associated with ROI

Integer value associated with ROI. This value controls the color of the ROI per the ROI colormap.

Undo: Undo the last action on the stack

Undo the last action on the stack.

Redo: Redo the last undone action

Redo the last undone action.

Join: Join the first node of the path to the last

Join the first node of the ROI to the last, thereby creating a close contour ROI. This is a necessary step before the filling operation. Joining is done by cutting the surface with a plane formed by the two nodes and the projection of the center of your window. You could double click at the last node, if you don’t want to use the ‘Join’ button.

Finish: Label ROI as finished.

Mark ROI as finished. Allows you to start drawing a new one. Once marked as finished, an ROI’s label and value can no longer be changed. To do so, you will need to ‘Undo’ the finish action.

Switch_ROI: Switch between ROIs.

Allows you to switch between ROIs. This is where you’ll suffer if ROIs on topologically isomorphic surfaces share identical labels.

Load: Load a Drawn ROI

Load a Drawn ROI. See BHelp for ‘Save’ below.

delete_ROI: Click twice in 5 seconds to delete ROI. No Undo for this action.

Delete a drawn ROI. This operation is not reversible, (no Undo here) so you’ll have to click twice.

Save: Save the Drawn ROI to disk.

Save the Drawn ROI to disk. Choose the file format and what is to be saved from the two menus ahead.

File format for saving ROI: Format options are 1D and NIML.

The 1D format is the same one used in AFNI.

It is an ASCII file with 2 values per line. The first value is a node index, the second is the node’s value. Needless, to say, this format does not support the storage of ROI auxiliary information such as Label and Parent Surface, etc., nor does it preserve the order in which nodes are traversed during a tracing. For that you’ll have to use :term:NIML.

NIML is a whole different story which will be documented (if necessary) in the future. Suffice it to say that in NIML format you can store all the auxiliary information about each ROI, unlike with the .1D format.

But more importantly, the NIML format allows you to preserve the order in which you traced the ROI. You can actually use Undo/ref:Undo<ROICont->ROI->Redo> on ROIs save in NIML format.This information can be later used for the purpose of sampling cortical activity along a particular path. This would be accomplished with the aid of ROI2dataset’s -nodelist* options, along with ConvertDset’s -node_select_1D option.

Which ROIs to save?

This: saves the current ROI. All: saves all ROIs on surfaces related to the Parent surface of the current ROI.