README.txt

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