=====================================================
MeTriX MuX Visual Quality Assessment Package README (v. 1.1)      Version 1.1 has been released! To read more about this version, click here.
=====================================================

1. Introduction: WHAT MeTriX MuX is, and WHO should use it.

2. Installation: HOW to obtain and configure MeTriX MuX.

3. Instructions: HOW to use MeTriX MuX.

4. Organization: HOW the files in the package are structured.

5. Modification: WHAT has been done to code written by other researchers.

6. Information: WHERE users can learn more about visual quality assessment algorithms.

7. Invitation: WHERE to send comments or feedback, which is encouraged!

8. Modernization: WHICH bugs have been fixed, and what features have been added (versioning information).


===============
1. INTRODUCTION
===============

MeTriX MuX is a Matlab package that implements wrapper code for a variety of visual quality assessment algorithms. A visual quality assessment algorithm is a function that assesses the difference between an original image and a distorted version of the image. The algorithms involved in this package, for the most part, were designed to operate on two images of the same size. If the images are not the same size, then the algorithms included herein do not necessarily apply.

Please notice that the quality assessment algorithms included in this package are the product of the devout research and hard work of many different researchers. The authors of this particular package are not in any way trying to take credit for any of the algorithms. In fact, many of these hard working researchers have made code available that computes the respective quality assessment algorithms, for which the authors are extremely grateful. As a result, almost all of the quality assessment code that appears in this package in its original form.

The only contribution of this package, if anything, is wrapper code. The intent of the authors is to make a large number of quality assessment algorithms accessible through a common interface, and to facilitate error condition checks such that it should be possible to apply any quality assessment algorithm with any pair of images. Back when Ezra Cornell was working on image quality assessment, he dropped this gem, which has become our M.O.:

"I would create a Matlab-based image quality assessment package such that any two images can be compared with any quality assessment algorithm on any platform [running Matlab R14 or higher]."

Who should use MeTriX MuX? If you are already quite skilled in the art, and have formed opinions regarding what algorithms are useful for what tasks, perhaps this package is not of interest. On the other hand, if you are curious about how a visual quality assessment algorithm might be applied to a particular problem, and you would like to throw a handful of approaches at the problem with minimal effort, then MeTriX MuX is for you!


===============
2. INSTALLATION
===============

1. Download http://foulard.ece.cornell.edu/gaubatz/metrix_mux/metrix_mux_1.1.zip.
2. Extract the contents of this file to your hard drive.
3. Obtain a copy of Matlab R14 or higher.
4. Start Matlab, and set your directory to the newly extracted 'metrix_mux' folder.
5. Run the configure_metrix_mux script. That is, at the prompt, type

>> configure_metrix_mux

Presumably, if you are reading this file, you have at least completed steps 1 and 2 successfully. All the configuration script does is update the Matlab path and run some MEX-file building routines. If the configure_metrix_mux routine completes successfully, the package should "just work". Earlier versions of Matlab may be supported eventually, and some may even work now, but this release of the package is only geared towards Matlab releases 14 and up.


===============
3. INSTRUCTIONS
===============

1. Read an image into Matlab.
2. Read a distorted version of that image into Matlab.
3. Call the metrix_mux function, with the original image as the first argument, the distorted image as the second argument, and a descriptor representing which algorithm to use to compare them for the third argument.


The following snippet of code illustrates how, for example, the package should be used to compare 'lena.png' with a distorted version of the same image, 'lena_messed_up.png', using structural similarity index to measure the difference between the two.

>> reference_image = double( imread('lena.png') );
>> distorted_image = double( imread('lena_messed_up.png') );
>> distorted_ssim_index = metrix_mux( reference_image, distorted_image, 'SSIM' );

IMPORTANT NOTE: This package expects that input image data is scaled as it would be in a typical image file, that is, that the digital values of the pixels fall in the range [0,255]. If the input images are not of the class double, they will be converted to that class before the assessment algorithm is applied. Bounds checking is not performed by this package to avoid accessing each pixel before applying an assessment algorithm.

The algorithms currently supported by this package, and their associated indicators, are listed in the table below:

algorithm      indicator string
mean-squared-error      'MSE'
peak signal-to-noise-ratio      'PSNR'
structural similarity index      'SSIM'
multi-scale SSIM index      'MSSIM'
visual signal-to-noise ratio      'VSNR'
visual information fidelity      'VIF'
pixel-based VIF      'VIFP'
universal quality index      'UQI'
information fidelity criterion      'IFC'
noise quality measure      'NQM'
weighted signal-to-noise ratio      'WSNR'
signal-to-noise ratio      'SNR'


