README.txt

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