Gamut, a program for computational color constancy

                      By Kobus Barnard (kobus@cs.arizona.edu)

         Available from http://www.cs.arizona.edu/~kobus/research/programs


This is the README file for the "gamut" program.  Gamut provides implementations
for several basic color constancy algorithms, as well as an overall framework
for testing color constancy algorithms.  It is meant, in part, to accompany the
publications:

     Kobus Barnard, Brian Funt, Vlad Cardei "A Comparison of Computational Color
     Constancy Algorithms; Part One: Methodology and Experiments with
     Synthesized Data," IEEE Transactions in Image Processng, in press.

     Kobus Barnard, Linday Martin, Adam Coath, and Brian Funt, "A Comparison of
     Computational Color Constancy Algorithms; Part Two: Experiments with Image
     Data," IEEE Transactions in Image Processng, in press.

Specifically, I have included input files which generate most of the results
found in those papers. The chief exception is that an implementation of Neural
Net color constancy is not provided. What is provided are implementations of the
two versions of the gray world algorithms used, the scale-by-max algorithm used,
the various 2D and 3D gamut mapping algorithms used, and the various versions of
color by correlation used. 

                                Conditions of use

Currently, I am making the code available for educational and research purposes.
Modifications of the code are permitted, as long as appropriate credit is
provided, and authorship is not misrepresented.  If you would like to make
commercial use of any of the code being distributed, then please contact me

If you make use of this software for your research, I would appreciate if you
cite or acknowlege the web site and/or the two papers mentioned above as
appropriate. 

                                Credits

Acknowlegement is due to Brian Funt who, as my PhD supervisor during the time
that most of the software was written, supported this work in many ways.  Kudos
also to Lindsay Martin who helped with some of the coding. Also, many thanks to
the Geometry Center for making the qhull software available.  This code uses a
slightly modified old version of qhull, which is being distributed under the
terms of use provided. Because it is an old version, I strongly discourage using
the code for purposes which can be better served by newer versions of the
software available on the web.

                                Problems

This program requires a non-trivial amount of resources, and can crash if the
process stack size is small. Depending on the version of unix, and how it has
been set up, you may need to use the command "unlimit" (sometimes spelt
"ulimit") to remove unreasonable restrictions. The program will also not likely
be able to do anything interesting if the overall amount of memory on your
system is less than 128 megs (256 megs recomended). 

I am certain that more widespread use will identify problems. This program was
written over a long period of time, and hacked for many purposes. Some of the
older parts are no longer used by myself, therefore could easily have been
broken by changes made to support more recent activities. 

Please let me know about any problems that you encounter compiling or running
the program.  However, I cannot guarantee that I will be able to find the time
to fix any particular problem. If you cannot compile the program on your (Unix)
system, then I may be willing to investigate, provided that you can provide me
with a guest account on the system in question.

If there is any chance that the problem you are reporting is related to
insufficient resources, please send me the output of the "limit" command, as
well as the amount of memory that you have. 

(Of course, fixes to either the build scripts or the code are much appreciated). 

                                Platforms

This is a Unix program. Currently I can build and run it on several flavors of
Linux, SunOS, and very old versions of HPUX and SGI/IRIX (only with gmake).  I
will make the required adjustments for Mac OS/X later this year (when my new mac
arrives).  For those who would prefer not to compile if possible, I have
provided executables for a few systems. 

                                Installation

Once you have downloaded, unzipped, and untarred, you will have the following
subdirectories of the distribution directory:
    bin/linux_386/gamut
    bin/sun5/gamut
    src/gamut/
    IEEE-TIP-part-one
    IEEE-TIP-part-two
    doc/help/gamut.help
    doc/man/cat1/gamut.1
    data/gamut

You will need to move the directories relevant to your use into more suitable
locations. Then, if you like, delete the rest. 

Executables for a few platforms are in the subdirectory bin. You may wish to
simply move the appropriate one to a location listed in PATH. 

Likely you will want to make use of the data in the data/gamut directory. The
program searches a number of locations for data, the easiest to describe is
~/data/gamut, so the easiest way to get started is to move the data/gamut
subdirectory to become the gamut subdirectory of ~/data. 

There is a man page in the distribution subdirectory doc/man/cat1/gamut.1. If
you would like to read it using man, then you need to put it in a location
listed in your MANPATH. 

There is a help file in the distribution subdirectory doc/help/gamut.help. If
you want to use help, then this file needs to be in either the directory where
you are running the program, or in ~/doc/help. 

I would not call this a well documented program, but you may as well look at
what I have written so far! Note that the man-page and the help file contain 
exactly the same information, as the one is generated from the other. 

If you would like to compile the program, go into the src/gamut distribution
subdirectory, and type "./build". Typing "make" also works, but doing so simply
calls the build script. The build script sets up the enviroment in a sub shell,
and then uses make to build the program. (My strategy is to provide copies of
the scripts that I use to setup my development environment and to build in the
same environment in a sub-shell to minimize the chances of environment variable
conflicts.)

Example scripts which produce the numbers used for the two IEEE TIP papers can
be found in the distribution subdirectories IEEE-TIP-part-one, and
IEEE-TIP-part-two. For some of the scripts I have included the results of
running the program with that input so that you can check that everything is
working correctly. 

                         Extending the program 

This software provides relatively powerful infrastructure for testing color
constancy algorithms. Thus it may be beneficial to integrate your algorithms
into it. Instructions for doing so are in the file template.txt in the
distribution subdirectory doc/programming. I would be happy to include your
algorithm with appropriate acknowlegements in future releases.