Rudin-Osher-Fatemi Total Variation Denoising using Split Bregman
Pascal Getreuer, pascal.getreuer@yale.edu, Yale University
Version 20120516 (May 16, 2012)

== Overview ==

This C source code accompanies with Image Processing On Line (IPOL) article
"Rudin-Osher-Fatemi Total Variation Denoising using Split Bregman" at 

    http://www.ipol.im/pub/algo/g_tv_denoising/

This code is used by the online IPOL demo:

    http://www.ipol.im/pub/demo/g_tv_denoising/

Future software releases and updates will be posted at 

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


== License (BSD) ==

Files randmt.c and randmt.h are copyright Makoto Matsumoto, Takuji Nishimura, 
Seiji Nishimura, Nicolas Limare, and Pascal Getreuer and are distributed under
the BSD license conditions described in the headers of those files.

File einstein.bmp is a standard test image.

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 three command line programs: tvdenoise, imnoise, and
imdiff.

    * tvdenoise: runs total variation regularized image denoising 

    * imnoise: simulates Gaussian, Laplace, or Poisson noise on an image

    * imdiff: compares two images with various image metrics


--- tvdenoise ---

Usage: tvdenoise <model>:<sigma> <noisy> <denoised>

where <noisy> and <denoised> are BMP (JPEG, PNG, or TIFF files can also be 
used if the program is compiled with libjpeg, libpng, and/or libtiff).
The program reads image <noisy> and applies TV regularized denoising to 
produce <denoised>.

The <model> argument denotes the noise model.  The parameter <sigma>
is the noise level, which is defined to be the square root of the
expected mean squared error.

The pixel intensities are denoted below by X[n] and Y[n], and they
are scaled as values between 0 and 255.  Values of Y[n] outside of
this range are saturated.

  gaussian:<sigma>  Additive white Gaussian noise
                    Y[n] ~ Normal(X[n], sigma^2)
                    p(Y[n]|X[n]) = exp( -|Y[n] - X[n]|^2/(2 sigma^2) )

  laplace:<sigma>   Laplace noise
                    Y[n] ~ Laplace(X[n], sigma/sqrt(2))
                    p(Y[n]|X[n]) = exp( -|Y[n] - X[n]| sqrt(2)/sigma )

  poisson:<sigma>   Poisson noise
                    Y[n] ~ Poisson(X[n]/a) a
                    where a = 255 sigma^2 / (mean value of X)


--- imnoise ---

Syntax: imnoise <model>:<sigma> <input> <output>

The program reads the image <input> and simulates noise to create <output>.
The <model>:<sigma> argument has the same meaning as in tvdenoise.


--- imdiff ---

Usage: imdiff [options] <exact file> <distorted file>

The imdiff program compares two images with various image metrics.

Options:
   -m <metric>  Metric to use for comparison, choices are
        max     Maximum absolute difference, max_n |A_n - B_n|
        mse     Mean squared error, 1/N sum |A_n - B_n|^2
        rmse    Root mean squared error, (MSE)^1/2
        psnr    Peak signal-to-noise ratio, -10 log10(MSE/255^2)
        mssim   Mean structural similarity index

   -s           Compute metric separately for each channel
   -p <pad>     Remove a margin of <pad> pixels before comparison
   -D <number>  D parameter for difference image

Alternatively, a difference image is generated by the syntax
   imdiff [-D <number>] <exact file> <distorted file> <output file>

The difference image is computed as
   D_n = 255/2 ((A_n - B_n)/D + 1).
Values outside of the range [0,255] are saturated.


Example:

    # Generate Gaussian noise with standard deviation 15 on "einstein.bmp"
    # and save the result to "noisy.bmp".
    ./imnoise gaussian:15 einstein.bmp noisy.bmp

    # Perform TV regularized denoising with the split Bregman algorithm on 
    # "noisy.bmp" and save the result to "denoised.bmp".
    ./tvdenoise -n gaussian:15 noisy.bmp denoised.bmp

    # Compare the original to the denoised image
    ./imdiff einstein.bmp denoised.bmp

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 (Linux) ==

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

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

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

This should produce three executables, tvdenoise, imnoise, and imdiff.

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

    make -f makefile.gcc srcdoc


== Compiling (Windows with MinGW+MSYS) ==

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/


--- Building with BMP only ---

The simplest way to build the tvdenoise programs is with support for only BMP
images. In this case, no external libraries are 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 three executables, tvdenoise, imnoise, and imdiff.


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

To use the tvdenoise 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 tvdenoise programs with the 
makefile.gcc included in this archive.

    make CC=gcc -f makefile.gcc

This should produce three executables, tvdenoise, imnoise, and imdiff.


== Compiling (Windows with MSVC) ==

The express version of the Microsoft Visual C++ (MSVC) compiler can be 
obtained for free at

    http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express


--- Building with BMP only ---

For simplicity, the makefile will build the programs with only BMP image 
support by default.  Open a Visual Studio Command Prompt (under Start Menu > 
Programs > Microsoft Visual Studio > Visual Studio Tools > Visual Studio 
Command Prompt), navigate to the folder containing the sources, and enter

    nmake -f makefile.vc all

This should produce three executables, tvdenoise, imnoise, and imdiff.


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

To include support for PNG and/or JPEG images, the libpng and libjpeg 
libraries are needed.  Edit the LIB lines at the top of makefile.vc to
tell where each library is installed, e.g.,

    LIBJPEG_DIR     = "C:/libs/jpeg-8b"
    LIBJPEG_INCLUDE = -I$(LIBJPEG_DIR)
    LIBJPEG_LIB     = $(LIBJPEG_DIR)/libjpeg.lib

Then compile using

    nmake -f makefile.vc all


== Code Overview ==

An overview description of the C source code is included in the file 
code_overview.txt.  Detailed documentation of the source code is available
online at

   http://www.ipol.im/pub/algo/g_tv_denoising/doc/index.html

Altenatively, the documentation can be generated using Doxygen with the
command "make -f makefile.gcc srcdoc".


== 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.