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.
Proceedings of the IEEE CVPR 2010.

[2] P. Felzenszwalb, R. Girshick, D. McAllester, D. Ramanan.  Object
Detection with Discriminatively Trained Part Based Models.
IEEE Transactions on Pattern Analysis and Machine Intelligence, Vol. 32, No. 9, September 2010.


Installation
============

No additional steps are required. This is now included as part of voc-release5.


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
---
../demo_cascade.m        Demo script
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

Threshold Training
---
cascade_model.m          Trains thresholds from positive examples
cascade_data.m           Function for generating score statistics
data/                    Directory containing score statistic files

Performance evaluation
---
cascade_test.m           Find detections in a test set using a cascade model

Helper functions & data
---
cascade_compile.m        Builds the cascade code
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
project_model.m          Computes PCA projection of a model
project_pyramid.m        Computes PCA projection of a feature pyramid
grammar2simple.m         Converts a grammar model to a simpler star-model format
gdetect_pos_c.m          Cascade version of gdetect_pos.m -- allows PCA 
                         detections to be restricted to a specific root location
gdetect_pos_prepare_c.m  Cascade version of gdetect_pos_prepare.m -- allows PCA
                         detections to be restricted to a specific root location
get_block_scores.m       Given a detection, computes the score of each parameter 
                         block


data directory
---
This directory is populated with files containing score statistics.  The
files are named with the schema:
  <model_class>_<model_year>_cascade_data_no_pca_<data_year>.mat
  <model_class>_<model_year>_cascade_data_pca_5_<data_year>.mat

That is, each file contains block 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
'pca_5' use PCA filters projected onto the first 5 principle components.

This release includes score statistics for PASCAL 2007, 2010 and
INRIA where model_year == data_year.