README.txt

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