-I. INTRODUCTION
+INTRODUCTION
+------------
- This is the open-source C++ implementation of the folded hierarchy
- of classifiers for cat detection described in
+ This is the documentation for the open-source C++ implementation of
+ the folded hierarchy of classifiers for cat detection described in
F. Fleuret and D. Geman, "Stationary Features and Cat Detection",
- Journal of Machine Learning Research (JMLR), 2008, to appear.
+ Journal of Machine Learning Research (JMLR), 9, 2549-2578, 2008.
- Please use that citation when referring to this software.
+ Please use that citation and the URL
- Contact Francois Fleuret at fleuret@idiap.ch for comments and bug
- reports.
+ http://www.idiap.ch/folded-ctf/
-II. INSTALLATION
+ when referring to this software.
- If you have installed the RateMyKitten images provided on
+ Contact Francois Fleuret at francois.fleuret@idiap.ch for comments
+ and bug reports.
- http://www.idiap.ch/folded-ctf
+INSTALLATION
+------------
- in the source directory, everything should work seamlessly by
- invoking the ./run.sh script.
+ If you have installed in the same directory as the source code the
+ RateMyKitten images available on the same web page as the source
+ code, everything should work seamlessly by invoking the ./run.sh
+ script.
It will
- * Compile the source code entirely
+ * Compile the source code entirely
- * Generate the "pool file" containing the uncompressed images
- converted to gray levels, labeled with the ground truth.
+ * Generate the "pool file" containing the uncompressed images
+ converted to gray levels, labelled with the ground truth.
- * Run 20 rounds of training / test (ten rounds for each of HB and
- H+B detectors with different random seeds)
+ * Run 20 rounds of training / test (ten rounds for each of HB and
+ H+B detectors with different random seeds)
You can run the full thing with the following commands if you have
wget installed
- > wget http://www.idiap.ch/folded-ctf/data/folding-gpl.tgz
- > tar zxvf folding-gpl.tgz
- > cd folding
- > wget http://www.idiap.ch/folded-ctf/data/rmk.tgz
- > tar zxvf rmk.tgz
- > ./run.sh
-
- Note that every one of the twenty rounds of training/testing takes
- more than three days on a powerful PC. However, the script detects
+ > wget http://www.idiap.ch/folded-ctf/data/folding-v1.0.tgz
+ > tar zxvf folding-v1.0.tgz
+ > cd folding
+ > wget http://www.idiap.ch/folded-ctf/data/rmk-v1.0.tgz
+ > tar zxvf rmk-v1.0.tgz
+ > ./run.sh
+
+ Note that for every round, we have to fully train a detector and run
+ the test through all the test scenes at 10 different thresholds,
+ including at very conservative thresholds for which the
+ computational efforts is very high. Hence, each round takes more
+ than three days on a powerful PC. However, the script detects
already running computations by looking at the presence of the
corresponding result directories. Hence, it can be run in parallel
on several machines as long as they see the same result directory.
When all or some of the experimental rounds are over, you can
- generate the ROC curves by invoking the ./graph.sh script. You need
- a fairly recent version of Gnuplot.
+ generate ROC curves by invoking ./graph.sh script. You need a fairly
+ recent version of Gnuplot.
+
+ If you pass the argument "pics" to the ./graphs.sh script, it will
+ save images from the data set with the ground truth plotted on them,
+ the pose-indexed referential, and examples of the pose-indexed
+ feature windows.
This program was developed on Debian GNU/Linux computers with the
following main tool versions
- * GNU bash, version 3.2.39
- * g++ 4.3.2
- * gnuplot 4.2 patchlevel 4
+ * GNU bash, version 3.2.39
+ * g++ 4.3.2
+ * gnuplot 4.2 patchlevel 4
+
+ Due to approximations in the optimized arithmetic operations with
+ g++, results may vary with different versions of the compiler and/or
+ different levels of optimization.
+
+EXECUTING THE PROGRAM
+---------------------
+
+ The main command has to be invoked with a list of parameter values,
+ followed by commands to execute. A parameter value is modified by
+ adding an argument of the form --parameter-name=value.
- Due to approximations in the optimized arithmetic operations with
- g++, results may vary with different versions of the compiler
- and/or different levels of optimization.
+ For instance, to open a scene pool ./something.pool, train a
+ detector and save it with all other parameters kept at their default
+ value, you would do
-III. PARAMETERS
+ ./folding --pool-name=./something.pool open-pool train-detector write-detector
- To set the value of a parameter, just add an argument of the form
- --parameter-name=value before the commands that should take it into
- account.
+PARAMETERS
+----------
For every parameter below, the default value is given between
parenthesis.
Should the pictures be generated for printing in black and white.
- * pool-name (no default)
+ * pool-name (none)
The scene pool file name.
- * test-pool-name (no default)
+ * test-pool-name (none)
Should we use a separate test pool file. If none is given, then
the test scenes are taken at random from the main pool file
* proportion-negative-cells-for-training (0.025)
Overall proportion of negative cells to use during learning (we
- sample among for boosting).
+ sample among them for boosting).
* nb-negative-samples-per-positive (10)
Should we display a progress bar during long computations.
-IV. COMMANDS
+COMMANDS
+--------
- * open-pool
+ * open-pool
- Open the pool of scenes.
+ Open the pool of scenes.
- * train-detector
+ * train-detector
- Create a new detector from the training scenes.
+ Create a new detector from the training scenes.
- * compute-thresholds
+ * compute-thresholds
- Compute the thresholds of the detector classifiers from the
- validation set to obtain the required wanted-true-positive-rate.
+ Compute the thresholds of the detector classifiers from the
+ validation set to obtain the required wanted-true-positive-rate.
- * test-detector
+ * test-detector
- Run the detector on the test scenes.
+ Run the detector on the test scenes.
- * sequence-test-detector
+ * sequence-test-detector
- Visit nb-wanted-true-positive-rates rates between 0 and
- wanted-true-positive-rate, for each compute the detector
- thresholds on the validation set and estimate the error rate on
- the test set.
+ Visit nb-wanted-true-positive-rates rates between 0 and
+ wanted-true-positive-rate, for each compute the detector
+ thresholds on the validation set and estimate the error rate on
+ the test set.
- * write-detector
+ * write-detector
- Write the current detector to the file detector-name
+ Write the current detector to the file detector-name
- * read-detector
+ * read-detector
- Read a detector from the file detector-name
+ Read a detector from the file detector-name
- * write-pool-images
+ * write-pool-images
- For every of the first nb-images of the pool, save one PNG image
- with the ground truth, one with the corresponding referential at
- the reference scale, and one with the feature material-feature-nb
- from the detector. This last image is not saved if either no
- detector has been read/trained or if no feature number has been
- specified.
+ For every of the first nb-images of the pool, save one PNG image
+ with the ground truth, one with the corresponding referential at
+ the reference scale, and one with the feature material-feature-nb
+ from the detector. This last image is not saved if either no
+ detector has been read/trained or if no feature number has been
+ specified.
--
Francois Fleuret
projects / folded-ctf.git / blobdiff