Merge pull request #10512 from sturkmen72:update_documentation

modules/core/include/opencv2/core/types.hpp

@@ -75,7 +75,7 @@ template<typename _Tp> class Complex
 {
 public:
 
-    //! constructors
+    //! default constructor
     Complex();
     Complex( _Tp _re, _Tp _im = 0 );
 
@@ -159,7 +159,7 @@ template<typename _Tp> class Point_
 public:
     typedef _Tp value_type;
 
-    // various constructors
+    //! default constructor
     Point_();
     Point_(_Tp _x, _Tp _y);
     Point_(const Point_& pt);
@@ -181,8 +181,8 @@ public:
     double cross(const Point_& pt) const;
     //! checks whether the point is inside the specified rectangle
     bool inside(const Rect_<_Tp>& r) const;
-
-    _Tp x, y; //< the point coordinates
+    _Tp x; //!< x coordinate of the point
+    _Tp y; //!< y coordinate of the point
 };
 
 typedef Point_<int> Point2i;
@@ -239,7 +239,7 @@ template<typename _Tp> class Point3_
 public:
     typedef _Tp value_type;
 
-    // various constructors
+    //! default constructor
     Point3_();
     Point3_(_Tp _x, _Tp _y, _Tp _z);
     Point3_(const Point3_& pt);
@@ -262,8 +262,9 @@ public:
     double ddot(const Point3_& pt) const;
     //! cross product of the 2 3D points
     Point3_ cross(const Point3_& pt) const;
-
-    _Tp x, y, z; //< the point coordinates
+    _Tp x; //!< x coordinate of the 3D point
+    _Tp y; //!< y coordinate of the 3D point
+    _Tp z; //!< z coordinate of the 3D point
 };
 
 typedef Point3_<int> Point3i;
@@ -316,7 +317,7 @@ template<typename _Tp> class Size_
 public:
     typedef _Tp value_type;
 
-    //! various constructors
+    //! default constructor
     Size_();
     Size_(_Tp _width, _Tp _height);
     Size_(const Size_& sz);
@@ -331,7 +332,8 @@ public:
     //! conversion of another data type.
     template<typename _Tp2> operator Size_<_Tp2>() const;
 
-    _Tp width, height; // the width and the height
+    _Tp width; //!< the width
+    _Tp height; //!< the height
 };
 
 typedef Size_<int> Size2i;
@@ -416,7 +418,7 @@ template<typename _Tp> class Rect_
 public:
     typedef _Tp value_type;
 
-    //! various constructors
+    //! default constructor
     Rect_();
     Rect_(_Tp _x, _Tp _y, _Tp _width, _Tp _height);
     Rect_(const Rect_& r);
@@ -442,7 +444,10 @@ public:
     //! checks whether the rectangle contains the point
     bool contains(const Point_<_Tp>& pt) const;
 
-    _Tp x, y, width, height; //< the top-left corner, as well as width and height of the rectangle
+    _Tp x; //!< x coordinate of the top-left corner
+    _Tp y; //!< y coordinate of the top-left corner
+    _Tp width; //!< width of the rectangle
+    _Tp height; //!< height of the rectangle
 };
 
 typedef Rect_<int> Rect2i;
