SURE Guided Piecewise Linear Image Denoising Algorithm
WANG Yi-Qing, yiqing.wang@polytechnique.edu, ENS Cachan


List of Source Files
====================

This source code creates five command line programs. 

SPLE_denoise.cpp	Command line program that performs S-PLE denoising
PLE_denoise.cpp  	Command line program that performs PLE denoising
imsample.cpp		Command line program that performs image sampling
imnoise.c     		Command line program that adds pseudorandom noise to an image
imdiff.c        	Command line program that compares two images

SPLE_lib.{cpp,h}	Implements SPLE_main_routine() the main routine for S-PLE 
PLE_lib.{cpp,h}  	Implements PLE_main_routine() the main routine for PLE 
util.{cpp,h}   	  	Implements general utilities such as image from/to patches conversion
DataProvider.{cpp,h}  	Implements a class for storing the initial Gaussian factor mixture 

randmt.{c,h}    	Mersenne Twister MT19937 pseudorandom number generator
imageio.{c,h}   	Image input and output for BMP, JPEG, PNG, and TIFF formats
conv.{c,h}      	Finite impulse response convolutions (used by imdiff.c)
basic.{c,h}     	Basic definitions and utilities used by all programs
io_png.{c.h}		Image input and output for PNG 
connected.h           	One version of connected component algorithm


S-PLE Denoising
================

The highlight of this source code is the implementation of a two-stage version 
of Expectation Maximization (EM) Gaussian factor parametrical inference algorithm.
This is an outline of how the denoising is performed in the SPLE_lib.cpp code:


SPLE_main_routine(), SPLE_lib.cpp:1020      (Program begins here)

    The input image is read with imread().

    Noise is added with add_gaussian_noise().

    SPLE_sub_routine() is called to perform the denoising.

    The denoised image is written with imwrite().



SPLE_sub_routine(), SPLE_lib.cpp:1074

    RGB_transform() is called to perform chrominance-luminance transform 
    to raise the signal-to-noise (SNR) in the first transformed channel.

    The program operates under two modes: Testing_Mode will enable
    far more intermediary outputs to allow testing and analysis. 
    Demo_Mode, on the other hand, minimizes computational cost so that 
    the program runs as fast as possible.

    read_config() is called to set up the Gaussian factor mixture. 

    The main loop for the EM iteration is on lines 1146:1222:

	calc_responsibilities()	computes for each (patch, model) pair the 
	conditional probability for a patch being generated by a model,
	thereby creating the patch map required for adaptive filter selection.

	update_PPCA() is called to update the Gaussian factor mixture.

	In Testing_Mode, patches will be filtered with filter_patches()
	at every EM iteration. Otherwise, this method is called only once at 
	the last iteration. 
	
	both_filters is a flag that lets filter_patches() process all the
	noisy patches with both Wiener and shrinkage filters. This is an option 
	that tends to yield the best denoising performance because the algorithm 
	can then decide between these two after having seen their SURE estimates.

	diffusion_deoise() is called to expand flat patches for more aggressive
	denoising in the flat areas of an image.
	 
     Clean up.



Image Sampling
================

This source code implements image sampling using tensor structure orientation detector 
To run it, first you need to provide a directory containing grayscale PNG format files
through a bash script named getPaths.sh. You can run

	./getPaths.sh

to get instructions on how to use this script. This is an outline of how image sampling
is performed: 

sample_images(), util.cpp:432

	read in list.txt (created by getPaths.sh) containing a list of paths to the 
	grayscale PNG images to sample from

	randomly pick a patch from a randomly chosen image and call tensorStructure() 
	to determine the model it belongs to. Iterate until the algorithm gets enough
	sample patches for all models

	compute the second order statistics as well as mixing weights. write_out_everything()
	is called to produce a file named by the user. (Caveat: you should save a copy of
	DataProvider.cpp and rename this newly obtained file to DataProvider.cpp in order to
	run S-PLE with it. See the section on imsample in README.txt for details.)