2 ######################################################################
5 This is the C++ implementation of the folded hierarchy of
6 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 cite this paper when referring to this software.
13 ######################################################################
16 This program was developed on Debian GNU/Linux computers with the
17 following main tool versions
19 * GNU bash, version 3.2.39
21 * gnuplot 4.2 patchlevel 4
23 If you have installed the RateMyKitten images provided on
25 http://www.idiap.ch/folded-ctf
27 in the source directory, everything should work seamlessly by
28 invoking the ./run.sh script. It will
30 * Compile the source code entirely
32 * Generate the "pool file" containing the uncompressed images
33 converted to gray levels, labeled with the ground truth.
35 * Run 20 rounds of training / test (ten rounds for each of HB and
36 H+B detectors with different random seeds)
38 You can also run the full thing with the following commands if you
41 > wget http://www.idiap.ch/folded-ctf/not-public-yet/data/folding-gpl.tgz
42 > tar zxvf folding-gpl.tgz
44 > wget http://www.idiap.ch/folded-ctf/not-public-yet/data/rmk.tgz
48 Note that every one of the twenty rounds of training/testing takes
49 more than three days on a powerful PC. However, the script detects
50 already running computations by looking at the presence of the
51 corresponding result directory. Hence, it can be run in parallel on
52 several machines as long as they see the same result directory.
54 When all or some of the experimental rounds are over, you can
55 generate the ROC curves by invoking the ./graph.sh script.
57 You are welcome to send bug reports and comments to fleuret@idiap.ch
59 ######################################################################
62 To set the value of a parameter during an experiment, just add an
63 argument of the form --parameter-name=value before the commands that
64 should take into account that value.
66 For every parameter below, the default value is given between
77 * pictures-for-article ("no")
79 Should the pictures be generated for printing in black and white.
81 * pool-name (no default)
83 Where are the data to use
85 * test-pool-name (no default)
87 Should we use a separate pool file, and ignore proportion-for-test
90 * detector-name ("default.det")
92 Where to write or from where to read the detector.
94 * result-path ("/tmp/")
96 In what directory should we save all the produced files during the
99 * loss-type ("exponential")
101 What kind of loss to use for the boosting. While different losses
102 are implemented in the code, only the exponential has been
107 How many images to process in list_to_pool or when using the
108 write-pool-images command.
112 Maximum depth of the decision trees used as weak learners in the
113 classifier. The default value corresponds to stumps.
115 * proportion-negative-cells-for-training (0.025)
117 Overall proportion of negative cells to use during learning (we
120 * nb-negative-samples-per-positive (10)
122 How many negative cells to sample for every positive cell during
125 * nb-features-for-boosting-optimization (10000)
127 How many pose-indexed features to use at every step of boosting.
129 * force-head-belly-independence ("no")
131 Should we force the independence between the two levels of the
132 detector (i.e. make an H+B detector)
134 * nb-weak-learners-per-classifier (10)
136 This parameter corresponds to the value U in the JMLR paper, and
137 should be set to 100.
139 * nb-classifiers-per-level (25)
141 This parameter corresponds to the value B in the JMLR paper.
145 How many levels in the hierarchy. This should be 2 for the JMLR
148 * proportion-for-train (0.5)
150 The proportion of scenes from the pool to use for training.
152 * proportion-for-validation (0.25)
154 The proportion of scenes from the pool to use for estimating the
157 * proportion-for-test (0.25)
159 The proportion of scenes from the pool to use to test the
162 * write-validation-rocs ("no")
164 Should we compute and save the ROC curves estimated on the
165 validation set during training.
167 * write-parse-images ("no")
169 Should we save one image for every test scene with the resulting
172 * write-tag-images ("no")
174 Should we save the (very large) tag images when saving the
177 * wanted-true-positive-rate (0.5)
179 What is the target true positive rate. Note that this is the rate
180 without post-processing and without pose tolerance in the
181 definition of a true positive.
183 * nb-wanted-true-positive-rates (10)
185 How many true positive rates to visit to generate the pseudo-ROC.
187 * min-head-radius (25)
189 What is the radius of the smallest heads we are looking for.
191 * max-head-radius (200)
193 What is the radius of the largest heads we are looking for.
195 * root-cell-nb-xy-per-radius (5)
197 What is the size of a (x,y) square cell with respect to the radius
200 * pi-feature-window-min-size (0.1)
202 What is the minimum pose-indexed feature windows size with respect
203 to the frame they are defined in.
205 * nb-scales-per-power-of-two (5)
207 How many scales do we visit between two powers of two.
209 * progress-bar ("yes")
211 Should we display a progress bar.
213 ######################################################################
218 Open the pool of scenes.
222 Create a new detector from the training scenes.
226 Compute the thresholds of the detector classifiers to obtain the
227 required wanted-true-positive-rate
231 Run the detector on the test scenes.
233 * sequence-test-detector
235 Visit nb-wanted-true-positive-rates rates between 0 and
236 wanted-true-positive-rate, for each compute the detector
237 thresholds on the validation set, estimate the error rate on the
242 Write the current detector to the file detector-name
246 Read a detector from the file detector-name
250 Write PNG images of the scenes in the pool.