X-Git-Url: https://fleuret.org/cgi-bin/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.txt;h=cbfa44afde8c9498d45673f1a5f6837104e486b3;hb=46071628964903cf0033d07492f7a1c506ce87d4;hp=3bca7f07e2381dcccf88b7f0d5e63247a6d50aa4;hpb=4953a336630d0ee905c949bf1fe846b85cabb744;p=folded-ctf.git diff --git a/README.txt b/README.txt index 3bca7f0..cbfa44a 100644 --- a/README.txt +++ b/README.txt @@ -1,67 +1,86 @@ -###################################################################### -## INTRODUCTION +I. INTRODUCTION +--------------- - This is the 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. - Please cite this paper when referring to this software. + Please use that citation when referring to this software. -###################################################################### -## INSTALLATION + Contact Francois Fleuret at fleuret@idiap.ch for comments and bug + reports. - 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 +II. INSTALLATION +---------------- If you have installed the RateMyKitten images provided on - http://www.idiap.ch/folded-ctf + http://www.idiap.ch/folded-ctf in the source directory, everything should work seamlessly by - invoking the ./run.sh script. It will + invoking the ./run.sh script. - * Compile the source code entirely + It will - * Generate the "pool file" containing the uncompressed images - converted to gray levels, labeled with the ground truth. + * Compile the source code entirely - * Run 20 rounds of training / test (ten rounds for each of HB and - H+B detectors with different random seeds) + * Generate the "pool file" containing the uncompressed images + converted to gray levels, labeled with the ground truth. - You can also run the full thing with the following commands if you - have wget installed + * Run 20 rounds of training / test (ten rounds for each of HB and + H+B detectors with different random seeds) - > wget http://www.idiap.ch/folded-ctf/not-public-yet/data/folding-gpl.tgz + 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/not-public-yet/data/rmk.tgz + > 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 already running computations by looking at the presence of the - corresponding result directory. Hence, it can be run in parallel on - several machines as long as they see the same result directory. + 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. + generate the ROC curves by invoking the ./graph.sh script. You need + a fairly recent version of Gnuplot. + + 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 + + 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. + +III. EXECUTING THE PROGRAM +-------------------------- + + The main command has to be invoked with a list of parameter values, + followed by commands to execute. + + 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. - You are welcome to send bug reports and comments to fleuret@idiap.ch + For instance, to open a scene pool ./something.pool, train a + detector and save it, you would do -###################################################################### -## PARAMETERS + ./folding --pool-name=./something.pool open-pool train-detector write-detector - To set the value of a parameter during an experiment, just add an - argument of the form --parameter-name=value before the commands that - should take into account that value. +IV. PARAMETERS +-------------- For every parameter below, the default value is given between parenthesis. @@ -78,14 +97,15 @@ Should the pictures be generated for printing in black and white. - * pool-name (no default) + * pool-name (none) - Where are the data to use + The scene pool file name. - * test-pool-name (no default) + * test-pool-name (none) - Should we use a separate pool file, and ignore proportion-for-test - then. + 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 + according to proportion-for-test. * detector-name ("default.det") @@ -110,12 +130,12 @@ * tree-depth-max (1) Maximum depth of the decision trees used as weak learners in the - classifier. The default value corresponds to stumps. + classifier. The default value of 1 corresponds to stumps. * proportion-negative-cells-for-training (0.025) Overall proportion of negative cells to use during learning (we - sample among them) + sample among them for boosting). * nb-negative-samples-per-positive (10) @@ -124,28 +144,27 @@ * nb-features-for-boosting-optimization (10000) - How many pose-indexed features to use at every step of boosting. + How many pose-indexed features to look at for optimization at + every step of boosting. * force-head-belly-independence ("no") Should we force the independence between the two levels of the detector (i.e. make an H+B detector) - * nb-weak-learners-per-classifier (10) + * nb-weak-learners-per-classifier (100) - This parameter corresponds to the value U in the JMLR paper, and - should be set to 100. + This parameter corresponds to the value U in the article. * nb-classifiers-per-level (25) - This parameter corresponds to the value B in the JMLR paper. + This parameter corresponds to the value B in the article. - * nb-levels (1) + * nb-levels (2) - How many levels in the hierarchy. This should be 2 for the JMLR - paper experiments. + How many levels in the hierarchy. - * proportion-for-train (0.5) + * proportion-for-train (0.75) The proportion of scenes from the pool to use for training. @@ -167,14 +186,16 @@ * write-parse-images ("no") Should we save one image for every test scene with the resulting - alarms. + alarms. This option generates a lot of images for every round and + is switched off by default. Switch it on to produce images such as + the full page of results in the paper. * write-tag-images ("no") Should we save the (very large) tag images when saving the materials. - * wanted-true-positive-rate (0.5) + * wanted-true-positive-rate (0.75) What is the target true positive rate. Note that this is the rate without post-processing and without pose tolerance in the @@ -208,46 +229,51 @@ * progress-bar ("yes") - Should we display a progress bar. + Should we display a progress bar during long computations. -###################################################################### -## COMMANDS +V. 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 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, 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 - Write PNG images of the scenes in the pool. + 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