Merge pull request #10635 from csukuangfj:doc-checkVector

modules/core/include/opencv2/core/mat.hpp

@@ -1778,7 +1778,27 @@ public:
      */
     size_t total(int startDim, int endDim=INT_MAX) const;
 
-    //! returns N if the matrix is 1-channel (N x ptdim) or ptdim-channel (1 x N) or (N x 1); negative number otherwise
+    /**
+     * @param elemChannels Number of channels or number of columns the matrix should have.
+     *                     For a 2-D matrix, when the matrix has only 1 column, then it should have
+     *                     elemChannels channels; When the matrix has only 1 channel,
+     *                     then it should have elemChannels columns.
+     *                     For a 3-D matrix, it should have only one channel. Furthermore,
+     *                     if the number of planes is not one, then the number of rows
+     *                     within every plane has to be 1; if the number of rows within
+     *                     every plane is not 1, then the number of planes has to be 1.
+     * @param depth The depth the matrix should have. Set it to -1 when any depth is fine.
+     * @param requireContinuous Set it to true to require the matrix to be continuous
+     * @return -1 if the requirement is not satisfied.
+     *         Otherwise, it returns the number of elements in the matrix. Note
+     *         that an element may have multiple channels.
+     *
+     * The following code demonstrates its usage for a 2-d matrix:
+     * @snippet snippets/core_mat_checkVector.cpp example-2d
+     *
+     * The following code demonstrates its usage for a 3-d matrix:
+     * @snippet snippets/core_mat_checkVector.cpp example-3d
+     */
     int checkVector(int elemChannels, int depth=-1, bool requireContinuous=true) const;
 
     /** @brief Returns a pointer to the specified matrix row.

samples/cpp/tutorial_code/snippets/core_mat_checkVector.cpp

@@ -0,0 +1,42 @@
+/**
+ * @brief It demonstrates the usage of cv::Mat::checkVector.
+ */
+
+#include <opencv2/core.hpp>
+
+int main()
+{
+    //! [example-2d]
+    cv::Mat mat(20, 1, CV_32FC2);
+    int n = mat.checkVector(2);
+    CV_Assert(n == 20); // mat has 20 elements
+
+    mat.create(20, 2, CV_32FC1);
+    n = mat.checkVector(1);
+    CV_Assert(n == -1); // mat is neither a column nor a row vector
+
+    n = mat.checkVector(2);
+    CV_Assert(n == 20); // the 2 columns are considered as 1 element
+    //! [example-2d]
+
+    mat.create(1, 5, CV_32FC1);
+    n = mat.checkVector(1);
+    CV_Assert(n == 5); // mat has 5 elements
+
+    n = mat.checkVector(5);
+    CV_Assert(n == 1); // the 5 columns are considered as 1 element
+
+    //! [example-3d]
+    int dims[] = {1, 3, 5}; // 1 plane, every plane has 3 rows and 5 columns
+    mat.create(3, dims, CV_32FC1); // for 3-d mat, it MUST have only 1 channel
+    n = mat.checkVector(5); // the 5 columns are considered as 1 element
+    CV_Assert(n == 3);
+
+    int dims2[] = {3, 1, 5}; // 3 planes, every plane has 1 row and 5 columns
+    mat.create(3, dims2, CV_32FC1);
+    n = mat.checkVector(5); // the 5 columns are considered as 1 element
+    CV_Assert(n == 3);
+    //! [example-3d]
+
+    return 0;
+}