From e88bf2bc3081863bac276589a7c9c960c1545952 Mon Sep 17 00:00:00 2001 From: HelenWong Date: Mon, 24 Nov 2014 13:08:04 -0800 Subject: [PATCH] Updated Documentation (HoughCircles) Rewrite the note on HoughCircles documentation to make it more clear Add note to clarify that the output vector of found circles is sorted by descending order of centres accumulator values. Also delete reductant lines on the HoughCircles documentation. Added comments to hough circles function. Added comments to icvhoughgradient Misalignment in line 1183 corrected --- modules/imgproc/doc/feature_detection.rst | 6 +++--- modules/imgproc/src/hough.cpp | 12 ++++++++++-- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/modules/imgproc/doc/feature_detection.rst b/modules/imgproc/doc/feature_detection.rst index 9c661d04fc..a756ff29d7 100644 --- a/modules/imgproc/doc/feature_detection.rst +++ b/modules/imgproc/doc/feature_detection.rst @@ -280,7 +280,7 @@ The function can be used to initialize a point-based tracker of an object. HoughCircles ------------ -Finds circles in a grayscale image using the Hough transform. +Finds circles in a grayscale image using a modification of the Hough transform. .. ocv:function:: void HoughCircles( InputArray image, OutputArray circles, int method, double dp, double minDist, double param1=100, double param2=100, int minRadius=0, int maxRadius=0 ) @@ -308,8 +308,6 @@ Finds circles in a grayscale image using the Hough transform. :param maxRadius: Maximum circle radius. -The function finds circles in a grayscale image using a modification of the Hough transform. - Example: :: #include @@ -343,6 +341,8 @@ Example: :: return 0; } +.. note:: The elements of the output vector of found circles ("circles" in the above example) are sorted in descending order of accumulator values. This way, the centres with the most supporting pixels appear first. + .. note:: Usually the function detects the centers of circles well. However, it may fail to find correct radii. You can assist to the function by specifying the radius range ( ``minRadius`` and ``maxRadius`` ) if you know it. Or, you may ignore the returned radius, use only the center, and find the correct radius using an additional procedure. .. seealso:: diff --git a/modules/imgproc/src/hough.cpp b/modules/imgproc/src/hough.cpp index 88482b4a8f..23cd41a5b3 100644 --- a/modules/imgproc/src/hough.cpp +++ b/modules/imgproc/src/hough.cpp @@ -1,4 +1,4 @@ -/*M/////////////////////////////////////////////////////////////////////////////////////// +/*M/////////////////////////////////////////////////////////////////////////////////////// // // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. // @@ -1024,10 +1024,14 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist, CvSeqReader reader; edges.reset(cvCreateMat( img->rows, img->cols, CV_8UC1 )); + + // Use the Canny Edge Detector to detect all the edges in the image. cvCanny( img, edges, MAX(canny_threshold/2,1), canny_threshold, 3 ); dx.reset(cvCreateMat( img->rows, img->cols, CV_16SC1 )); dy.reset(cvCreateMat( img->rows, img->cols, CV_16SC1 )); + + /*Use the Sobel Derivative to compute the local gradient of all the non-zero pixels in the edge image.*/ cvSobel( img, dx, 1, 0, 3 ); cvSobel( img, dy, 0, 1, 3 ); @@ -1038,6 +1042,8 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist, cvZero(accum); storage.reset(cvCreateMemStorage()); + /* Create sequences for the nonzero pixels in the edge image and the centers of circles + which could be detected.*/ nz = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage ); centers = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), storage ); @@ -1118,7 +1124,8 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist, sort_buf.resize( MAX(center_count,nz_count) ); cvCvtSeqToArray( centers, &sort_buf[0] ); - + /*Sort candidate centers in descending order of their accumulator values, so that the centers + with the most supporting pixels appear first.*/ std::sort(sort_buf.begin(), sort_buf.begin() + center_count, cv::hough_cmp_gt(adata)); cvClearSeq( centers ); cvSeqPushMulti( centers, &sort_buf[0], center_count ); @@ -1173,6 +1180,7 @@ icvHoughCirclesGradient( CvMat* img, float dp, float min_dist, continue; dist_buf->cols = nz_count1; cvPow( dist_buf, dist_buf, 0.5 ); + // Sort non-zero pixels according to their distance from the center. std::sort(sort_buf.begin(), sort_buf.begin() + nz_count1, cv::hough_cmp_gt((int*)ddata)); dist_sum = start_dist = ddata[sort_buf[nz_count1-1]];