***************************************************************************
* All the software  contained in this library  is protected by copyright. *
* Permission  to use, copy, modify, and  distribute this software for any *
* purpose without fee is hereby granted, provided that this entire notice *
* is included  in all copies  of any software which is or includes a copy *
* or modification  of this software  and in all copies  of the supporting *
* documentation for such software.                                        *
***************************************************************************
* THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED *
* WARRANTY. IN NO EVENT, NEITHER  THE AUTHORS, NOR THE PUBLISHER, NOR ANY *
* MEMBER  OF THE EDITORIAL BOARD OF  THE JOURNAL  "NUMERICAL ALGORITHMS", *
* NOR ITS EDITOR-IN-CHIEF, BE  LIABLE FOR ANY ERROR  IN THE SOFTWARE, ANY *
* MISUSE  OF IT  OR ANY DAMAGE ARISING OUT OF ITS USE. THE ENTIRE RISK OF *
* USING THE SOFTWARE LIES WITH THE PARTY DOING SO.                        *
***************************************************************************
* ANY USE  OF THE SOFTWARE  CONSTITUTES  ACCEPTANCE  OF THE TERMS  OF THE *
* ABOVE STATEMENT.                                                        *
***************************************************************************

AUTHORS:

       Germana Landi
       Dipartimento di Matematica
       Universita' di Bologna, Bologna, Italy
       germana.landi@unibo.it

       Elena Loli Piccolomini
       Dipartimento di Matematica
       Universita' di Bologna, Bologna, Italy
       elena.loli@unibo.it

REFERENCE:

       NPTool: a Matlab software for nonnegative image restoration 
       with Newton projection methods
       NUMERICAL ALGORITHMS, 62 (2013), pp. 487-504
       DOI: 10.1007/s11075-012-9602-x.

SOFTWARE REVISION DATE:

       V1.0, April 2012

SOFTWARE LANGUAGE:

       Matlab 7.6

======================================================================
PACKAGE
======================================================================

The directory contains the following files

README         : this file
Contents.m     : Contents file for Matlab
Amult.m        : function for the matrix vector product of the hessian of
                 the objective function
armijo_NCGP.m  : function implementing the Armijo rule in the NCGP method
armijo_NP.m    : function implementing the Armijo rule in the NP method
armijo_QNP.m   : function implementing the Armijo rule in the QNP method
KLTKb_obj.m    : function for the evaluation of the objective function, 
                 its gradient and hessian for deblurring of Poisson 
                 corrupted images with Tikhonov regularization
KLTVb_obj.m    : function for the evaluation of the objective function, 
                 its gradient and hessian for deblurring of Poisson 
                 corrupted images with Total Variation regularization
KLTVn_obj.m    : function for the evaluation of the objective function, 
                 its gradient and hessian for denoising of Poisson 
                 corrupted images with Total Variation regularization
LSTKb_obj.m    : function for the evaluation of the objective function, 
                 its gradient and hessian for deblurring of Gaussian 
                 corrupted images with Tikhonov regularization
LSTVb_obj.m    : function for the evaluation of the objective function, 
                 its gradient and hessian for deblurring of Gaussian 
                 corrupted images with Total Variation regularization
LSTVn_obj.m    : function for the evaluation of the objective function, 
                 its gradient and hessian for denoising of Gaussian 
                 corrupted images with Total Variation regularization
maerror.m      : function computing the Mean Absolute Error between two 
                 images
mserror.m      : function computing the Mean Square Error between two 
                 images
NCGP.m         : function implementing the NCGP method
NP.m           : function implementing the NP method
NPoutput.m     : function printing the results and visualizing the images
PCGsolver.m    : function for the solution of the linear system of NCGP 
                 with the Preconditioned Conjugate Gradients method        
psnratio.m     : function computing the Peak Signal-to-Noise ratio between 
                 two images
QNP.m          : function implementing the QNP method
SetTV.m        : function for setting up the discretization for the 
                 Total Variation function

Examples       : directory with data files and example files.
driver_ncgp.m          : driver for examples of the NCGP method
driver_np_qnp.m        : driver for examples of the NP method
example_deblurKLTIKH.m : example of how to use NCGP for deblurring 
                         Poisson-corrupted images with Tikhonov 
                         regularization
example_deblurKLTV.m   : example of how to use NCGP for deblurring 
                         Poisson-corrupted images with Total Variation 
                         regularization
example_deblurLSTIKH.m : example of how to use NCGP for deblurring 
                         Gaussian-corrupted images with Tikhonov 
                         regularization 
example_deblurLSTV.m   : example of how to use NCGP for deblurring 
                         Gaussian-corrupted images with Total Variation 
                         regularization
example_denoiseKLTV.m  : example of how to use NCGP for denoising 
                         Poisson-corrupted images with Total Variation 
                         regularization
example_denoiseLSTV.m  : example of how to use NCGP for denoising 
                         Gaussian-corrupted images with Total Variation 
                         regularization
example_np.m           : example of how to use NP for deblurring 
                         Gaussian-corrupted images with Tikhonov 
                         regularization
example_qnp.m          : example of how to use QNP for deblurring 
                         Poisson-corrupted images with Total Variation 
                         regularization
brain_lstv.mat         : mat file containing the data (exact image, blurred  
                         noisy image, psf image) for restoring a 256-by-256 
                         brain image corrupted by Gaussian noise
brainpet.mat           : mat file containing the data (exact image, blurred 
                         noisy image, psf image and background value) for 
                         restoring a 256-by-256 PET brain image corrupted 
                         by Poisson noise
dot.mat                : mat file containing the data (exact image and noisy 
                         image) for denoising the 100-by-100 dot image  
                         corrupted by Gaussian noise
galaxy_NGC1288.mat     : mat file containing the data (exact image, blurred 
                         noisy image, psf image and background value) for 
                         restoring a 256-by-256 galaxy image corrupted 
                         by Poisson noise
phantom38.mat          : mat file containing the data (exact image, blurred 
                         and noisy image, psf image and background value) 
                         for restoring a synthetic geometric 400-by-400 image
                         corrupted by Poisson noise
SheppLogan.mat         : mat file containing the data (exact image, blurred 
                         noisy image, psf image and background value) for
                         restoring the 256-by-256 Shepp Logan image corrupted
                         by Poisson noise
test_lstk.m            : mat file containing the data (exact image, blurred 
                         noisy image and psf image) for restoring the
                         256-by-256 cameraman image corrupted by Gaussian 
                         noise
startup.m              : startup file for adding the path of the toolbox

======================================================================
HOW TO INSTALL
======================================================================

Unpack the archive file. The directory NPTool will be created with all
the needed files inside and a subdirectory Examples with the examples, 
driver  and startup files.
Add the directory NPTool with all its subdirectories to the path in
Matlab/Octave or launch startup.m.

======================================================================
TEST
======================================================================

To test the software there are some drivers or examples script files 
(in the Examples directory).
You can launch them from the Matlab prompt and compare their results 
with those reposrted in the article. The numerical results should change
at most for the last decimal digits.