There is an "advanced" mode of use that is as follows. Some of the algorithms require an image to be a certain size in order to function properly. Normally, the package performs this preprocessing automatically, but if you are inclined to use the same image for several different comparisons, you can call the preprocessing routine, preprocess_metrix_mux, explicitly to prevent the preprocessing routine from doing the same operation multiple times for the same image:

>> reference_image = imread('lena.png') );
>> reference_image = preprocess_metrix_mux( reference_image );
>> distorted_image = imread('lena_messed_up.png');
>> distorted_image = preprocess_metrix_mux( distorted_image );
>>
>> distorted_ssim_index = metrix_mux( reference_image, distorted_image, 'SSIM' );
>> distorted_psnr = metrix_mux( reference_image, distorted_image, 'PSNR' );
>>
>> really_distorted_image = imread('lena_really_messed_up.png');
>> really_distorted_ssim_index = metrix_mux( reference_image, really_distorted_image, 'SSIM' );

In this case, since the "really" distorted image is only used during one comparison, there is nothing gained by manually calling the preprocessing routine, so it is not called. Also, each image is converted to the double class by the preprocess_metrix_mux routine. In the previous example above, this conversion was not necessary. This preprocessing routine is applied to each image that is passed to the metrix_mux function. If no further preprocessing is required, however, this routine has no effect.

ANOTHER IMPORTANT NOTE: Please be very aware of what the preprocessing function does, even if you do not intend to call it explicitly. If 'IFC','VIF','VSNR' or 'WSNR' are to be applied, the image is symmetrically extended in both dimensions until each dimension is a multiple of 32 and is at least 128. If the image is a color image, regardless of algorithm is to be applied, the image is converted to a grayscale representation. (Future releases may support color images, but the present version does not.)


===============
4. ORGANIZATION
===============

The files included in this package are organized into the following structure. Folder are indicated with '+' signs, and files are denoted with '-' signs. The '.' characters represent files or folders that are not named (for space).

+ MeTriX MuX [base directory]

     - metrix_mux.m [the main gateway to quality assessment algorithms]
     - preprocess_metrix_mux.m [preprocessing routine, called by metrix_mux]
     - configure_metrix_mux.m [installation script]
     - test_metrix_mux.m [test script, called by the installation script]
     - readme.html [an HTML-based overview of this package]

+ metrix [algorithm-specific wrapper files]

     - metrix_mse.m [mean-squared-error wrapper]
     - metrix_ssim.m [structural similarity wrapper]
     - metrix_vsnr.m [visual signal-to-noise-ratio wrapper]
     - compile_metrix_vsnr.m [VSNR MEX hook builder]
     .
     .
     .
     + ssim [folder with designer-written SSIM index computation code]
     + vsnr [folder with designer-written VSNR computation code]
     .
     .
     .

+ utilities [non-algorithm-specific routines]

     + matlabPyrTools [a Matlab steerable pyramid package]
     + dwt2d [two-dimensional discrete wavelet transform Matlab code]



The main folder contains 5 files: an installation script, a test routine, a preprocessing command, an algorithm computation command, and an .html instructions file. Every user will need to run the installation script, configure_metrix_mux, once and will access algorithm computation routines through metrix_mux. The metrix_mux routine will call the preprocessing routine, which will modify the input images to allow the assessment algorithms to be applied, if necessary. The test routine is called by the installation script to test that the installed package actually works.

Code in the 'metrix' folder contains wrappers for each individual algorithm, as well as custom build routines for compiling any non-Matlab code (non-.m file routines, such as MEX interfaces).

Each algorithm wrapper is in a file titled 'metrix_' followed by the name of the algorithm. (While this choice may seem redundant and somewhat unnecessary, it results in much cleaner code than a single file with a giant ugly switch statement.) In the same way, each custom build routine is called 'compile_metrix_', followed by the name of the algorithm. The 'metrix_' functions are called from the metrix_mux command, and the 'compile_metrix_' functions are called from the configure_metrix_mux command. The subfolders within this folder contain designer-created algorithm computation routines, specific to the algorithm denoted by the name of the subfolder. The subfolders of the 'utilities' folder contains code to compute transforms that is called by several of the assessment algorithms.

