4 This is the open-source C++ implementation of the folded hierarchy
5 of classifiers for cat detection described in
7 F. Fleuret and D. Geman, "Stationary Features and Cat Detection",
8 Journal of Machine Learning Research (JMLR), 2008, to appear.
10 Please use that citation when referring to this software.
12 Contact Francois Fleuret at fleuret@idiap.ch for comments and bug
17 If you have installed the RateMyKitten images provided on
19 http://www.idiap.ch/folded-ctf
21 in the source directory, everything should work seamlessly by
22 invoking the ./run.sh script.
26 * Compile the source code entirely
28 * Generate the "pool file" containing the uncompressed images
29 converted to gray levels, labeled with the ground truth.
31 * Run 20 rounds of training / test (ten rounds for each of HB and
32 H+B detectors with different random seeds)
34 You can run the full thing with the following commands if you have
37 > wget http://www.idiap.ch/folded-ctf/data/folding-gpl.tgz
38 > tar zxvf folding-gpl.tgz
40 > wget http://www.idiap.ch/folded-ctf/data/rmk.tgz
44 Note that every one of the twenty rounds of training/testing takes
45 more than three days on a powerful PC. However, the script detects
46 already running computations by looking at the presence of the
47 corresponding result directories. Hence, it can be run in parallel
48 on several machines as long as they see the same result directory.
50 When all or some of the experimental rounds are over, you can
51 generate the ROC curves by invoking the ./graph.sh script. You need
52 a fairly recent version of Gnuplot.
54 This program was developed on Debian GNU/Linux computers with the
55 following main tool versions
57 * GNU bash, version 3.2.39
59 * gnuplot 4.2 patchlevel 4
61 Due to approximations in the optimized arithmetic operations with
62 g++, results may vary with different versions of the compiler
63 and/or different levels of optimization.
67 To set the value of a parameter, just add an argument of the form
68 --parameter-name=value before the commands that should take it into
71 For every parameter below, the default value is given between
82 * pictures-for-article ("no")
84 Should the pictures be generated for printing in black and white.
86 * pool-name (no default)
88 The scene pool file name.
90 * test-pool-name (no default)
92 Should we use a separate test pool file. If none is given, then
93 the test scenes are taken at random from the main pool file
94 according to proportion-for-test.
96 * detector-name ("default.det")
98 Where to write or from where to read the detector.
100 * result-path ("/tmp/")
102 In what directory should we save all the produced files during the
105 * loss-type ("exponential")
107 What kind of loss to use for the boosting. While different losses
108 are implemented in the code, only the exponential has been
113 How many images to process in list_to_pool or when using the
114 write-pool-images command.
118 Maximum depth of the decision trees used as weak learners in the
119 classifier. The default value of 1 corresponds to stumps.
121 * proportion-negative-cells-for-training (0.025)
123 Overall proportion of negative cells to use during learning (we
124 sample among for boosting).
126 * nb-negative-samples-per-positive (10)
128 How many negative cells to sample for every positive cell during
131 * nb-features-for-boosting-optimization (10000)
133 How many pose-indexed features to look at for optimization at
134 every step of boosting.
136 * force-head-belly-independence ("no")
138 Should we force the independence between the two levels of the
139 detector (i.e. make an H+B detector)
141 * nb-weak-learners-per-classifier (100)
143 This parameter corresponds to the value U in the article.
145 * nb-classifiers-per-level (25)
147 This parameter corresponds to the value B in the article.
151 How many levels in the hierarchy.
153 * proportion-for-train (0.75)
155 The proportion of scenes from the pool to use for training.
157 * proportion-for-validation (0.25)
159 The proportion of scenes from the pool to use for estimating the
162 * proportion-for-test (0.25)
164 The proportion of scenes from the pool to use to test the
167 * write-validation-rocs ("no")
169 Should we compute and save the ROC curves estimated on the
170 validation set during training.
172 * write-parse-images ("no")
174 Should we save one image for every test scene with the resulting
175 alarms. This option generates a lot of images for every round and
176 is switched off by default. Switch it on to produce images such as
177 the full page of results in the paper.
179 * write-tag-images ("no")
181 Should we save the (very large) tag images when saving the
184 * wanted-true-positive-rate (0.75)
186 What is the target true positive rate. Note that this is the rate
187 without post-processing and without pose tolerance in the
188 definition of a true positive.
190 * nb-wanted-true-positive-rates (10)
192 How many true positive rates to visit to generate the pseudo-ROC.
194 * min-head-radius (25)
196 What is the radius of the smallest heads we are looking for.
198 * max-head-radius (200)
200 What is the radius of the largest heads we are looking for.
202 * root-cell-nb-xy-per-radius (5)
204 What is the size of a (x,y) square cell with respect to the radius
207 * pi-feature-window-min-size (0.1)
209 What is the minimum pose-indexed feature windows size with respect
210 to the frame they are defined in.
212 * nb-scales-per-power-of-two (5)
214 How many scales do we visit between two powers of two.
216 * progress-bar ("yes")
218 Should we display a progress bar during long computations.
224 Open the pool of scenes.
228 Create a new detector from the training scenes.
232 Compute the thresholds of the detector classifiers from the
233 validation set to obtain the required wanted-true-positive-rate.
237 Run the detector on the test scenes.
239 * sequence-test-detector
241 Visit nb-wanted-true-positive-rates rates between 0 and
242 wanted-true-positive-rate, for each compute the detector
243 thresholds on the validation set and estimate the error rate on
248 Write the current detector to the file detector-name
252 Read a detector from the file detector-name
256 For every of the first nb-images of the pool, save one PNG image
257 with the ground truth, one with the corresponding referential at
258 the reference scale, and one with the feature material-feature-nb
259 from the detector. This last image is not saved if either no
260 detector has been read/trained or if no feature number has been