traincascade.markdown 13.3 KB
Newer Older
wester committed
1 2 3 4 5 6
Cascade Classifier Training {#tutorial_traincascade}
===========================

Introduction
------------

a  
Kai Westerkamp committed
7 8 9 10
The work with a cascade classifier inlcudes two major stages: training and detection. Detection
stage is described in a documentation of objdetect module of general OpenCV documentation.
Documentation gives some basic information about cascade classifier. Current guide is describing how
to train a cascade classifier: preparation of the training data and running the training application.
wester committed
11 12 13

### Important notes

a  
Kai Westerkamp committed
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
There are two applications in OpenCV to train cascade classifier: opencv_haartraining and
opencv_traincascade. opencv_traincascade is a newer version, written in C++ in accordance to
OpenCV 2.x API. But the main difference between this two applications is that opencv_traincascade
supports both Haar @cite Viola01 and @cite Liao2007 (Local Binary Patterns) features. LBP features
are integer in contrast to Haar features, so both training and detection with LBP are several times
faster then with Haar features. Regarding the LBP and Haar detection quality, it depends on
training: the quality of training dataset first of all and training parameters too. It's possible to
train a LBP-based classifier that will provide almost the same quality as Haar-based one.

opencv_traincascade and opencv_haartraining store the trained classifier in different file
formats. Note, the newer cascade detection interface (see CascadeClassifier class in objdetect
module) support both formats. opencv_traincascade can save (export) a trained cascade in the older
format. But opencv_traincascade and opencv_haartraining can not load (import) a classifier in
another format for the futher training after interruption.

Note that opencv_traincascade application can use TBB for multi-threading. To use it in multicore
mode OpenCV must be built with TBB.

Also there are some auxilary utilities related to the training.

-   opencv_createsamples is used to prepare a training dataset of positive and test samples.
    opencv_createsamples produces dataset of positive samples in a format that is supported by
    both opencv_haartraining and opencv_traincascade applications. The output is a file
    with \*.vec extension, it is a binary format which contains images.
-   opencv_performance may be used to evaluate the quality of classifiers, but for trained by
    opencv_haartraining only. It takes a collection of marked up images, runs the classifier and
    reports the performance, i.e. number of found objects, number of missed objects, number of
    false alarms and other information.

Since opencv_haartraining is an obsolete application, only opencv_traincascade will be described
futher. opencv_createsamples utility is needed to prepare a training data for opencv_traincascade,
so it will be described too.

Training data preparation
-------------------------

For training we need a set of samples. There are two types of samples: negative and positive.
Negative samples correspond to non-object images. Positive samples correspond to images with
detected objects. Set of negative samples must be prepared manually, whereas set of positive samples
is created using opencv_createsamples utility.
wester committed
54 55 56

### Negative Samples

a  
Kai Westerkamp committed
57 58 59 60 61 62 63 64
Negative samples are taken from arbitrary images. These images must not contain detected objects.
Negative samples are enumerated in a special file. It is a text file in which each line contains an
image filename (relative to the directory of the description file) of negative sample image. This
file must be created manually. Note that negative samples and sample images are also called
background samples or background images, and are used interchangeably in this document.
Described images may be of different sizes. But each image should be (but not nessesarily) larger
than a training window size, because these images are used to subsample negative image to the
training size.
wester committed
65

a  
Kai Westerkamp committed
66
An example of description file:
wester committed
67 68 69 70 71 72 73 74 75 76 77 78 79

Directory structure:
@code{.text}
/img
  img1.jpg
  img2.jpg
bg.txt
@endcode
File bg.txt:
@code{.text}
img/img1.jpg
img/img2.jpg
@endcode
a  
Kai Westerkamp committed
80
### Positive Samples
wester committed
81

a  
Kai Westerkamp committed
82 83
Positive samples are created by opencv_createsamples utility. They may be created from a single
image with object or from a collection of previously marked up images.
wester committed
84

a  
Kai Westerkamp committed
85 86 87 88 89
Please note that you need a large dataset of positive samples before you give it to the mentioned
utility, because it only applies perspective transformation. For example you may need only one
positive sample for absolutely rigid object like an OpenCV logo, but you definetely need hundreds
and even thousands of positive samples for faces. In the case of faces you should consider all the
race and age groups, emotions and perhaps beard styles.
wester committed
90

a  
Kai Westerkamp committed
91 92 93 94
So, a single object image may contain a company logo. Then a large set of positive samples is
created from the given object image by random rotating, changing the logo intensity as well as
placing the logo on arbitrary background. The amount and range of randomness can be controlled by
command line arguments of opencv_createsamples utility.
wester committed
95

a  
Kai Westerkamp committed
96
Command line arguments:
wester committed
97

a  
Kai Westerkamp committed
98
-   -vec \<vec_file_name\>
wester committed
99

a  
Kai Westerkamp committed
100
    Name of the output file containing the positive samples for training.
wester committed
101

a  
Kai Westerkamp committed
102
-   -img \<image_file_name\>
wester committed
103

a  
Kai Westerkamp committed
104 105 106 107 108 109 110 111
    Source object image (e.g., a company logo).

-   -bg \<background_file_name\>

    Background description file; contains a list of images which are used as a background for
    randomly distorted versions of the object.

-   -num \<number_of_samples\>
wester committed
112

a  
Kai Westerkamp committed
113
    Number of positive samples to generate.
wester committed
114

a  
Kai Westerkamp committed
115
-   -bgcolor \<background_color\>
wester committed
116

a  
Kai Westerkamp committed
117 118 119 120
    Background color (currently grayscale images are assumed); the background color denotes the
    transparent color. Since there might be compression artifacts, the amount of color tolerance
    can be specified by -bgthresh. All pixels withing bgcolor-bgthresh and bgcolor+bgthresh range
    are interpreted as transparent.
wester committed
121

a  
Kai Westerkamp committed
122 123
-   -bgthresh \<background_color_threshold\>
-   -inv
wester committed
124

a  
Kai Westerkamp committed
125
    If specified, colors will be inverted.
wester committed
126

a  
Kai Westerkamp committed
127
-   -randinv
wester committed
128

a  
Kai Westerkamp committed
129
    If specified, colors will be inverted randomly.
wester committed
130

a  
Kai Westerkamp committed
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 160 161 162 163 164 165 166 167 168
-   -maxidev \<max_intensity_deviation\>

    Maximal intensity deviation of pixels in foreground samples.

-   -maxxangle \<max_x_rotation_angle\>
-   -maxyangle \<max_y_rotation_angle\>
-   -maxzangle \<max_z_rotation_angle\>

    Maximum rotation angles must be given in radians.

-   -show

    Useful debugging option. If specified, each sample will be shown. Pressing Esc will continue
    the samples creation process without.

-   -w \<sample_width\>

    Width (in pixels) of the output samples.

-   -h \<sample_height\>

    Height (in pixels) of the output samples.

For following procedure is used to create a sample object instance: The source image is rotated
randomly around all three axes. The chosen angle is limited my -max?angle. Then pixels having the
intensity from [bg_color-bg_color_threshold; bg_color+bg_color_threshold] range are
interpreted as transparent. White noise is added to the intensities of the foreground. If the -inv
key is specified then foreground pixel intensities are inverted. If -randinv key is specified then
algorithm randomly selects whether inversion should be applied to this sample. Finally, the obtained
image is placed onto an arbitrary background from the background description file, resized to the
desired size specified by -w and -h and stored to the vec-file, specified by the -vec command line
option.

Positive samples also may be obtained from a collection of previously marked up images. This
collection is described by a text file similar to background description file. Each line of this
file corresponds to an image. The first element of the line is the filename. It is followed by the
number of object instances. The following numbers are the coordinates of objects bounding rectangles
(x, y, width, height).
wester committed
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186

An example of description file:

Directory structure:
@code{.text}
/img
  img1.jpg
  img2.jpg
info.dat
@endcode
File info.dat:
@code{.text}
img/img1.jpg  1  140 100 45 45
img/img2.jpg  2  100 200 50 50   50 30 25 25
@endcode
Image img1.jpg contains single object instance with the following coordinates of bounding rectangle:
(140, 100, 45, 45). Image img2.jpg contains two object instances.

a  
Kai Westerkamp committed
187 188
In order to create positive samples from such collection, -info argument should be specified instead
of \`-img\`:
wester committed
189

a  
Kai Westerkamp committed
190
-   -info \<collection_file_name\>
wester committed
191

a  
Kai Westerkamp committed
192
    Description file of marked up images collection.
wester committed
193

a  
Kai Westerkamp committed
194 195 196
The scheme of samples creation in this case is as follows. The object instances are taken from
images. Then they are resized to target samples size and stored in output vec-file. No distortion is
applied, so the only affecting arguments are -w, -h, -show and -num.
wester committed
197

a  
Kai Westerkamp committed
198 199
opencv_createsamples utility may be used for examining samples stored in positive samples file. In
order to do this only -vec, -w and -h parameters should be specified.
wester committed
200

a  
Kai Westerkamp committed
201 202 203
Note that for training, it does not matter how vec-files with positive samples are generated. But
opencv_createsamples utility is the only one way to collect/create a vector file of positive
samples, provided by OpenCV.
wester committed
204

a  
Kai Westerkamp committed
205 206
Example of vec-file is available here opencv/data/vec_files/trainingfaces_24-24.vec. It can be
used to train a face detector with the following window size: -w 24 -h 24.
wester committed
207

a  
Kai Westerkamp committed
208 209
Cascade Training
----------------
wester committed
210

a  
Kai Westerkamp committed
211 212 213
The next step is the training of classifier. As mentioned above opencv_traincascade or
opencv_haartraining may be used to train a cascade classifier, but only the newer
opencv_traincascade will be described futher.
wester committed
214

a  
Kai Westerkamp committed
215
Command line arguments of opencv_traincascade application grouped by purposes:
wester committed
216

a  
Kai Westerkamp committed
217
-#  Common arguments:
wester committed
218

a  
Kai Westerkamp committed
219
    -   -data \<cascade_dir_name\>
wester committed
220

a  
Kai Westerkamp committed
221
        Where the trained classifier should be stored.
wester committed
222

a  
Kai Westerkamp committed
223
    -   -vec \<vec_file_name\>
wester committed
224

a  
Kai Westerkamp committed
225
        vec-file with positive samples (created by opencv_createsamples utility).
wester committed
226

a  
Kai Westerkamp committed
227
    -   -bg \<background_file_name\>
wester committed
228

a  
Kai Westerkamp committed
229
        Background description file.
wester committed
230

a  
Kai Westerkamp committed
231 232
    -   -numPos \<number_of_positive_samples\>
    -   -numNeg \<number_of_negative_samples\>
wester committed
233

a  
Kai Westerkamp committed
234
        Number of positive/negative samples used in training for every classifier stage.
wester committed
235

a  
Kai Westerkamp committed
236
    -   -numStages \<number_of_stages\>
wester committed
237

a  
Kai Westerkamp committed
238
        Number of cascade stages to be trained.
wester committed
239

a  
Kai Westerkamp committed
240
    -   -precalcValBufSize \<precalculated_vals_buffer_size_in_Mb\>
wester committed
241

a  
Kai Westerkamp committed
242
        Size of buffer for precalculated feature values (in Mb).
wester committed
243

a  
Kai Westerkamp committed
244
    -   -precalcIdxBufSize \<precalculated_idxs_buffer_size_in_Mb\>
wester committed
245

a  
Kai Westerkamp committed
246 247
        Size of buffer for precalculated feature indices (in Mb). The more memory you have the
        faster the training process.
wester committed
248

a  
Kai Westerkamp committed
249
    -   -baseFormatSave
wester committed
250

a  
Kai Westerkamp committed
251 252
        This argument is actual in case of Haar-like features. If it is specified, the cascade will
        be saved in the old format.
wester committed
253

a  
Kai Westerkamp committed
254
    -   -numThreads \<max_number_of_threads\>
wester committed
255

a  
Kai Westerkamp committed
256 257
        Maximum number of threads to use during training. Notice that the actual number of used
        threads may be lower, depending on your machine and compilation options.
wester committed
258

a  
Kai Westerkamp committed
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
    -   -acceptanceRatioBreakValue \<break_value\>

        This argument is used to determine how precise your model should keep learning and when to stop.
        A good guideline is to train not further than 10e-5, to ensure the model does not overtrain on your training data.
        By default this value is set to -1 to disable this feature.

-#  Cascade parameters:

    -   -stageType \<BOOST(default)\>

        Type of stages. Only boosted classifier are supported as a stage type at the moment.

    -   -featureType\<{HAAR(default), LBP}\>

        Type of features: HAAR - Haar-like features, LBP - local binary patterns.

    -   -w \<sampleWidth\>
    -   -h \<sampleHeight\>

        Size of training samples (in pixels). Must have exactly the same values as used during
        training samples creation (opencv_createsamples utility).

-#  Boosted classifer parameters:

    -   -bt \<{DAB, RAB, LB, GAB(default)}\>

        Type of boosted classifiers: DAB - Discrete AdaBoost, RAB - Real AdaBoost, LB - LogitBoost,
        GAB - Gentle AdaBoost.

    -   -minHitRate \<min_hit_rate\>

        Minimal desired hit rate for each stage of the classifier. Overall hit rate may be estimated
        as (min_hit_rate\^number_of_stages).

    -   -maxFalseAlarmRate \<max_false_alarm_rate\>

        Maximal desired false alarm rate for each stage of the classifier. Overall false alarm rate
        may be estimated as (max_false_alarm_rate\^number_of_stages).

    -   -weightTrimRate \<weight_trim_rate\>

        Specifies whether trimming should be used and its weight. A decent choice is 0.95.

    -   -maxDepth \<max_depth_of_weak_tree\>

        Maximal depth of a weak tree. A decent choice is 1, that is case of stumps.

    -   -maxWeakCount \<max_weak_tree_count\>

        Maximal count of weak trees for every cascade stage. The boosted classifier (stage) will
        have so many weak trees (\<=maxWeakCount), as needed to achieve the
        given -maxFalseAlarmRate.
wester committed
311

a  
Kai Westerkamp committed
312
-#  Haar-like feature parameters:
wester committed
313

a  
Kai Westerkamp committed
314
    -   -mode \<BASIC (default) | CORE | ALL\>
wester committed
315

a  
Kai Westerkamp committed
316 317 318
        Selects the type of Haar features set used in training. BASIC use only upright features,
        while ALL uses the full set of upright and 45 degree rotated feature set. See @cite Lienhart02
        for more details.
wester committed
319

a  
Kai Westerkamp committed
320
-#  Local Binary Patterns parameters:
wester committed
321

a  
Kai Westerkamp committed
322
    Local Binary Patterns don't have parameters.
wester committed
323

a  
Kai Westerkamp committed
324 325 326 327
After the opencv_traincascade application has finished its work, the trained cascade will be saved
in cascade.xml file in the folder, which was passed as -data parameter. Other files in this folder
are created for the case of interrupted training, so you may delete them after completion of
training.
wester committed
328

a  
Kai Westerkamp committed
329
Training is finished and you can test you cascade classifier!