@@ -481,24 +486,10 @@ struct Type< Rect_<_Tp> > { enum { value = CV_MAKETYPE(Depth<_Tp>::value, 4) };
 /** @brief The class represents rotated (i.e. not up-right) rectangles on a plane.
 
 Each rectangle is specified by the center point (mass center), length of each side (represented by
-cv::Size2f structure) and the rotation angle in degrees.
+#Size2f structure) and the rotation angle in degrees.
 
 The sample below demonstrates how to use RotatedRect:
-@code
-    Mat image(200, 200, CV_8UC3, Scalar(0));
-    RotatedRect rRect = RotatedRect(Point2f(100,100), Size2f(100,50), 30);
-
-    Point2f vertices[4];
-    rRect.points(vertices);
-    for (int i = 0; i < 4; i++)
-        line(image, vertices[i], vertices[(i+1)%4], Scalar(0,255,0));
-
-    Rect brect = rRect.boundingRect();
-    rectangle(image, brect, Scalar(255,0,0));
-
-    imshow("rectangles", image);
-    waitKey(0);
-@endcode
+@snippet snippets/core_various.cpp RotatedRect_demo
 ![image](pics/rotatedrect.png)
 
 @sa CamShift, fitEllipse, minAreaRect, CvBox2D
@@ -506,9 +497,9 @@ The sample below demonstrates how to use RotatedRect:
 class CV_EXPORTS RotatedRect
 {
 public:
-    //! various constructors
+    //! default constructor
     RotatedRect();
-    /**
+    /** full constructor
     @param center The rectangle mass center.
     @param size Width and height of the rectangle.
     @param angle The rotation angle in a clockwise direction. When the angle is 0, 90, 180, 270 etc.,
@@ -529,10 +520,12 @@ public:
     Rect boundingRect() const;
     //! returns the minimal (exact) floating point rectangle containing the rotated rectangle, not intended for use with images
     Rect_<float> boundingRect2f() const;
-
-    Point2f center; //< the rectangle mass center
-    Size2f size;    //< width and height of the rectangle
-    float angle;    //< the rotation angle. When the angle is 0, 90, 180, 270 etc., the rectangle becomes an up-right rectangle.
+    //! returns the rectangle mass center
+    Point2f center;
+    //! returns width and height of the rectangle
+    Size2f size;
+    //! returns the rotation angle. When the angle is 0, 90, 180, 270 etc., the rectangle becomes an up-right rectangle.
+    float angle;
 };
 
 template<> class DataType< RotatedRect >
@@ -637,7 +630,7 @@ OpenCV to pass pixel values.
 template<typename _Tp> class Scalar_ : public Vec<_Tp, 4>
 {
 public:
-    //! various constructors
+    //! default constructor
     Scalar_();
     Scalar_(_Tp v0, _Tp v1, _Tp v2=0, _Tp v3=0);
     Scalar_(_Tp v0);
@@ -654,10 +647,10 @@ public:
     //! per-element product
     Scalar_<_Tp> mul(const Scalar_<_Tp>& a, double scale=1 ) const;
 
-    // returns (v0, -v1, -v2, -v3)
+    //! returns (v0, -v1, -v2, -v3)
     Scalar_<_Tp> conj() const;
 
-    // returns true iff v1 == v2 == v3 == 0
+    //! returns true iff v1 == v2 == v3 == 0
     bool isReal() const;
 };
 
@@ -695,14 +688,13 @@ struct Type< Scalar_<_Tp> > { enum { value = CV_MAKETYPE(Depth<_Tp>::value, 4) }
 /** @brief Data structure for salient point detectors.
 
 The class instance stores a keypoint, i.e. a point feature found by one of many available keypoint
-detectors, such as Harris corner detector, cv::FAST, cv::StarDetector, cv::SURF, cv::SIFT,
-cv::LDetector etc.
+detectors, such as Harris corner detector, #FAST, %StarDetector, %SURF, %SIFT etc.
 
 The keypoint is characterized by the 2D position, scale (proportional to the diameter of the
 neighborhood that needs to be taken into account), orientation and some other parameters. The
 keypoint neighborhood is then analyzed by another algorithm that builds a descriptor (usually
 represented as a feature vector). The keypoints representing the same object in different images
-can then be matched using cv::KDTree or another method.
+can then be matched using %KDTree or another method.
 */
 class CV_EXPORTS_W_SIMPLE KeyPoint
 {
@@ -808,9 +800,9 @@ public:
     CV_WRAP DMatch(int _queryIdx, int _trainIdx, float _distance);
     CV_WRAP DMatch(int _queryIdx, int _trainIdx, int _imgIdx, float _distance);
 
-    CV_PROP_RW int queryIdx; // query descriptor index
-    CV_PROP_RW int trainIdx; // train descriptor index
-    CV_PROP_RW int imgIdx;   // train image index
+    CV_PROP_RW int queryIdx; //!< query descriptor index
+    CV_PROP_RW int trainIdx; //!< train descriptor index
+    CV_PROP_RW int imgIdx;   //!< train image index
 
     CV_PROP_RW float distance;
 
@@ -868,8 +860,8 @@ public:
     TermCriteria(int type, int maxCount, double epsilon);
 
     int type; //!< the type of termination criteria: COUNT, EPS or COUNT + EPS
-    int maxCount; // the maximum number of iterations/elements
-    double epsilon; // the desired accuracy
+    int maxCount; //!< the maximum number of iterations/elements
+    double epsilon; //!< the desired accuracy
 };
 
 

modules/imgcodecs/include/opencv2/imgcodecs.hpp

@@ -197,48 +197,7 @@ should have alpha set to 0, fully opaque pixels should have alpha set to 255/655
 
 The sample below shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom
 compression parameters :
-@code
-    #include <opencv2/opencv.hpp>
-
-    using namespace cv;
-    using namespace std;
-
-    void createAlphaMat(Mat &mat)
-    {
-        CV_Assert(mat.channels() == 4);
-        for (int i = 0; i < mat.rows; ++i) {
-            for (int j = 0; j < mat.cols; ++j) {
-                Vec4b& bgra = mat.at<Vec4b>(i, j);
-                bgra[0] = UCHAR_MAX; // Blue
-                bgra[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); // Green
-                bgra[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); // Red
-                bgra[3] = saturate_cast<uchar>(0.5 * (bgra[1] + bgra[2])); // Alpha
-            }
-        }
-    }
-
-    int main(int argv, char **argc)
-    {
-        // Create mat with alpha channel
-        Mat mat(480, 640, CV_8UC4);
-        createAlphaMat(mat);
-
-        vector<int> compression_params;
-        compression_params.push_back(IMWRITE_PNG_COMPRESSION);
-        compression_params.push_back(9);
-
-        try {
-            imwrite("alpha.png", mat, compression_params);
-        }
-        catch (cv::Exception& ex) {
-            fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what());
-            return 1;
-        }
-
-        fprintf(stdout, "Saved PNG file with alpha data.\n");
-        return 0;
-    }
-@endcode
+@include snippets/imgcodecs_imwrite.cpp
 @param filename Name of the file.
 @param img Image to be saved.
 @param params Format-specific parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ... .) see cv::ImwriteFlags

