image analogies : software

'Unfiltered' painting (A) : 'Filtered' painting (A') :: Input image (B) : Target image (B')
A
A'
B
B'

From this page, you can download "lf," the software that we used to create all of the output images in the "Image Analogies" paper. Precompiled executables are provided for Linux and Windows 2000; porting to other platforms should be straightforward. We have provided a few examples to make it easy to experiment with "lf."

This is research code, and thus very messy and poorly-documented. We do not promise that it works, and we do not promise to support it. Use at your own risk! However, other people have been able to successfully download and run this software.

We highly recommend reading the paper if you are interested in experimenting with this software. It describes the algorithm in detail, gives some tips for designing filters, and describes some of the limitations of the software.

"lf" was written by Aaron Hertzmann and Chuck Jacobs. The source code is freely distributed for educational, research and non-profit purposes. Please contact us if you would like to license the library for use in commercial products.

In case you were wondering, "lf" stands for "learn filter."

If you get any cool results with this software, or make any improvements, we would be interested in hearing about it.

I want it now!

Download the distribution here. Use "tar xvfz lf.tar.gz" to decompress it on Unix; use StuffIt or WinZip on Windows. Executables are provided for Linux ("lf_linux") and Windows ("lfWindows.exe").

Compiling

A "Makefile" is included for Unix systems, and a Microsoft Visual Studio workspace file ("lfWindows.dsw") for Windows. You may need to modify these files to match your system. In the past, we have been able to compile this code on an SGI. On Unix, you will need to first make dependency files before running "make" for the first time, by running "touchd.sh".

Quick Start

The software has far too many options, none of which are currently documented. Instead, we have provided a number of samples that you can modify to create your own tests. Just run:

where argfile.txt is one of the ".txt" files included with the distribution. Modify the ".txt" files to test different images or to change settings. For example, use

to test our texture synthesis algorithm on the flowers texture. The results will be saved to folders in the directory specified in the parameter file. There is also an interactive version; set "useInterface: true" on the command line or in the argument file to use it.

All input images must be in the PNG or PPM formats, or BMP on Windows.

"lf" can be a demanding application when the training (A and A') images are large. Many of our color NPR images required several hours on a 1GHz processor with 700MB memory.

In general, the most important parameter to experiment with is the "coherenceEps" parameter (called "kappa" in the paper). Different values will work best for different training pairs.

The parameter settings included here for the Wei-Levoy and Ashikhmin algorithms are slightly different from those described in their papers, in the boundary handling, randomization, and possibly neighborhood sizes.

Requirements and Libraries

The "lf" distribution uses several great, free libraries: OpenGL, GLUT libraries, GLUI (by Paul Rademacher), libPNG, ANN (by David Mount and Sunil Arya), LAPACK/blas and pthreads for Win32. Most or all of the needed libraries for Windows are included with the distribution; most are already included in common Linux distributions. If you are using one of these platforms, odds are that you do not need to download anything. Otherwise, if you seem to be missing a library, it might be one of these.

If you don't have LAPACK, you can disable it by undefining "LAPACK" in the Makefile/project file. You won't be able to use histogram matching, though. Similarly, you may be able to run without pthreads by undefining "THREADS".

Missing features, bugs

In the paper, we use steerable filters when processing line art filters; this code is not included in the distribution for minor technical reasons. Interactive editing (shown in the video) is also not included.

There appear to be some minor bugs in the code. If the program crashes (or, more likely, an assertion fails), try settings "cheesyBoundaries: false". This turns off a hack we sometimes used to speed up boundary computation; the hack has a subtle bug involving predictions near image boundaries. We might fix the bug sometime in the future.

Test images

You can get more test images from the Image Analogies page. These are the same images as used in the paper, with the addition with some imperceptible JPEG artifacts. Contact us if you absolutely positively must have the original non-lossy images.