% S-PLE and PLE image denoising.

# BUGFIX

07/11/2013: fix a bug in code operating under the demo mode
            (SPLE_lib.cpp, lines 1201-1202) 

# ABOUT

* Author    : Yi-Qing WANG <yiqing.wang@polytechnique.edu>
* Copyright : (C) 2012 Yi-Qing WANG 
* Licence   : GPL v3+, see GPLv3.txt

# OVERVIEW

This source code provides an implementation of the S-PLE and PLE image denoising.

# License (BSD)

Files randmt.{c,h}, io_png.{c,h}, basic.{c,h}, conv.{c,h}, imageio.{c,h}, imdiff.c, 
imnoise.c 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.

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 five command line programs: denoiseSPLE, denoisePLE, 
imnoise, and imdiff.

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

    * imdiff: compares two images with various image metrics
    
    * imsample: samples images to form a Gaussian mixture 

    * denoiseSPLE: runs S-PLE image denoising 
    
    * denoisePLE: runs PLE image denoising 


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

Syntax: 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.

--- imsample ---

Syntax: imsample [options]

[options] allows to choose <flat_threshold> <orient_threshold> <minimal_num_samples>
and <data_file>. Note that <data_file> cannot be DataProvider.cpp for safety reasons.
Yet you need to rename <data_file>, once created, to DataProvider.cpp in order to
use it in S-PLE.

The recommanded steps: 

1. create a file, e.g. path2MyImages and put in it the absolute path to the directory 
   from which the sampling will be carried out.

2. run the bash script getPaths.sh 

	./getPaths.sh $(cat path2MyImages)

   to create a file containing sample image paths.

3. simply run 

	./imsample
	
    or

	./imsample --help	 
 
    to get instructions on how you can parametrize the executation

4. rename DataProvider.cpp 
 
	mv DataProvider.cpp DataProvider.cpp.copy

   and <new_cpp>, which is dataCXX.cpp by default or any name you give to imsample 

	mv <new_cpp> DataProvider.cpp

5. compile again

	make

   or

	make OMP=1
  
   if your system supports OpenMP.
	

--- denoiseSPLE ---

Syntax: denoiseSPLE <input> <sigma> <iteration number> <output> [options]

The program reads the image <input>, adds noise with <sigma> and runs S-PLE 
<iteration number> times to create <output>. [options] allows to choose 
between Testing_Mode and Demo_Mode. If this field is left unspecified, the 
program defaults to Demo_Mode. 


--- denoisePLE ---

Syntax: denoisePLE <input> <sigma> <iteration number> <output> 

The program reads the image <input>, adds noise with <sigma> and runs PLE 
<iteration number> times to create <output>. 

Each of these programs prints detailed usage information when executed 
without arguments.

# UNIX/LINUX/MAC USER GUIDE

The code is compilable on Unix/Linux and Mac OS. 

- Compilation.
 
Automated compilation requires the make program.

- Library.
 
This code requires libpng, eigen (v.3) and newmat (v.10). The compressed file comes
with a copy of the latter two libraries.

- Image format.
 
Only the PNG format is supported. 
 
- Usage.

1. Download the code package and extract it. Go to that directory. 

2. Compile the source code (on Unix/Linux/Mac OS). If OpenMP (http://openmp.org/)
is supported, run

	make OMP=1

Otherwise, run 

	make

# Code Overview

An overview description of the source code is included in the file 
code_overview.txt. 

Altenatively, the documentation can be generated using Doxygen with the
command "make srcdoc".

# ABOUT THIS FILE

Copyright 2012 Yi-Qing WANG 

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without any warranty.