Added the "Similarity check (PNSR and SSIM) on the GPU" tutorial. Corrected an highgui TOC tree mistake.

doc/conf.py

@@ -357,21 +357,26 @@ extlinks = {'cvt_color': ('http://opencv.willowgarage.com/documentation/cpp/imgp
             'svms':('http://opencv.itseez.com/modules/ml/doc/support_vector_machines.html#%s', None),
             'xmlymlpers':('http://opencv.itseez.com/modules/core/doc/xml_yaml_persistence.html#%s', None),
 			'huivideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None),
-            'filtering':('http://opencv.itseez.com/modules/imgproc/doc/filtering.html#%s', None),
+			'gpuinit' : ('http://opencv.itseez.com/modules/gpu/doc/initalization_and_information.html#%s', None),
+			'gpudatastructure' : ('http://opencv.itseez.com/modules/gpu/doc/data_structures.html#%s', None),
+			'gpuopmatrices' : ('http://opencv.itseez.com/modules/gpu/doc/operations_on_matrices.html#%s', None),
+			'gpuperelement' : ('http://opencv.itseez.com/modules/gpu/doc/per_element_operations.html#%s', None),
+			'gpuimgproc' : ('http://opencv.itseez.com/modules/gpu/doc/image_processing.html#%s', None),
+			'gpumatrixreduct' : ('http://opencv.itseez.com/modules/gpu/doc/matrix_reductions.html#%s', None),'filtering':('http://opencv.itseez.com/modules/imgproc/doc/filtering.html#%s', None),
             'point_polygon_test' : ('http://opencv.willowgarage.com/documentation/cpp/imgproc_structural_analysis_and_shape_descriptors.html#cv-pointpolygontest%s', None),
             'feature_detector' : ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_feature_detectors.html#featuredetector%s', None),
-	    'feature_detector_detect' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_feature_detectors.html#cv-featuredetector-detect%s', None ),
+	        'feature_detector_detect' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_feature_detectors.html#cv-featuredetector-detect%s', None ),
-	    'surf_feature_detector' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_feature_detectors.html#surffeaturedetector%s', None ),
+	        'surf_feature_detector' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_feature_detectors.html#surffeaturedetector%s', None ),
-	    'draw_keypoints' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_drawing_function_of_keypoints_and_matches.html#cv-drawkeypoints%s', None ),
+	        'draw_keypoints' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_drawing_function_of_keypoints_and_matches.html#cv-drawkeypoints%s', None ),
-	    'descriptor_extractor': ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_extractors.html#descriptorextractor%s', None ),
+	        'descriptor_extractor': ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_extractors.html#descriptorextractor%s', None ),
-	    'descriptor_extractor_compute' : ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_extractors.html#cv-descriptorextractor-compute%s', None ),
+	        'descriptor_extractor_compute' : ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_extractors.html#cv-descriptorextractor-compute%s', None ),
-	    'surf_descriptor_extractor' : ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_extractors.html#surfdescriptorextractor%s', None ),
+	        'surf_descriptor_extractor' : ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_extractors.html#surfdescriptorextractor%s', None ),
-	    'draw_matches' : ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_drawing_function_of_keypoints_and_matches.html#cv-drawmatches%s', None ),
+	        'draw_matches' : ( 'http://opencv.willowgarage.com/documentation/cpp/features2d_drawing_function_of_keypoints_and_matches.html#cv-drawmatches%s', None ),
-	    'find_homography' : ('http://opencv.willowgarage.com/documentation/cpp/calib3d_camera_calibration_and_3d_reconstruction.html?#findHomography%s', None),
+	        'find_homography' : ('http://opencv.willowgarage.com/documentation/cpp/calib3d_camera_calibration_and_3d_reconstruction.html?#findHomography%s', None),
-	    'perspective_transform' : ('http://opencv.willowgarage.com/documentation/cpp/core_operations_on_arrays.html?#perspectiveTransform%s', None ),
+	        'perspective_transform' : ('http://opencv.willowgarage.com/documentation/cpp/core_operations_on_arrays.html?#perspectiveTransform%s', None ),
-	    'flann_based_matcher' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_matchers.html?#FlannBasedMatcher%s', None),
+	        'flann_based_matcher' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_matchers.html?#FlannBasedMatcher%s', None),
-	    'brute_force_matcher' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_matchers.html?#BruteForceMatcher%s', None ),
+	        'brute_force_matcher' : ('http://opencv.willowgarage.com/documentation/cpp/features2d_common_interfaces_of_descriptor_matchers.html?#BruteForceMatcher%s', None ),
-	    'flann' : ('http://opencv.willowgarage.com/documentation/cpp/flann_fast_approximate_nearest_neighbor_search.html?%s', None )			 		 
+	        'flann' : ('http://opencv.willowgarage.com/documentation/cpp/flann_fast_approximate_nearest_neighbor_search.html?%s', None )			 		 
            }
 
 

doc/tutorials/gpu/table_of_content_gpu/table_of_content_gpu.rst

@@ -1,12 +1,36 @@
 .. _Table-Of-Content-GPU:
 
 *gpu* module. GPU-Accelerated Computer Vision
------------------------------------------------------------
+---------------------------------------------
 
 Squeeze out every little computation power from your system by using the power of your video card to run the OpenCV algorithms.
 
-.. include:: ../../definitions/noContent.rst
+.. include:: ../../definitions/tocDefinitions.rst
+
++ 
+  .. tabularcolumns:: m{100pt} m{300pt}
+  .. cssclass:: toctableopencv
+
+  =============== ======================================================
+  |hVideoWrite|   *Title:* :ref:`gpuBasicsSimilarity`
+
+                  *Compatibility:* > OpenCV 2.0
+
+                  *Author:* |Author_BernatG|
+
+                  This will give a good grasp on how to approach coding on the GPU module, once you already know how to handle the other modules. As a test case it will port the similarity methods from the tutorial :ref:`videoInputPSNRMSSIM` to the GPU. 
+
+  =============== ======================================================
+
+  .. |hVideoWrite| image:: images/gpu-basics-similarity.png
+                   :height: 90pt
+                   :width:  90pt
 
 .. raw:: latex
 
    \pagebreak
+
+.. toctree::
+   :hidden:
+
+   ../gpu-basics-similarity/gpu-basics-similarity

doc/tutorials/highgui/table_of_content_highgui/table_of_content_highgui.rst

@@ -1,7 +1,7 @@
 .. _Table-Of-Content-HighGui:
 
 *highgui* module. High Level GUI and Media
------------------------------------------------------------
+------------------------------------------
 
 This section contains valuable tutorials about how to read/save your image/video files and how to use the built-in graphical user interface of the library. 
 
@@ -74,3 +74,4 @@ This section contains valuable tutorials about how to read/save your image/video
 
    ../trackbar/trackbar
    ../video-input-psnr-ssim/video-input-psnr-ssim
+   ../video-write/video-write

samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp

@@ -0,0 +1,352 @@
+#include <iostream>                   // Console I/O
+#include <sstream>                    // String to number conversion
+
+#include <opencv2/core/core.hpp>      // Basic OpenCV structures
+#include <opencv2/imgproc/imgproc.hpp>// Image processing methods for the CPU
+#include <opencv2/highgui/highgui.hpp>// Read images
+#include <opencv2/gpu/gpu.hpp>        // GPU structures and methods
+
+using namespace std;
+using namespace cv;
+
+double getPSNR(const Mat& I1, const Mat& I2);      // CPU versions
+Scalar getMSSIM( const Mat& I1, const Mat& I2);
+
+double getPSNR_GPU(const Mat& I1, const Mat& I2);  // Basic GPU versions
+Scalar getMSSIM_GPU( const Mat& I1, const Mat& I2);
+
+struct BufferPSNR                                     // Optimized GPU versions
+{   // Data allocations are very expensive on GPU. Use a buffer to solve: allocate once reuse later.
+    gpu::GpuMat gI1, gI2, gs, t1,t2;
+
+    gpu::GpuMat buf;
+};
+double getPSNR_GPU_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b);
+
+struct BufferMSSIM                                     // Optimized GPU versions
+{   // Data allocations are very expensive on GPU. Use a buffer to solve: allocate once reuse later.
+    gpu::GpuMat gI1, gI2, gs, t1,t2;
+
+    gpu::GpuMat I1_2, I2_2, I1_I2;
+    vector<gpu::GpuMat> vI1, vI2;
+
+    gpu::GpuMat mu1, mu2; 
+    gpu::GpuMat mu1_2, mu2_2, mu1_mu2; 
+
+    gpu::GpuMat sigma1_2, sigma2_2, sigma12; 
+    gpu::GpuMat t3; 
+
+    gpu::GpuMat ssim_map;
+
+    gpu::GpuMat buf;
+};
+Scalar getMSSIM_GPU_optimized( const Mat& i1, const Mat& i2, BufferMSSIM& b);
+
+void help()
+{
+    cout
+        << "\n--------------------------------------------------------------------------" << endl
+        << "This program shows how to port your CPU code to GPU or write that from scratch." << endl
+        << "You can see the performance improvement for the similarity check methods (PSNR and SSIM)."  << endl
+        << "Usage:"                                                               << endl
+        << "./gpu-basics-similarity referenceImage comparedImage numberOfTimesToRunTest(like 10)." << endl
+        << "--------------------------------------------------------------------------"   << endl
+        << endl;
+}
+
+int main(int argc, char *argv[])
+{
+	help(); 
+    Mat I1 = imread(argv[1]);           // Read the two images
+    Mat I2 = imread(argv[2]);
+
+    if (!I1.data || !I2.data)           // Check for success
+    {
+        cout << "Couldn't read the image";
+        return 0;
+    }
+
+    BufferPSNR bufferPSNR;
+    BufferMSSIM bufferMSSIM;
+    
+    int TIMES; 
+    stringstream sstr(argv[3]); 
+    sstr >> TIMES;
+    double time, result;
+
+    //------------------------------- PSNR CPU ----------------------------------------------------
+    time = (double)getTickCount();    
+
+    for (int i = 0; i < TIMES; ++i)
+        result = getPSNR(I1,I2);
+
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    time /= TIMES;
+
+    cout << "Time of PSNR CPU (averaged for " << TIMES << " runs): " << time << " milliseconds."
+        << " With result of: " <<  result << endl; 
+
+    //------------------------------- PSNR GPU ----------------------------------------------------
+    time = (double)getTickCount();    
+
+    for (int i = 0; i < TIMES; ++i)
+        result = getPSNR_GPU(I1,I2);
+
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    time /= TIMES;
+
+    cout << "Time of PSNR GPU (averaged for " << TIMES << " runs): " << time << " milliseconds."
+        << " With result of: " <<  result << endl; 
+
+    //------------------------------- PSNR GPU Optimized--------------------------------------------
+    time = (double)getTickCount();                                  // Initial call
+    result = getPSNR_GPU_optimized(I1, I2, bufferPSNR);
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    cout << "Initial call GPU optimized:              " << time  <<" milliseconds."
+         << " With result of: " << result << endl;
+
+    time = (double)getTickCount();    
+    for (int i = 0; i < TIMES; ++i)
+        result = getPSNR_GPU_optimized(I1, I2, bufferPSNR);
+
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    time /= TIMES;
+
+    cout << "Time of PSNR GPU OPTIMIZED ( / " << TIMES << " runs): " << time 
+         << " milliseconds." << " With result of: " <<  result << endl << endl; 
+
+
+    //------------------------------- SSIM CPU -----------------------------------------------------
+    Scalar x;
+    time = (double)getTickCount();    
+
+    for (int i = 0; i < TIMES; ++i)
+        x = getMSSIM(I1,I2);
+
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    time /= TIMES;
+
+    cout << "Time of MSSIM CPU (averaged for " << TIMES << " runs): " << time << " milliseconds."
+        << " With result of B" << x.val[0] << " G" << x.val[1] << " R" << x.val[2] << endl; 
+
+    //------------------------------- SSIM GPU -----------------------------------------------------
+    time = (double)getTickCount();    
+
+    for (int i = 0; i < TIMES; ++i)
+        x = getMSSIM_GPU(I1,I2);
+
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    time /= TIMES;
+
+    cout << "Time of MSSIM GPU (averaged for " << TIMES << " runs): " << time << " milliseconds."
+        << " With result of B" << x.val[0] << " G" << x.val[1] << " R" << x.val[2] << endl; 
+
+    //------------------------------- SSIM GPU Optimized--------------------------------------------
+    time = (double)getTickCount();    
+    x = getMSSIM_GPU_optimized(I1,I2, bufferMSSIM);
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    cout << "Time of MSSIM GPU Initial Call            " << time << " milliseconds."
+        << " With result of B" << x.val[0] << " G" << x.val[1] << " R" << x.val[2] << endl; 
+
+    time = (double)getTickCount();    
+
+    for (int i = 0; i < TIMES; ++i)
+        x = getMSSIM_GPU_optimized(I1,I2, bufferMSSIM);
+
+    time = 1000*((double)getTickCount() - time)/getTickFrequency();
+    time /= TIMES;
+
+    cout << "Time of MSSIM GPU OPTIMIZED ( / " << TIMES << " runs): " << time << " milliseconds."
+        << " With result of B" << x.val[0] << " G" << x.val[1] << " R" << x.val[2] << endl << endl; 
+    return 0;
+}
+
+
+double getPSNR(const Mat& I1, const Mat& I2)
+{
+    Mat s1; 
+    absdiff(I1, I2, s1);       // |I1 - I2|
+    s1.convertTo(s1, CV_32F);  // cannot make a square on 8 bits
+    s1 = s1.mul(s1);           // |I1 - I2|^2
+
+    Scalar s = sum(s1);         // sum elements per channel
+
+    double sse = s.val[0] + s.val[1] + s.val[2]; // sum channels
+
+    if( sse <= 1e-10) // for small values return zero
+        return 0;
+    else
+    {
+        double  mse =sse /(double)(I1.channels() * I1.total());
+        double psnr = 10.0*log10((255*255)/mse);
+        return psnr;
+    }
+}
+
+double getPSNR_GPU(const Mat& I1, const Mat& I2)
+{
+    gpu::GpuMat gI1, gI2, gs, t1,t2; 
+
+    gI1.upload(I1);
+    gI2.upload(I2);
+
+    gI1.convertTo(t1, CV_32F);
+    gI2.convertTo(t2, CV_32F);
+
+    gpu::absdiff(t1.reshape(1), t2.reshape(1), gs); 
+    gpu::multiply(gs, gs, gs);
+    
+    Scalar s = gpu::sum(gs);
+    double sse = s.val[0] + s.val[1] + s.val[2];
+
+    if( sse <= 1e-10) // for small values return zero
+        return 0;
+    else
+    {
+        double  mse =sse /(double)(gI1.channels() * I1.total());
+        double psnr = 10.0*log10((255*255)/mse);
+        return psnr;
+    }
+}
+
+double getPSNR_GPU_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b)
+{    
+    b.gI1.upload(I1);
+    b.gI2.upload(I2);
+
+    b.gI1.convertTo(b.t1, CV_32F);
+    b.gI2.convertTo(b.t2, CV_32F);
+
+    gpu::absdiff(b.t1.reshape(1), b.t2.reshape(1), b.gs);
+    gpu::multiply(b.gs, b.gs, b.gs);
+
+    double sse = gpu::sum(b.gs, b.buf)[0];
+
+    if( sse <= 1e-10) // for small values return zero
+        return 0;
+    else
+    {
+        double mse = sse /(double)(I1.channels() * I1.total());
+        double psnr = 10.0*log10((255*255)/mse);
+        return psnr;
+    }
+}
+
+Scalar getMSSIM( const Mat& i1, const Mat& i2)
+{ 
+    const double C1 = 6.5025, C2 = 58.5225;
+    int d     = CV_32F;
+
+    Mat I1, I2; 
+    i1.convertTo(I1, d);           // cannot calculate on one byte large values
+    i2.convertTo(I2, d); 
+
+    Mat I2_2   = I2.mul(I2);        // I2^2
+    Mat I1_2   = I1.mul(I1);        // I1^2
+    Mat I1_I2  = I1.mul(I2);        // I1 * I2
+	
+    Mat mu1, mu2;  
+    GaussianBlur(I1, mu1, Size(11, 11), 1.5);
+    GaussianBlur(I2, mu2, Size(11, 11), 1.5);
+
+    Mat mu1_2   =   mu1.mul(mu1);    
+    Mat mu2_2   =   mu2.mul(mu2); 
+    Mat mu1_mu2 =   mu1.mul(mu2);
+
+    Mat sigma1_2, sigma2_2, sigma12; 
+
+    GaussianBlur(I1_2, sigma1_2, Size(11, 11), 1.5);
+    sigma1_2 -= mu1_2;
+
+    GaussianBlur(I2_2, sigma2_2, Size(11, 11), 1.5);
+    sigma2_2 -= mu2_2;
+
+    GaussianBlur(I1_I2, sigma12, Size(11, 11), 1.5);
+    sigma12 -= mu1_mu2;
+
+    ///////////////////////////////// FORMULA ////////////////////////////////
+    Mat t1, t2, t3; 
+
+    t1 = 2 * mu1_mu2 + C1; 
+    t2 = 2 * sigma12 + C2; 
+    t3 = t1.mul(t2);              // t3 = ((2*mu1_mu2 + C1).*(2*sigma12 + C2))
+
+    t1 = mu1_2 + mu2_2 + C1; 
+    t2 = sigma1_2 + sigma2_2 + C2;     
+    t1 = t1.mul(t2);               // t1 =((mu1_2 + mu2_2 + C1).*(sigma1_2 + sigma2_2 + C2))
+
+    Mat ssim_map;
+    divide(t3, t1, ssim_map);      // ssim_map =  t3./t1;
+
+    Scalar mssim = mean( ssim_map ); // mssim = average of ssim map
+    return mssim; 
+}
+
+Scalar getMSSIM_GPU_optimized( const Mat& i1, const Mat& i2, BufferMSSIM& b)
+{ 
+    int cn = i1.channels();
+    const float C1 = 6.5025f, C2 = 58.5225f;
+
+    b.gI1.upload(i1);
+    b.gI2.upload(i2);
+
+    gpu::Stream stream;
+
+    stream.enqueueConvert(b.gI1, b.t1, CV_32F);
+    stream.enqueueConvert(b.gI2, b.t2, CV_32F);      
+
+    gpu::split(b.t1, b.vI1, stream);
+    gpu::split(b.t2, b.vI2, stream);
+    Scalar mssim;
+
+    for( int i = 0; i < b.gI1.channels(); ++i )
+    {        
+        gpu::multiply(b.vI2[i], b.vI2[i], b.I2_2, stream);        // I2^2
+        gpu::multiply(b.vI1[i], b.vI1[i], b.I1_2, stream);        // I1^2
+        gpu::multiply(b.vI1[i], b.vI2[i], b.I1_I2, stream);       // I1 * I2
+
+        gpu::GaussianBlur(b.vI1[i], b.mu1, Size(11, 11), 1.5, 0, BORDER_DEFAULT, -1, stream);
+        gpu::GaussianBlur(b.vI2[i], b.mu2, Size(11, 11), 1.5, 0, BORDER_DEFAULT, -1, stream);
+
+        gpu::multiply(b.mu1, b.mu1, b.mu1_2, stream);   
+        gpu::multiply(b.mu2, b.mu2, b.mu2_2, stream);   
+        gpu::multiply(b.mu1, b.mu2, b.mu1_mu2, stream);   
+
+        gpu::GaussianBlur(b.I1_2, b.sigma1_2, Size(11, 11), 1.5, 0, BORDER_DEFAULT, -1, stream);
+        gpu::subtract(b.sigma1_2, b.mu1_2, b.sigma1_2, stream);
+        //b.sigma1_2 -= b.mu1_2;  - This would result in an extra data transfer operation
+
+        gpu::GaussianBlur(b.I2_2, b.sigma2_2, Size(11, 11), 1.5, 0, BORDER_DEFAULT, -1, stream);
+        gpu::subtract(b.sigma2_2, b.mu2_2, b.sigma2_2, stream);
+        //b.sigma2_2 -= b.mu2_2;
+
+        gpu::GaussianBlur(b.I1_I2, b.sigma12, Size(11, 11), 1.5, 0, BORDER_DEFAULT, -1, stream);
+        gpu::subtract(b.sigma12, b.mu1_mu2, b.sigma12, stream);
+        //b.sigma12 -= b.mu1_mu2;
+
+        //here too it would be an extra data transfer due to call of operator*(Scalar, Mat)
+        gpu::multiply(b.mu1_mu2, 2, b.t1, stream); //b.t1 = 2 * b.mu1_mu2 + C1; 
+        gpu::add(b.t1, C1, b.t1, stream);
+        gpu::multiply(b.sigma12, 2, b.t2, stream); //b.t2 = 2 * b.sigma12 + C2; 
+        gpu::add(b.t2, C2, b.t2, stream);     
+
+        gpu::multiply(b.t1, b.t2, b.t3, stream);     // t3 = ((2*mu1_mu2 + C1).*(2*sigma12 + C2))
+
+        gpu::add(b.mu1_2, b.mu2_2, b.t1, stream);
+        gpu::add(b.t1, C1, b.t1, stream);
+
+        gpu::add(b.sigma1_2, b.sigma2_2, b.t2, stream);
+        gpu::add(b.t2, C2, b.t2, stream);
+
+
+        gpu::multiply(b.t1, b.t2, b.t1, stream);     // t1 =((mu1_2 + mu2_2 + C1).*(sigma1_2 + sigma2_2 + C2))        
+        gpu::divide(b.t3, b.t1, b.ssim_map, stream);      // ssim_map =  t3./t1;
+
+        stream.waitForCompletion();
+
+        Scalar s = gpu::sum(b.ssim_map, b.buf);    
+        mssim.val[i] = s.val[0] / (b.ssim_map.rows * b.ssim_map.cols);
+
+    }
+    return mssim; 
+}