Total Variation Deconvolution using Split Bregman
Pascal Getreuer, getreuer@cmla.ens-cachan.fr, CMLA, ENS Cachan
Version 20130706 (July 6, 2013)

  *** Please cite IPOL article "Total Variation Deconvolution using      ***
  *** Split Bregman" 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 "Total Variation Deconvolution using Split Bregman" at

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

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  


== 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: tvdeconv, imblur, and
imdiff.

    * tvdeconv: runs total variation regularized image deconvolution

    * imblur: blurs and adds noise to an image

    * imdiff: compares two images with various image metrics


--- tvdeconv ---

Usage: tvdeconv [param:value ...] 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).
This program performs TV regularized deconvolution.

Parameters
  K:<kernel>             blur kernel for deconvolution
      K:disk:<radius>         filled disk kernel
      K:gaussian:<sigma>      Gaussian kernel
      K:<file>                read kernel from text or image file
  lambda:<value>         fidelity weight
  noise:<model>          noisy model
      noise:gaussian          additive Gaussian noise (default)
      noise:laplace           Laplace noise
      noise:poisson           Poisson noise
  f:<file>               input file (alternative syntax)
  u:<file>               output file (alternative syntax)
  jpegquality:<number>   quality for saving JPEG images (0 to 100)


--- imblur ---

Usage: imblur [param:value ...] input output

The imblur program blurs and adds noise to an image.

Parameters
  K:<kernel>             blur kernel for deconvolution
      K:disk:<radius>         filled disk kernel
      K:gaussian:<sigma>      Gaussian kernel
      K:<file>                read kernel from text or image file
  noise:<model>:<sigma>  simulate noise with standard deviation sigma
      noise:gaussian:<sigma>  additive white Gaussian noise
      noise:laplace:<sigma>   Laplace noise
      noise:poisson:<sigma>   Poisson noise
  f:<file>               input file (alternative syntax)
  u:<file>               output file (alternative syntax)
  jpegquality:<number>   quality for saving JPEG images (0 to 100)


--- 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 "blurry.bmp".
    ./imblur K:disk:1 noise:gaussian:5 einstein.bmp blurry.bmp

    # Perform TV regularized deconvolution with the split Bregman algorithm
    # on "blurry.bmp" and save the result to "deconv.bmp".
    ./tvdeconv K:disk:1 lambda:50 blurry.bmp deconv.bmp

    # Compare the original to the restored image
    ./imdiff einstein.bmp deconv.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 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 tvdeconv_20130706.tgz
    cd tvdeconv_20130706
    make -f makefile.gcc

This should produce three executables, tvdeconv, imblur, 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/

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 three executables, tvdeconv, imblur, and imdiff.


--- 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 three executables, tvdeconv, imblur, 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

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

    http://www.fftw.org/install/windows.html

Edit LIBFFTW3 lines at the top of makefile.vc to tell where the library files
are installed.

    LIBFFTW3_DIR     = "D:/libs/fftw"
    LIBFFTW3_INCLUDE = -I$(LIBFFTW3_DIR)
    LIBFFTW3_LIB     = $(LIBFFTW3_DIR)/libfftw3-3.lib $(LIBFFTW3_DIR)/libfftw3f-3.lib


--- 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, tvdeconv, imblur, 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


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