AFNI Colorscales

Feb 2003 -- RW Cox

AFNI now has the ability to display functional overlays with a "continuous" colorscale, rather than with a color bar that has a small set of color steps. To select such a colorscale, you set the "#" chooser below the color bar to the new setting "**". This setting is illustrated in the picture below:

AFNI screenshot AFNI animation

Other features of the colorscale include:

Button-1 click in the colorscale will flip it top-to-bottom. Click again to flip it back to the original state.
Button-3 click in the colorscale will popup a chooser of available colorscales. The first four shown in the chooser in the AFNI screenshot above are built-in to AFNI.
- The two colorscales named "Color_circle_something" are periodic (including the one shown), and could be suitable for displaying some kind of phase maps (e.g., for retinotopy, B-field maps, etc.).
  - AJJ is Andrzej Jesmanowicz; ZSS is Ziad Saad. These color circles come from some ideas I "borrowed" from them.
- The last two colorscales in the picture's list are read in from files at AFNI startup. Details of such files, and how to tell AFNI to load them, are given below.
- At this time, the only way to load a colorscale definition after AFNI starts up is via a script command DEFINE_COLORSCALE. This is more fully defined in README.driver.
You can use the "Rota" buttons to rotate the colorscale.
- To get it back to where it started (after you mess it up), reload the colorscale using the Button-3 popup chooser.
- Holding a "Shift" key down while pressing a "Rota" arrow will rotate in steps of 4 color levels instead of the default 1 level per click. Since there are 128 level, 1 level per click is pretty slow.
On the "Inten" Button-3 popup menu:
- Item "Save to PPM" will save an image of the current colorscale to a PPM-formatted file.
- Item "Set Top Value" can still be used to set the range of the colorscale.
- Item "Equalize Spacing" has no meaning when applied to the colorscale; neither do the "Palettes".
The current colorscale can be saved/restored from a .afni.startup_script; for (slightly) more information, see README.driver.
- However, if you've rotated or flipped the colorscale, that situation is not save-able or restore-able.
When using a colorscale, you probably want to set the Func and Thresh resample modes to "Li" (from "NN") on the "Define Datamode" control panel. Otherwise, you'll be doing smooth coloring on spatially blocky data, which isn't very interesting.
When you set the colorscale to "Pos", then functional values below zero will not be colored. If the colorscale bottom value is nonzero, then functional values below that level will get the bottom color. In either case, functional values above the top level will get the top color. This usage is the same as how the discrete-panes color bar works.
- Recall that a functional value of zero is never given a color.
The animation above was made by using "Rota" to cycle through the colorscale, while using the image viewer "Rec" option to record all 128 images, and then saving them with in the "aGIF" (animated GIF) format.
- If you understand all that, then you are qualified to be an AFNI Certified Expert (ACE)!
N.B.: Colorscales do not yet work in the AFNI volume rendering plugins.

Defining Colorscales in External Files:
A colorscale is defined by giving the colors at various points along the scale, from top to bottom. Positions along the scale are given numerically, decreasing from top to bottom. A sample file:

     Yellow-Red-Blue
      1.0  #ffff00  // yellow = red+green
      0.7  #ffaa00
      0.5  #ff0000  // pure red
      0.3  #aa00aa
      0.0  #0000ff  // pure blue

The first line gives the title of the colorscale, as it will appear in the Button-3 popup. No spaces are allowed in the title!
The other lines are of the form "number color". In this example, the numbers range from 1.0 (=top) to 0.0 (=bottom). The actual range of numbers can be anything convenient (e.g., 100=top to 0=bottom).
- These numbers have nothing to do with the scale values that appear at the right of the colorscale.
- The numbers in this colorscale file are there only to provide the locations of the breakpoints between the defined colors.
- Comments are allowed at the end of lines, as shown.
- A line starting with a comment will be skipped.
Colors are specified as in X11 (cf. "man XParseColor"):
- In the example, I've used 2 hex digits per color channel.
- Colors are interpolated (linearly in RGB space) between the break locations given in the file.
The color #000000 (pure black) will not be overlaid by AFNI. In the colorscale display, it will show as a neutral gray value, indicating a gap in the colorscale. If you do want to overlay a very dark color, then use the color #010101, which is visually black.
There are exactly 128 color locations on a colorscale.
- Using the "Rota" buttons will move the colorscale 1 color step at a time, which is pretty slow.

