*/
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.
--- /dev/null
+/**
+ * @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;
+}