5 This is the documentation for the open-source C++ implementation of
6 the folded hierarchy of classifiers for cat detection described in
8 F. Fleuret and D. Geman, "Stationary Features and Cat Detection",
9 Journal of Machine Learning Research (JMLR), 2008, to appear.
11 Please use that citation when referring to this software.
13 Contact Francois Fleuret at fleuret@idiap.ch for comments and bug
19 If you have installed the RateMyKitten images provided on
21 http://www.idiap.ch/folded-ctf
23 in the source directory, everything should work seamlessly by
24 invoking the ./run.sh script.
28 * Compile the source code entirely
30 * Generate the "pool file" containing the uncompressed images
31 converted to gray levels, labelled with the ground truth.
33 * Run 20 rounds of training / test (ten rounds for each of HB and
34 H+B detectors with different random seeds)
36 You can run the full thing with the following commands if you have
39 > wget http://www.idiap.ch/folded-ctf/data/folding-gpl.tgz
40 > tar zxvf folding-gpl.tgz
42 > wget http://www.idiap.ch/folded-ctf/data/rmk.tgz
46 Note that for every round, we have to fully train a detector and run
47 the test through all the test scenes at 10 different thresholds,
48 including at very conservative thresholds for which the
49 computational efforts is very high. Hence, each round takes more
50 than three days on a powerful PC. However, the script detects
51 already running computations by looking at the presence of the
52 corresponding result directories. Hence, it can be run in parallel
53 on several machines as long as they see the same result directory.
55 When all or some of the experimental rounds are over, you can
56 generate the ROC curves by invoking the ./graph.sh script. You need
57 a fairly recent version of Gnuplot.
59 This program was developed on Debian GNU/Linux computers with the
60 following main tool versions
62 * GNU bash, version 3.2.39
64 * gnuplot 4.2 patchlevel 4
66 Due to approximations in the optimized arithmetic operations with
67 g++, results may vary with different versions of the compiler and/or
68 different levels of optimization.
73 The main command has to be invoked with a list of parameter values,
74 followed by commands to execute.
76 To set the value of a parameter, just add an argument of the form
77 --parameter-name=value before the commands that should take it into
80 For instance, to open a scene pool ./something.pool, train a
81 detector and save it, you would do
83 ./folding --pool-name=./something.pool open-pool train-detector write-detector
88 For every parameter below, the default value is given between
99 * pictures-for-article ("no")
101 Should the pictures be generated for printing in black and white.
105 The scene pool file name.
107 * test-pool-name (none)
109 Should we use a separate test pool file. If none is given, then
110 the test scenes are taken at random from the main pool file
111 according to proportion-for-test.
113 * detector-name ("default.det")
115 Where to write or from where to read the detector.
117 * result-path ("/tmp/")
119 In what directory should we save all the produced files during the
122 * loss-type ("exponential")
124 What kind of loss to use for the boosting. While different losses
125 are implemented in the code, only the exponential has been
130 How many images to process in list_to_pool or when using the
131 write-pool-images command.
135 Maximum depth of the decision trees used as weak learners in the
136 classifier. The default value of 1 corresponds to stumps.
138 * proportion-negative-cells-for-training (0.025)
140 Overall proportion of negative cells to use during learning (we
141 sample among them for boosting).
143 * nb-negative-samples-per-positive (10)
145 How many negative cells to sample for every positive cell during
148 * nb-features-for-boosting-optimization (10000)
150 How many pose-indexed features to look at for optimization at
151 every step of boosting.
153 * force-head-belly-independence ("no")
155 Should we force the independence between the two levels of the
156 detector (i.e. make an H+B detector)
158 * nb-weak-learners-per-classifier (100)
160 This parameter corresponds to the value U in the article.
162 * nb-classifiers-per-level (25)
164 This parameter corresponds to the value B in the article.
168 How many levels in the hierarchy.
170 * proportion-for-train (0.75)
172 The proportion of scenes from the pool to use for training.
174 * proportion-for-validation (0.25)
176 The proportion of scenes from the pool to use for estimating the
179 * proportion-for-test (0.25)
181 The proportion of scenes from the pool to use to test the
184 * write-validation-rocs ("no")
186 Should we compute and save the ROC curves estimated on the
187 validation set during training.
189 * write-parse-images ("no")
191 Should we save one image for every test scene with the resulting
192 alarms. This option generates a lot of images for every round and
193 is switched off by default. Switch it on to produce images such as
194 the full page of results in the paper.
196 * write-tag-images ("no")
198 Should we save the (very large) tag images when saving the
201 * wanted-true-positive-rate (0.75)
203 What is the target true positive rate. Note that this is the rate
204 without post-processing and without pose tolerance in the
205 definition of a true positive.
207 * nb-wanted-true-positive-rates (10)
209 How many true positive rates to visit to generate the pseudo-ROC.
211 * min-head-radius (25)
213 What is the radius of the smallest heads we are looking for.
215 * max-head-radius (200)
217 What is the radius of the largest heads we are looking for.
219 * root-cell-nb-xy-per-radius (5)
221 What is the size of a (x,y) square cell with respect to the radius
224 * pi-feature-window-min-size (0.1)
226 What is the minimum pose-indexed feature windows size with respect
227 to the frame they are defined in.
229 * nb-scales-per-power-of-two (5)
231 How many scales do we visit between two powers of two.
233 * progress-bar ("yes")
235 Should we display a progress bar during long computations.
242 Open the pool of scenes.
246 Create a new detector from the training scenes.
250 Compute the thresholds of the detector classifiers from the
251 validation set to obtain the required wanted-true-positive-rate.
255 Run the detector on the test scenes.
257 * sequence-test-detector
259 Visit nb-wanted-true-positive-rates rates between 0 and
260 wanted-true-positive-rate, for each compute the detector
261 thresholds on the validation set and estimate the error rate on
266 Write the current detector to the file detector-name
270 Read a detector from the file detector-name
274 For every of the first nb-images of the pool, save one PNG image
275 with the ground truth, one with the corresponding referential at
276 the reference scale, and one with the feature material-feature-nb
277 from the detector. This last image is not saved if either no
278 detector has been read/trained or if no feature number has been