FAST-ER Documentation

1.0

Copyright and License

The software is Copyright (c) Edward Rosten and Los Alamos National Laboratory, 2008. There are no restrictions on using this software and it may only be redistributed under the terms of the GNU General Public License (a copy of which is included in the file LICENSE). No copyright is claimed on the output generated by these programs. The files in the fast_trees directory are generated trivially from the programs included herein, and so are not under copyright.

Introduction

This project contains a suite of programs to generate an optimized corner detector, test corner detectors on a variety of datasets, generate MATLAB and optimized C++ code, and some utilities for handling the datasets. The project also includes ready to use pre-generated trees in the fast_trees directory. Generated trees in intermediate, C++ and MATLAB form are availavle for FAST-8, FAST-9, FAST-10, FAST-11, FAST-12 and FAST-ER. In the case of FAST-ER, the FAST detector has been learned from the best FAST-ER tree (included as best_faster.tree) with features extracted from all available images in the Cambridge dataset.

To make on any unix-like environment, do:

./configure && make

There is no install option.

This will create the following executables:

• learn_detector This learns a detector from a repeatability dataset.
• extract_features This extracts features from an image sequence which can be turned in to a decision tree.
• learn_fast_tree This learns a FAST decision tree, from extracted data.
• Programs for generating code from the learned tree, in various language/library combinations.
  • C++ / libCVD
    • fast_tree_to_cxx_score_bsearch
    • fast_tree_to_cxx_score_iterate
  • MATLAB
    • fast_tree_to_matlab_score_bsearch
• test_repeatability Measure the repeatability of a detector.
• warp_to_png This converts a repeatability dataset in to a rather faster loading format.
• image_warp This program allows visual inspection of the quality of a dataset.
• fast_N_features This program generates all possible FAST-N features for consumption by learn_fast_tree .

Requirements

This code requires the following libraries from http://mi.eng.cam.ac.uk/~er258/cvd

• libCVD (compiled with TooN and LAPACK support)
• TooN
• GVars3
• tag For repeatability testing, the SUSAN detector can be used if the reference implementation is downloaded and placed in the directory. It is abailable from http://users.fmrib.ox.ac.uk/~steve/susan/susan2l.c

Running the system

The complete sequence of operations for FAST-ER is as follows:

1. Make the executable:

   ./configure && make

2. Generating a new FAST-ER detector.

   An example detector (the best known detector, used in the results section of the paper) is already in best_faster.tree .

   1. Set up learn_detector.cfg. The default parameters are good, except you will need to set up the system to point to the repeatability dataset you wish to use.

   2. Run the corner detector learning program

      ./learn_detector > logfile

      If you run it more than once, you will probably want to alter the random seed in the configuration file.

   3. Extract a detector from the logfile

      awk 'a&&!NF{exit}a;/Final tree/{a=1}' logfile > new_detector.tree

3. Measuring the repeatability of a detector

   ./test_repeatability --detector faster2 --faster2 new_detector.tree > new_detector_repeatability.txt

   The file new_detector_repeatability.txt can be plotted with almost any graph plotting program. A variety of detectors can be tested using this program. See test_repeatability for more information.

4. Generating accelerated tree based detectors.
   1. Features can be generated (for instance for FAST-N) or extracted from images, as is necessary for FAST-ER. FAST-N features can be extracted using fast_N_features:

      ./fast_N_features --N 9 > features.txt

      Alternatively, they can be extracted from images using extract_features:

      ./extract_features IMAGE1 [IMAGE2 ...] > features.txt

   2. A decision tree can be learned from the features using learn_fast_tree:

      learn_fast_tree < features.txt > fast-tree.txt

   3. The decision tree needs to be turned in to source code before it can be easily used. This is performed using fast_tree_to_cxx_score_bsearch , fast_tree_to_cxx_score_iterate , or fast_tree_to_matlab_score_bsearch .

      The name describes the target language, and the method by which the score is computed (iteraton or binary search). For monotonic trees, the result is the same, but for the more general non-monotonic trees produced by FAST-ER, the results may be slightly different.

      These programs are used in the following way:

      fast_tree_to_cxx_score_bsearch NAME fast-tree.txt > fast_tree.cxx

      NAME specifies the name of the function. If Matlab code is generated, then it is recommended that NAME is used for an output file NAME.m.

      The result is a usable source code file. In the case of generated C++, the file is compatible with libCVD, and the output of the corner detector can be fed to libCVD's nonmax_suppression function. The generated code does not make use of SSE. To do this, you will have to specify weights to learn_fast_tree and modify fast_tree_to_cxx_score_bsearch to hardwire the initial questions in the tree.

      In the case of Matlab, the generated file comes with code to perform nonmaximal suppression if desired. This code is generated in straight Matlab, so corner detection will not be especially fast.

---