README.txt

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