Added the "Mask operations on matrices" tutorial (with its sample). Plus modified some other core tutorials.

doc/conf.py

@@ -355,6 +355,7 @@ extlinks = {'cvt_color': ('http://opencv.willowgarage.com/documentation/cpp/imgp
             'imgprocfilter':('http://opencv.itseez.com/modules/imgproc/doc/filtering.html#%s', None),
             '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),
+            '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)
            }
 

doc/tutorials/core/basic_linear_transform/basic_linear_transform.rst

@@ -8,13 +8,15 @@ Goal
 
 In this tutorial you will learn how to:
 
-* Access pixel values 
+.. container:: enumeratevisibleitemswithsquare
 
-* Initialize a matrix with zeros
+   + Access pixel values 
 
-* Learn what :saturate_cast:`saturate_cast <>` does and why it is useful
+   + Initialize a matrix with zeros
 
-* Get some cool info about pixel transformations
+   + Learn what :saturate_cast:`saturate_cast <>` does and why it is useful
+
+   + Get some cool info about pixel transformations
 
 Cool Theory
 =================

doc/tutorials/core/how_to_scan_images/how_to_scan_images.rst

@@ -58,6 +58,8 @@ Another issue is how do we measure time? Well OpenCV offers two simple functions
    t = ((double)getTickCount() - t)/getTickFrequency(); 
    cout << "Times passed in seconds: " << t << endl;
 
+.. _How_Image_Stored_Memory: 
+
 How the image matrix is stored in the memory?
 =============================================
 
@@ -175,5 +177,5 @@ Finally, you may watch a sample run of the program on the `video posted <https:/
 .. raw:: html
 
   <div align="center">
-  <iframe title="Install OpenCV by using its source files - Part 1" width="560" height="349" src="http://www.youtube.com/embed/fB3AN5fjgwc?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
+  <iframe title="How to scan images in OpenCV?" width="560" height="349" src="http://www.youtube.com/embed/fB3AN5fjgwc?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
   </div>

doc/tutorials/core/mat-mask-operations/mat-mask-operations.rst

@@ -1,14 +1,14 @@
-.. _maskOperations:
+.. _maskOperationsFilter:
 
-Mask operations on matrixes
+Mask operations on matrices
 ***************************
 
-Mask operations on matrixes are quite simple. The idea is that we recalculate each pixels value in an image according to a matrix mask. This mask holds values that will just how much influence have neighbor pixel values (and the pixel value itself) to the new pixel value. From a mathematical point of view we make a weighted average, with our specified values. 
+Mask operations on matrices are quite simple. The idea is that we recalculate each pixels value in an image according to a mask matrix (also known as kernel). This mask holds values that will just how much influence have neighbor pixel values (and the pixel value itself) to the new pixel value. From a mathematical point of view we make a weighted average, with our specified values. 
 
 Our test case
 =============
 
-Let us consider the issue of an image contrast enchancement method. Basically we want to apply for every pixel of the image the following formula: 
+Let us consider the issue of an image contrast enhancement method. Basically we want to apply for every pixel of the image the following formula: 
 
 .. math::
 
@@ -21,4 +21,117 @@ Let us consider the issue of an image contrast enchancement method. Basically we
                         +1 &  0 & -1 &  0 \cr
                     }
 
-The first notation is by using a formula, while the second is a compacted version of the first by using a mask. You use the mask by puting the center of the mask matrix (in the upper case noted by the zero-zero index) on the pixel you want to calculate and sum up the pixel values multiplicated with the overlapped matrix values. It's the same thing, however in case of large matrices the later notation is a lot easier to look over. 
+The first notation is by using a formula, while the second is a compacted version of the first by using a mask. You use the mask by putting the center of the mask matrix (in the upper case noted by the zero-zero index) on the pixel you want to calculate and sum up the pixel values multiplicity with the overlapped matrix values. It's the same thing, however in case of large matrices the later notation is a lot easier to look over. 
+
+Now let us see how we can make this happen by using the basic pixel access method or by using the :filtering:`filter2D <filter2d>` function. 
+
+The Basic Method
+================
+
+Here's a function that will do this: 
+
+.. code-block:: cpp
+
+   void Sharpen(const Mat& myImage,Mat& Result)
+   {
+       CV_Assert(myImage.depth() == CV_8U);  // accept only uchar images
+
+       Result.create(myImage.size(),myImage.type());
+       const int nChannels = myImage.channels();
+
+       for(int j = 1 ; j < myImage.rows-1; ++j)
+       {
+           const uchar* previous = myImage.ptr<uchar>(j - 1);
+           const uchar* current  = myImage.ptr<uchar>(j    );
+           const uchar* next     = myImage.ptr<uchar>(j + 1);
+
+           uchar* output = Result.ptr<uchar>(j);
+
+           for(int i= nChannels;i < nChannels*(myImage.cols-1); ++i)
+           {
+               *output++ = saturate_cast<uchar>(5*current[i] 
+                            -current[i-nChannels] - current[i+nChannels] - previous[i] - next[i]);
+           }
+       }
+
+       Result.row(0).setTo(Scalar(0));
+       Result.row(Result.rows-1).setTo(Scalar(0));
+       Result.col(0).setTo(Scalar(0));
+       Result.col(Result.cols-1).setTo(Scalar(0));
+   }
+
+At first we make sure that the input images data is in unsigned char format. For this we use the :utilitysystemfunctions:`CV_Assert <cv-assert>` function that throws an error when the expression inside it is false.
+
+.. code-block:: cpp
+
+   CV_Assert(myImage.depth() == CV_8U);  // accept only uchar images
+
+We create an output image with the same size and the same type than our input. As you can see at the :ref:`How_Image_Stored_Memory` section, depending on the number of channels we may have one or more subcolumns. We will iterate through them via pointers so the total number of elements depends from this number.
+
+.. code-block:: cpp
+
+   Result.create(myImage.size(),myImage.type());
+   const int nChannels = myImage.channels();
+
+We'll use the plain C [] operator to access pixels. Because we need to access multiple rows at the same time we'll acquire the pointers for each of them (a previous, a current and a next line). We need another pointer to where we're going to save the calculation. Then simply access the right items with the [] operator. For moving the output pointer ahead we simply increase this (with one byte) after each operation:
+
+.. code-block:: cpp
+
+   for(int j = 1 ; j < myImage.rows-1; ++j)
+   {
+       const uchar* previous = myImage.ptr<uchar>(j - 1);
+       const uchar* current  = myImage.ptr<uchar>(j    );
+       const uchar* next     = myImage.ptr<uchar>(j + 1);
+
+       uchar* output = Result.ptr<uchar>(j);
+
+       for(int i= nChannels;i < nChannels*(myImage.cols-1); ++i)
+       {
+           *output++ = saturate_cast<uchar>(5*current[i] 
+                        -current[i-nChannels] - current[i+nChannels] - previous[i] - next[i]);
+       }
+   }
+
+On the borders of the image the upper notation results inexistent pixel locations (like minus one - minus one). In these points our formula is undefined. A simple solution is to do not apply the mask in these points and, for example, maintain the images previous values by copying these values over to these locations:
+
+.. code-block:: cpp
+
+   Result.row(0).setTo(Scalar(0));             // The top row 
+   Result.row(Result.rows-1).setTo(Scalar(0)); // The left column
+   Result.col(0).setTo(Scalar(0));             // The right column
+   Result.col(Result.cols-1).setTo(Scalar(0)); // The bottom row
+
+The filter2D function
+=====================
+
+Applying such filters are so common in image processing that in OpenCV there exist a function that will take care of applying the mask (also called a kernel in some places). For this you first need to define a *Mat* object that holds the mask:
+
+.. code-block:: cpp
+
+   Mat kern = (Mat_<char>(3,3) <<  0, -1,  0, 
+                                  -1,  5, -1,
+                                   0, -1,  0);
+
+Then call the :filtering:`filter2D <filter2d>` function specifying the input, the output image and the kernell to use: 
+
+.. code-block:: cpp
+
+   filter2D(I, K, I.depth(), kern ); 
+
+The function even has a fifth optional argument to specify the center of the kernel, and a sixth one for determining what to do in the regions where the operation is undefined (borders). Using this function has the advantage that it's shorter, more verbose and that because they are some optimization techniques implemented usually faster than the *hand method*. For example in my while the first one took only 13 milliseconds the second took around 31 milliseconds. Quite some difference.
+
+For example: 
+
+.. image:: images/resultMatMaskFilter2D.png
+   :alt: A sample output of the program
+   :align: center
+
+You can download this source code from :download:`here <../../../../samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp>` or look in the OpenCV source code libraries sample directory at :file:`samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp`.
+
+Check out an instance of running the program on our `YouTube channel <http://www.youtube.com/watch?v=7PF1tAU9se4>`_ . 
+
+.. raw:: html
+
+  <div align="center">
+ <iframe width="560" height="349" src="https://www.youtube.com/embed/7PF1tAU9se4?hd=1" frameborder="0" allowfullscreen></iframe>
+  </div>

doc/tutorials/core/random_generator_and_text/random_generator_and_text.rst

@@ -1,7 +1,7 @@
 .. _Drawing_2:
 
-Fancy Drawing!
+Random generator and text with OpenCV
-****************
+*************************************
 
 Goals
 ======
@@ -9,15 +9,15 @@ Goals
 In this tutorial you will learn how to:
 
 * Use the *Random Number generator class* (:rng:`RNG <>`) and how to get a random number from a uniform distribution.
-* Display Text on an OpenCV window by using the function :put_text:`putText <>`
+* Display text on an OpenCV window by using the function :put_text:`putText <>`
 
 Code
 =====
-* In the previous tutorial we drew diverse geometric figures, giving as input parameters such as coordinates (in the form of :point:`Points <>`), color, thickness, etc. You might have noticed that we gave specific values for these arguments.
+* In the previous tutorial (:ref:`Drawing_1`) we drew diverse geometric figures, giving as input parameters such as coordinates (in the form of :point:`Points <>`), color, thickness, etc. You might have noticed that we gave specific values for these arguments.
  
-* In this tutorial, we intend to use *random* values for the drawing parameters. Also, we intend to populate our image with a big number of geometric figures. Since we will be initializing them in a random fashion, this process will be automatic and made by using *loops*
+* In this tutorial, we intend to use *random* values for the drawing parameters. Also, we intend to populate our image with a big number of geometric figures. Since we will be initializing them in a random fashion, this process will be automatic and made by using *loops* .
 
-* This code is in your OpenCV sample folder. Otherwise you can grab it from `here <https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/tutorial_code/Basic/Drawing_2.cpp>`_
+* This code is in your OpenCV sample folder. Otherwise you can grab it from `here <https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/tutorial_code/Basic/Drawing_2.cpp>`_ .
 
 Explanation
 ============
@@ -81,9 +81,6 @@ Explanation
 
    .. code-block:: cpp
 
-      /**
-       * @function Drawing_Random_Lines
-       */
       int Drawing_Random_Lines( Mat image, char* window_name, RNG rng )
       {
         int lineType = 8;
@@ -101,7 +98,6 @@ Explanation
          if( waitKey( DELAY ) >= 0 )
          { return -1; }
         }
-
         return 0;
       }
 