An alternative format for the file is to omit the numbers indicating the break locations. In this case, the break locations will be taken to be equally spaced. For example:

     Yellow-Red-Blue
      #ffff00
      #ffaa00
      #ff0000
      #aa00aa
      #0000ff

This example is not exactly the same as the other one, since the breakpoints are evenly spaced now (as if they had been given as 1.0, 0.75, 0.5, 0.25, and 0.0). With this alternative format, if you want to manually specify all 128 colors, you can do so, 1 color per line, remembering that the first line of the file is taken to be the colorscale title.

Reading Colorscales at AFNI Startup:
Certain colorscale files are read at AFNI startup. You specify them by setting environment variables of the form AFNI_COLORSCALE_xx for xx=01,02,...,99. These filenames will be looked for in the current directory when you start AFNI, or in your home directory (if they aren't in the current directory). The colorscale above, for example, is stored in my home directory in file .afni.color_YRB and is read in with the line

      AFNI_COLORSCALE_01 = .afni.color_YRB

in the ***ENVIRONMENT section of my ${HOME}/.afnirc file.

You can set environment variable AFNI_COLORSCALE_DEFAULT to the name of the colorscale that you wish to be the default (not the filename, but the name at the top of the file, as it would appear on the colorscale popup chooser). As a special case, setting this to the string NO will set up AFNI so that the older discrete-panes color bar is used. (N.B.: AFNI_COLORSCALE_DEFAULT only has effect if you are using AFNI with a TrueColor X11 visual; if you are using a PseudoColor visual, your default setup will be discrete-panes. I have not tested colorscales with PseudoColor, but suspect that they don't work very well.)

X11 Color Names (extracted from "man XParseColor"):
An RGB Device specification is identified by the prefix rgb: and conforms to the following syntax:

       rgb:red/green/blue

       red, green, blue := h | hh | hhh | hhhh
       h := single hexadecimal digits (case insignificant)

Note that h indicates the value scaled in 4 bits, hh the value scaled in 8 bits, hhh the value scaled in 12 bits, and hhhh the value scaled in 16 bits, respectively.

For backward compatibility, an older syntax for RGB Device is supported, but its continued use is not encouraged. The syntax is an initial sharp sign character followed by a numeric specification, in one of the following formats:

       #RGB                (4 bits each)
       #RRGGBB             (8 bits each)
       #RRRGGGBBB          (12 bits each)
       #RRRRGGGGBBBB       (16 bits each)

The R, G, and B represent single hexadecimal digits. When fewer than 16 bits each are specified, they represent the most significant bits of the value (unlike the rgb: syntax, in which values are scaled). For example, the string #3a7 is the same as #3000a0007000.

An RGB intensity specification is identified by the prefix rgbi: and conforms to the following syntax:

       rgbi:red/green/blue

Note that red, green, and blue are floating-point values between 0.0 and 1.0, inclusive. The input format for these values is an optional sign, a string of numbers possibly containing a decimal point, and an optional exponent field containing an E or e followed by a possibly signed integer string.

The standard device-independent string specifications have the following syntax:

       CIEXYZ:X/Y/Z
       CIEuvY:u/v/Y
       CIExyY:x/y/Y
       CIELab:L/a/b
       CIELuv:L/u/v
       TekHVC:H/V/C

All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are floating-point values. The syntax for these values is an optional plus or minus sign, a string of digits possibly containing a decimal point, and an optional exponent field consisting of an "E" or "e" followed by an optional plus or minus followed by a string of digits.