Setting Up AFNI Colors and Palettes
===================================
You can set up the colors and palette tables used by AFNI in the
file .afnirc in your home directory.  This file will be read when
AFNI starts.  Each section of this file starts with a string of
the form "***NAME", where "NAME" is the name of the section.  At
present, three sections are available:
   ***COLORS      -- for defining new colors
   ***PALETTES    -- for defining the layout of colors used for
                     functional overlays (the "palette tables").
   ***ENVIRONMENT -- for defining Unix environment variables that
                     affect the way AFNI works.

Note that you can have more than one of each section in the setup
file (although there is no particular reason why this is needed).
Comments can be put in the .afnirc file using the C++ "//" style:
everything from the "//" to the end of line will be ignored.

The file AFNI.afnirc in the afni98.tgz distribution contains
an example of defining colors and using them to create palettes
for functional overlay.

Defining the Colors Available for Overlays
------------------------------------------
The "***COLORS" section is used to define colors that will be added
to the color menu that is used for functional overlays, crosshairs,
etc.  A sample is

***COLORS
   qblue = #804cff            // RGB hexadecimal color definition
   zblue = rgbi:0.5/0.3/1.0   // RGB floating point intensities

The general form of a color definition line is
   label = definition
where "label" is what you want to appear on the menu, and "definition"
is a valid X11 color definition.  (The spaces around "=" are required.)
In the first line, I have defined the label "qblue" using hexadecimal
notation for the RGB components (each one has 2 hex digits).  In the
second line, I have defined the color "zblue" using the RGB intensity
format, where each of the numbers after the string "rgbi:" is between
0.0 and 1.0 (inclusive) and indicates the intensity of the desired color
component.

Note that the file /usr/lib/X11/rgb.txt (or its equivalent) contains
the definitions of many color names that the X11 system recognizes.
See 'man XLookupColor' for more information on the many ways to define
colors to X11.

If you use a label that has been defined previously (either internally
within AFNI, or earlier in the setup file), then that color will be
redefined.  That is, you could do something stupid like
   blue = red
and AFNI won't complain at all.  ("blue" is one of the pre-defined colors
in AFNI.  I suppose you could use this 'feature' to make AFNI into some
sort of twisted Stroop test.)  Color labels are case sensitive, so
"BLUE = red" is different than "blue = red".  You cannot redefine the
label "none".

On 8 bit graphics systems (the vast majority), you must be parsimonious
when defining new colors.  You may run out of color "cells", since there
are only 2**8 = 256 available at one time.  All the colors used for
the windowing system, the buttons, the grayscale images, and the overlays
must come from this limited reservoir.  On a 12 bit system (e.g., SGI),
there are 2**12 = 4096 color cells available, which is effectively
unlimited.

Defining the Palette Tables
---------------------------
A palette is a listing of colors and separating numerical values that
are used to define a functional overlay scheme.  These are controlled
by the "***PALETTES" section in the setup file.  Each palette has a
name associated, and a number of color "panes".  For example:

***PALETTES
  rainbow [3]
    1.0 -> blue     // The spaces around "->" are required
    0.2 -> green
   -0.4 -> hotpink  // There are N lines for palette entry [N]

This defines a palette table "rainbow", and in the entry for 3 panes
sets up the pbar to have 1.0 as its maximum value, then to have the
color "blue" be assigned to the pane that runs down to 0.2, then the
color "green" assigned to the next pane running down to -0.4, and then
the color "hotpink" assigned to the last pane (which will run down to
-1.0, since the minimum value is the negative of the maximum value).

Each palette table can have palettes from 2 panes up to 20, denoted
by [2] to [20].  A palette table, can also have palettes that are
restricted to positive values only.  These are denoted by [2+] to
[20+].  An example is

  rainbow [3+]
    1.0 -> blue
    0.5 -> none
    0.1 -> limegreen

If the rainbow palette is the active one, when you switch to positive-
only function mode (using the "Pos" toggle button), and then to use 3
panes (using the "#" chooser), then the top pane will run from 1.0 to
0.5 in blue, the second pane from 0.5 to 0.1 and have no color, and the
third pane from 0.1 to 0.0 in limegreen.

It is possible to define palettes that only change the colors,
not the separating values.  This is done by using the special
word IGNORE in place of the values:

  rainbow [4+]
    IGNORE -> blue
    IGNORE -> green
    IGNORE -> hotpink
    IGNORE -> none

All of the values must be IGNORE, or none of them.  When a
palette like the one above is loaded, only the colors in the
pbar will change -- the pane heights will be left unchanged.

The New Palette Menu
--------------------
Attached to the "Inten" label atop the color pbar is a popup menu
that is activated using mouse button 3.  This menu has the following
items:

   Equalize Spacing   = Sets the spacings in the currently visible
                          palette to be uniform in size.

   Set Top Value      = Sets the top value in the currently visible
                          palette to a number you choose.  Note that
                          you will probably need to adjust the
                          "Range" control if you change the top value
                          from 1.0, since the thresholds for making
                          functional overlays are determined by
                          multiplying the pbar values times the
                          value in the "Range" or "autoRange" control.

   Read in palette    = Reads in a palette file.  This is another
                          file like .afnirc (with ***COLORS and/or
                          ***PALETTES sections).  AFNI expects such
                          files to have names that end in ".pal".
                    N.B.: New colors defined this way will NOT be visible
                          on previously created color menus (such as the
                          Crosshairs Color chooser), but will be visible
                          on menus created later.
                    N.B.: Reading in a palette that has the same name
                          as an existing one will NOT create a new one.

   Write out palette  = Writes out the currently visible palette to
                          a ".pal" file.  In this way, you can set up
                          a palette that you like, write it out, and
                          then read it back in later.  (Or you could
                          copy the data into your .afnirc file, and
                          it would be available in all later runs.)
                          The program asks you for a palette name,
                          which is also used to for the filename -- if
                          you enter "elvis" for the palette name, then
                          AFNI will write to the file "elvis.pal".  If
                          this file already exists, the palette is
                          appended to the end of the file; otherwise,
                          the file is created.

   Show Palette Table = Pops up a text window showing the definitions
                          of all the colors and palettes.  Mostly useful
                          for debugging purposes.

   Set Pal "chooser"  = A menu that lets you pick the palette table
                          that is currently active.  Note that reading
                          in a palette table does not make it active --
                          you must then choose it from this menu.  Writing
                          a palette out does not enter it into this menu.
         ======>>> N.B.:  If a palette table does not have an entry for a
                          given number of panes, then nothing will happen
                          until you use the "#" chooser to make the number
                          of panes correspond to the selected palette table.
         => 18 Sep 1998:  In versions of AFNI released after this date,
                          reading in a palette file causes the last
                          palette in that file to become the active one.
                          [Suggested by SM Rao of MCW Neuropsychology]

Unix Environment Variables [June 1999]
--------------------------------------
You can set Unix environment variables for an interactive AFNI run in
the .afnirc file.  This is done with the ***ENVIRONMENT section.  An
example is

***ENVIRONMENT
  AFNI_HINTS = YES
  AFNI_SESSTRAIL = 3

The blanks around the "=" are required, since that is how the setup
processing routine breaks lines up into pieces.  For a list of the
environment variables that affect AFNI, see README.environment.

The Future
----------
I will probably add more sections to the setup file.  Someday.  Maybe.

=======================================
| Robert W. Cox, PhD                  |
| National Institute of Mental Health |
| Bethesda, MD USA                    |
=======================================
