-------------------------------------------
entry variable: $val2rgblut -- abs name col LUT file
-------------------------------------------
default: */$scandir/val2rgb.lut

The "lut:" entry shows the current color lookup
table (LUT) file (usu. not loaded at initial
startup).  To load a color look up table, select
one from the "lut:" dropdown and click "R".

The color look-up table (LUT) file name is used
with colscale=12 (colorscale radio button "lt",
real-valued color scale), colscale=13 (complex
amplitude), and colscale=14 (complex phase).

Left-click the "Col:" label to get a pop-up with
all of the color scales (incl. 13 and 14).

This file can have any name and be saved to and
read from anywhere, but by default, and in order
to be automatically read on tksurfer startup, it
is inside the current scandir, e.g.:

 $FUNCTIONALS_DIR/110219MS/image/scan1/val2rgb.lut

Color LUT for Real-Valued Data

Here is an example of the ASCII file format for a
positive real-valued color scale ranging from
gray->red->blue->green:

## default val->color lookup table (req: ascending)
# val   red     green   blue
0.0     88      88      88
1.0     255     0       0
2.0     0       0       255
3.5     0       255     0

The val's are floating point data numbers,
possibly negative, that have to be in ascending
order (non-ascending entries skipped).  The table
entries do not have to be evenly spaced.

The r,g,b colors are each 0-255.  Empty lines and
comment lines (lines starting with '#') are
ignored.

Interpolated, Bottom-Edge, ZeroSymmetric Flags

Three flags ("intp", "bot", "sym", at the upper
right, above "lt" radiobutton) control the
interpretation of the value-to-RGBcolor entries
in the color table.  There are 8 different
possible combinations of these three flags.  The
last two flags only affect LUT's for real-valued
data or complex-valued amplitude (for
complex-valued phase data, see below).

Interpolated vs. Non-interpolated LUT

If $interpolatelutflag is 1 ("intp" ticked at
upper right), the r,g,b entries in the table are
linearly interpolated to the next table entry for
intermediate data val's.

If $interpolatelutflag is 0 ("intp" unticked),
the r,g,b color stays constant until the next,
possibly unevenly spaced, table entry.

Here is a tcl script that reads the real-valued
look-up table above and displays data with
interpolation first OFF, then ON:

   set val2rgblut /tmp/zz.lut
   read_val2rgblut
   set fthresh 0   ;# no trunc
   set colscale 12
   set interpolatelutflag 0
   redraw
   set interpolatelutflag 1
   redraw

Bottom-Edge-Defined vs. Center-Defined Colors (real)

If $botedgelutflag is 1 ("bot" ticked at upper
right), the r,g,b entries in the table specify
the data value for the bottom of the range of a
color.  In this case, the displayed color changes
(or is interpolated), as the data value hits (or
approaches) the value of the next entry.

If $botedgelutflag is 0 ("bot" unticked), the
r,g,b entries in the table specify the data value
for the center of a color.  In this case, the
displayed color changes (or is interpolated), as
the data value hits (or approaches) the midpoint
value to the next entry.

Center-defined colors are perhaps more intutive.
Bottom-edge defined colors are easier to use when
you want to define/mark specific contours.

Zero Symmetric vs. One-Sided (bottom) Threshold (real)

Finally, if $zerosymmfadeflag is 1 ("sym" ticked
at upper right), (s)fthresh and (s)fmid will cut
into the color scale symmetrically in both
directions from zero.

If $zerosymmfadeflag is 0 ("sym" unticked),
(s)fthresh and (s)fmid cut into the color scale
only from the bottom.

When this flag is set ("sym" is ticked), there is
a secondary effect when "bot" is also ticked
(bottom-edge defined colors).  The "bottom" range
of a color for *negative* values is flipped.
That is, the value for the bottom range of a
color is always nearest zero, from either above
zero or below zero.

Color LUT files complex-valued phase

If $colscale 12 ("lt" radio button) is first
selected, and then $complexvalflag is set to 1
("cpx" clicked), then a *phase* color LUT file is
expected instead ("lt" radio button is
unclicked), which is "ltw", $colscale 14.  This
can be selected directly by left-clicking the
"Col:" label to get the all-colorscales popup,
and then selecting the "ltw" button.

In this case, val's (first column) should begin
at 0.0 and end at 1.0, and the colors for 0.0 and
1.0 should typically be the same if you want the
phase colors to wrap around smoothly.  If
$interpolatelutflag is turned off, discrete
colors are used as if $botedgelutflag was ON.
There is no effect of changing $botedgelutflag or
$zerosymmfadeflag with this colscale.

You can write out an example file like this by
clicking the phase color wheel ("w1") and writing
out a LUT file ("W" to right of "lut:" entry).
Note that the *currently displayed* color scale
is written out -- i.e., it will incorporate any
effects of $revphaseflag, $angle_offset, and
$angle_cycles.

Here is an example of a LUT for complex phase
suitable for hand-editing (R->B->G):

## default val->color lookup table
# val   red     green   blue
0.0     255      0       0
0.3333  0        0     255
0.6667  0      255       0
1.0     255      0       0

N.B.: The *display* of phase color LUT's is
affected by $revphaseflag and $angle_offset (but
not by $angle_cycles, which is equivalent to
changing the look up table as opposed to just
rotating or reversing it).  Because of this, to
re-display a phase color LUT just written without
change, turn off $revphaseflag and set
$angle_offset to 0.0 after re-reading the LUT.

Color LUT files complex-valued *amplitude*

Finally, a color LUT can be used to display the
complex-valued *amplitude*.  This color is set
interactively by left-clicking the "Col:" label
to get the all-colorscales popup and selecting
the "lta" button.

Here is how to do this in a tcl script (similar
would work for other LUT colscales, too):

  setfile val2rgblut my-cplx-amp.lut
  read_val2rgblut
  set complexvalflag 1
  set colscale 13
  redraw

HOWTO write LUT for current color scale

See help for the "W" button for more details.
Note that the written-out color table potentially
takes into consideration the state of all of
these parameters (depending on whether data
is real or complex):

  $complexvalflag
  $angle_offset
  $angle_cycles
  $fthresh, $sfthresh
  $fmid, $sfmid
  $fslope, $sfslope
  $revphaseflag
  $invphaseflag
  $interpolatelutflag
  $botedgelutflag
  $zerosymmfadeflag

This means that if the just-written-out color
scale is immediately re-read, some of these
parameters will be recursively applied.  To avoid
this:

  set complexvalflag <same-as-writefile-time>
  set angle_offset 0.0
  set fthresh <below-any-data-value>
  set fmid <below-any-data-value>
  set sfmid <below-any-stat-value>
  set fslope <large>
  set sfslope <large>
  set revphaseflag 0
  set invphaseflag 0
  set interpolatelutflag 1
  set botedgelutflag 0
  set zerosymmfadeflag 0