doc/tutorials/core/table_of_content_core/table_of_content_core.rst

@@ -46,6 +46,25 @@ Here you will learn the about the basic building blocks of the library. A must r
                    :width:  90pt
                    
 
++
+  .. tabularcolumns:: m{100pt} m{300pt}
+  .. cssclass:: toctableopencv
+
+  =============== ======================================================
+   |HowFilterIm|  **Title:** :ref:`maskOperationsFilter`
+
+                  *Compatibility:* > OpenCV 2.0
+
+                  *Author:* |Author_BernatG|
+
+                  You'll find out how to scan images with neighbor access and use the :filtering:`filter2D <filter2d>` function to apply kernel filters on images.
+
+  =============== ======================================================
+
+  .. |HowFilterIm| image:: images/matMaskFilter2DOp.png
+                   :height: 90pt
+                   :width:  90pt
+
 +
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
@@ -171,10 +190,10 @@ Here you will learn the about the basic building blocks of the library. A must r
    
    ../mat - the basic image container/mat - the basic image container
    ../how_to_scan_images/how_to_scan_images
+   ../mat-mask-operations/mat-mask-operations
    ../adding_images/adding_images
    ../basic_linear_transform/basic_linear_transform
    ../basic_geometric_drawing/basic_geometric_drawing
    ../random_generator_and_text/random_generator_and_text
