Face-Based Luminance Matching: Software
These pages describe lumFace, all the VTK code that I wrote for
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
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:
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.
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.
- README.txt: tells you to go here
- LICENSE.txt: tells you that this stuff is LGPL'd
- lumCompare2.tcl: Simple stand-alone program for
experimenting with face-based luminance matching to see how it works
on different colors.
- lumGamma.tcl: For determining the gamma of your CRT.
- lumMakeMap.tcl: For generating
- genMaps.txt, genPnts.txt: unu
scripts which take the output of lumGamma.tcl and lumMakeMap.tcl to
generate images of the control points and continuous colormaps, before
and after luminance matching.
- img/: directory of images used by the TCL programs.
- img/gen/: some scripts I wrote using
to automate the generation of types of images used by the programs above.
- userstudy/: all the files relating to the programs I used
to collect data for the paper.
How to create colormaps!
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
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"
Then by typing:
# 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
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.
the gamma.txt and igamma.txt files are used to control
how the interpolation is done, and the resulting maps are in
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.