samples/cpp/tutorial_code/ImgTrans/imageSegmentation.cpp

@@ -73,15 +73,15 @@ int main()
 //! [bin]
     // Create binary image from source image
     Mat bw;
-    cvtColor(src, bw, CV_BGR2GRAY);
-    threshold(bw, bw, 40, 255, CV_THRESH_BINARY | CV_THRESH_OTSU);
+    cvtColor(src, bw, COLOR_BGR2GRAY);
+    threshold(bw, bw, 40, 255, THRESH_BINARY | THRESH_OTSU);
     imshow("Binary Image", bw);
 //! [bin]
 
 //! [dist]
     // Perform the distance transform algorithm
     Mat dist;
-    distanceTransform(bw, dist, CV_DIST_L2, 3);
+    distanceTransform(bw, dist, DIST_L2, 3);
 
     // Normalize the distance image for range = {0.0, 1.0}
     // so we can visualize and threshold it
@@ -92,7 +92,7 @@ int main()
 //! [peaks]
     // Threshold to obtain the peaks
     // This will be the markers for the foreground objects
-    threshold(dist, dist, .4, 1., CV_THRESH_BINARY);
+    threshold(dist, dist, .4, 1., THRESH_BINARY);
 
     // Dilate a bit the dist image
     Mat kernel1 = Mat::ones(3, 3, CV_8UC1);
@@ -108,7 +108,7 @@ int main()
 
     // Find total markers
     vector<vector<Point> > contours;
-    findContours(dist_8u, contours, CV_RETR_EXTERNAL, CV_CHAIN_APPROX_SIMPLE);
+    findContours(dist_8u, contours, RETR_EXTERNAL, CHAIN_APPROX_SIMPLE);
 
     // Create the marker image for the watershed algorithm
     Mat markers = Mat::zeros(dist.size(), CV_32SC1);
@@ -165,4 +165,4 @@ int main()
 
     waitKey(0);
     return 0;
-}
+}
\ No newline at end of file

samples/cpp/tutorial_code/snippets/core_reduce.cpp

@@ -23,8 +23,8 @@ int main()
         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);
