Information =========== Project webpage: http://people.cs.uchicago.edu/~rbg/star-cascade/ This is an implementation of our star-cascade algorithm for object detection with deformable part models. This algorithm is described in [1]. See [2] for more general information about our object detection system. By building cascade detectors for our deformable part models we obtain an average detection time speedup of roughly 14x on the PASCAL 2007 dataset with almost no effect on AP scores. By allowing for a reduction in recall (i.e., increasing the global detection threshold), we can obtain speedup factors as high as 40x for some classes with almost loss in precision. (All timing comparisons are between single-threaded implementations of both algorithms.) This package contains object detection and cascade threshold learning code. It also contains pre-computed statistics needed to select thresholds for the models included in the release of our object detection system. These statistics were computed on the PASCAL 2006, 2007, 2009, and INRIA Person datasets. In each case, the statistics were computed on the same data that the detectors were trained on. In principle, thresholds selected from this data could be too aggressive due to over-fitting, however we have not observed this problem in practice. The system is implemented in MATLAB, with a few helper functions written in C++ for efficiency reasons. The software was tested on several versions of Linux and Mac OS X using MATLAB versions R2009b and R2010a. There may be compatibility issues with other versions of MATLAB and with other platforms. For questions concerning the code please contact Ross Girshick at <rbg AT cs DOT uchicago DOT edu>. References ========== [1] P. Felzenszwalb, R. Girshick, D. McAllester. Cascade Object Detection with Deformable Part Models. To appear in the Proceedings of the IEEE CVPR 2010. [2] P. Felzenszwalb, R. Girshick, D. McAllester, D. Ramanan. Object Detection with Discriminatively Trained Part Based Models. To appear in the IEEE Transactions on Pattern Analysis and Machine Intelligence. Installation ============ 0. This package is an add-on for our object detection system, which can be downloaded at http://people.cs.uchicago.edu/~pff/latent/. You must install that system first in order to use the cascade code. 1. Extract the source code and compile the C++ MEX files. After downloading the source package, extract it inside your voc-release4 directory. $ tar zxvf voc-release4-star-cascade.tgz The code will be unpacked into its own directory named 'star-cascade'. Switch to that directory, compile the code, and switch back to the voc-release4 directory. $ cd star-cascade $ make $ cd .. 2. Edit globals.m. Add the following two lines to the end of globals.m in your voc-release4 installation. % directory for cascade algorithm data cscdir = [pwd() '/star-cascade/data/']; 3. Start matlab. Start matlab inside your voc-release4 directory. To use the cascade code you will need to add it to your path with the following matlab command. >> addpath star-cascade; Now run to see a demonstration of cascade detection. >> cascade_demo Fin. Basic Usage =========== The function cascade_model() takes a model and produces a new model for use with the cascade detection algorithm. The new model has cascade thresholds that are trained on score statistics. Score statistics for the models included in the voc-release4 distribution have been pre-computed and are included in this download. csc_model = cascade_model(model, data_year, pca, global_thresh); An example. % load the PASCAL 2007 bicycle model into the variable 'model' load('VOC2007/bicycle_final'); % produce a cascade model trained on the 2007 dataset % using 5 dimensional PCA filters and a global detection % threshold of -1. csc_model = cascade_model(model, '2007', 5, -1); % compute the feature pyramid for image im pyra = featpyramid(im, csc_model); % get cascade detections [dets, boxes] = cascade_detect(pyra, csc_model, csc_model.thresh); Source Code Overview ==================== Cascade Detection --- cascade_detect.m Matlab function for cascade detection. cascade.cc C++ star-cascade implementation & MEX interface. model.{cc,h} C++ representation of cascade models. timer.h Simple timer for profiling. Makefile Makefile for building the MEX code. cascade-2pass.cc Experimental version not described in the paper that is about 1.25-1.75x faster. fconv_var_dim.cc Same as fconvMT.cc from voc-release4 -- supports features and filters with variable dimension (voc-release4.01 uses fconvsse.cc by default, which assumes HOG features have a fixed dimensionality) Threshold Training --- cascade_model.m Trains thresholds from positive examples. cascade_data.m Function for generating score statistics. writescores.m Write score statistics to a file. readscorestats.m Reads a score statistics file. data/ Directory containing score statistic files. Performance evaluation --- cascade_demo.m Demo script. cascade_test.m Find detections in a test set using a cascade model. compare_runtime.m Compare runtime performance of DP and cascade algorithms. (See the README note in this file before using.) cascade_thresh.m Find a detection threshold from a PR curve. Helper functions & data --- pca.mat PCA coefficients from PCA of HOG features. pca_of_hog.m Function used to generate pca.mat. project.m Computes PCA projection of a filter or feature map. projectmodel.m Computes PCA projection of a model. projectpyramid.m Computes PCA projection of a feature pyramid. gdetectvalid.m Modified version of gdetect.m used by cascade_data.m. grammar2simple.m Converts a grammar model to a simpler star-model format. data directory --- This directory is populated with files containing score statistics. The files are named with the schema: <model_class>_<model_year>_cascade_data_det_<data_year>.inf <model_class>_<model_year>_cascade_data_pca0_<data_year>.inf <model_class>_<model_year>_cascade_data_pca5_<data_year>.inf That is, each file contains score statistics for the object category <model_class> that were trained using data from the <model_year> PASCAL dataset with score statistics computed using the <data_year> PASCAL dataset. Files with 'pca0' use the full filters and files with 'pca5' use PCA filters projected onto the first 5 principle components. This release includes score statistics for PASCAL 2006, 2007, 2009 and INRIA where model_year == data_year.
rbgirshick/star-cascade
Cascade Object Detection with Deformable Part Models – Add-on package for voc-release4.01
MATLAB