Improve the documentation.

Add demo code for cv::reduce, cv::merge and cv::split.

modules/core/include/opencv2/core.hpp

@@ -847,6 +847,13 @@ obtained. For example, the function can be used to compute horizontal and vertic
 raster image. In case of REDUCE_MAX and REDUCE_MIN , the output image should have the same type as the source one.
 In case of REDUCE_SUM and REDUCE_AVG , the output may have a larger element bit-depth to preserve accuracy.
 And multi-channel arrays are also supported in these two reduction modes.
+
+The following code demonstrates its usage for a single channel matrix.
+@snippet snippets/core_reduce.cpp example
+
+And the following code demonstrates its usage for a two-channel matrix.
+@snippet snippets/core_reduce.cpp example2
+
 @param src input 2D matrix.
 @param dst output vector. Its size and type is defined by dim and dtype parameters.
 @param dim dimension index along which the matrix is reduced. 0 means that the matrix is reduced to
@@ -866,6 +873,10 @@ elements of i-th input array are treated as mv[i].channels()-element vectors.
 
 The function cv::split does the reverse operation. If you need to shuffle channels in some other
 advanced way, use cv::mixChannels.
+
+The following example shows how to merge 3 single channel matrices into a single 3-channel matrix.
+@snippet snippets/core_merge.cpp example
+
 @param mv input array of matrices to be merged; all the matrices in mv must have the same
 size and the same depth.
 @param count number of input matrices when mv is a plain C array; it must be greater than zero.
@@ -889,6 +900,10 @@ The function cv::split splits a multi-channel array into separate single-channel
 \f[\texttt{mv} [c](I) =  \texttt{src} (I)_c\f]
 If you need to extract a single channel or do some other sophisticated channel permutation, use
 mixChannels .
+
+The following example demonstrates how to split a 3-channel matrix into 3 single channel matrices.
+@snippet snippets/core_split.cpp example
+
 @param src input multi-channel array.
 @param mvbegin output array; the number of arrays must match src.channels(); the arrays themselves are
 reallocated, if needed.

modules/ts/include/opencv2/ts.hpp

@@ -392,14 +392,14 @@ public:
         FAIL_MEMORY_CORRUPTION_BEGIN=-7,
         FAIL_MEMORY_CORRUPTION_END=-8,
 
-        // the tested function (or test ifself) do not deallocate some memory
+        // the tested function (or test itself) do not deallocate some memory
         FAIL_MEMORY_LEAK=-9,
 
         // the tested function returned invalid object, e.g. matrix, containing NaNs,
         // structure with NULL or out-of-range fields (while it should not)
         FAIL_INVALID_OUTPUT=-10,
 
-        // the tested function returned valid object, but it does not match to
+        // the tested function returned valid object, but it does not match
         // the original (or produced by the test) object
         FAIL_MISMATCH=-11,
 
@@ -407,7 +407,7 @@ public:
         // but it differs too much from the original (or produced by the test) object
         FAIL_BAD_ACCURACY=-12,
 
-        // the tested function hung. Sometimes, can be determined by unexpectedly long
+        // the tested function hung. Sometimes, it can be determined by unexpectedly long
         // processing time (in this case there should be possibility to interrupt such a function
         FAIL_HANG=-13,
 
@@ -448,7 +448,7 @@ public:
     std::vector<std::string> data_search_subdir;
 protected:
 
-    // these are allocated within a test to try keep them valid in case of stack corruption
+    // these are allocated within a test to try to keep them valid in case of stack corruption
     RNG rng;
 
     // information about the current test

samples/cpp/tutorial_code/snippets/core_merge.cpp

@@ -0,0 +1,36 @@
+/**
+ * @file core_merge.cpp
+ * @brief It demonstrates the usage of cv::merge.
+ *
+ * It shows how to merge 3 single channel matrices into a 3-channel matrix.
+ *
+ * @author KUANG Fangjun
+ * @date August 2017
+ */
+
+#include <iostream>
+#include <opencv2/core.hpp>
+
+using namespace std;
+using namespace cv;
+
+int main()
+{
+    //! [example]
+    Mat m1 = (Mat_<uchar>(2,2) << 1,4,7,10);
+    Mat m2 = (Mat_<uchar>(2,2) << 2,5,8,11);
+    Mat m3 = (Mat_<uchar>(2,2) << 3,6,9,12);
+
+    Mat channels[3] = {m1, m2, m3};
+    Mat m;
+    merge(channels, 3, m);
+    /*
+    m =
+    [  1,   2,   3,   4,   5,   6;
+       7,   8,   9,  10,  11,  12]
+    m.channels() = 3
+    */
+    //! [example]
+
+    return 0;
+}

