This distribution contains the python source code used in the
following research paper to remove vignette and exposure variation
from panoramic sequences of images:

Dan B Goldman and Jiun-Hung Chen. "Vignette and Exposure Calibration
and Compensation." To appear in Proceedings of ICCV 2005, Beijing,
October 2005.

This is research code, and is provided without warranty or support,
under the X11 license.  (See LICENSE file for details.)  Don't use it
to run your nuclear reactor, OK?

INSTALLING
----------

This code requires the following packages and programs, all of which
are downloadable online:

Python 2.3	http://www.python.org
Numarray 1.3.3  http://www.stsci.edu/resources/software_hardware/numarray
PIL             http://www.pythonware.com/products/pil
AutoStitch      http://www.autostitch.net

AutoStitch runs only on Windows.  The python code has been tested on
Linux and Mac OS X, but NOT on Windows.  (Don't ask...)  

In addition, it requires a data file which can be downloaded
from Columbia at the following site:

http://www1.cs.columbia.edu/CAVE/research/softlib/dorfEmor.html

(Install the "emor.txt" file in the data directory.)

RUNNING
-------

1. First, solve for the alignment between frames using AutoStitch.  I
won't document how to do that here, the docs that come with AutoStitch
should be enough to get you going.  Autostitch will also blend your
panorama for you, but as I discuss in the paper, blending will not
eliminate vignetting or exposure artifacts completely.  (But it's
better than nothing.)  AutoStitch leaves a file called "pano.txt" in
the directory with your stitched panorama, this is what we really
want.

I've provided a sample set of images in the images/senore directory
with a pano.txt file already computed.

2. Put the included python directory in your PYTHONPATH.

3. Solve for the vignetting parameters by running the python script
"solve3.py".  The parameters are:

solve3.py <imgdir> <npoints> [<dmax>]

imgdir:  The directory containing the images and pano.txt file.
npoints: The number of sample points to use for the solution.
         (I used 1000 for my best results, but you can often get
	 by with fewer)
dmax:    An optional threshhold for a robust distance metric.
         Seems to slow things down without improving the solution,
         so I don't recommend using this argument.

For example, to run the solver on the test data, do this:

python/solve3.py images/senore 200

After a long while (see notes below), this script will dump a new file
called "k.txt" in the image directory.  This contains the vignette,
exposure, and response curve parameters for the image sequence.  If
you get tired of waiting, you can interrupt the solver with control-c,
and it will save out the current solution to the k.txt file.

(In case you want to know what the data in k.txt means: The first 3
numbers are the polynomial vignette curve coefficients, denoted
alpha_2, alpha_4, and alpha_6 in the paper.  The next 5 numbers are
the PCA response curve coefficients, denoted beta.  The rest of the
sequence contains the per-frame exposures, denoted t_i.)

4. Solve for de-vignetted images, and create a merged panorama, by
running the script "devmerge3.py".  The parameters are:

devmerge3.py <imgdir> <outfile> [<scale> [<kfile>]]

imgdir:  The directory containing the images, and pano.txt file.
outfile: The name of the output panorama file.
scale:   Optionally change resolution of output panorama.  (default 1.0)
kfile:   Optionally specify a k.txt file.       (default <imgdir>/k.txt)

The scale factor is used to adjust the size of the final cylindrical
panorama.  I recommend using a small scale at first (.25) when working
with high-resolution images, since the default scaling of 1.0 keeps
pixels roughly the same size as in the original images.

In addition to the output panorama, this script will save some
additional files into the same directory, using the basename of the
output file (that is, everything but the file extension):

<basename>.<origfilename>: Solved frames
<basename>.#.png:          Solved frames, transformed into cyl. image coords.

5. Optionally, save out the "unsolved" images into a panorama also.
Why would you want to do this?  The cylindrical image coordinates for
the panorama don't match the spherical panoramas generated by
autostitch.  So to make it easier to compare your vignette- and
exposure-corrected panorama to what it would look like without
vignette or exposure correction, you can generate an uncorrected
panorama using the same cylindrical transformation:

merge.py <imgdir> <outfile> [scale]

SPEED
-----

This code is real slow.  Nonlinear optimization on lots of variables
can be a bear, but even more so when you're using a brain-dead
optimizer like Nelder-Mead.  And although I've tried to take advantage
of the excellent numarray module to keep the code as fast is it can
be, I haven't done any extensive profiling, and it would no doubt be
oodles faster in C.  If anyone out there would like to help make a
faster version, please contact me!

dgoldman (at) cs (dot) washington (dot) edu