AFNI file: README.driver
=====================================================
*** Driving AFNI from a Plugout or a Startup Script ***
=====================================================
An external program (i.e., a "plugout") can control some aspects of AFNI.
This functionality is invoked by passing a command line of the form
DRIVE_AFNI command arguments ...
to AFNI (once the plugout connection is open, of course). The commands
available are described below. The sample plugout plugout_drive.c can
be used to test how things work (highly recommended before you start
writing your own code).
A startup Script (file ".afni.startup_script") can also give a sequence
of commands to be run immediately after AFNI starts up. The file consists
of a sequence of command lines (without the "DRIVE_AFNI" prefix). It is
also possible to read in a Script file using the "Datamode->Misc->Run Script"
button from the AFNI controller. Some of the current state of AFNI can
be saved to ".afni.startup_script" using the "Datamode->Misc->Save Layout"
button (by giving a blank as the filename -- or any filename containing the
string "script" -- other filenames produce a 'layout' description which
is intended to be included in your .afnirc file).
You can also give commands to AFNI on the 'afni' command line, using the
'-com' option. For example:
afni -com 'OPEN_WINDOW A.axialimage' \
-com 'SWITCH_UNDERLAY anat' \
-com 'SAVE_JPEG A.axialimage sss.jpg' \
-com 'QUIT' \
somedirectory
could be used to create an image file 'sss.jpg' automatically. The AFNI GUI
would open up (and so X11 must be running), but no user interaction would
actually occur -- the image opens and gets saved, and then AFNI just ends.
N.B.: If the 'QUIT' command weren't included above, AFNI would remain open,
ready for user interaction after the image file was saved.
==============================================================================
A programmer of a plugin can register a command string and a callback function
to be called when that command string is 'driven' to AFNI. For example:
static int junkfun( char *cmd )
{
fprintf(stderr,"junkfun('%s')\n",cmd) ; return 0 ;
}
AFNI_driver_register( "JUNK" , junkfun ) ;
If the callback function return value is negative, a warning message will be
printed to stderr; otherwise, the return value is ignored. The string that
is passed to the callback function is everything AFTER the initial command
and the blank(s) that follows; in the above example, if "JUNK elvis lives"
were the driver command, then junkfun is called with the string "elvis lives".
In a plugin, the logical place to put the call to AFNI_driver_register() is
in the PLUGIN_init() function.
If you call AFNI_driver_register() with a new command name that duplicates
an existing one, then an error message is printed to stderr and this call
will be ignored. For this reason, you may want to prefix your commands
with some identifier; for example, a hypothetical diffusion tensor analysis
plugin could give command names starting with "DTI_". Or perhaps use your
institution's name or your initials as a prefix, as in "NIMH_" or "RWC_".
=============================================================================
COMMANDS (in no coherent order)
-------------------------------
ADD_OVERLAY_COLOR colordef colorlab
Adds the color defined by the string "colordef" to the list of overlay
colors. It will appear in the menus with the label "colordef". Example:
ADD_OVERLAY_COLOR #ff5599 pinkish
SET_THRESHOLD [c.]val [dec]
Sets the threshold slider for controller index 'c' (default='A') to level
".val" (a number between .0000 and .9999, inclusive). If the optional
'dec' parameter is set, this is a number between 0 and 4 (inclusive) setting
the power-of-ten factor for the slider. Example:
SET_THRESHOLD A.3000 2
will set the '**' (decimal) level of the slider to 2 and the slider value to
30 (=0.3000*100).
++ You can also use "SET_FUNC_THRESH" for the command name.
SET_THRESHNEW [c] val [flags]
Sets the threshold slider for controller index 'c' (default='A') to the
numerical value 'val', which must be in the range [0..9999]. If the
optional 'flags' string contains the character '*', then the slider decimal
offset (i.e., the '**' setting) will be changed to match the size of 'val'.
If 'flags' contains the character 'p', then 'val will be interepreted as
a p-value (and so must be between 0.0 and 1.0). Examples:
SET_THRESHNEW A 9.2731
SET_THRESHNEW B 0.3971 *p
SET_PBAR_NUMBER [c.]num
Sets the number of panes in the color pbar to 'num' (currently must be between
2 and 20, inclusive). Example:
SET_PBAR_NUMBER A.10
SET_PBAR_SIGN [c.]+ or [c.]-
Sets the color pbar to be positive-only (+) or signed (-). Example:
SET_PBAR_SIGN A.+
SET_PBAR_ALL [c.]{+|-}num val=color val=color ...
Sets all color pbar parameters at once;
The initial string specifies the controller ('A', 'B', etc.), the sign
condition of the pbar ('+' or '-') and the number of panes to setup.
'num' equations of the form 'val=color' follow the initial string;
these set up the top levels and colors of each pane. Example:
SET_PBAR_ALL A.+5 2.0=yellow 1.5=green 1.0=blue 0.5=red 0.2=none
The top pane runs from 2.0-1.5 and is yellow; the second pane runs from
1.5-1.0 and is blue, etc. The 'color' values must be legal color labels.
SET_PBAR_ALL [c.]{+|-}99 topval colorscale_name [options]
Sets the color pbar for controller #c to be in "continuous" colorscale
mode. Again, '+' or '-' is used to specify if the colorscale should
be positive-only or signed. The special value of 99 panes is used
to indicate colorscale mode. The number 'topval' tells the scale
value to go at the top of the colorscale. The string 'colorscale_name'
tells which colorscale to use. For example:
SET_PBAR_ALL A.+99 1.0 Color_circle_AJJ
The 'options' available at this time only apply when in this "continuous"
colorscale case. They are
ROTA=n => after loading the colorscale, rotate it by 'n' steps
FLIP => after loading the colorscale, flip it upside down
These options are part of how the AFNI_PBAR_LOCK function works, and
probably aren't relevant for manual use.
PBAR_ROTATE [c.]{+|-}
Rotates the color pbar in the positive ('+') or negative ('-') direction:
PBAR_ROTATE A.+
DEFINE_COLORSCALE name number=color number=color ...
or DEFINE_COLORSCALE name color color color
Defines a new colorscale with the given name. The format of the following
arguments is either like "1.0=#ffff00" or like "#ff00ff" (all must be in the
same format). See http://afni.nimh.nih.gov/afni/afni_colorscale.html for
more information about the format of color names and about how the colorscale
definition works.
++ You can also use "DEFINE_COLOR_SCALE" for the command name.
SET_FUNC_AUTORANGE [c.]{+|-}
Sets the function "autoRange" toggle to be on ('+') or off ('-'):
SET_FUNC_AUTORANGE A.+
SET_FUNC_RANGE [c.]value
Sets the functional range to 'value'. If value is 0, this turns autoRange
on; if value is positive, this turns autoRange off:
SET_FUNC_RANGE A.0.3333
SET_FUNC_VISIBLE [c.]{+|-}
Turns the "See Overlay" toggle on or off:
SET_FUNC_VISIBLE A.+
You can also use SEE_OVERLAY for this, which is closer to the label on
the GUI button.
SEE_OVERLAY
Same as SET_FUNC_VISIBLE
SET_FUNC_RESAM [c.]{NN|Li|Cu|Bk}[.{NN|Li|Cu|Bk}]
Sets the functional resampling mode:
SET_FUNC_RESAM A.Li.Li
sets the func and threshold resampling modes both to Linear interpolation.
OPEN_PANEL [c.]Panel_Name
Opens the specified controller panel, where 'Panel_Name' is one of
'Define_Overlay', 'Define_Datamode', or 'Define_Markers'. At this time,
there is no way to close a panel except from the GUI.
SYSTEM command string
Executes "command string" using the system() library function; for
example, "SYSTEM mkdir aaa".
CHDIR newdirectory
Changes the current directory; for example, "CHDIR aaa". This is the
directory into which saved files (e.g., images) will be written.
RESCAN_THIS [c]
rescans the current session directory for controller 'c', where 'c'
is one of 'A', 'B', 'C', 'D', or 'E'. If 'c' is absent, the 'A'
controller's current session is scanned.
SET_SESSION [c.]directoryname
Switches controller 'c' to be looking at the named directory. The
match on directory names is done by a sub-string match - that is,
directoryname = "fred" will match an AFNI session directory named
"wilhelm/frederick/von/guttenstein".
++ You can also use "SWITCH_SESSION" or "SWITCH_DIRECTORY" for the command.
SET_VIEW [c.]view
Switches controller 'c' to the named "view", which can be one of
'orig', 'acpc' or 'tlrc'. The underlay dataset must have an
appropriate transformation.
SET_ANATOMY [c.]prefix [i]
Switches controller 'c' to be looking at the anatomical dataset with
the given prefix. The prefix must be a perfect match - this is NOT
a sub-string match.
++ If an optional integer is given (separated by a space) after the
prefix, this is the sub-brick index to view.
++ You can also use "SWITCH_ANATOMY" or "SWITCH_UNDERLAY" for the command.
++ The 'prefix' can also be the dataset IDcode string, if you insist.
SET_FUNCTION [c.]prefix [j [k]]
Same, but for the functional dataset in controller 'c'.
++ If an optional integer is given (separated by a space) after the
prefix, this is the sub-brick index to view as the 'OLay'; if a second
integer is given, this is the sub-brick index to use as the 'Thr'.
++ You can also use "SWITCH_FUNCTION" or "SWITCH_OVERLAY" for the command.
SET_SUBBRICKS [c] i j k
Without switching underlay or overlay datasets, change the sub-bricks
being viewed in the viewer specified by the initial letter.
Index i = underlay sub-brick (grayscale)
Index j = overlay sub-brick for 'Olay' (color)
Index k = overlay sub-brick for 'Thr' (threshold)
For example, "SET_SUBBRICKS B 33 -1 44" will set the underlay sub-brick
to 33, the threshold sub-brick to 44, and will not change the color
sub-brick (since -1 is not a legal value).
++ You can also use "SET_SUB_BRICKS" for the command name.
OPEN_WINDOW [c.]windowname [options]
Opens a window from controller 'c'. The window name can be one of
axialimage sagittalimage coronalimage
axialgraph sagittalgraph coronalgraph
If the specified controller is not yet opened, it will be opened
first (like pressing the 'New' button). If the command is of the
form "OPEN_WINDOW c", then only the controller itself will be opened.
For all windows, one allowed option is:
geom=PxQ+R+S or geom=PxQ or geom=+R+S
to make the window be PxQ pixels in size and located at screen
coordinates (R,S).
Another option for both graph and image windows is
keypress=c -> where 'c' is a single character to send as if
the user pressed that key in the specified window
++ multiple keypress= options can be used, but
each one can only send one keystroke;
example: "keypress=Z keypress=Z"
to zoom in twice in an image viewer.
For image windows, other options available are:
ifrac=number -> set image fraction in window to number (<= 1.0)
mont=PxQ:R -> montage P across, Q down, every R'th slice
opacity=X -> where X is from 0..9
crop=x1:x2,y1:y2 -> crop images from voxels x1 to x2, and y1 to y2
(inclusive) -- mostly for use in .afni.startup_script;
use x1=x2=0 and y1=y2=0 to turn cropping off.
For graph windows, other options available are:
matrix=number -> use 'number' sub-graphs (<= 21)
pinnum=number -> pin the graph length to 'number' time points
pinbot=a pintop=b -> pin the graph time window to run from 'a..b'
You can also open plugin windows with a windowname like so:
A.plugin.buttonlabel
where buttonlabel is the plugin's button label with blanks replaced
by underscores or hyphens (e.g., Render_Dataset). You can also use
the geom=+R+S option with this type of window opening, to position
the plugin interface window. There is no way to control any other
settings in the plugin interface (e.g., pre-set some fields).
If the specified image or graph window is already open, you can still
use this command to alter some of its properties.
++ You can also use "ALTER_WINDOW" for the command name, which makes
more sense if you are using this to apply some change to an already
open viewer window.
CLOSE_WINDOW [c.]windowname
Closes a window from controller 'c'. You can only close graph and image
viewer windows this way, not plugin windows.
SAVE_JPEG [c.]windowname filename
Save a JPEG dump of the given window to 'filename' (using the cjpeg filter,
which must be in the path). The windowname can be one of 'axialimage',
'sagittalimage', 'coronalimage', 'axialgraph', 'sagittalgraph', or
'coronalgraph'. If the filename does not end in the string ".jpg" or
".JPG", then ".jpg" will be appended.
++ Saving is done via the cjpeg program, which must be in the path,
and is included in the standard AFNI source and binary collections.
++ If the dataset has non-square voxels, then the default method of
saving images will produce non-square pixels (as extracted from
the dataset) -- this will make the images look peculiar when
you open them later. To avoid this peculiarity, set environment
variable AFNI_IMAGE_SAVESQUARE to YES (cf. SETENV below).
This comment applies to all image SAVE_* commands below, except
for SAVE_RAW* (where AFNI_IMAGE_SAVESQUARE has no effect).
SAVE_PNG [c.]windowname filename
Like SAVE_JPEG, but saves to the lossless PNG format.
++ Saving is done via the pnmtopng filter, which must be in the path.
Unlike cjpeg, this program is NOT part of the AFNI collection, but
must be installed separately (usually by getting the NETPBM package).
SAVE_FILTERED [c.]windowname filtercommand
Like SAVE_JPEG or SAVE_PNG, but instead of a filename, you
give a Unix filter that processes a PPM file. For example
SAVE_FILTERED axialimage 'pnmcut 10 20 120 240 | pnmtopng > zork.png'
will crop the image and save it into a PNG file. You'll need to become
familiar with the NETPBM package if you want to use this command.
++ As indicated in the example, you'll need to put filtercommand
in quotes if it contains blanks, which it almost surely will.
Other filter examples:
Save to a PPM file: 'cat > zork.ppm'
Save to a TIFF file: 'ppm2tiff -c none > zork.tif'
SAVE_ALLJPEG [c].imagewindowname filename
SAVE_ALLPNG [c].imagewindowname filename
SAVE_MPEG [c].imagewindowname filename
SAVE_AGIF [c].imagewindowname filename
Save ALL the images in the given image sequence viewer (either as a
series of JPEG/PNG files, or as one animation file). The windowname can
be one of 'axialimage', 'sagittalimage', or 'coronalimage'. Do NOT
put a suffix like '.jpg' or '.mpg' on the filename -- it will be added.
++ Unlike 'SAVE_JPEG', these commands do not work with graph windows.
SAVE_RAW [c.]imagewindowname filename
Saves the raw data from the given image viewer to a file. This data
is the slice data extracted from the dataset, not further processed
in any way (unlike the other SAVE_* image options, which convert the
slice data to grayscale or colors). This output file contains only
the data, with no header of any sort indicating the dimensions of the
image or the actual type of data stored therein.
SAVE_RAWMONT [c.]imagewindowname filename
Saves the raw data from the given image viewer to a file, AS MONTAGED.
(The montage gap is ignored.) Same as 'SAVE_RAW' if the montage
isn't on.
SET_DICOM_XYZ [c] x y z
SET_SPM_XYZ [c] x y z
SET_IJK [c] i j k
Set the controller coordinates to the given triple; DICOM_XYZ has the
coordinates in DICOM (RAI) order, SPM_XYZ has the coordinates in SPM
(LPI) order, and IJK has voxel indexes instead of spatial coordinates.
SET_XHAIRS [c.]code
Set the crosshairs ('Xhairs') control to the specified value, where
'code' is one of the following strings:
OFF SINGLE MULTI LR_AP LR_IS AP_IS LR AP IS
READ_NIML_FILE fname
Reads the NIML-formatted file 'fname' from disk and processes it as if
the data in the file had been sent to AFNI through a TCP/IP socket.
PURGE_MEMORY [dataset_prefix]
If no prefix is given, the sub-bricks of all datasets will be purged from
memory, and when re-used, AFNI will re-read them from disk. If a prefix
is given, only that dataset (in all coordinate views) will be purged.
++ "Locked" datasets will not be purged -- a dataset will be locked
into memory if it can't be re-read from disk (e.g., was sent from SUMA;
is being drawn upon, nudged, or acquired in realtime; was loaded from
a '3dcalc()' command line call; or was fetched across the Web).
QUIT
AFNI will exit immediately. Communication with the dead being difficult,
this action forestalls all further attempts to send commands to AFNI.
SETENV name value
Set the environment variable "name" to "value" in AFNI; for example
SETENV AFNI_CROSSHAIR_LINES YES
SETENV AFNI_IMAGE_SAVESQUARE YES
Most of the time, when you set an environment variable inside AFNI,
just changing the variable won't have any immediate visible effect.
Only when you instigate something that this variable controls will
anything change in AFNI. Thus, you may want to 'REDISPLAY' afterwards.
GETENV name
Get the value of environment variable "name", and print to the terminal.
For example:
GETENV AFNI_PLUGINPATH
would show the directory that plugins were loaded from, if set:
AFNI_PLUGINPATH = /home/elvis/abin
If a variable is not set, the output says as much:
AFNI_PLUGINPATH =
REDISPLAY
Forces all images and graphs to be redrawn.
SLEEP ms
Causes AFNI to sleep for "ms" milliseconds. The main use would be in
a script file to provide a pause between some effects.
QUIET_PLUGOUTS
Turns off normal plugout communications messages
NOISY_PLUGOUTS
Turns on normal plugout communication messages
TRACE {YES | NO}
Turns debug tracing on or off. Mostly for AFNI developers.
==============================================================================
** GRAPHS **
============
The following commands are used to open graph windows and manipulate them.
These commands don't actually interact with the rest of AFNI - they are
really just using AFNI as a graph display server. [This functionality
was added per the request of Jerzy Bodurka at the NIH, to provide a way
to graph physiological signals monitored while the subject is in the
scanner, at the same time the EPI images are being sent to the AFNI
realtime plugin.]
At present there are two similar kinds of graphs:
XY = connected (x,y) pairs - you must supply (x,y) for each new point
1D = x increments by 1 each time, so you only give y for each new point;
when x overflows past the right boundary, it wraps back to x=0.
Each graph can have multiple sub-graphs, which are stacked up vertically
with separate y axes and a common x axis (sub-graph #1 at the bottom, etc.).
Label strings in the graphs are interpreted in a TeX-like fashion. In
particular, an underscore means to start a subscript and a circumflex means
to start a superscript. Subscript or superscripts that are more than one
character long can be grouped using curly {braces}.
Greek letters and other special characters can be included using TeX-like
escapes. For example, "time (\Delta t=0.1)" might be a good label for the
x-axis of a 1D graph. The full list of such escapes is
\Plus \Cross \Diamond \Box
\FDiamond \FBox \FPlus \FCross \Burst \Octagon
\alpha \beta \gamma \delta \epsilon \zeta
\eta \theta \iota \kappa \lambda \mu
\nu \xi \omicron \pi \rho \sigma
\tau \upsilon \phi \chi \psi \omega
\Alpha \Beta \Gamma \Delta \Epsilon \Zeta
\Eta \Theta \Iota \Kappa \Lambda \Mu
\Nu \Xi \Omicron \Pi \Rho \Sigma
\Tau \Upsilon \Phi \Chi \Psi \Omega
\propto \int \times \div \approx \partial
\cap \langle \rangle \ddagger \pm
\leq \S \hbar \lambar
\cup \degree \nabla \downarrow
\leftarrow \rightarrow \leftrightarrow \oint
\in \notin \surd \cents
\bar \exists \geq \forall
\subset \oplus \otimes \dagger
\neq \supset \infty \uparrow
\{ \} \\ \_ \?
All characters are drawn with line strokes from an internal font; standard
fonts (e.g., Helvetica) are not available. If you want classier looking
graphs, stop whining and find another program.
--------------------------
OPEN_GRAPH_XY gname toplab xbot xtop xlab ny ybot ytop ylab nam_1 .. nam_ny
This opens a graph window for graphing non-MRI data. Each graph window
has a gname string; this lets you graph into more than one window.
Other arguments are
toplab = string to graph at top of graph [empty]
xbot = numerical minimum of x-axis in graph [0]
xtop = numerical maximum of x-axis in graph [1]
xlab = string to graph below x-axis [empty]
ny = number of sub-graphs (all share same x-axis) [1]
ybot = numerical minimum of y-axis in graph [0]
ytop = numerical maximum of y-axis in graph [1]
ylab = string to graph to left of y-axis [empty]
nam_1 = name to plot at right of sub-graph 1, etc. [not plotted]
Arguments are separated by spaces. If a label has a space in it, you can
put the label inside "double" or 'single' quote characters. If you don't
want a particular label plotted, make it the empty string "" or ''. If you
don't want names plotted at the right of sub-graphs, stop the arguments at
ylab. Only the gname argument is strictly required - the other arguments
have default values, which are given in [brackets] above.
CLOSE_GRAPH_XY gname
Closes the graph window with the given name.
CLEAR_GRAPH_XY gname
Clears the graph out of the given window (leaves the axes and labels).
ADDTO_GRAPH_XY gname x y_1 y_2 .. y_ny [repeat]
Actually plots data into the given window. In the i-th sub-graph, a line
will be drawn connecting to (x,y_i), for i=1..ny. You can put many sets
of points on the line, subject to the limitation that a plugout command
line cannot contain more than 64 Kbytes.
--------------------------
OPEN_GRAPH_1D gname toplab nx dx xlab ny ybot ytop ylab nam_1 .. nam_ny
Opens a graph window that is set up to plot nx points across with spacing dx,
in ny separate sub-graphs. When the graph is full, the graph recycles back
to the beginning. The meaning and [default] values of parameters are:
toplab = string to graph at top of graph [empty]
nx = number of points along the x-axis [500]
dx = spacing between x-axis points [1]
xlab = string to graph below x-axis [empty]
ny = number of sub-graphs (all share same x-axis) [1]
ybot = numerical minimum of y-axis in graph [0]
ytop = numerical maximum of y-axis in graph [1]
ylab = string to graph to left of y-axis [empty]
nam_1 = name to plot at right of sub-graph 1, etc. [not plotted]
CLOSE_GRAPH_1D gname
Closes the graph window with the given name.
CLEAR_GRAPH_1D gname
Clears the graph out of the given window (leaves the axes and labels).
ADDTO_GRAPH_1D gname y_1 y_2 .. y_ny [repeat]
Actually plots data into the given window. You can put many sets of ny
values at a time on the command line, subject to the limitation that a
plugout command line cannot contain more than 64 Kbytes. Also, if you
put more than nx sets of values, only the first nx will be plotted, since
that will fill up the graph through one full cycle.
--------------------------
SET_GRAPH_GEOM gname geom=X-geometry-string
This lets you move/resize a graph (1D or XY). X-geometry-string is one
of the forms:
300x100 = set window size to 300 pixels wide, 100 high
+50+90 = set window location to 50 pixels across, 90 down
300x100+50+90 = set window size and location at the same time
This page auto-generated on
Sat Mar 14 05:55:35 EST 2009