README.txt

   1
   2 INTRODUCTION
   3 ------------
   4
   5   This is the documentation for the open-source C++ implementation of
   6   the folded hierarchy of classifiers for cat detection described in
   7
   8      F. Fleuret and D. Geman, "Stationary Features and Cat Detection",
   9      Journal of Machine Learning Research (JMLR), 2008, to appear.
  10
  11   Please use that citation and the original URL
  12
  13      http://www.idiap.ch/folded-ctf
  14
  15   when referring to this software.
  16
  17   Contact Francois Fleuret at fleuret@idiap.ch for comments and bug
  18   reports.
  19
  20 INSTALLATION
  21 ------------
  22
  23   If you have installed in the same directory as the source code the
  24   RateMyKitten images available on the same web page as the source
  25   code, everything should work seamlessly by invoking the ./run.sh
  26   script.
  27
  28   It will
  29
  30   * Compile the source code entirely
  31
  32   * Generate the "pool file" containing the uncompressed images
  33     converted to gray levels, labelled with the ground truth.
  34
  35   * Run 20 rounds of training / test (ten rounds for each of HB and
  36     H+B detectors with different random seeds)
  37
  38   You can run the full thing with the following commands if you have
  39   wget installed
  40
  41   > wget http://www.idiap.ch/folded-ctf/data/folding-gpl.tgz
  42   > tar zxvf folding-gpl.tgz
  43   > cd folding
  44   > wget http://www.idiap.ch/folded-ctf/data/rmk.tgz
  45   > tar zxvf rmk.tgz
  46   > ./run.sh
  47
  48   Note that for every round, we have to fully train a detector and run
  49   the test through all the test scenes at 10 different thresholds,
  50   including at very conservative thresholds for which the
  51   computational efforts is very high. Hence, each round takes more
  52   than three days on a powerful PC. However, the script detects
  53   already running computations by looking at the presence of the
  54   corresponding result directories. Hence, it can be run in parallel
  55   on several machines as long as they see the same result directory.
  56
  57   When all or some of the experimental rounds are over, you can
  58   generate the ROC curves by invoking the ./graph.sh script. You need
  59   a fairly recent version of Gnuplot.
  60
  61   This program was developed on Debian GNU/Linux computers with the
  62   following main tool versions
  63
  64   * GNU bash, version 3.2.39
  65   * g++ 4.3.2
  66   * gnuplot 4.2 patchlevel 4
  67
  68   Due to approximations in the optimized arithmetic operations with
  69   g++, results may vary with different versions of the compiler and/or
  70   different levels of optimization.
  71
  72 EXECUTING THE PROGRAM
  73 ---------------------
  74
  75   The main command has to be invoked with a list of parameter values,
  76   followed by commands to execute.
  77
  78   To set the value of a parameter, just add an argument of the form
  79   --parameter-name=value before the commands that should take it into
  80   account.
  81
  82   For instance, to open a scene pool ./something.pool, train a
  83   detector and save it, you would do
  84
  85     ./folding --pool-name=./something.pool open-pool train-detector write-detector
  86
  87 PARAMETERS
  88 ----------
  89
  90   For every parameter below, the default value is given between
  91   parenthesis.
  92
  93   * niceness (5)
  94
  95     Process priority
  96
  97   * random-seed (0)
  98
  99     Global random seed
 100
 101   * pictures-for-article ("no")
 102
 103     Should the pictures be generated for printing in black and white.
 104
 105   * pool-name (none)
 106
 107     The scene pool file name.
 108
 109   * test-pool-name (none)
 110
 111     Should we use a separate test pool file. If none is given, then
 112     the test scenes are taken at random from the main pool file
 113     according to proportion-for-test.
 114
 115   * detector-name ("default.det")
 116
 117     Where to write or from where to read the detector.
 118
 119   * result-path ("/tmp/")
 120
 121     In what directory should we save all the produced files during the
 122     computation.
 123
 124   * loss-type ("exponential")
 125
 126     What kind of loss to use for the boosting. While different losses
 127     are implemented in the code, only the exponential has been
 128     thoroughly tested.
 129
 130   * nb-images (-1)
 131
 132     How many images to process in list_to_pool or when using the
 133     write-pool-images command.
 134
 135   * tree-depth-max (1)
 136
 137     Maximum depth of the decision trees used as weak learners in the
 138     classifier. The default value of 1 corresponds to stumps.
 139
 140   * proportion-negative-cells-for-training (0.025)
 141
 142     Overall proportion of negative cells to use during learning (we
 143     sample among them for boosting).
 144
 145   * nb-negative-samples-per-positive (10)
 146
 147     How many negative cells to sample for every positive cell during
 148     training.
 149
 150   * nb-features-for-boosting-optimization (10000)
 151
 152     How many pose-indexed features to look at for optimization at
 153     every step of boosting.
 154
 155   * force-head-belly-independence ("no")
 156
 157     Should we force the independence between the two levels of the
 158     detector (i.e. make an H+B detector)
 159
 160   * nb-weak-learners-per-classifier (100)
 161
 162     This parameter corresponds to the value U in the article.
 163
 164   * nb-classifiers-per-level (25)
 165
 166     This parameter corresponds to the value B in the article.
 167
 168   * nb-levels (2)
 169
 170     How many levels in the hierarchy.
 171
 172   * proportion-for-train (0.75)
 173
 174     The proportion of scenes from the pool to use for training.
 175
 176   * proportion-for-validation (0.25)
 177
 178     The proportion of scenes from the pool to use for estimating the
 179     thresholds.
 180
 181   * proportion-for-test (0.25)
 182
 183     The proportion of scenes from the pool to use to test the
 184     detector.
 185
 186   * write-validation-rocs ("no")
 187
 188     Should we compute and save the ROC curves estimated on the
 189     validation set during training.
 190
 191   * write-parse-images ("no")
 192
 193     Should we save one image for every test scene with the resulting
 194     alarms. This option generates a lot of images for every round and
 195     is switched off by default. Switch it on to produce images such as
 196     the full page of results in the paper.
 197
 198   * write-tag-images ("no")
 199
 200     Should we save the (very large) tag images when saving the
 201     materials.
 202
 203   * wanted-true-positive-rate (0.75)
 204
 205     What is the target true positive rate. Note that this is the rate
 206     without post-processing and without pose tolerance in the
 207     definition of a true positive.
 208
 209   * nb-wanted-true-positive-rates (10)
 210
 211     How many true positive rates to visit to generate the pseudo-ROC.
 212
 213   * min-head-radius (25)
 214
 215     What is the radius of the smallest heads we are looking for.
 216
 217   * max-head-radius (200)
 218
 219     What is the radius of the largest heads we are looking for.
 220
 221   * root-cell-nb-xy-per-radius (5)
 222
 223     What is the size of a (x,y) square cell with respect to the radius
 224     of the head.
 225
 226   * pi-feature-window-min-size (0.1)
 227
 228     What is the minimum pose-indexed feature windows size with respect
 229     to the frame they are defined in.
 230
 231   * nb-scales-per-power-of-two (5)
 232
 233     How many scales do we visit between two powers of two.
 234
 235   * progress-bar ("yes")
 236
 237     Should we display a progress bar during long computations.
 238
 239 COMMANDS
 240 --------
 241
 242   * open-pool
 243
 244     Open the pool of scenes.
 245
 246   * train-detector
 247
 248     Create a new detector from the training scenes.
 249
 250   * compute-thresholds
 251
 252     Compute the thresholds of the detector classifiers from the
 253     validation set to obtain the required wanted-true-positive-rate.
 254
 255   * test-detector
 256
 257     Run the detector on the test scenes.
 258
 259   * sequence-test-detector
 260
 261     Visit nb-wanted-true-positive-rates rates between 0 and
 262     wanted-true-positive-rate, for each compute the detector
 263     thresholds on the validation set and estimate the error rate on
 264     the test set.
 265
 266   * write-detector
 267
 268     Write the current detector to the file detector-name
 269
 270   * read-detector
 271
 272     Read a detector from the file detector-name
 273
 274   * write-pool-images
 275
 276     For every of the first nb-images of the pool, save one PNG image
 277     with the ground truth, one with the corresponding referential at
 278     the reference scale, and one with the feature material-feature-nb
 279     from the detector. This last image is not saved if either no
 280     detector has been read/trained or if no feature number has been
 281     specified.
 282
 283 --
 284 Francois Fleuret
 285 October 2008