Go to | Kobus Barnard 's source code page | Kobus Barnard 's research page | Kobus Barnard 's Home Page

Gamut program home page

(Source code for computational color constancy)

Please direct questions and comments to Kobus Barnard.

This is the home page for the "gamut" program including links to the source, executables, data files, scripts, and documentation. 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 "A comparison of color constancy algorithms" part one and part two. 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.

This program does not work on Microsoft Windows

My most comon correspondence regarding this software is the result of assuming that it should work on Microsoft Windows---it doesn't. If you port this code to Microsoft Windows, then I encourage you to share your port with others. Drop me a line and I will be happy to link to a Windows version, or even mirror it on our server. However, I have no immediate plans to get a Windows machine, let alone update this code for it. Sorry!

Conditions of use

The use of this software is restricted to educational and research purposes. Modifying the code is endorsed, 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 (kobus AT cs DOT arizona DOT edu).

If you make use of this software for your research, I would appreciate it 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 much 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 by the authors/distributors of that program. 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 from the above link.

Changes since the first release:

I have posted version 1.2.0. This is the previous code synchronized with the librarary code it depends on and the build system it uses. Both of these have undergone a fair bit of development since gamut was released, but gamut itself has only seen small changes.
I have added some documentation on how to use the template files to extend the program, and I have added new template files (simple_template.[ch]) which should be an easier starting point. Ideally others will add their algorithms to this software. I would be happy to include contributions from other researchers with attribtution in future releases.

Slight change for linux and gcc libraries post 3.0. I am referring to this version as 1.0.1. If you compiled 1.0.0 with gcc 3.2, you may be getting random crashes before you do anything. This patch should fix this. I have left the executables for sun5, hpux, and sgi, the same.

As reported by Alok Ladsariya, "make clean" removes source files if you use the source directory for object files (I think this is the default). I patched this on Nov 25, 2002.

I have added the data/camera directory containing the file sensors.spect. An acceptable version of the sensors is hard coded, but the program looks for this file first.

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 shell command "unlimit" (or "ulimit", depending on your shell) to remove unreasonable restrictions. On the mac, I recomend 'limit stacksize 64000' since you cannot make it unlimited.If the program terminates or crashes without doing anything, this is most likely the reason. 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. When released I was able to build and run it on several flavors of Linux, SunOS, and very old versions of HPUX and SGI/IRIX (only with gmake). Currently, I am able to build and run the newer version (starting with 1.2.0) on linux on various hardwares and an intel Mac on 32 bit xeon. It probably compiles for PPC macs. It probably compiles for SunOS but I have not tested it recently.

Installation

Once you have downloaded, unzipped, and untarred, you will have a number of directories listed below. 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 possibly 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.

This program is not particularly 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. A few options for compiling can be set by modifying the build scripts as documented in the comments within.

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. However, reproducing all the numbers in the reference results might be a little optimistic. They are reproducible in spirit, but changes in libraries and systems over the years has lead to some small discrepencies.

Download

Click to download all but image data

If you would like to use any of our image data (not necessary to get started), you will need to download that sperarately from here. Specifically, to reproduce the IEEE-TIP-part-two experiments, you will want to put untarred versions of mondrian_16_bit and specular_16_bit into the data directory (default location is ~/data/gamut). These data sets are quite large! You may prefer using the 8 bit versions instead, and use an editor to change all "16_bit" to "8_bit" in the files input-std-mon and input-std-spec in the directories IEEE-TIP-part-two/experiment-[1-3]. Using 8 bit data will only have a modest effect on the results.

After downloding, unzipping, and untarring, you will end up with the following:

    gamut/bin/linux_386/gamut
    gamut/bin/sun5/gamut
    gamut/src/gamut/
    gamut/IEEE-TIP-part-one
    gamut/IEEE-TIP-part-two
    gamut/doc/help/gamut.help
    gamut/doc/man/cat1/gamut.1
    gamut/data/gamut

See the "installation" section above for further details on getting started.