=====================================================
** Driving AFNI from a Plugout or a Startup Script **
=====================================================
A plugout can control some aspects of AFNI.  This is done 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).

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

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.

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 Function" toggle on or off:
    SET_FUNC_VISIBLE A.+

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_Function', 'Define_Datamode', or 'Define_Markers'.  At this time,
  there is no way to close a panel.

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.  If the specified controller
  is not open, the acknowledgement from AFNI will be "BAD", otherwise
  it will be "good".

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

SET_ANATOMY [c.]prefix
  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.

SET_FUNCTION [c.]prefix
  Same, but for the functional dataset in controller 'c'.

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).
  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
  For graph windows, other options available are:
    matrix=number -> use number sub-graphs (<= 21)
    pinnum=number -> pin the graph length to number time points
  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.
  If the specified image or graph window is already open, you can still
  use this command to alter some of its properties.

CLOSE_WINDOW [c].windowname
  Closes a window from controller 'c'.  You can only close graph and image
  viewer windows this way, not plugin windows.

QUIT
  AFNI will exit immediately.

SETENV name value
  Set the environment variable "name" to "value" in AFNI; for example
    SETENV AFNI_CROSSHAIR_LINES YES

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.


============
** 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.

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, 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
