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 when referring to this software.
  12
  13   Contact Francois Fleuret at fleuret@idiap.ch for comments and bug
  14   reports.
  15
  16 INSTALLATION
  17 ------------
  18
  19   If you have installed the RateMyKitten images provided on
  20
  21      http://www.idiap.ch/folded-ctf
  22
  23   in the source directory, everything should work seamlessly by
  24   invoking the ./run.sh script.
  25
  26   It will
  27
  28   * Compile the source code entirely
  29
  30   * Generate the "pool file" containing the uncompressed images
  31     converted to gray levels, labelled 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 run the full thing with the following commands if you have
  37   wget installed
  38
  39   > wget http://www.idiap.ch/folded-ctf/data/folding-gpl.tgz
  40   > tar zxvf folding-gpl.tgz
  41   > cd folding
  42   > wget http://www.idiap.ch/folded-ctf/data/rmk.tgz
  43   > tar zxvf rmk.tgz
  44   > ./run.sh
  45
  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.
  54
  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.
  58
  59   This program was developed on Debian GNU/Linux computers with the
  60   following main tool versions
  61
  62   * GNU bash, version 3.2.39
  63   * g++ 4.3.2
  64   * gnuplot 4.2 patchlevel 4
  65
  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.
  69
  70 EXECUTING THE PROGRAM
  71 ---------------------
  72
  73   The main command has to be invoked with a list of parameter values,
  74   followed by commands to execute.
  75
  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
  78   account.
  79
  80   For instance, to open a scene pool ./something.pool, train a
  81   detector and save it, you would do
  82
  83     ./folding --pool-name=./something.pool open-pool train-detector write-detector
  84
  85 PARAMETERS
  86 ----------
  87
  88   For every parameter below, the default value is given between
  89   parenthesis.
  90
  91   * niceness (5)
  92
  93     Process priority
  94
  95   * random-seed (0)
  96
  97     Global random seed
  98
  99   * pictures-for-article ("no")
 100
 101     Should the pictures be generated for printing in black and white.
 102
 103   * pool-name (none)
 104
 105     The scene pool file name.
 106
 107   * test-pool-name (none)
 108
 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.
 112
 113   * detector-name ("default.det")
 114
 115     Where to write or from where to read the detector.
 116
 117   * result-path ("/tmp/")
 118
 119     In what directory should we save all the produced files during the
 120     computation.
 121
 122   * loss-type ("exponential")
 123
 124     What kind of loss to use for the boosting. While different losses
 125     are implemented in the code, only the exponential has been
 126     thoroughly tested.
 127
 128   * nb-images (-1)
 129
 130     How many images to process in list_to_pool or when using the
 131     write-pool-images command.
 132
 133   * tree-depth-max (1)
 134
 135     Maximum depth of the decision trees used as weak learners in the
 136     classifier. The default value of 1 corresponds to stumps.
 137
 138   * proportion-negative-cells-for-training (0.025)
 139
 140     Overall proportion of negative cells to use during learning (we
 141     sample among them for boosting).
 142
 143   * nb-negative-samples-per-positive (10)
 144
 145     How many negative cells to sample for every positive cell during
 146     training.
 147
 148   * nb-features-for-boosting-optimization (10000)
 149
 150     How many pose-indexed features to look at for optimization at
 151     every step of boosting.
 152
 153   * force-head-belly-independence ("no")
 154
 155     Should we force the independence between the two levels of the
 156     detector (i.e. make an H+B detector)
 157
 158   * nb-weak-learners-per-classifier (100)
 159
 160     This parameter corresponds to the value U in the article.
 161
 162   * nb-classifiers-per-level (25)
 163
 164     This parameter corresponds to the value B in the article.
 165
 166   * nb-levels (2)
 167
 168     How many levels in the hierarchy.
 169
 170   * proportion-for-train (0.75)
 171
 172     The proportion of scenes from the pool to use for training.
 173
 174   * proportion-for-validation (0.25)
 175
 176     The proportion of scenes from the pool to use for estimating the
 177     thresholds.
 178
 179   * proportion-for-test (0.25)
 180
 181     The proportion of scenes from the pool to use to test the
 182     detector.
 183
 184   * write-validation-rocs ("no")
 185
 186     Should we compute and save the ROC curves estimated on the
 187     validation set during training.
 188
 189   * write-parse-images ("no")
 190
 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.
 195
 196   * write-tag-images ("no")
 197
 198     Should we save the (very large) tag images when saving the
 199     materials.
 200
 201   * wanted-true-positive-rate (0.75)
 202
 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.
 206
 207   * nb-wanted-true-positive-rates (10)
 208
 209     How many true positive rates to visit to generate the pseudo-ROC.
 210
 211   * min-head-radius (25)
 212
 213     What is the radius of the smallest heads we are looking for.
 214
 215   * max-head-radius (200)
 216
 217     What is the radius of the largest heads we are looking for.
 218
 219   * root-cell-nb-xy-per-radius (5)
 220
 221     What is the size of a (x,y) square cell with respect to the radius
 222     of the head.
 223
 224   * pi-feature-window-min-size (0.1)
 225
 226     What is the minimum pose-indexed feature windows size with respect
 227     to the frame they are defined in.
 228
 229   * nb-scales-per-power-of-two (5)
 230
 231     How many scales do we visit between two powers of two.
 232
 233   * progress-bar ("yes")
 234
 235     Should we display a progress bar during long computations.
 236
 237 COMMANDS
 238 --------
 239
 240   * open-pool
 241
 242     Open the pool of scenes.
 243
 244   * train-detector
 245
 246     Create a new detector from the training scenes.
 247
 248   * compute-thresholds
 249
 250     Compute the thresholds of the detector classifiers from the
 251     validation set to obtain the required wanted-true-positive-rate.
 252
 253   * test-detector
 254
 255     Run the detector on the test scenes.
 256
 257   * sequence-test-detector
 258
 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
 262     the test set.
 263
 264   * write-detector
 265
 266     Write the current detector to the file detector-name
 267
 268   * read-detector
 269
 270     Read a detector from the file detector-name
 271
 272   * write-pool-images
 273
 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
 279     specified.
 280
 281 --
 282 Francois Fleuret
 283 October 2008