YET ANOTHER IMPORTANT NOTE: Code that implements a steerable pyramid decomposition is needed by several of the algorithms included in this package. As a result, the matlabPyrTools package has been included in entirety expressly for this purpose. To learn more about the steerable pyramid decomposition, click here. This decomposition contains several computationally intensive steps. Furthermore, there are in existence a variety of optimizations that speed some of these steps up. If you are one of the intrepid researchers who has established a fully-functioning optimized version of the matlabPyrTools package, by all means, use that version instead of the one included in this package! If it works really well, why not share it?


===============
5. MODIFICATION
===============

Some algorithms have been modified to create a more portable package, but all code provided by image quality assessment algorithm designers has been retained in its original form. If the package uses a modified version of a file created by a different author, the suffix _modified is attached the file name. Furthermore, all comments added by the author of the MeTriX MuX package appear in these particular files as %%%MM%%%, to make the nature of the modifications as clear as possible. Modified files are always placed in the same folders as the originals.


==============
6. INFORMATION
==============

Again, the author did not design any of the algorithms included in this package, but only has provided wrapper code such that a variety of algorithms can be easily accessed through a common interface. This package is available at the following website:

http://foulard.ece.cornell.edu/gaubatz/metrix_mux/

This package uses each included quality assessment algorithm with default settings for input parameters. Interested users are strongly encouraged to read the documentation associated with individual quality assessment algorithms in order to gain a better understanding of how to use the algorithms.

More information for the included algorithms and/or original code can be found at the following websites:

algorithmwebsite
mean-squared-error (MSE)    http://foulard.ece.cornell.edu/gaubatz/metrix_mux/MSE.html
peak signal-to-noise ratio (PSNR)    [see above]
signal-to-noise ratio (SNR)    [see above]
    
structural similarity (SSIM) index    http://www.ece.uwaterloo.ca/~z70wang/research/ssim/
multi-scale SSIM index    [see above]
    
visual signal-to-noise ratio (VSNR)    http://foulard.ece.cornell.edu/dmc27/vsnr/vsnr.html
    
visual information fidelity (VIF)    http://live.ece.utexas.edu/research/quality/
pixel-based VIF    [see above]
information fidelity criterion (IFC)    [see above]
    
universal quality index (UQI)    http://www.cns.nyu.edu/~zwang/files/research/quality_index/demo.html
    
noise quality measure (NQM)    http://signal.ece.utexas.edu/software/
weighted signal-to-noise ratio (WSNR)    [see above]


=============
7. INVITATION
=============
The goal of this package is to provide convenient, portable, efficient access to image quality assessment algorithms in Matlab. This goal has not yet been achieved in full, but progress has been made. Initial focus is on portability, and later releases will involved optimizations.

Please send all comments, questions, suggestions of feedback (especially if you would like to contribute) to

Thanks!

================
8. MODERNIZATION
================
This section is dedicated to explanations regarding new releases, the latest features, bug fixes, as well as access to previous versions of MeTriX MuX.

MeTriX MuX Version 1.1 represents the latest release, with some bug fixes and additional features. Here's what's new in version 1.1:

  • modified code has been added such that NQM and WSNR functions work with non-square images
  • the standard signal-to-noise-ratio (SNR) ratio is now included
  • bug fix: the default angle in metrix_nqm.m is now computed in degrees (instead of radians)
  • bug fix: metrix_wsnr.m calls code to compute WSNR (instead of IFC)
  • bug fix: metrix_mux.m handles numerical indicator strings without causing an error


    • Special thanks the Daniele Ticca and David Rouse for their input!

    Download older versions here:

    MeTriX MuX Version 1.0

    =============================
    EXPLANATION and DISCLAMATION
    =============================
    It should be noted that the name of the package implies that it acts as multiplexor for image quality metrics, which strictly speaking, are not the same things as quality assessment algorithms. The authors realize that it is not necessarily appropriate to refer to a given quality assessment algorithm as a "metric", since in the mathematical sense, it may not be one. They feel, however, that the notational convenience of referring to a quality assessment tool colloquially, if not incorrectly, as a "metric" outweighs the chore of using one the multi-syllabic alternatives. To remind users that the package does not in fact act as a wrapper for quality metrics, the word "metric" is transmogrified into the form "metrix". Also, according to a limited set of test users, the title "metrix_mux" was more memorable than the technically more correct yet loquacious alternative, "perceptual_quality_assessment_algorithm_mux".

    The wrapper code included in this package is provided as is without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The author(s) shall in no event be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages.