
========================================================================
TDP (Transformed Dirichlet Process) Matlab Software
========================================================================

Copyright (C) 2008, Erik B. Sudderth and Antonio Torralba.
(sudderth[at]alum[dot]mit[dot]edu, torralba[at]csail[dot]mit[dot]edu)

The TDP software package includes several Matlab classes, as well as
auxiliary functions and scripts, which implement MCMC learning algorithms 
for the models described in the following journal publication:
  Describing Visual Scenes Using Transformed Objects and Parts
  E. B. Sudderth, A. Torralba, W. T. Freeman, and A. S. Willsky
  Int. J. Comp. Vision, vol. 77, pp. 291-330, 2008.
Please cite this paper in any publications using the TDP package.

TDP supports image/data analysis with the following model families:
* DP/HDP mixture models for "bag of word/feature" data representations.
* Parametric, latent Dirichlet allocation (LDA) models for sharing 
  parts among multiple object categories.  IJCV Sec. 3.2, 5.3.
* Nonparametric, hierarchical Dirichlet process (HDP) models for 
  sharing parts among multiple object categories.  IJCV Sec. 4, 5.
* Parametric, contextual models for scenes containing a fixed,
  known set of object categories.  IJCV Sec. 6, 9.
* Nonparametric, transformed Dirichlet process (TDP) models
  for scenes with unknown sets of objects.  IJCV Sec. 8, 9.

The focus of this software is on extending hierarchical topic models to
incorporate spatial dependencies, for applications in visual object
recognition and scene understanding.  However, the TDP code can also be
easily used to learn simpler "bag of features" models, or used with data
arising in entirely different application domains.

========================================================================
Package Organization and Documentation
========================================================================

Each subdirectory contains either a README.txt file, or a Matlab 
Contents.m directory summary, which provide more detailed documentation.

Summary of TDP package contents:
/affineFeatures:  
  Extraction of affine invariant and edge-based features, 
  computation of SIFT descriptors, and visualization.
/database:  
  Image databases used for experiments in the IJCV paper,
  as well as precomputed features stored in Matlab .mat files.
/datastat:  
  Auxiliary functions used to cache sufficient statistics
  of features, used by various MCMC learning algorithms.
/demoModels:  
  Pre-trained object and scene models, used by demo scripts.
/sceneLDA:  
  Matlab classes for learning parametric models with finite, 
  known numbers of objects and parts.
/sceneTDP:  
  Matlab classes for learning nonparametric, Dirichlet process models 
  with potentially infinite numbers of objects and parts.
/scripts:  
  Training, test, and visualization scripts showing how to
  use the TDP package with realistic image databases.
/scripts/database*:  
  Scripts for precomputing sparse image features.
/utilities:  
  Utility routines for random number generation, statistical
  evaluation of performance on test data, and visualization.

========================================================================
Setup and Usage Examples
========================================================================

For an example of sparse feature extraction, see demoAffine.m.
To use the feature extraction code, you must first take two steps:
1) Modify affineFeatures/features.m by setting HOME_TDP to the absolute
   path where you installed the TDP package.
2) Download feature extraction software provided by the Oxford Visual
   Geometry Group, and place it in the affineFeatures/ directory:
     http://www.robots.ox.ac.uk/~vgg/software/
   Files needed:  h_affine.ln, mser.ln, compute_descriptors.ln

For visualizations of pre-trained TDP models for objects and scenes,
see demoHDPobject.m and demoTDPscene.m.

For simple examples demonstrating how to learn various model types from
toy data, see sceneLDA/test_*.m and sceneTDP/test_*.m.

For more complex scripts demonstrating learning and visualization with
real image databases, see the scripts/ subdirectory.

========================================================================
Acknowledgments
========================================================================

Portions of the TDP package were adapted from Yee Whye Teh's
"Nonparametric Bayesian Mixture Models" package, release 1.
Available from:  http://www.gatsby.ucl.ac.uk/~ywteh

Affine-invariant feature extraction code provided by the Oxford Visual
Geometry Group:  http://www.robots.ox.ac.uk/~vgg/software/

Functions for edge extraction and linkage provided by P. D. Kovesi:
  MATLAB and Octave Functions for Computer Vision and Image Processing.
  School of Computer Science & Software Engineering,
  The University of Western Australia.   
Available from:  http://www.csse.uwa.edu.au/~pk/research/matlabfns/

========================================================================
Copyright & License
========================================================================

The TDP package and code were written by Erik Sudderth and Antonio Torralba,
and are copyrighted under the GNU Lesser General Public License:
  Copyright (C) 2008, Erik B. Sudderth and Antonio Torralba.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published 
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

