Added Laplace and Canny reST tutorials and corrected a small bug in Canny sample code

doc/conf.py

@@ -312,6 +312,7 @@ extlinks = {'cvt_color': ('http://opencv.willowgarage.com/documentation/cpp/imgp
  	    'scharr': ('http://opencv.willowgarage.com/documentation/cpp/image_filtering.html#cv-scharr%s', None),
             'laplacian': ('http://opencv.willowgarage.com/documentation/cpp/image_filtering.html#cv-laplacian%s', None),
 	    'canny': ('http://opencv.willowgarage.com/documentation/cpp/imgproc_feature_detection.html?#Canny%s', None),
+	    'copy_to': ('http://opencv.willowgarage.com/documentation/cpp/core_basic_structures.html?#Mat::copyTo%s', None), 	
             'opencv_group' : ('http://tech.groups.yahoo.com/group/OpenCV/%s', None)
            }
 

doc/tutorials/imgproc/imgtrans/canny_detector/canny_detector.rst

@@ -10,10 +10,82 @@ In this tutorial you will learn how to:
 
 a. Use the OpenCV function :canny:`Canny <>` to implement the Canny Edge Detector.
 
+Theory
+=======
+
+#. The *Canny Edge detector* was developed by John F. Canny in 1986. Also known to many as the *optimal detector*, Canny algorithm aims to satisfy three main criteria:
+
+   * **Low error rate:** Meaning a good detection of only existent edges.
+   * **Good localization:** The distance between edge pixels detected and real edge pixels have to be minimized.
+   * **Minimal response:** Only one detector response per edge.  
+
+Steps
+------
+
+#. Filter out any noise. The Gaussian filter is used for this purpose. An example of a Gaussian kernel of :math:`size = 5` that might be used is shown below:
+
+   .. math::
+   
+      K = \dfrac{1}{159}\begin{bmatrix}
+			    2 & 4 & 5 & 4 & 2 \\
+			    4 & 9 & 12 & 9 & 4 \\
+			    5 & 12 & 15 & 12 & 5 \\
+			    4 & 9 & 12 & 9 & 4 \\
+			    2 & 4 & 5 & 4 & 2 
+              		    \end{bmatrix} 
+
+
+#. Find the intensity gradient of the image. For this, we follow a procedure analogous to Sobel: 
+
+   a. Apply a pair of convolution masks (in :math:`x` and :math:`y` directions:
+
+      .. math::
+   
+         G_{x} = \begin{bmatrix}
+         -1 & 0 & +1  \\
+         -2 & 0 & +2  \\
+         -1 & 0 & +1 
+         \end{bmatrix}
+   
+         G_{y} = \begin{bmatrix}
+         -1 & -2 & -1  \\
+         0 & 0 & 0  \\
+         +1 & +2 & +1 
+         \end{bmatrix} 
+
+   b. Find the gradient strength and direction with:
+
+      .. math::
+         \begin{array}{l}
+         G = \sqrt{ G_{x}^{2} + G_{y}^{2} } \\        
+         \theta = \arctan(\dfrac{ G_{y} }{ G_{x} })
+         \end{array}
+
+      The direction is rounded to one of four possible angles (namely 0, 45, 90 or 135)
+
+#. *Non-maximum* suppression is applied. This removes pixels  that are not considered to be part of an edge. Hence, only thin lines (candidate edges) will remain.
+
+#. *Hysteresis*: The final step. Canny does use two thresholds (upper and lower):
+
+   a. If a pixel gradient is higher than the *upper* threshold, the pixel is accepted as an edge
+   b. If a pixel gradient value is below the *lower* threshold, then it is rejected.
+   c. If the pixel gradient is between the two thresholds, then it will be accepted only if it is connected to a pixel that is above the *upper* threshold. 
+
+   Canny recommended a *upper*:*lower* ratio between 2:1 and 3:1.
+  
+#. For more details, you can always consult your favorite Computer Vision book. 
 
 Code
 =====
 
+#. **What does this program do?**
+ 
+   * Asks the user to enter a numerical value to set the lower threshold for our *Canny Edge Detector* (by means of a Trackbar)
+   * Applies the *Canny Detector* and generates a **mask** (bright lines representing the edges on a black background).
+   * Applies the mask obtained on the original image and display it in a window.
+ 
+#. The tutorial code's is shown lines below. You can also download it from `here <https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/tutorial_code/ImgTrans/CannyDetector_Demo.cpp>`_
+
 .. code-block::  cpp
 
    #include "opencv2/imgproc/imgproc.hpp"
@@ -42,10 +114,10 @@ Code
    void CannyThreshold(int, void*)
    {
      /// Reduce noise with a kernel 3x3
-     blur( src_gray, dst, Size(3,3) );
+     blur( src_gray, detected_edges, Size(3,3) );
 
      /// Canny detector
-     Canny( src_gray, detected_edges, lowThreshold, lowThreshold*ratio, kernel_size );
+     Canny( detected_edges, detected_edges, lowThreshold, lowThreshold*ratio, kernel_size );
 
      /// Using Canny's output as a mask, we display our result
      dst = Scalar::all(0);
@@ -64,6 +136,9 @@ Code
      if( !src.data )
      { return -1; }
 
+     /// Create a matrix of the same type and size as src (for dst)
+     dst.create( src.size(), src.type() );
+
      /// Convert the image to grayscale
      cvtColor( src, src_gray, CV_BGR2GRAY );
 
@@ -81,3 +156,129 @@ Code
 
      return 0;
      }
+
+Explanation
+============
+
+#. Create some needed variables:
+
+   .. code-block:: cpp
+
+      Mat src, src_gray;
+      Mat dst, detected_edges;
+
+      int edgeThresh = 1;
+      int lowThreshold;
+      int const max_lowThreshold = 100;
+      int ratio = 3;
+      int kernel_size = 3;
+      char* window_name = "Edge Map";
+
+    Note the following:
+
+    a. We establish a ratio of lower:upper threshold of 3:1 (with the variable *ratio*)
+    b. We set the kernel size of :math:`3` (for the Sobel operations to be performed internally by the Canny function)
+    c. We set a maximum value for the lower Threshold of :math:`100`.
+
+
+#. Loads the source image:
+
+   .. code-block:: cpp
+
+      /// Load an image
+      src = imread( argv[1] );
+
+      if( !src.data )
+        { return -1; }
+
+#. Create a matrix of the same type and size of *src* (to be *dst*)
+ 
+   .. code-block:: cpp
+
+      dst.create( src.size(), src.type() );
+
+#. Convert the image to grayscale (using the function :cvt_color:`cvtColor <>`:
+
+   .. code-block:: cpp
+
+      cvtColor( src, src_gray, CV_BGR2GRAY );
+
+#. Create a window to display the results
+
+   .. code-block:: cpp
+     namedWindow( window_name, CV_WINDOW_AUTOSIZE );
+
+#. Create a Trackbar for the user to enter the lower threshold for our Canny detector:
+
+   .. code-block:: cpp
+
+     createTrackbar( "Min Threshold:", window_name, &lowThreshold, max_lowThreshold, CannyThreshold );
+
+   Observe the following:
+
+   a. The variable to be controlled by the Trackbar is *lowThreshold* with a limit of *max_lowThreshold* (which we set to 100 previously)
+   b. Each time the Trackbar registers an action, the callback function *CannyThreshold* will be invoked.
+
+#. Let's check the *CannyThreshold* function, step by step:
+
+   a. First, we blur the image with a filter of kernel size 3:
+
+      .. code-block:: cpp
+
+         blur( src_gray, detected_edges, Size(3,3) );
+
+   b. Second, we apply the OpenCV function :canny:`Canny <>`:
+
+      .. code-block:: cpp
+
+        Canny( detected_edges, detected_edges, lowThreshold, lowThreshold*ratio, kernel_size );
+
+      where the arguments are:
+
+      * *detected_edges*: Source image, grayscale
+      * *detected_edges*: Output of the detector (can be the same as the input)
+      * *lowThreshold*: The value entered by the user moving the Trackbar
+      * *highThreshold*: Set in the program as three times the lower threshold (following Canny's recommendation)
+      * *kernel_size*: We defined it to be 3 (the size of the Sobel kernel to be used internally)
+
+#. We fill a *dst* image with zeros (meaning the image is completely black).
+
+   .. code-block:: cpp
+
+      dst = Scalar::all(0);
+    
+#. Finally, we will use the function :copy_to:`copyTo <>` to map only the areas of the image that are identified as edges (on a black background). 
+  
+   .. code-block:: cpp
+
+      src.copyTo( dst, detected_edges);
+
+   :copy_to:`copyTo <>` copy the *src* image onto *dst*. However, it will only copy the pixels in the locations where they have non-zero values. Since the output of the Canny detector is the edge contours on a black background, the resulting *dst* will be black in all the area but the detected edges.
+
+#. We display our result:
+
+   .. code-block:: cpp
+
+      imshow( window_name, dst );
+
+Result
+=======
+
+#. After compiling the code above, we can run it giving as argument the path to an image. For example, using as an input the following image:
+
+   .. image:: images/Canny_Detector_Tutorial_Original_Image.jpg
+           :alt: Original test image
+           :width: 200pt
+           :align: center
+
+   and moving the slider, trying different threshold, we obtain the following result:
+
+   .. image:: images/Canny_Detector_Tutorial_Result.jpg
+           :alt: Result after running Canny
+           :width: 200pt
+           :align: center
+  
+   Notice how the image is superposed to the black background on the edge regions.
+  
+
+

doc/tutorials/imgproc/imgtrans/filter_2d/filter_2d.rst

@@ -135,22 +135,20 @@ Code
 Explanation
 =============
 
-#. We begin with the usual steps:
+#. Load an image
 
-   * Load an image
-
-     .. code-block:: cpp
+   .. code-block:: cpp
 
-     	src = imread( argv[1] );
+      src = imread( argv[1] );
 
-     	if( !src.data )
-     	  { return -1; }
+      if( !src.data )
+        { return -1; }
 
-   * Create a window to display the result
+#. Create a window to display the result
 
-     .. code-block:: cpp
+   .. code-block:: cpp
 
-     	namedWindow( window_name, CV_WINDOW_AUTOSIZE );
+      namedWindow( window_name, CV_WINDOW_AUTOSIZE );
 
 #. Initialize the arguments for the linear filter
 

doc/tutorials/imgproc/imgtrans/laplace_operator/laplace_operator.rst

@@ -15,16 +15,47 @@ a. Use the OpenCV function :laplacian:`Laplacian <>` to implement a discrete ana
 Theory
 =======
 
+#. In the previous tutorial we learned how to use the *Sobel Operator*. It was based on the fact that in the edge area, the pixel intensity shows a "jump" or a high variation of intensity. Getting the first derivative of the intensity, we observed that an edge is characterized by a maximum, as it can be seen in the figure:
+
+   .. image:: images/Laplace_Operator_Tutorial_Theory_Previous.jpg
+           :alt: Previous theory
+           :height: 200pt
+           :align: center
+
+#. And...what happens if we take the second derivative?
+
+   .. image:: images/Laplace_Operator_Tutorial_Theory_ddIntensity.jpg
+           :alt: Second derivative
+           :height: 200pt
+           :align: center
+
+   You can observe that the second derivative is zero! So, we can also use this criterion to attempt to detect edges in an image. However, note that zeros will not only appear in edges (they can actually appear in other meaningless locations); this can be solved by applying filtering where needed.
+
+
 Laplacian Operator
 -------------------
 
-.. math::
+#. From the explanation above, we deduce that the second derivative can be used to *detect edges*. Since images are "*2D*", we would need to take the derivative in both dimensions. Here, the Laplacian operator comes handy.
+ 
+#. The *Laplacian operator* is defined by:
+
+  .. math::
+
+     Laplace(f) = \dfrac{\partial^{2} f}{\partial x^{2}} + \dfrac{\partial^{2} f}{\partial y^{2}}
 
-   Laplace(f) = \dfrac{\partial^{2} f}{\partial x^{2}} + \dfrac{\partial^{2} f}{\partial y^{2}}
+#. The Laplacian operator is implemented in OpenCV by the function :laplacian:`Laplacian <>`. In fact, since the Laplacian uses the gradient of images, it calls internally the *Sobel* operator to perform its computation.
 
 Code
 ======
 
+#. **What does this program do?**
+ 
+   * Loads an image
+   * Remove noise by applying a Gaussian blur and then convert the original image to grayscale 
+   * Applies a Laplacian operator to the grayscale image and stores the output image
+   * Display the result in a window
+
+#. The tutorial code's is shown lines below. You can also download it from `here <https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/tutorial_code/ImgTrans/Laplace_Demo.cpp>`_
 
 .. code-block:: cpp
 
@@ -75,3 +106,83 @@ Code
 
      return 0;
      }
+
+
+Explanation
+============
+
+#. Create some needed variables:
+
+   .. code-block:: cpp
+
+      Mat src, src_gray, dst;
+      int kernel_size = 3; 
+      int scale = 1;
+      int delta = 0;
+      int ddepth = CV_16S;
+      char* window_name = "Laplace Demo";
+
+#. Loads the source image:
+
+   .. code-block:: cpp
+
+      src = imread( argv[1] );
+
+      if( !src.data )
+        { return -1; }
+
+#. Apply a Gaussian blur to reduce noise:
+
+   .. code-block:: cpp
+
+      GaussianBlur( src, src, Size(3,3), 0, 0, BORDER_DEFAULT );
+ 
+#. Convert the image to grayscale using :cvt_color:`cvtColor <>`
+
+   .. code-block:: cpp
+
+      cvtColor( src, src_gray, CV_RGB2GRAY );
+
+#. Apply the Laplacian operator to the grayscale image:
+
+   .. code-block:: cpp
+
+      Laplacian( src_gray, dst, ddepth, kernel_size, scale, delta, BORDER_DEFAULT );
+
+   where the arguments are:
+
+   * *src_gray*: The input image.
+   * *dst*: Destination (output) image
+   * *ddepth*: Depth of the destination image. Since our input is *CV_8U* we define *ddepth* = *CV_16S* to avoid overflow
+   * *kernel_size*: The kernel size of the Sobel operator to be applied internally. We use 3 in this example.
+   * *scale*, *delta* and *BORDER_DEFAULT*: We leave them as default values.
+
+#. Convert the output from the Laplacian operator to a *CV_8U* image:
+
+   .. code-block:: cpp
+
+      convertScaleAbs( dst, abs_dst );
+
+#. Display the result in a window:
+
+   .. code-block:: cpp
+
+      imshow( window_name, abs_dst );
+
+
+Results
+========
+
+#. After compiling the code above, we can run it giving as argument the path to an image. For example, using as an input:
+
+   .. image:: images/Laplace_Operator_Tutorial_Original_Image.jpg
+           :alt: Original test image
+           :width: 250pt
+           :align: center
+
+#. We obtain the following result. Notice how the trees and the silhouette of the cow are approximately well defined (except in areas in which the intensity are very similar, i.e. around the cow's head). Also, note that the roof of the house behind the trees (right side) is notoriously marked. This is due to the fact that the contrast is higher in that region.
+
+   .. image:: images/Laplace_Operator_Tutorial_Result.jpg
+           :alt: Original test image
+           :width: 250pt
+           :align: center

doc/tutorials/imgproc/imgtrans/sobel_derivatives/sobel_derivatives.rst

@@ -29,7 +29,25 @@ Theory
            :height: 200pt
            :align: center
  
-   You can easily notice that in an *edge*, the pixel intensity *changes* in a notorious way. A good way to express *changes* is by using *derivatives*. A high change in gradient indicates a major change in the image.
+   You can easily notice that in an *edge*, the pixel intensity *changes* in a notorious way. A good way to express *changes* is by using *derivatives*. A high change in gradient indicates a major change in the image. 
+
+#. To be more graphical, let's assume we have a 1D-image. An edge is shown by the "jump" in intensity in the plot below:
+
+   .. image:: images/Sobel_Derivatives_Tutorial_Theory_Intensity_Function.jpg
+           :alt:  Intensity Plot for an edge
+           :height: 200pt
+           :align: center
+
+#. The edge "jump" can be seen more easily if we take the first derivative (actually, here appears as a maximum)
+
+   .. image:: images/Sobel_Derivatives_Tutorial_Theory_dIntensity_Function.jpg
+           :alt:  First derivative of Intensity - Plot for an edge
+           :height: 200pt
+           :align: center
+
+#. So, from the explanation above, we can deduce that a method to detect edges in an image can be performed by locating pixel locations where the gradient is higher than its neighbors (or to generalize, higher than a threshold).
+
+#. More detailed explanation, please refer to **Learning OpenCV** by Bradski and Kaehler
 
 Sobel Operator
 ---------------
@@ -44,7 +62,7 @@ Assuming that the image to  be operated is :math:`I`:
 
 #. We calculate two derivatives:
 
-   a. **Horizontal changes**: This is computed by convolving :math:`I` with a kernel :math:`G_{x}` such as:
+   a. **Horizontal changes**: This is computed by convolving :math:`I` with a kernel :math:`G_{x}` with odd size. For example for a kernel size of 3, :math:`G_{x}` would be computed as:
 
       .. math::
    
@@ -54,7 +72,7 @@ Assuming that the image to  be operated is :math:`I`:
          -1 & 0 & +1 
          \end{bmatrix} * I
 
-   b. **Vertical changes**: This is computed by convolving :math:`I` with a kernel :math:`G_{y}` such as:
+   b. **Vertical changes**: This is computed by convolving :math:`I` with a kernel :math:`G_{y}` with odd size. For example for a kernel size of 3, :math:`G_{y}` would be computed as:
 
       .. math::
    
@@ -77,6 +95,26 @@ Assuming that the image to  be operated is :math:`I`:
       G = |G_{x}| + |G_{y}|
 
 
+.. note::
+
+   When the size of the kernel is :math:`3`, the Sobel kernel shown above may produce noticeable inaccuracies (after all, Sobel is only an approximation of the derivative). OpenCV addresses this inaccuracy for kernels of size 3 by using the :scharr:`Scharr <>` function. This is as fast but more accurate than the standar Sobel function. It implements the following kernels:
+
+      .. math::
+
+         G_{x} = \begin{bmatrix}
+         -3 & 0 & +3  \\
+         -10 & 0 & +10  \\
+         -3 & 0 & +3 
+         \end{bmatrix} 
+   
+         G_{y} = \begin{bmatrix}
+         -3 & -10 & -3  \\
+         0 & 0 & 0  \\
+         +3 & +10 & +3 
+         \end{bmatrix} 
+
+  You can check out more information of this function in the OpenCV reference (:scharr:`Scharr <>`). Also, in the sample code below, you will notice that above the code for :sobel:`Sobel <>` function there is also code for the :scharr:`Scharr <>` function commented. Uncommenting it (and obviously commenting the Sobel stuff) should give you an idea of how this function works.
+
 Code
 =====
 

samples/cpp/tutorial_code/ImgTrans/CannyDetector_Demo.cpp

@@ -30,10 +30,10 @@ char* window_name = "Edge Map";
 void CannyThreshold(int, void*)
 {
     /// Reduce noise with a kernel 3x3
-    blur( src_gray, dst, Size(3,3) );
+    blur( src_gray, detected_edges, Size(3,3) );
 
     /// Canny detector
-    Canny( src_gray, detected_edges, lowThreshold, lowThreshold*ratio, kernel_size );
+    Canny( detected_edges, detected_edges, lowThreshold, lowThreshold*ratio, kernel_size );
 
     /// Using Canny's output as a mask, we display our result
     dst = Scalar::all(0);
@@ -54,6 +54,9 @@ int main( int argc, char** argv )
   if( !src.data )
     { return -1; }
 
+  /// Create a matrix of the same type and size as src (for dst)
+  dst.create( src.size(), src.type() );
+
   /// Convert the image to grayscale
   cvtColor( src, src_gray, CV_BGR2GRAY );