Automatic Color Enhancement (ACE) and its Fast Implementation
Pascal Getreuer, getreuer@cmla.ens-cachan.fr, CMLA, ENS Cachan
Version 20130706 (July 6, 2013)

  *** Please cite IPOL article "Automatic Color Enhancement (ACE) and ***
  *** its Fast Implementation" if you publish results obtained with   ***
  *** this software.                                                  ***


== Overview ==

This C source code is a revision of the code accompanying Image Processing On
Line (IPOL) article "Automatic Color Enhancement (ACE) and its Fast 
Implementation" at

  http://dx.doi.org/10.5201/ipol.2012.g-ace

The original peer-reviewed IPOL version of the code is available from the
article page.

Future software releases and updates will be posted at

  http://dev.ipol.im/~getreuer/code

Compared to the IPOL version, this revision differs in the following ways:

    * Included zlib.h in imageio.c for compatibility with libpng 1.5 and later
    
    * Removed arbitrary limit on alpha in acecli.c


== License (BSD) ==

File avs.jpg was created by NASA (http://dragon.larc.nasa.gov/retinex/).

All other files are distributed according to the simplified BSD license.  You
should have received a copy of this license along this program.  If not, see
<http://www.opensource.org/licenses/bsd-license.html>.


== Program Usage ==

This source code includes two command line programs: ace and histeq

    * ace: runs ACE color enhancement

    * histeq: performs uniform histogram equalization


--- ace ---

Usage: ace [options] input output

where "input" and "output" are BMP files (JPEG, PNG, or TIFF files can also
be used if the program is compiled with libjpeg, libpng, and/or libtiff).

Options:
  -a <number>  alpha, stronger implies stronger enhancement
  -w <omega>   omega, spatial weighting function, choices are
               1/r      default ACE, omega(x,y) = 1/sqrt(x^2+y^2)
               1        constant, omega(x,y) = 1
               G:#      Gaussian, where # specifies sigma,
                        omega(x,y) = exp(-(x^2+y^2)/(2 sigma^2))
  -m <method>  method to use for fast computation, choices are
               interp:# interpolate s_a(L - I(x)) with # levels
               poly:#   polynomial s_a with degree #

  -q <number>  quality for saving JPEG images (0 to 100)


--- histeq ---

Usage: histeq [options] input output

Options:
   -b <number>     number of histogram bins (default 256)
   -q <number>     quality for saving JPEG images (0 to 100)


Example:

    # Perform ACE automatic color enhancement on avs.jpg with alpha = 8
    ./ace -a 8 -m interp:12 avs.jpg ace.bmp

    # Perform uniform histogram equalization
    ./histeq avs.jpg equalized.bmp

Note: If the programs are compiled without libjpeg support, please convert
avs.jpg to avs.bmp in Windows Bitmap BMP format and use this as the input.

Each of these programs prints detailed usage information when executed
without arguments or "--help".


== Compiling ==

Instructions are included below for compiling on Linux sytems with GCC, on
Windows with MinGW+MSYS, and on Windows with MSVC.

Compiling requires the FFTW3 Fourier transform library (http://www.fftw.org/).
For supporting additional image formats, the programs can optionally be
compiled with libjpeg, libpng, and/or libtiff.  Windows BMP images are always
supported.


== Compiling (Linux) ==

To compile this software under Linux, first install the development files for
libfftw, libjpeg, libpng, and libtiff.  On Ubuntu and other Debian-based
systems, enter the following into a terminal:
    sudo apt-get install build-essential libfftw3-dev libjpeg8-dev libpng-dev libtiff-dev
On Redhat, Fedora, and CentOS, use
    sudo yum install make gcc libfftw-devel libjpeg-turbo-devel libpng-devel libtiff-devel

Then to compile the software, use make with makefile.gcc:

    tar -xf ace_20130706.tar.gz
    cd ace_20130706
    make -f makefile.gcc

This should produce two executables, ace and histeq.

Source documentation can be generated with Doxygen (www.doxygen.org).

    make -f makefile.gcc srcdoc


== Compiling (Windows) ==

The MinGW+MSYS is a convenient toolchain for Linux-like development under
Windows.  MinGW and MSYS can be obtained from

    http://downloads.sourceforge.net/mingw/

The FFTW3 library is needed to compile the programs.  FFTW3 can be
obtained from

    http://www.fftw.org/

Instructions for building FFTW3 with MinGW+MSYS can be found at

    http://www.fftw.org/install/windows.html
    http://neuroimaging.scipy.org/doc/manual/html/devel/install/windows_scipy_build.html


--- Building with BMP only ---

The simplest way to build the tvdeconv programs is with support for only BMP
images.  In this case, only the FFTW3 library is required.  Edit makefile.gcc
and comment the LDLIB lines to disable use of libjpeg, libpng, and libtiff:

    #LDLIBJPEG=-ljpeg
    #LDLIBPNG=-lpng -lz
    #LDLIBTIFF=-ltiff

Then open an MSYS terminal and compile the program with

    make CC=gcc -f makefile.gcc

This should produce the executables ace and histeq.


--- Building with PNG, JPEG, and/or TIFF support ---

To use the tvdeconv program with PNG, JPEG, and/or TIFF images, the
following libraries are needed.

    For PNG:    libpng and zlib
    For JPEG:   libjpeg
    For TIFF:   libtiff

These libraries can be obtained at
    
    http://www.libpng.org/pub/png/libpng.html
    http://www.zlib.net/
    http://www.ijg.org/
    http://www.remotesensing.org/libtiff/

It is not necessary to include support for all of these libraries, for
example, you may choose to support only PNG by building zlib and libpng
and commenting the LDLIBJPEG and LDLIBTIF lines in makefile.gcc.

Instructions for how to build the libraries with MinGW+MSYS are provided at

    http://permalink.gmane.org/gmane.comp.graphics.panotools.devel/103
    http://www.gaia-gis.it/spatialite-2.4.0/mingw_how_to.html

Once the libraries are installed, build the tvdeconv programs with the
makefile.gcc included in this archive.

    make CC=gcc -f makefile.gcc

This should produce two executables, ace and histeq.


== Compiling (Mac OSX) ==

The following instructions are untested and may require adaptation, but
hopefully they provide something in the right direction.

First, install the XCode developer tools.  One way to do this is from
the OSX install disc, in which there is a folder of optional installs
including a package for XCode.

The program requires the free FFTW library to build.  Optionally, it can
also use the libpng, libjpeg, and libtiff libraries to support more image
formats.  These libraries can be obtained on Mac OSX from the Fink project

    http://www.finkproject.org/

Go to the Download -> Quick Start page for instructions on how to get
started with Fink.  The Fink Commander program may then be used to download
and install the packages fftw, libpng, libjpeg, and libtiff.  It may be
necessary to install fftw-dev, libpng-dev, libjpeg-dev, and libtiff-dev as
well.

Once the libraries are installed, compile the program using the included
makefile "makefile.gcc":

    make -f makefile.gcc

This should produce the executables ace and histeq.


== Acknowledgements ==

This material is based upon work supported by the National Science
Foundation under Award No. DMS-1004694.  Any opinions, findings, and
conclusions or recommendations expressed in this material are those of
the author(s) and do not necessarily reflect the views of the National
Science Foundation.