+        reduce(m, col_sum, 0, REDUCE_SUM, CV_32F);
+        reduce(m, row_sum, 1, REDUCE_SUM, CV_32F);
         /*
         m =
         [  1,   2;
@@ -40,22 +40,22 @@ int main()
         //! [example]
 
         Mat col_average, row_average, col_min, col_max, row_min, row_max;
-        reduce(m, col_average, 0, CV_REDUCE_AVG, CV_32F);
+        reduce(m, col_average, 0, REDUCE_AVG, CV_32F);
         cout << "col_average =\n" << col_average << endl;
 
-        reduce(m, row_average, 1, CV_REDUCE_AVG, CV_32F);
+        reduce(m, row_average, 1, REDUCE_AVG, CV_32F);
         cout << "row_average =\n" << row_average << endl;
 
-        reduce(m, col_min, 0, CV_REDUCE_MIN, CV_8U);
+        reduce(m, col_min, 0, REDUCE_MIN, CV_8U);
         cout << "col_min =\n" << col_min << endl;
 
-        reduce(m, row_min, 1, CV_REDUCE_MIN, CV_8U);
+        reduce(m, row_min, 1, REDUCE_MIN, CV_8U);
         cout << "row_min =\n" << row_min << endl;
 
-        reduce(m, col_max, 0, CV_REDUCE_MAX, CV_8U);
+        reduce(m, col_max, 0, REDUCE_MAX, CV_8U);
         cout << "col_max =\n" << col_max << endl;
 
-        reduce(m, row_max, 1, CV_REDUCE_MAX, CV_8U);
+        reduce(m, row_max, 1, REDUCE_MAX, CV_8U);
         cout << "row_max =\n" << row_max << endl;
 
         /*
@@ -86,7 +86,7 @@ int main()
         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);
+        reduce(m, col_sum_per_channel, 0, REDUCE_SUM, CV_32F);
         /*
         col_sum_per_channel =
         [9, 12]

samples/cpp/tutorial_code/snippets/core_various.cpp

+#include <opencv2/opencv.hpp>
+
+using namespace std;
+using namespace cv;
+
+int main()
+{
+    //! [Algorithm]
+    Ptr<Feature2D> sbd = SimpleBlobDetector::create();
+    FileStorage fs_read("SimpleBlobDetector_params.xml", FileStorage::READ);
+
+    if (fs_read.isOpened()) // if we have file with parameters, read them
+    {
+        sbd->read(fs_read.root());
+        fs_read.release();
+    }
+    else // else modify the parameters and store them; user can later edit the file to use different parameters
+    {
+        fs_read.release();
+        FileStorage fs_write("SimpleBlobDetector_params.xml", FileStorage::WRITE);
+        sbd->write(fs_write);
+        fs_write.release();
+    }
+
+    Mat result, image = imread("../data/detect_blob.png", IMREAD_COLOR);
+    vector<KeyPoint> keypoints;
+    sbd->detect(image, keypoints, Mat());
+
+    drawKeypoints(image, keypoints, result);
+    for (vector<KeyPoint>::iterator k = keypoints.begin(); k != keypoints.end(); ++k)
+        circle(result, k->pt, (int)k->size, Scalar(0, 0, 255), 2);
+
+    imshow("result", result);
+    waitKey(0);
+    //! [Algorithm]
+
+    //! [RotatedRect_demo]
+    Mat test_image(200, 200, CV_8UC3, Scalar(0));
+    RotatedRect rRect = RotatedRect(Point2f(100,100), Size2f(100,50), 30);
+
+    Point2f vertices[4];
+    rRect.points(vertices);
+    for (int i = 0; i < 4; i++)
+        line(test_image, vertices[i], vertices[(i+1)%4], Scalar(0,255,0), 2);
+
+    Rect brect = rRect.boundingRect();
+    rectangle(test_image, brect, Scalar(255,0,0), 2);
+
+    imshow("rectangles", test_image);
+    waitKey(0);
+    //! [RotatedRect_demo]
+    return 0;
+}

samples/cpp/tutorial_code/snippets/imgcodecs_imwrite.cpp

+#include <opencv2/opencv.hpp>
+
+using namespace cv;
+using namespace std;
+
+static void createAlphaMat(Mat &mat)
+{
+    CV_Assert(mat.channels() == 4);
+    for (int i = 0; i < mat.rows; ++i)
+    {
+        for (int j = 0; j < mat.cols; ++j)
+        {
+            Vec4b& bgra = mat.at<Vec4b>(i, j);
+            bgra[0] = UCHAR_MAX; // Blue
+            bgra[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); // Green
+            bgra[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); // Red
+            bgra[3] = saturate_cast<uchar>(0.5 * (bgra[1] + bgra[2])); // Alpha
+        }
+    }
+}
+
+int main()
+{
+    // Create mat with alpha channel
+    Mat mat(480, 640, CV_8UC4);
+    createAlphaMat(mat);
+    vector<int> compression_params;
+    compression_params.push_back(IMWRITE_PNG_COMPRESSION);
+    compression_params.push_back(9);
+
+    bool result = false;
+    try
+    {
+        result = imwrite("alpha.png", mat, compression_params);
+    }
+    catch (const cv::Exception& ex)
+    {
+        fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what());
+    }
+    if (result)
+        printf("Saved PNG file with alpha data.\n");
+    else
+        printf("ERROR: Can't save PNG file.\n");
+    return result ? 0 : 1;
+}