-   ../mat-mask-operations/mat-mask-operations
    ../discrete_fourier_transform/discrete_fourier_transform
    ../file_input_output_with_xml_yml/file_input_output_with_xml_yml

samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp

@@ -0,0 +1,86 @@
+#include <opencv2/core/core.hpp>
+#include <opencv2/highgui/highgui.hpp>
+#include <opencv2/imgproc/imgproc.hpp>
+#include <iostream>
+
+using namespace std; 
+using namespace cv;
+
+void help(char* progName)
+{
+    cout << endl 
+        <<  "This program shows how to filter images with mask: the write it yourself and the"
+        << "filter2d way. " << endl
+        <<  "Usage:"                                                                        << endl
+        << progName << " [image_name -- default lena.jpg] [G -- grayscale] "        << endl << endl;
+}
+
+
+void Sharpen(const Mat& myImage,Mat& Result);
+
+int main( int argc, char* argv[])
+{
+    help(argv[0]);
+    const char* filename = argc >=2 ? argv[1] : "lena.jpg";
+
+    Mat I, J, K;
+
+    if (argc >= 3 && !strcmp("G", argv[2]))
+        I = imread( filename, CV_LOAD_IMAGE_GRAYSCALE);
+    else
+        I = imread( filename, CV_LOAD_IMAGE_COLOR);
+
+    namedWindow("Input", CV_WINDOW_AUTOSIZE);
+    namedWindow("Output", CV_WINDOW_AUTOSIZE);
+
+    imshow("Input", I);
+    double t = (double)getTickCount();
+    
+    Sharpen(I, J); 
+    
+    t = ((double)getTickCount() - t)/getTickFrequency();
+    cout << "Hand written function times passed in seconds: " << t << endl;
+
+    imshow("Output", J);
+    cvWaitKey(0);
+
+    Mat kern = (Mat_<char>(3,3) <<  0, -1,  0, 
+                                   -1,  5, -1,
+                                    0, -1,  0);
+    t = (double)getTickCount();
+    filter2D(I, K, I.depth(), kern ); 
+    t = ((double)getTickCount() - t)/getTickFrequency();
+    cout << "Built-in filter2D time passed in seconds:      " << t << endl;
+
+    imshow("Output", K);
+
+    cvWaitKey(0);
+    return 0; 
+}
+void Sharpen(const Mat& myImage,Mat& Result)
+{
+    CV_Assert(myImage.depth() == CV_8U);  // accept only uchar images
+
+    const int nChannels = myImage.channels();
+    Result.create(myImage.size(),myImage.type());
+    
+    for(int j = 1 ; j < myImage.rows-1; ++j)
+    {
+        const uchar* previous = myImage.ptr<uchar>(j - 1);
+        const uchar* current  = myImage.ptr<uchar>(j    );
+        const uchar* next     = myImage.ptr<uchar>(j + 1);
+
+        uchar* output = Result.ptr<uchar>(j);
+
+        for(int i= nChannels;i < nChannels*(myImage.cols-1); ++i)
+        {
+            *output++ = saturate_cast<uchar>(5*current[i] 
+                         -current[i-nChannels] - current[i+nChannels] - previous[i] - next[i]);
+        }
+    }
+
+    Result.row(0).setTo(Scalar(0));
+    Result.row(Result.rows-1).setTo(Scalar(0));
+    Result.col(0).setTo(Scalar(0));
+    Result.col(Result.cols-1).setTo(Scalar(0));
+}