Usage: A program to drive suma from command line.
DriveSuma [options] -com COM1 -com COM2 ...
Mandatory parameters:
---------------------
-com COM: Command to be sent to SUMA.
At least one command must be used
and various commands can follow in
succession.
COM is the command string and consists
of at least an action ACT. Some actions
require additional parameters to follow
ACT.
Actions (ACT) and their parameters:
-----------------------------------
o pause [MSG]: Pauses DriveSuma and awaits
an 'Enter' to proceed with
other commands.
MSG is an optional collection of
strings that can be displayed as
a prompt to the user. See usage
in examples below.
o sleep DUR: Put DriveSuma to sleep for a duration DUR.
DUR is the duration, specified with something
like 2s (or 2) or 150ms
See usage in examples below.
o show_surf: Send surface to SUMA.
+ Mandatory parameters for show_surf action:
-surf_label S_LABEL: A label (identifier) to assign to the
surface
-i_TYPE SURF: Name of surface file, see surface I/O
options below for details.
+ Optional parameters for show_surf action:
-surf_state STATE: Name the state of that surface
-surf_winding WIND: Winding of triangles. Choose
from ccw or cw (normals on sphere
pointing in). This option affects
the lighting of the surface.
+ Example show_surf:
1- Create some surface
2- Start SUMA
3- Send new surface to SUMA
---------------------------
CreateIcosahedron -rd 4
suma -niml &
echo 'Wait until suma is ready then proceed.'
DriveSuma -com show_surf -label icoco \
-i_fs CreateIco_surf.asc
o node_xyz: Assign new coordinates to surface in SUMA
+ Mandatory parameters for action node_xyz:
-surf_label S_LABEL: A label to identify the target
surface
-xyz_1D COORDS.1D: A 1D formatted file containing a new
coordinate for each of the nodes
forming the surface. COORDS.1D must
have three columns.
Column selectors can be used here as
they are in AFNI.
If you do not have the coordinates handy in a 1D file
and would prefer to get them directly from a surface,
you can substitute -xyz_1D COORDS.1D with any valid suma
surface input option. For example, if you want to send
the coords of surface surf.gii, you can just use -i surf.gii,
in lieu of -node_xyz COORDS.1D
+ Example node_xyz (needs surface from 'Example show_surf')
1- Create some variation on the coords of the surface
2- Send new coordinates to SUMA
3- Manipulate the x coordinate now
4- Send new coordinates again to SUMA
-------------------------------------
o get_label: have current label associated with current node printed
o set_outplug filename: redirect output to file instead of stdout
ConvertSurface -i_fs CreateIco_surf.asc \
-o_1D radcoord radcoord \
-radial_to_sphere 100
DriveSuma -com node_xyz -label icoco \
-xyz_1D radcoord.1D.coord'[0,1,2]'
1deval -a radcoord.1D.coord'[0]' -expr 'sin(a)*100' \
> xmess.1D ;1dcat xmess.1D radcoord.1D.coord'[1,2]' \
> somecoord.1D.coord ; rm xmess.1D
DriveSuma -com node_xyz -label icoco \
-xyz_1D somecoord.1D.coord
o viewer_cont: Apply settings to viewer or viewer controller
+ Optional parameters for action viewer_cont:
(Parameter names reflect GUI labels or key strokes.)
-autorecord RECORD_PREFIX: Set the autorecord prefix
See 'Ctrl+r' in suma's interactive help for
details.
You can can use this option to make different snapshots
go to different directories or filenames. For example:
...
-com viewer_cont -autorecord left/Javier.ppm \
-key 'ctrl+left' -key 'ctrl+r' \
-com viewer_cont -autorecord right/Javier.ppm \
-key 'ctrl+right' -key 'ctrl+r' \
...
-bkg_col R G B: Set the color of the background to R G B triplet.
R G B values must be between 0 and 1
-load_view VIEW_FILE: Load a previously
saved view file (.vvs).
Same as 'File-->Load View'
-load_do DO_FILE: Load a displayable object file
For detailed information on DO_FILE's format,
see the section under suma's help (ctrl+h)
where the function of Ctrl+Alt+s is detailed.
-do_draw_mask MASKMODE: Restrict where DO node-based objects are
displayed. MASKMODE is one of:
All: No restrictions
n3Crosshair: Crosshair node + 3 neighboring layers
n2Crosshair: Crosshair node + 2 neighboring layers
n1Crosshair: Crosshair node only
None: Show nothing.
See also Ctrl+p option in SUMA.
-fixed_do NIML_DO_STRING: Load a fixed coordinate type NIML DO that
is defined by the string NIML_DO_STRING.
This is more convenient than specifying
a simple DO in a file. For example:
DriveSuma -com viewer_cont \
-fixed_do "<T text='Hi' coord='0.5 0.2 0'/>"
or the simpler:
DriveSuma -com viewer_cont \
-fixed_do "<T text='Up here' p=tlf/>"
DriveSuma -com viewer_cont \
-fixed_do "<T text='Down there' p=bcf/>"
Repeated calls to -fixed_do would replace the previous
object with the new one. You could specify multiple DOs
by adding a qualifier string to the option -fixed_do.
For example:
DriveSuma -com viewer_cont \
-fixed_do1 "<T text='Tango' coord='0.5 0.2 0'/>"
DriveSuma -com viewer_cont \
-fixed_do2 "<T text='ognaT' coord='0.2 0.2 0'/>"
DriveSuma -com viewer_cont \
-fixed_do1 "<T text='-X-' coord='0.5 0.2 0'/>"
DriveSuma -com viewer_cont \
-fixed_do3 "<Tex target='FRAME' \
filename='funstuff/face_afniman.jpg'/>"
or for a more useful example for how you can add a logo on
the bottom right side and way back in the viewer:
DriveSuma -com viewer_cont \
-fixed_do3 "<I target='FRAME' \
coord = '1 0 1' \
h_align = 'right' \
v_align = 'bot' \
filename='funstuff/face_afniman.jpg'/>"
For more information about DOs, see NIDO section below
(visible with -help option) and demo script @DO.examples.
-Fixed_do NIML_DO_STRING: Same as -fixed_do, but spits out some
debugging info.
-mobile_do NIML_DO_STRING: Mobile version of -fixed_do
-Mobile_do NIML_DO_STRING: Mobile version of -Fixed_do
---------------------------------------------
Details for Displayble objects in NIML format (NIDO).
A NIDO is a collection of displayable objects specified in an ascii file.
NIDO is a collection of elements with the first element named 'nido_head'
That first element can contain attributes that describe the entire NIDO
and default attributes for the remaining elements.
The following example shows a nido_head element with possible attributes.
You do not need to set them all if you don't care to do so. Note that all
attributes are strings and should be enclosed in single or double quotes.
<nido_head
coord_type = 'fixed'
default_color = '1.0 0.2 0.6'
default_font = 'tr24'
bond = ''
render_mode = ''
/>
coord_type attribute:
Describes the coordinate type of all elements in NIDO.
* If 'fixed' then that means then the elements do not move with
suma's surfaces, and the coordinate units are assumed to be in the
range [0,1] with '0 0 0' being the lower left corner of the screen
and closest to you. The z coordinate is useful for assigning elements
to either the background (1) or the foreground (0) of the scene.
Elements in the foreground would always be visible, while those in the
background may be obscured by the rendered surface.
* If 'mobile' then the elements will move along with your object.
In that case, the coordinates you specify are in the same space
as your rendered objects. Also, with 'mobile' NIDO, you can specify
location by specifying a 'node' attribute as illustrated below.
* Default NIDO coordinate type is: 'mobile'
default_color attribute:
3 (R G B) , or 4 (R G B A) color values between [0, 1]
Elements that do not have their own 'col' attribute set, will use
default_color instead. At the moment however, A is not being used.
Default default_color is '1.0 1.0 1.0'
default_font attribute:
String specifying font. All fonts are from the GLUT library.
Elements that do not have their own 'font' attribute set, will use
default_font instead.
Default default_font is 'f9'
Allowed fonts are:
'f8', or 'font8': Constant width 8 size font
'f9', or 'font9': Constant width 9 size font
'tr10', or 'times_roman10'
'tr24', or 'times_roman24'
'he10', or 'helvetica10'
'he12', or 'helvetica12'
'he18', or 'helvetica18'
default_SO_label:
Label identifying surface from which elements get their node based
parameters extracted.
This is mostly useful when the coordinate system's type is 'mobile'
The default is the currently selected surface in SUMA. If no surface
is currently selected, some random surface is picked.
default_node:
One integer which specifies the index of the node to which all elements
belong. This value essentially specifies the 'node' attribute of
individual elements should the 'node' attribute be missing.
A missing default_node, or a value of -1 indicate there is no default
node.
bond:
If set to 'surface' then NIDO is attached to a particular surface.
This means that if a surface is not displayed, none of the elements in
this NIDO would be displayed. Default is 'none'
render_mode:
Used to force rendering mode of NIDO elements to a certain value.
Choose from: Viewer, Fill, Line, Points, Hide, Default or ''
Default is '' with rendering mode unmodified before rendering NIDO.
After 'nido_head' comes a list of elements of various types.
Text element example:
<T
font = 'he12'
coord = '0.5 0.5 0'
col = '0.21 0.9 0.61'
text = 'The Middle
----------'
h_align = 'center'
v_align = 'center'
/>
text attribute:
Put the text you want to display between single or double quotes.
You can do multi-line text.
coord attribute:
XYZ coordinates whose units are determined by nido_head's coord_type.
See also p attribute
p attribute:
A convenience positioning attribute for placing text in fixed screen
coordinates. If present, it will override coord, h_align, and v_align
attributes. Its value is two to 3 characters long.
1st char: t for top, c for center or m for middle, b for bottom
2nd char: l for left, c for center or m for middle, r for right
3rd char: f for front, r for rear (optional)
h_align and v_align are set in a manner that makes sense for these
special position flags.
font attribute:
Sets the font for the text element. If not specified, font is set per
default_font.
col attribute:
Sets the color for the text element. If not specified, col is set per
default_color.
h_align:
Sets the horizontal alignment. Choose from 'l' (default) for left,
'c' for center, or 'r' for right.
v_align:
Sets the horizontal alignment. Choose from 'b' (default) for bottom,
'c' for center, or 't' for top.
node:
Places the object at a node's location in the surface object defined by
SO_label attribute. Note that this option overrides coord and might
confuse you if NIDO's coord_type is 'fixed'. In such a case, the
location would be that of the node, before you moved the surface.
SO_label:
Label of Surface Object from which the element gets its node based
parameters extracted. Default is NIDO's default_SO_label
Sphere element example (only new attributes are detailed):
<S
node = '0'
col = '0.9 0.1 0.61'
rad = '35'
line_width = '1.5'
style = 'silhouette'
stacks = '20'
slices = '20'
/>
rad attribute:
Radius of the sphere (default 10).
rad.ef attribute:
In lieu of rad, this parameter would
make the radius be a fraction of the average edge length
for the surface related to this sphere.
line_width attribute:
Width of line (segments) of sphere's mesh
stacks attribute:
Number of longitudes (default 10).
slices attribute:
Number of lattitudes (default 10).
style attribute:
Style of sphere rendering. Choose from:
fill (default), line, silhouette, or point
See OpenGL's gluQuadricStyle function for details.
Other acceptable attributes:
node, coord, and SO_label
Image element example (only new attributes are detailed):
<I
coord = '0.4 0.5 1'
filename = 'face_alexmartin2.jpg'
h_align = 'center'
v_align = 'bot'
/>
filename attribute:
Specifies the filename of the image. If the filename has no path, SUMA
will search your path for a match before failing.
Other acceptable attributes:
h_align, v_align, coord, node, and SO_label.
Texture element example:
<Tex
filename = 'face_afniman.jpg'
target = 'FRAME'
frame_coords = '
0.0 0.0 1
0.0 1.0 1
1.0 1.0 1
1.0 0.0 1 '
mix_mode = 'blend'
coord_gen = 'sphere'
/>
filename attribute:
Specifies the filename of the texture image.
target attribute:
Specifies the target of the texture.
If target is 'FRAME' then the texture is bound to a quadrilateral whose
coordinates are defined by the frame_coords attribute. This is useful
for putting a background image in SUMA for example, when NIDO is of
a 'fixed' coord_type. Alternately, target can be the label of a
surface, or a bunch of surfaces sharing the label string.
The default is 'ALL_SURFS' which targets all surfaces being displayed
frame_coords attribute:
Specify the coordinate of the quadrilateral onto which the texture
is bound. This is of use when target is set to 'FRAME'. The default
coordinates are set to:
0.0 0.0 1
0.0 1.0 1
1.0 1.0 1
1.0 0.0 1 '
For 'fixed' coord_type, this default sets up a rectangle that fills up
the suma viewer in the background of the scene.
BUG: If you reduce z in 'fixed' coord_type, the texture map be
positioned closer to the foreground, and should obscure objects behind
it. But for some reason, no surfaces get rendered in that case, no
matter where they lie relative to the texture frame.
For 'mobile' coord_type, the texture frame coordinates are in the same
units as those for the rendered objects.
Showing textures in frames is like displaying an image except that:
- Textures will scale with changes in viewer size for 'fixed' coord_type
and zoom factor for 'mobile' coord_type. While image size only depends
on its number of pixels.
- Frame orientation is arbitrary for textures. For images, the frame is
always aligned with the pixel arrays (always facing you). With images,
you can only control where its center is located.
mix_mode attribute:
Specifies the way texture mixes with node colors.
Choose from: 'decal', 'blend', 'replace', and 'modulate'.
Default is 'replace' when target is 'frame' and 'modulate' for
other target values. These parallel OpenGL's GL_DECAL, GL_BLEND, etc.
coord_gen attribute:
Specifies how texture coordinate generation is done, when target is not
'FRAME'. Choose from: 'sphere', 'object', 'eye'. Default is 'sphere'
For detail, see OpenGL's GL_SPHERE_MAP, GL_OBJECT_LINEAR, etc.
Try the script :ref:`@DO.examples<@DO.examples>` for concrete examples on
displayable objects.
---------------------------------------------
-key KEY_STRING: Act as if the key press KEY_STRING
was applied in the viewer.
~ Not all key presses from interactive
mode are allowed here.
~ Available keys and their variants are:
[, ], comma (or ','), period (or '.'), space,
a, b, d, G, j, m, n, p, r, t, z,
up, down, left, right, and F1 to F12.
~ Key variants are specified this way:
ctrl+Up or ctrl+alt+Down etc.
~ For help on key actions consult SUMA's
GUI help.
~ Using multiple keys in the same command
might not result in the serial display of
the effect of each key, unless 'd' modifier
is used as shown further below. For example,
-key right -key right would most likely
produce one image rotated twice rather than
two images, each turned right once.
The -key string can be followed by modifiers:
For example, -key:r5:s0.2 has two modifiers,
r5 and s0.2. All modifiers are separated by ':'.
'r' Repeat parameter, so r5 would repeat the
same key 5 times.
's' Sleep parameter, so s0.2 would sleep for 0.2
seconds between repeated keys.
'd' Immediate redisplay flag. That is useful
when you are performing a succession of keys and
want to ensure each individual one gets displayed
and recorded (most likely). Otherwise, successive
keys may only display their resultant. 'd' is used
automatically with 's' modifier.
'p' Pause flag. Requires user intervention to proceed.
'v' Value string. The string is passed to the function
that processes this key, as if you'd entered that string
in the GUI directly. To avoid parsing headaches, you
should use quotes with this qualifier. For example, say
you want to pass 0.0 0.0 0.0 to the 'ctrl+j' key press.
At the shell you would enter:
DriveSuma -com viewer_cont '-key:v"0.8 0 10.3"' ctrl+j
In another example, say you want to jump to node 54 on the
right hemisphere (hence the 'R' in '54R'), then you would
execute:
DriveSuma -com viewer_cont '-key:v54R' j
-viewer VIEWER: Specify which viewer should be acted
upon. Default is viewer 'A'. Viewers
must be created first (ctrl+n) before
they can be acted upon.
You can also refer to viewers with integers
0 for A, 1 for B, etc.
For -viewer to take effect it must be in the
same -com viewer_cont ... commands. For example:
... -com viewer_cont -viewer B -viewer_size 600 900 ...
-viewer_width or (-width) WIDTH: Set the width in pixels of
the current viewer.
-viewer_height or (-height) HEIGHT: Set the height in pixels of
the current viewer.
-viewer_size WIDTH HEIGHT : Convenient combo of -viewer_width
and -viewer_height
-viewer_position X Y: Set position on the screen
-controller_position X Y: Set position of the object (surface)
controller on the screen
-inout_notify y/n: Turn on or off function call tracing
-N_foreg_smooth n: Number of foreground smoothing iterations
Same as suma's interactive '8' key or what
you'd set with env: SUMA_NumForeSmoothing
-N_final_smooth n: Number of final color smoothing iterations
Same as suma's interactive '*' key or what
you'd set with env: SUMA_NumForeSmoothing
+ Example viewer_cont (assumes all previous examples have
been executed and suma is still running).
- a series of commands that should be obvious.
-------------------------------------
DriveSuma -com viewer_cont -key R -key ctrl+right
DriveSuma -com viewer_cont -key:r3:s0.3 up \
-key:r2:p left -key:r5:d right \
-key:r3 z -key:r5 left -key F6
DriveSuma -com viewer_cont -key m -key down \
-com sleep 2s -com viewer_cont -key m \
-key:r4 Z -key ctrl+right
DriveSuma -com viewer_cont -key m -key right \
-com pause press enter to stop this misery \
-com viewer_cont -key m
o recorder_cont: Apply commands to recorder window
+ Optional parameters for action recorder_cont:
-anim_dup DUP: Save DUP copies of each frame into movie
This has the effect of slowing movies down
at the expense of file size, of course.
DUP's default is set by the value of AFNI_ANIM_DUP
environment variable.
To set DUP back to its default value,
use -anim_dup 0.
-save_as PREFIX.EXT: Save image(s) in recorder
in the format determined by
extension EXT.
Allowed extensions are:
agif or gif: Animated GIF (movie)
mpeg or mpg: MPEG (movie)
jpeg or jpg: JPEG (stills)
png: PNG (stills)
-save_index IND: Save one image indexed IND (start at 0)
-save_range FROM TO: Save images from FROM to TO
-save_last: Save last image (default for still formats)
-save_last_n N: Save last N images
-save_all: Save all images (default for movie formats)
-cwd ABSPATH: Set ABSPATH as SUMA's working directory.
This path is used for storing output files
or loading dsets.
+ Example recorder_cont (assumes there is a recorder window)
currently open from SUMA.
-------------------------------------
DriveSuma -com recorder_cont -save_as allanimgif.agif \
-com recorder_cont -save_as lastone.jpg -save_last \
-com recorder_cont -save_as three.jpg -save_index 3 \
-com recorder_cont -save_as some.png -save_range 3 6
o object_cont: Apply settings to object controller.
o surf_cont: Apply settings to surface controller.
Note that for most cases, the use of object_cont and surf_cont is
interchangeable.
+ Optional parameters for action surf_cont:
(Parameter names reflect GUI labels.)
-surf_label S_LABEL: A label to identify the target surface
-load_dset DSET: Load a dataset
! NOTE: When using -load_dset you can follow it
with -surf_label in order to attach
the dataset to a particular target surface.
-view_surf y/n: Show or hide surface S_LABEL
-RenderMode V/F/L/P/H: Set the render mode for surface S_LABEL.
-TransMode V/0/../16: Set the transparency mode for surface S_LABEL.
-load_col COL: Load a colorfile named COL.
Similar to what one loads under
SUMA-->ctrl+s-->Load Col
COL contains 4 columns, of
the following format:
n r g b
where n is the node index and
r g b are thre flooat values between 0 and 1
specifying the color of each node.
-view_surf_cont y/n: View surface controller
-view_object_cont y/n: View object controller
-masks: Equivalent of pressing 'Masks' in tract controller
-2xmasks: Equivalent of pressing 'Masks' twice in tract controller
-delete_all_masks: Well, delete all the masks.
-load_masks: Equivalent of pressing 'Load Masks' in masks controller
-save_masks: Equivalent of pressing 'Save Masks' in masks controller
-switch_surf S_LABEL: switch state to that of surface
labeled S_LABEL and make that surface
be in focus.
-switch_dset DSET: switch dataset to DSET
-view_dset y/n: Set view toggle button of DSET
-1_only y/n: Set 1_only toggle button of DSET
-switch_cmap CMAP: switch colormap to CMAP
-switch_cmode CMODE: switch color mapping mode to CMODE
-load_cmap CMAP.1D.cmap: load and switch colormap in
file CMAP.1D.cmap
-I_sb ISB: Switch intensity to ISBth column (sub-brick)
-I_range IR0 IR1: set intensity range from IR0 to IR1.
If only one number is given, the range
is symmetric from -|IR0| to |IR0|.
-shw_0 y/n or
-show_0 y/n: Set shw 0 toggle button of DSET.
-SET_FUNC_ALPHA y/n or
-SET_FUNC_ALPHA on/off
-SET_FUNC_ALPHA A.Linear/A.Quadratic
-SET_FUNC_BOXED y/n or
-SET_FUNC_BOXED on/off
-Dsp MODE: Set the viewing mode of the current DSET.
MODE is one of XXX, Con, Col, or 'C&C'
(single quotes necessary for 'C&C' MODE).
This is equivalent to setting the 'Dsp' menu button
in the surface controller. The option is applied
to the current DSET on the selected surface.
-T_sb TSB: Switch threshold to TSBth column (sub-brick)
Set TSB to -1 to turn off thresholding.
-T_val THR: Set threshold to THR, you can now append p or % for
pvalue or percentile threshold setting.
-B_sb BSB: Switch brightness modulation to BSBth column (sub-brick)
-B_range BR0 BR1: set brightness clamping range from BR0 to BR1.
If only one number is given, the range
is symmetric from -|BR0| to |BR0|.
-B_scale BS0 BS1: Modulate brightness by BS0 factor for BR0 or lower
by BS1 factor for BR1 or higher, and linearly
interpolate scaling for BR0 < values < BR1
-Dim DIM: Set the dimming factor.
-Opa OPA: Set the opacity factor.
-Clst RAD AREA: Set the clustering parameters
-UseClst y/n: Turn on/off clustering
-setSUMAenv "'ENVname=ENVvalue'": Set an ENV in SUMA. Note that
most SUMA env need to be set at SUMA's launch time.
Setting the env from DriveSuma may not achieve what
you want, so consider using suma's -setenv instead.
-write_surf_cont_help FILE.txt: Write help output for surface
controller uses into file FILE.txt (in append mode)
Make sure the surface controller is open before you
use this command.
-write_surf_cont_sphinx_help FILE.rst: Same as -write_surf_cont_help,
but write SPHINX formatted RST file.
-snap_surf_cont_widgets FROOT: Takes snapshots of various widget
groupings and save them under FROOT*
Also, in the same vein as -write_surf_cont_help,
-write_surf_cont_sphinx_help, and -snap_surf_cont_widgets you have:
-write_vol_cont_help
-write_vol_cont_sphinx_help
-snap_vol_cont_widgets
-write_tract_cont_help
-write_tract_cont_sphinx_help
-snap_tract_cont_widgets
-write_mask_cont_help
-write_mask_cont_sphinx_help
-snap_mask_cont_widgets
-write_graph_cont_help
-write_graph_cont_sphinx_help
-snap_graph_cont_widgets
-write_roi_cont_help
-write_roi_cont_sphinx_help
-snap_roi_cont_widgets
-write_suma_cont_help
-write_suma_cont_sphinx_help
-snap_suma_cont_widgets
-write_mouse_keyb_help FILE.txt: Write help output for mouse and
keyboard shortcuts.
-write_mouse_keyb_sphinx_help FILE.rst: Same as -write_mouse_keyb_help
, but write SPHINX formatted RST file.
-write_mouse_cmap_keyb_help FILE.txt: Write help output for mouse and
keyboard shortcuts.
-write_mouse_cmap_keyb_sphinx_help FILE.rst: Same
as -write_mouse_cmap_keyb_help, but write SPHINX
formatted RST file.
+ Example surf_cont (assumes all previous examples have
been executed and suma is still running).
- Obvious chicaneries to follow:
--------------------------------
echo 1 0 0 > bbr.1D.cmap; echo 1 1 1 >> bbr.1D.cmap; \
echo 0 0 1 >> bbr.1D.cmap
IsoSurface -shape 4 128 -o_ply blooby.ply
quickspec -spec blooby.spec -tn ply blooby.ply
SurfaceMetrics -curv -spec blooby.spec \
-surf_A blooby -prefix blooby
DriveSuma -com show_surf -surf_label blooby \
-i_ply blooby.ply -surf_winding cw \
-surf_state la_blooby
DriveSuma -com surf_cont -load_dset blooby.curv.1D.dset \
-surf_label blooby -view_surf_cont y
DriveSuma -com surf_cont -I_sb 7 -T_sb 8 -T_val 0.0
DriveSuma -com surf_cont -I_range 0.05 -T_sb -1
DriveSuma -com surf_cont -I_sb 8 -I_range -0.1 0.1 \
-T_val 0.02 -Dim 0.4
DriveSuma -com surf_cont -B_sb 7 -B_range 0.5 -B_scale 0.1 0.9
DriveSuma -com surf_cont -switch_dset Convexity -1_only y
DriveSuma -com surf_cont -switch_cmap roi64 -1_only n
DriveSuma -com surf_cont -switch_cmode Dir
DriveSuma -com surf_cont -view_dset n
DriveSuma -com surf_cont -switch_dset blooby.curv.1D.dset \
-view_surf_cont n -I_range -0.05 0.14
DriveSuma -com surf_cont -load_cmap bbr.1D.cmap
+ Example for loading masks onto tracts
-------------------------------------
#This uses one of the tract files output by FATCAT's demo.
#and some tracts mask called triplets.niml.do
suma -tract DTI/o.NETS_OR_000.niml.tract &
DriveSuma -com object_cont -view_object_cont y \
-com object_cont -2xmasks \
-com object_cont -delete_all_masks \
-com object_cont -load_masks triplets.niml.mo
o kill_suma: Close suma and quit.
Advice:
-------
If you get a colormap in your recorded image, it is
because the last thing you drew was the surface controller
which has an openGL surface for a colormap. In such cases,
Force a redisplay of the viewer with something like:
-key:r2:d m
where the m key is pressed twice (nothing)
changes in the setup but the surface is
redisplayed nonetheless because of the 'd'
key option.
Crashes: It is possible for SUMA to crash under certain combinations
of commands that involve opening X windows followed by
some command. For example, suma might crash with:
DriveSuma -com viewer_cont -viewer_size 600 600 -key 'ctrl+n'
Splitting such a command into two DriveSuma instances gets
around the problem:
DriveSuma -com viewer_cont -viewer_size 600 600
DriveSuma -com viewer_cont -key 'ctrl+n'
Options:
--------
-echo_edu: Echos the entire command line (without -echo_edu)
for edification purposes
-echo_nel_stdout: Spit out the NIML object being sent to SUMA for
-echo_nel_stderr: edification purposes. These two options are meant
to help motivate the example in HalloSuma.
You need to have SUMA up and listening for this option
to take effect.
Example: DriveSuma -echo_nel_stdout -com viewer_cont '-key:v28' j
-echo_nel FILE: Write the elements to FILE.
You can also use stdout or stderr for FILE.
-examples: Show all the sample commands and exit
-help: All the help, in detail.
** NOTE: You should also take a look at scripts @DO.examples and
@DriveSuma for examples. Suma's interactive help (ctrl+h) for
the kinds of controls you can have with -key option.
-h: -help, with slightly less detail
-help_nido: Show the help for NIML Displayable Objects and exit.
Same as suma -help_nido
-C_demo: execute a preset number of commands
which are meant to illustrate how one
can communicate with SUMA from one's
own C code. Naturally, you'll need to
look at the source code file SUMA_DriveSuma.c
Example:
suma -niml &
DriveSuma -C_demo
Specifying input surfaces using -i or -i_TYPE options:
-i_TYPE inSurf specifies the input surface,
TYPE is one of the following:
fs: FreeSurfer surface.
If surface name has .asc it is assumed to be
in ASCII format. Otherwise it is assumed to be
in BINARY_BE (Big Endian) format.
Patches in Binary format cannot be read at the moment.
sf: SureFit surface.
You must specify the .coord followed by the .topo file.
vec (or 1D): Simple ascii matrix format.
You must specify the coord (NodeList) file followed by
the topo (FaceSetList) file.
coord contains 3 floats per line, representing
X Y Z vertex coordinates.
topo contains 3 ints per line, representing
v1 v2 v3 triangle vertices.
ply: PLY format, ascii or binary.
Only vertex and triangulation info is preserved.
stl: STL format, ascii or binary.
This format of no use for much of the surface-based
analyses. Objects are defined as a soup of triangles
with no information about which edges they share. STL is only
useful for taking surface models to some 3D printing
software.
mni: MNI .obj format, ascii only.
Only vertex, triangulation, and node normals info is preserved.
byu: BYU format, ascii.
Polygons with more than 3 edges are turned into
triangles.
bv: BrainVoyager format.
Only vertex and triangulation info is preserved.
dx: OpenDX ascii mesh format.
Only vertex and triangulation info is preserved.
Requires presence of 3 objects, the one of class
'field' should contain 2 components 'positions'
and 'connections' that point to the two objects
containing node coordinates and topology, respectively.
gii: GIFTI XML surface format.
obj: OBJ file format for triangular meshes only. The following
primitives are preserved: v (vertices), f (faces, triangles
only), and p (points)
Note that if the surface filename has the proper extension,
it is enough to use the -i option and let the programs guess
the type from the extension.
You can also specify multiple surfaces after -i option. This makes
it possible to use wildcards on the command line for reading in a bunch
of surfaces at once.
-onestate: Make all -i_* surfaces have the same state, i.e.
they all appear at the same time in the viewer.
By default, each -i_* surface has its own state.
For -onestate to take effect, it must precede all -i
options with on the command line.
-anatomical: Label all -i surfaces as anatomically correct.
Again, this option should precede the -i_* options.
More variants for option -i:
-----------------------------
You can also load standard-mesh spheres that are formed in memory
with the following notation
-i ldNUM: Where NUM is the parameter controlling
the mesh density exactly as the parameter -ld linDepth
does in CreateIcosahedron. For example:
suma -i ld60
create on the fly a surface that is identical to the
one produced by: CreateIcosahedron -ld 60 -tosphere
-i rdNUM: Same as -i ldNUM but with NUM specifying the equivalent
of parameter -rd recDepth in CreateIcosahedron.
To keep the option confusing enough, you can also use -i to load
template surfaces. For example:
suma -i lh:MNI_N27:ld60:smoothwm
will load the left hemisphere smoothwm surface for template MNI_N27
at standard mesh density ld60.
The string following -i is formatted thusly:
HEMI:TEMPLATE:DENSITY:SURF where:
HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh' or 'rh'.
You must specify a hemisphere with option -i because it is
supposed to load one surface at a time.
You can load multiple surfaces with -spec which also supports
these features.
TEMPLATE: Specify the template name. For now, choose from MNI_N27 if
you want to use the FreeSurfer reconstructed surfaces from
the MNI_N27 volume, or TT_N27
Those templates must be installed under this directory:
/home/afniHQ/.afni/data/
If you have no surface templates there, download
https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz
and/or
https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz
and/or
https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI152_2009.tgz
and untar them under directory /home/afniHQ/.afni/data/
DENSITY: Use if you want to load standard-mesh versions of the template
surfaces. Note that only ld20, ld60, ld120, and ld141 are in
the current distributed templates. You can create other
densities if you wish with MapIcosahedron, but follow the
same naming convention to enable SUMA to find them.
SURF: Which surface do you want. The string matching is partial, as long
as the match is unique.
So for example something like: suma -i l:MNI_N27:ld60:smooth
is more than enough to get you the ld60 MNI_N27 left hemisphere
smoothwm surface.
The order in which you specify HEMI, TEMPLATE, DENSITY, and SURF, does
not matter.
For template surfaces, the -sv option is provided automatically, so you
can have SUMA talking to AFNI with something like:
suma -i l:MNI_N27:ld60:smooth &
afni -niml /home/afniHQ/.afni/data/suma_MNI_N27
Specifying surfaces using -t* options:
-tn TYPE NAME: specify surface type and name.
See below for help on the parameters.
-tsn TYPE STATE NAME: specify surface type state and name.
TYPE: Choose from the following (case sensitive):
1D: 1D format
FS: FreeSurfer ascii format
PLY: ply format
MNI: MNI obj ascii format
BYU: byu format
SF: Caret/SureFit format
BV: BrainVoyager format
GII: GIFTI format
NAME: Name of surface file.
For SF and 1D formats, NAME is composed of two names
the coord file followed by the topo file
STATE: State of the surface.
Default is S1, S2.... for each surface.
Specifying a surface specification (spec) file:
-spec SPEC: specify the name of the SPEC file.
As with option -i, you can load template
spec files with symbolic notation trickery as in:
suma -spec MNI_N27
which will load the all the surfaces from template MNI_N27
at the original FreeSurfer mesh density.
The string following -spec is formatted in the following manner:
HEMI:TEMPLATE:DENSITY where:
HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh', 'rh', 'lr', or
'both' which is the default if you do not specify a hemisphere.
TEMPLATE: Specify the template name. For now, choose from MNI_N27 if
you want surfaces from the MNI_N27 volume, or TT_N27
for the Talairach version.
Those templates must be installed under this directory:
/home/afniHQ/.afni/data/
If you have no surface templates there, download one of:
https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz
https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz
https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI152_2009.tgz
and untar them under directory /home/afniHQ/.afni/data/
DENSITY: Use if you want to load standard-mesh versions of the template
surfaces. Note that only ld20, ld60, ld120, and ld141 are in
the current distributed templates. You can create other
densities if you wish with MapIcosahedron, but follow the
same naming convention to enable SUMA to find them.
This parameter is optional.
The order in which you specify HEMI, TEMPLATE, and DENSITY, does
not matter.
For template surfaces, the -sv option is provided automatically, so you
can have SUMA talking to AFNI with something like:
suma -spec MNI_N27:ld60 &
afni -niml /home/afniHQ/.afni/data/suma_MNI_N27
[-novolreg]: Ignore any Rotate, Volreg, Tagalign,
or WarpDrive transformations present in
the Surface Volume.
[-noxform]: Same as -novolreg
[-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname
to be ENVvalue. Quotes are necessary.
Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'"
See also options -update_env, -environment, etc
in the output of 'suma -help'
Common Debugging Options:
[-trace]: Turns on In/Out debug and Memory tracing.
For speeding up the tracing log, I recommend
you redirect stdout to a file when using this option.
For example, if you were running suma you would use:
suma -spec lh.spec -sv ... > TraceFile
This option replaces the old -iodbg and -memdbg.
[-TRACE]: Turns on extreme tracing.
[-nomall]: Turn off memory tracing.
[-yesmall]: Turn on memory tracing (default).
NOTE: For programs that output results to stdout
(that is to your shell/screen), the debugging info
might get mixed up with your results.
Global Options (available to all AFNI/SUMA programs)
-h: Mini help, at time, same as -help in many cases.
-help: The entire help output
-HELP: Extreme help, same as -help in majority of cases.
-h_view: Open help in text editor. AFNI will try to find a GUI editor
-hview : on your machine. You can control which it should use by
setting environment variable AFNI_GUI_EDITOR.
-h_web: Open help in web browser. AFNI will try to find a browser.
-hweb : on your machine. You can control which it should use by
setting environment variable AFNI_GUI_EDITOR.
-h_find WORD: Look for lines in this programs's -help output that match
(approximately) WORD.
-h_raw: Help string unedited
-h_spx: Help string in sphinx loveliness, but do not try to autoformat
-h_aspx: Help string in sphinx with autoformatting of options, etc.
-all_opts: Try to identify all options for the program from the
output of its -help option. Some options might be missed
and others misidentified. Use this output for hints only.
