*** empty log message ***
[folded-ctf.git] / README.txt
1
2 INTRODUCTION
3
4   This is the C++ implementation of the folded hierarchy of
5   classifiers for cat detection described in
6
7      F. Fleuret and D. Geman, "Stationary Features and Cat Detection",
8      Journal of Machine Learning Research (JMLR), 2008, to appear.
9
10   Please cite this paper when referring to this software.
11
12 INSTALLATION
13
14   This program was developed on Debian GNU/Linux computers with the
15   following main tool versions
16
17    * GNU bash, version 3.2.39
18    * g++ 4.3.2
19    * gnuplot 4.2 patchlevel 4
20
21   If you have installed the RateMyKitten images provided on
22
23     http://www.idiap.ch/folded-ctf
24
25   in the source directory, everything should work seamlessly by
26   invoking the ./run.sh script. It will
27
28    * Compile the source code entirely
29
30    * Generate the "pool file" containing the uncompressed images
31      converted to gray levels, labeled with the ground truth.
32
33    * Run 20 rounds of training / test (ten rounds for each of HB and
34      H+B detectors with different random seeds)
35
36   You can also run the full thing with the following commands if you
37   have wget installed
38
39      wget http://www.idiap.ch/folded-ctf/not-public-yet/data/folding-gpl.tgz
40      tar zxvf folding-gpl.tgz
41      cd folding
42      wget http://www.idiap.ch/folded-ctf/not-public-yet/data/rmk.tgz
43      tar zxvf rmk.tgz
44      ./run.sh
45
46   Note that every one of the twenty rounds of training/testing takes
47   more than three days on a powerful PC. However, the script detects
48   already running computations by looking at the presence of the
49   corresponding result directory. Hence, it can be run in parallel on
50   several machines as long as they see the same result directory.
51
52   When all or some of the experimental rounds are over, you can
53   generate the ROC curves by invoking the ./graph.sh script.
54
55   You are welcome to send bug reports and comments to fleuret@idiap.ch
56
57 PARAMETERS
58
59   To set the value of a parameter during an experiment, just add an
60   argument of the form --parameter-name=value before the commands that
61   should take into account that value.
62
63   For every parameter below, the default value is given between
64   parenthesis.
65
66   * niceness (5)
67
68     Process priority
69
70   * random-seed (0)
71
72     Global random seed
73
74   * pictures-for-article ("no")
75
76     Should the pictures be generated to be clear in b&w
77
78   * pool-name (no default)
79
80     Where are the data to use
81
82   * test-pool-name (no default)
83
84     Should we use a separate pool file, and ignore proportion-for-test
85     then.
86
87   * detector-name ("default.det")
88
89     Where to write or from where to read the detector.
90
91   * result-path ("/tmp/")
92
93     In what directory should we save all the produced file during the
94     computation.
95
96   * loss-type ("exponential")
97
98     What kind of loss to use for the boosting. While different loss are
99     implementer in the code, only the exponential has been thoroughly
100     tested.
101
102   * nb-images (-1)
103
104     How many images to process in list_to_pool or when using the
105     write-pool-images command.
106
107   * tree-depth-max (1)
108
109     Maximum depth of the decision trees used as weak learners in the
110     classifier.
111
112   * proportion-negative-cells-for-training (0.025)
113
114     Overall proportion of negative cells to use during learning (we
115     sample among them)
116
117   * nb-negative-samples-per-positive (10)
118
119     How many negative cell to sample for every positive cell during
120     training.
121
122   * nb-features-for-boosting-optimization (10000)
123
124     How many pose-indexed features to use at every step of boosting.
125
126   * force-head-belly-independence (no)
127
128     Should we force the independence between the two levels of the
129     detector (i.e. make an H+B detector)
130
131   * nb-weak-learners-per-classifier (10)
132
133     This parameter corresponds to the value U in the JMLR paper, and
134     should be set to 100.
135
136   * nb-classifiers-per-level (25)
137
138     This parameter corresponds to the value B in the JMLR paper.
139
140   * nb-levels (1)
141
142     How many levels in the hierarchy, this is 2 for the JMLR paper
143     experiments.
144
145   * proportion-for-train (0.5)
146
147     The proportion of scenes from the pool to use for training.
148
149   * proportion-for-validation (0.25)
150
151     The proportion of scenes from the pool to use for estimating the
152     thresholds.
153
154   * proportion-for-test (0.25)
155
156     The proportion of scenes from the pool to use to test the
157     detector.
158
159   * write-validation-rocs ("no")
160
161     Should we compute and save the ROC curves estimated on the
162     validation set during training.
163
164   * write-parse-images ("no")
165
166     Should we save one image for every test scene with the resulting
167     alarms.
168
169   * write-tag-images ("no")
170
171     Should we save the (very large) tag images when saving the
172     materials.
173
174   * wanted-true-positive-rate (0.5)
175
176     What is the target true positive rate. Note that this is the rate
177     without post-processing and without pose tolerance in the
178     definition of a true positive.
179
180   * nb-wanted-true-positive-rates (10)
181
182     How many true positive rates to visit to generate the pseudo-ROC.
183
184   * min-head-radius (25)
185
186     What is the radius of the smallest heads we are looking for.
187
188   * max-head-radius (200)
189
190     What is the radius of the largest heads we are looking for.
191
192   * root-cell-nb-xy-per-radius (5)
193
194     What is the size of a (x,y) square cell with respect to the radius
195     of the head.
196
197   * pi-feature-window-min-size (0.1)
198
199     What is the minimum pose-indexed feature windows size with respect
200     to the frame they are defined in.
201
202   * nb-scales-per-power-of-two (5)
203
204     How many scales do we visit between two powers of two.
205
206   * progress-bar ("yes")
207
208     Should we display a progress bar.
209
210 COMMANDS
211
212    open-pool
213    train-detector
214    compute-thresholds
215    test-detector
216    sequence-test-detector
217    write-detector
218    read-detector
219    write-pool-images
220
221   --
222   Francois Fleuret
223   October 200