/****** Matrix Source Coding C code ******/
/****** Developed by Jianing Wei *****/
/****** Contact: weijianing@gmail.com ****/
/****** This work was Jianing's Ph.D. work at Purdue ***/
/* Citation of corresponding publications is much appreciated. */
/* Jianing Wei, Charles Bouman, and Jan Allebach,
   Fast space-varying convolution using matrix source coding, 
   submitted to IEEE Transactions on Image Processing in April 2013 */
/* Jianing Wei, Guangzhi Cao, Charles Bouman, and Jan Allebach,
   Fast space-varying convolution and its application in stray 
   light reduction, Proceedings of SPIE/IS&T Conf. on Computational 
   Imaging VII, January, 2009. */

/******************* Disclaimer ************************/
GNU general public license is applicable to this software. 
Please note the following:
1. The code/software is provided as it is. No technical 
support/customer support is provided.
2. Please use the software at your own risk. We are not 
responsible for any damages or risks.
3. This software is for academic research purpose only. 
If you are interested in the commercial use, please contact 
Jianing Wei at weijianing@gmail.com. 
Use or copying without permission is prohibited.

/*******************    Usage    **********************/
This software contains both offline and online part of 
the matrix source coding algorithm.
 
1. Offline matrix source coding
a) Go to folder ./main/offline/, and type "make".
b) Prepare a parameter file as input to the program. 
   A sample parameter file "parameter_set1_256x256_delta_0.2.txt" 
   is provided. In this parameter file, you will specify PSF 
   parameters, scaling factors file, circle size file, and 
   output coded matrix file. Sample scaling factors file and 
   circle size file are provided in ./main/offline/prediction/.
c) Run the program: ./MatrixCoding yourparameterfile.txt
d) You should have a coded matrix file after the program finished 
   running. This is an offline process and it can take very long. 
   A 256x256 image resolution can take a couple of hours to run. 

2. Online space-varying convolution
a) Go to folder ./main/online/, and type "make"
b) Run the program: ./OnlineConv img.pgm mscmatrix.dat scaling_factors.txt
   img.pgm -- input image
   mscmatrix.dat -- the coded matrix you obtained in the offline part.
   scaling_factors.txt -- your scaling factors file used in the offline part.
c) Now you should have an output file named "output.txt" and obtain the NRMSE error. 
   Note that since this code computes the NRMSE error, it will compute the rigorous 
   space-varying convolution as ground-truth. It won't be fast. You may easily modify 
   the code if you don't need the NRMSE error to skip the ground-truth computation.
d) If you want a matlab interface, please go to folder ./main/online/stray_reduction/. 
   You can compile the mex code using file "compile_online.m", then you can enjoy 
   the convinience of mex code "mx_online_main_space_varying.*". This mex code 
   will perform fast space-varying convolution inside matlab using the coded 
   matrix you computed in the offline part. In addition, it won't compute ground-truth 
   if only one lefthand side argument is provided. So it is fast!
   Usage of mex function:
     stray_img = mx_online_main_space_varying(img, coded_matrix, scaling_factors);
     img -- your input image, which is a matlab matrix (double type)
     coded_matrix -- your coded matrix file name, which is a matlab string
     scaling_factors -- your scaling factors file name, which is a matlab string
     stray_img -- your output image

I'm sorry for the not so clean code. But I hope you enjoy it! If you find 
any bug, please let me know. Thanks!

Jianing
May 4, 2013