samples/cpp/tutorial_code/snippets/core_reduce.cpp

@@ -0,0 +1,98 @@
+/**
+ * @file core_reduce.cpp
+ * @brief It demonstrates the usage of cv::reduce .
+ *
+ * It shows how to compute the row sum, column sum, row average,
+ * column average, row minimum, column minimum, row maximum
+ * and column maximum of a cv::Mat.
+ *
+ * @author KUANG Fangjun
+ * @date August 2017
+ */
+
+#include <iostream>
+#include <opencv2/core.hpp>
+
+using namespace std;
+using namespace cv;
+
+int main()
+{
+    {
+        //! [example]
+        Mat m = (Mat_<uchar>(3,2) << 1,2,3,4,5,6);
+        Mat col_sum, row_sum;
+
+        reduce(m, col_sum, 0, CV_REDUCE_SUM, CV_32F);
+        reduce(m, row_sum, 1, CV_REDUCE_SUM, CV_32F);
+        /*
+        m =
+        [  1,   2;
+           3,   4;
+           5,   6]
+        col_sum =
+        [9, 12]
+        row_sum =
+        [3;
+         7;
+         11]
+         */
+        //! [example]
+
+        Mat col_average, row_average, col_min, col_max, row_min, row_max;
+        reduce(m, col_average, 0, CV_REDUCE_AVG, CV_32F);
+        cout << "col_average =\n" << col_average << endl;
+
+        reduce(m, row_average, 1, CV_REDUCE_AVG, CV_32F);
+        cout << "row_average =\n" << row_average << endl;
+
+        reduce(m, col_min, 0, CV_REDUCE_MIN, CV_8U);
+        cout << "col_min =\n" << col_min << endl;
+
+        reduce(m, row_min, 1, CV_REDUCE_MIN, CV_8U);
+        cout << "row_min =\n" << row_min << endl;
+
+        reduce(m, col_max, 0, CV_REDUCE_MAX, CV_8U);
+        cout << "col_max =\n" << col_max << endl;
+
+        reduce(m, row_max, 1, CV_REDUCE_MAX, CV_8U);
+        cout << "row_max =\n" << row_max << endl;
+
+        /*
+        col_average =
+        [3, 4]
+        row_average =
+        [1.5;
+         3.5;
+         5.5]
+        col_min =
+        [  1,   2]
+        row_min =
+        [  1;
+           3;
+           5]
+        col_max =
+        [  5,   6]
+        row_max =
+        [  2;
+           4;
+           6]
+        */
+    }
+
+    {
+        //! [example2]
+        // two channels
+        char d[] = {1,2,3,4,5,6};
+        Mat m(3, 1, CV_8UC2, d);
+        Mat col_sum_per_channel;
+        reduce(m, col_sum_per_channel, 0, CV_REDUCE_SUM, CV_32F);
+        /*
+        col_sum_per_channel =
+        [9, 12]
+        */
+        //! [example2]
+    }
+
+    return 0;
+}

samples/cpp/tutorial_code/snippets/core_split.cpp

@@ -0,0 +1,39 @@
+/**
+ * @file core_split.cpp
+ * @brief It demonstrates the usage of cv::split .
+ *
+ * It shows how to split a 3-channel matrix into a 3 single channel matrices.
+ *
+ * @author KUANG Fangjun
+ * @date August 2017
+ */
+
+#include <iostream>
+#include <opencv2/core.hpp>
+
+using namespace std;
+using namespace cv;
+
+int main()
+{
+    //! [example]
+    char d[] = {1,2,3,4,5,6,7,8,9,10,11,12};
+    Mat m(2, 2, CV_8UC3, d);
+    Mat channels[3];
+    split(m, channels);
+
+    /*
+    channels[0] =
+    [  1,   4;
+       7,  10]
+    channels[1] =
+    [  2,   5;
+       8,  11]
+    channels[2] =
+    [  3,   6;
+       9,  12]
+    */
+    //! [example]
+
+    return 0;
+}