Face-Based Luminance Matching: Software

These pages describe lumFace, all the VTK code that I wrote for my Visualization 2002 paper, both for the user study and for the talk/demo. This software implements all the steps needed to generate colormaps with pretermined patterns of luminance variation, including monotonically increasing luminance, and isoluminance.

It is currently implemented in Tcl/Tk/VTK, since that's what I know, but Java would probably be a much more appropriate language. Since this whole project was one big thesis distraction, I don't have time right now to do a Java port.

Getting all the software

VTK 4.0

On Windows, you have to install these programs. When I've installed them, in this order, and accept all defaults, everything works fine: On unix, you're more on your own:

teem/unu

In order to process the output of the VTK programs to create an actual colormap, I use the "unu" program, a command-line interface to the Utah Nrrd Utilities. Using "unu" allows one to process a text file containing RGB triples and create a PPM or PNG image of the continuously interpolated colormap. "Unu" wasn't exactly meant for this task, but it works fine, and you might find it useful for other tasks involving processing raster data of arbitrary type and dimension.

You'll need to download teem, version 1.5beta1 or later. Its probably simplest if you use one of the pre-compiled binaries. "Unu" is one of the programs in the "bin" directory of the teem distribution. You'll need to add that bin to your path.

And one more annoyance for Windows users. You'll need to get Cygwin so that you have a unix look-alike shell from which to run the genPnts.txt and genMaps.txt unu scripts.

lumFace

The software is distributed as a gzip-compressed tarball: The tarball will expand into a new directory called "lumFace". Using GNU tar, you can untar and uncompress in one shot with "tar xzvf". Winzip can deal with this too, however, you MUST disable "TAR file smart CR/LF conversion": Options menu... Configuration... Miscellaneous tab.

What comes in lumFace

The TCL programs are described in greater detail below. Contact me if you want more information about the files relating to the user study.

How to create colormaps!

Step 0:
lumCompare2.tcl

Step 1:
lumGamma.tcl

Step 2:
lumMakeMap.tcl

Step 3:
genPnts.txt, genMaps.txt

Once you've run lumGamma.tcl, and "Save + Quit" with the correct gamma setting for your monitor, you've created gamma.txt and igamma.txt files for storing the gamma and its reciprocal. Once you've run lumMakeMap.tcl, you've created a mapout.txt file with the luminance-adjusted control points. Now we do something with them.

Assuming that you have "unu" in your path, at a unix/cygwin shell type "source genPnts.txt". If "gamma.txt" contains "2.3", "igamma.txt" contains "0.434...", and "mapout.txt" contains: 

# begin level = 0.600; end level = 0.600
1.0 0.2168 0.2168
0.6424 0.6424 0.0
0.0 0.7352 0.0
0.0 0.6824 0.6824
0.5112 0.5112 1.0
0.9048 0.0 0.9048
Then by typing: 
source genPnts.txt
you should generate a PPM image, called "pnts.ppm" like this:
This shows the colormap control points before and after luminance adjustment. I generated this "mapout.txt" using a PC monitor in the SCI Lab. When you 
source genMaps.txt
the gamma.txt and igamma.txt files are used to control how the interpolation is done, and the resulting maps are in "maps.ppm":
The top map is the result of straight-forward interpolation of the control points. The second one is the result of luminance-controlled interpolation (based on gamma) between the control points. How isoluminant this looks to you depend on the gamma of your display and the relative luminances of the three phosphors. The paper did not seek to address the problem of making more uniform that rate of color variation within the colormap.