1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
/**
\page tutorial-imgproc-cht Tutorial: Gradient-based Circle Hough Transform
\tableofcontents
\section imgproc_cht_intro Introduction
The Circle Hough Transform (*CHT*) is an image processing algorithm that permits to
detect circles in an image. We refer the interested reader to the
[Wikipedia page](https://en.wikipedia.org/wiki/Circle_Hough_Transform) to have a better
understanding on the principles of the algorithm.
The ViSP implementation relies on the Gradient-based implementation of the
algorithm.
During the step where the algorithm votes for center candidates, we use the gradient information
in order to reduce the dimensionality of the search space. Instead of voting in circular pattern,
we vote along a straight line that follows the gradient.
\image html img-tutorial-cht-center-votes.png
Then, during the step where the algorithm votes for radius candidates for each center candidate,
we check the colinearity between the gradient at a considered point and the line which links the
point towards the center candidate. If they are "enough" colinear, we increment the corresponding
radius bin vote by 1. (*NB*: instead of incrementing one bin by one, we increment two bins by a number between
0 and 1 in our implementation to be more robust against the limits min and max of the radius and
the bin size). The "enough" characteristic is controlled by the circle perfectness
parameter.
\image html img-tutorial-cht-radius-votes.png
\section imgproc_cht_howto How to use the tutorial
It is possible to configure the `vpCircleHoughTransform` class using a JSON file.
To do so, you need to install [JSON for modern C++](https://visp-doc.inria.fr/doxygen/visp-daily/supported-third-parties.html#soft_tool_json)
and compile ViSP with it.
You can also configure the `vpCircleHoughTransform` class using command line arguments.
To know what are the different command line arguments the software accept, please run:
```
$ cd tutorial/imgproc/hough-transform
$ ./tutorial-circle-hough --help
```
To run the software on an image like `coins2.jpg` provided with the tutorial and using a JSON configuration file, please run:
```
$ ./tutorial-circle-hough --input coins2.jpg --config config/detector_img.json
```
If you would rather use the command line arguments, please run:
```
$ ./tutorial-circle-hough --input coins2.jpg \
--averaging-window-size 5 \
--canny-backend opencv-backend \
--filtering-type gaussianblur+scharr-filtering \
--canny-thresh -1 -1 \
--lower-canny-ratio 0.6 \
--upper-canny-ratio 0.9 \
--gaussian-kernel 5 \
--gaussian-sigma 1 \
--dilatation-kernel-size 5 \
--center-thresh 70 \
--circle-probability-thresh 0.725 \
--radius-limits 34 75 \
--merging-thresh 5 5 \
--circle-perfectness 0.65 \
--circle-probability-thresh 0.725 \
--center-xlim 0 1920 \
--center-ylim 0 1080 \
--expected-nb-centers -1 \
--edge-filter 3 \
--gradient-kernel 3
```
\note The configuration file `config/detector_img.json` has been tuned to detect circles in the image `coins2.jpg`.
If the detections seem a bit off, you might need to change the parameters in `config/detector_img.json` or in the
command line.
\note The default values of the program corresponds to these fine-tuned parameters. Running the program
without any additional parameters should give the same result:
```
./tutorial-circle-hough
```
\subsection imgproc_cht_howto_video How to use a video
You can use the software to run circle detection on a video saved as a
sequence of images that are named
```
${BASENAME}%d.png
```
For instance with `${BASENAME}` = `video_`, you can have the following list
of images: `video_0001.png`, `video_0002.png` and so on.
To run the software using a JSON configuration file, please run:
```
$ ./tutorial-circle-hough --input /path/to/video/${BASENAME}%d.png --config config/detector_img.json
```
To run the software using the command arguments, please run:
```
$ ./tutorial-circle-hough --input /path/to/video/${BASENAME}%d.png \
--averaging-window-size 5 \
--canny-backend opencv-backend \
--filtering-type gaussianblur+scharr-filtering \
--canny-thresh -1 -1 \
--lower-canny-ratio 0.6 \
--upper-canny-ratio 0.9 \
--gaussian-kernel 5 \
--gaussian-sigma 1 \
--dilatation-kernel-size 5 \
--center-thresh 70 \
--circle-probability-thresh 0.725 \
--radius-limits 34 75 \
--merging-thresh 5 5 \
--circle-perfectness 0.65 \
--circle-probability-thresh 0.725 \
--center-xlim 0 1920 \
--center-ylim 0 1080 \
--expected-nb-centers -1 \
--edge-filter 3 \
--gradient-kernel 3
```
\section imgproc_cht_explanations Detailed explanations about the tutorial
If you decide to use a video as input, the relevant piece of code that permits to
perform circle detection on the successive images of the video is the following:
\snippet tutorial-circle-hough.cpp Manage video
If you decide to use a single image as input, the relevant piece of code that permits to
perform circle detection on the image is the following:
\snippet tutorial-circle-hough.cpp Manage single image
If you did not use a JSON file to configure the `vpCircleHoughTransform` detector,
the following structure defines the parameters of the algorithm based on the
command line arguments:
\snippet tutorial-circle-hough.cpp Algo params
The initialization of the algorithm is performed in the following piece of code.
If a JSON configuration file is given as input configuration, it will be preferred
to the command line arguments:
\snippet tutorial-circle-hough.cpp Algo init
To run the circle detection, you must call the following method:
\snippet tutorial-circle-hough.cpp Run detection
The call to vpCircleHoughTransform::getDetectionsProbabilities permits to know the confidence in each detection.
It is sorted in the same way that are sorted the detections.
You could have also used the following method to get only the `num_best` best
detections:
\code
int num_best; // Set it to the number of circles you want to keep
std::vector<vpImageCircle> detections = detector.detect(I, num_best);
\endcode
Then, you can iterate on the vector of detections using a synthax similar to the following:
\snippet tutorial-circle-hough.cpp Iterate detections
*/
|
