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