README

Information
===========

Webpage for the project: http://www.cs.uchicago.edu/~pff/latent

This is an implementation of our object detection system based on
mixtures of deformable part models.  The system is fully described in
[2].  An earlier version of the system was described in [1].  

The distribution contains the object detection and model learning
code.  It also contains models trained on the PASCAL datasets.

The system is implemented in Matlab, with a few helper functions
written in C/C++ for efficiency reasons.  The software was tested on
several versions of Linux and Mac OS X.


References
==========

[1] P. Felzenszwalb, D. McAllester, D. Ramaman.  
A Discriminatively Trained, Multiscale, Deformable Part Model.  
Proceedings of the IEEE CVPR 2008.

[2] P. Felzenszwalb, R. Girshick, D. McAllester, D. Ramanan.  Object
Detection with Discriminatively Trained Part Based Models.
In preparation.


Basic Usage
===========

1. Unpack the code.
2. Start matlab.
3. Run the 'compile' script to compile the helper functions.
   (you may need to edit compile.m to use a different convolution 
    routine depending on your system)
4. Load a model and an image.
5. Use 'process' to detect objects.

example:
> load VOC2007/car_final.mat;   % car model trained on the PASCAL 2007 dataset
> im = imread('000034.jpg');    % test image
> bbox = process(im, model, 0); % detect objects
> showboxes(im, bbox);          % display results

The main functions defined in the object detection code are:

boxes = detect(im, model, thresh)
bbox = getboxes(model, boxes)
bbox = nms(bbox, overlap)
bbox = clipboxes(im, bbox)
showboxes(im, boxes)
visualizemodel(model)

Their usage is demonstrated in the 'demo' script.  

The directories 'VOC200?' contain matlab datafiles with models trained
on several PASCAL datasets (the train+val subsets).  Loading one of
these files from within matlab will define a variable 'model' with the
model trained for a particular object category.  The value
'model.thresh' defines a threshold that can be used in the 'detect'
function to obtain a high recall rate.

Using the learning code
=======================

1. Download and install the 2006/2007/2008 PASCAL VOC devkit and dataset.
   (you should set VOCopts.testset='test' in VOCinit.m)
2. Modify 'globals.m' according to your configuration.
3. Run 'make' to compile the LSVM gradient descent code.
4. Start matlab.
5. Run the 'compile' script to compile the helper functions.
   (you may need to edit compile.m to use a different convolution 
    routine depending on your system)
6. Use the 'pascal' script to train and evaluate a model. 

example:
> pascal('person', 2);   % train and evaluate a 2 component person model

The learning code saves a number of intermediate files in a cache
directory defined in 'globals.m'.  You should delete these files
before training models on different datasets, or when training new
models after modifing the code.  

The code also generates some very large temporary files during
training.  They are placed in a temporary directory defined in
'globals.m'.  This directory should be in a local filesystem.