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

The unmarked entry at the right of the fn-F2
interface, under the color scale radio buttons
contains the filename of the color look-up table
(LUT) for use with colscale=12 (color scale radio
button "lt", real-valued color scale),
colscale=13 (complex amplitude, script-only), and
colscale=14 (complex phase: "lt" then "cpx", or
read LUT with "cpx" clicked).

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 tkmedit startup, it
is inside the current scandir, e.g.:

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

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
# 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 numbers, possibly
negative, that have to be in ascending order (tho
not necessarily evenly spaced).  The r,g,b's are
0-255.  Empty lines and comment lines (lines
starting with '#') are ignored.

Interpolated LUT

If $interpolatelutflag is 1 ("intplut" check at
upper right), the r,g,b entries in the table are
linearly interpolated for intermediate val's.
Val's off the top end of the scale are clamped to
the top entry; val's below the bottom edge fade
to the background curvature.  The fthresh (N.B.:
*not* absolute value of fthresh) is respected.

Non-interpolated LUT 

If $interpolatelutflag is 0, the r,g,b color
stays the same for vals until halfway to the next
(possibly unevenly spaced) val in the table, and
reverts to background at at a similar spacing for
val's beyond both the bottom *and* the top end of
the LUT table.

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

Color LUT files complex-valued phase/amplitude

If $complexvalflag is true ("cpx" clicked), then
a *phase* color LUT file is expected ($colscale
14).  The 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.  The
complex phase LUT always interpolates (no effect
of changing $interpolatelutflag).

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

The display of phase color LUT's is affected by
$revphaseflag and $angle_offset (but not by
$angle_cycles).  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.

A color LUT for complex-valued *amplitude* is
also available from a script.  First read in the
color LUT (which now can range above 1.0), and
set $complexvalflag (click "cpx"), then as the
last step (since interface clicks on "cpx"
auto-pick real vs. complex phase colscale) set
the colscale to complex *amplitude* LUT with a
one-line tcl script:

  set colscale 13
