detectors/acfReadme.m: added proper readme, updated demos to point to…

… readme

detector/Contents.m

@@ -1,27 +1,17 @@
 % DETECTOR
 % See also
 %
-% Fast detector code is based on the papers:
-%  [1] P. Dollár, Z. Tu, P. Perona and S. Belongie
-%   "Integral Channel Features", BMVC 2009.
-%  [2] P. Dollár, S. Belongie and P. Perona
-%   "The Fastest Pedestrian Detector in the West," BMVC 2010.
-%  [3] P. Dollár, R. Appel and W. Kienzle
-%   "Crosstalk Cascades for Frame-Rate Pedestrian Detection," ECCV 2012.
-%  [4] P. Dollár, R. Appel, S. Belongie and P. Perona
-%   "Fast Feature Pyramids for Object Detection", PAMI 2014.
-% Please cite a subset of the above papers if you end up using the code.
-% The PAMI 2014 paper has the most thorough and up to date descriptions.
-% Code written and maintained by Piotr Dollar and Ron Appel.
+% Please see acfReadme for an overview of the detection code.
 %
 % Aggregate channel features object detector:
 %   acfDemoCal   - Demo for aggregate channel features object detector on Caltech dataset.
 %   acfDemoInria - Demo for aggregate channel features object detector on Inria dataset.
 %   acfDetect    - Run aggregate channel features object detector on given image(s).
 %   acfModify    - Modify aggregate channel features object detector.
+%   acfReadme    - Aggregate Channel Features Detector Overview.
 %   acfTest      - Test aggregate channel features object detector given ground truth.
 %   acfTrain     - Train aggregate channel features object detector.
-% 
+%
 % Object bounding box utilities and labeling tools:
 %   bbApply      - Functions for manipulating bounding boxes (bb).
 %   bbGt         - Bounding box (bb) annotations struct, evaluation and sampling routines.

detector/acfDemoCal.m

@@ -1,17 +1,6 @@
 % Demo for aggregate channel features object detector on Caltech dataset.
 %
-% (1) Download data and helper routines from Caltech Peds Website
-%  www.vision.caltech.edu/Image_Datasets/CaltechPedestrians/
-%  (1a) Download Caltech-USA files: videos/set*.tar and annotations.zip
-%  (1b) Copy above to CaltechPeds/data-USA/ and extract contents
-%  (1c) Download evaluation code (routines necessary for extracting images)
-%  Note: for CaltechPeds setup details please see CaltechPeds/readme.txt
-% (2) Set dataDir/ variable below to point to location to extract data.
-% (3) Launch "matlabpool open" for faster training if available.
-% (4) Run demo script and enjoy your newly minted fast ped detector!
-%
-% Note: pre-trained model files are provided (delete to re-train).
-% Re-training may give slightly variable results on different machines.
+% See also acfReadme.m
 %
 % Piotr's Computer Vision Matlab Toolbox      Version NEW
 % Copyright 2014 Piotr Dollar.  [pdollar-at-gmail.com]
@@ -38,10 +27,8 @@
 pLoad={'lbls',{'person'},'ilbls',{'people'},'squarify',{3,.41}};
 opts.pLoad = [pLoad 'hRng',[50 inf], 'vRng',[1 1] ];
 
-%% optionally set up opts for LDCF version of detector (see acfTrain)
-if( 0 )
-  opts.filters=[5 4]; opts.name='models/LdcfCaltech';
-end
+%% optionally switch to LDCF version of detector (see acfTrain)
+if( 0 ), opts.filters=[5 4]; opts.name='models/LdcfCaltech'; end
 
 %% train detector (see acfTrain)
 detector = acfTrain( opts );

detector/acfDemoInria.m

@@ -1,17 +1,6 @@
 % Demo for aggregate channel features object detector on Inria dataset.
 %
-% (1) Download data and helper routines from Caltech Peds Website
-%  www.vision.caltech.edu/Image_Datasets/CaltechPedestrians/
-%  (1a) Download INRIA files: videos/set*.tar and annotations.zip
-%  (1b) Copy above to CaltechPeds/data-INRIA/ and extract contents
-%  (1c) Download evaluation code (routines necessary for extracting images)
-%  Note: for CaltechPeds setup details please see CaltechPeds/readme.txt
-% (2) Set dataDir/ variable below to point to location to extract data.
-% (3) Launch "matlabpool open" for faster training if available.
-% (4) Run demo script and enjoy your newly minted fast ped detector!
-%
-% Note: pre-trained model files are provided (delete to re-train).
-% Re-training may give slightly variable results on different machines.
+% See also acfReadme.m
 %
 % Piotr's Computer Vision Matlab Toolbox      Version NEW
 % Copyright 2014 Piotr Dollar.  [pdollar-at-gmail.com]
@@ -35,7 +24,7 @@
 opts.negImgDir=[dataDir 'train/neg']; opts.pBoost.pTree.fracFtrs=1/16;
 opts.pLoad={'squarify',{3,.41}}; opts.name='models/AcfInria';
 
-%% optionally set up opts for LDCF version of detector (see acfTrain)
+%% optionally switch to LDCF version of detector (see acfTrain)
 if( 0 )
   opts.filters=[5 4]; opts.pJitter=struct('flip',1,'nTrn',3,'mTrn',1);
   opts.pBoost.pTree.maxDepth=3; opts.pBoost.discrete=0; opts.seed=2;
@@ -68,5 +57,5 @@
 end
 
 %% optionally show top false positives ('type' can be 'fp','fn','tp','dt')
-if( 0 ), bbGt('cropRes',gt,dt,imgNms,'type','fn','n',50,...
+if( 0 ), bbGt('cropRes',gt,dt,imgNms,'type','fp','n',50,...
     'show',3,'dims',opts.modelDs([2 1])); end

detector/acfReadme.m

@@ -0,0 +1,109 @@
+% Aggregate Channel Features Detector Overview.
+%
+% Piotr's Computer Vision Matlab Toolbox      Version NEW
+% Copyright 2014 Piotr Dollar.  [pdollar-at-gmail.com]
+% Licensed under the Simplified BSD License [see external/bsd.txt]
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%% 1. Introduction. %%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% The detector portion of this toolbox implements the Aggregate Channel
+% Features (ACF) object detection code. The ACF detector is a fast and
+% effective sliding window detector (30 fps on a single core). It is an
+% evolution of the Viola & Jones (VJ) detector but with an ~1000 fold
+% decrease in false positives (at the same detection rate). ACF is best
+% suited for quasi-rigid object detection (e.g. faces, pedestrians, cars).
+%
+% The detection code was written by Piotr Dollár with contributions by Ron
+% Appel and Woonhyun Nam (with bug reports/suggestions from many others).
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%% 2. Papers. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% The detector was introduced and described through the following papers:
+%  [1] P. Dollár, Z. Tu, P. Perona and S. Belongie
+%   "Integral Channel Features", BMVC 2009.
+%  [2] P. Dollár, S. Belongie and P. Perona
+%   "The Fastest Pedestrian Detector in the West," BMVC 2010.
+%  [3] P. Dollár, R. Appel and W. Kienzle
+%   "Crosstalk Cascades for Frame-Rate Pedestrian Detection," ECCV 2012.
+%  [4] P. Dollár, R. Appel, S. Belongie and P. Perona
+%   "Fast Feature Pyramids for Object Detection," PAMI 2014.
+%  [5] W. Nam, P. Dollár, and J.H. Han
+%   "Local Decorrelation For Improved Pedestrian Detection," NIPS 2014.
+% Please see: http://vision.ucsd.edu/~pdollar/research.html#ObjectDetection
+%
+% A short summary of the papers, organized by detector name:
+%
+% [1] "Integral Channel Features" [ICF] - Introduced channel features and
+% modified the VJ framework to compute integral images (and Haar wavelets)
+% over the channels. Substantially outperformed HOG and at faster speeds.
+%
+% [2] "Fastest Pedestrian Detector in the West" [FPDW] - We observed that
+% features computed at one scale can be used to approximate features at
+% nearby scales, increasing detector speed with little loss in accuracy.
+%
+% [3] "Crosstalk Cascades" - This work coupled cascade evaluation at nearby
+% positions and scales to exploit correlations in detector responses at
+% neighboring locations. Further increased speed of the ICF detector.
+%
+% [4] "Aggregate Channel Features" [ACF] - We found that single-scale
+% square Haar wavelets were sufficient in the ICF framework. Thus instead
+% of computing integral images and Haar wavelets, we simply smooth and
+% downsample the channels and the features are now single pixel lookups in
+% the "aggregated" channels.
+%
+% [5] "Locally Decorralated Channel Features" [LDCF] - Filtering the
+% channel features with appropriate data-derived filters can remove local
+% correlations from the channels. Given decorrelated features, boosted
+% decision trees generalize much better giving a nice boost in accuracy.
+%
+% This code implements ACF [4] and LDCF [5]. It does not implement ICF [1]
+% or FPDW [2] which are now obsolete and supplemented by ACF. Crosstalk
+% cascades [3] are also not used as classifier evalution in ACF is very
+% fast (no need to compute Haar wavelets). However, ACF does use the simple
+% but highly effective "constant soft cascades" from [3].
+%
+% Please cite a subset of the above papers as appropriate if you end up
+% using this code to support a publication. Thanks!
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%% 3. Setup. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% (A) Please install and setup the toolbox as described online:
+%  http://vision.ucsd.edu/~pdollar/toolbox/doc/index.html
+% You may need to recompile for your system, see toolboxCompile. Note:
+% enabling OpenMP during compile will significantly speed training.
+%
+% (B) Important: to train the detectors and run the detection demos you
+% need to install the Caltech Pedestrian Detection Benchmark available at:
+%  http://www.vision.caltech.edu/Image_Datasets/CaltechPedestrians/
+% In particular, make sure to download and install:
+%  (B1) Matlab evaluation/labeling code version 3.2.1 or later
+%  (B2) INRIA data (necessary for the INRIA demo)
+%  (B3) Caltech-USA data (necessary for the Caltech demo)
+% Please follow the instruction in the readme of the Caltech code. You only
+% need to download the data and code and place appropriately, there is no
+% need to look closely at the evaluation code. Initially running the demos
+% (acfDemoInria and acfDemoCal) will convert the data from the Caltech data
+% format to a format useable by ACF. If this step fails it means the
+% Caltech code or data is not properly setup.
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%% 4. Getting Started. %%%%%%%%%%%%%%%%%%%%%%%%
+%
+% After performing the setup, see acfDemoInria.m and acfDemoCal.m for demos
+% and visualizations.
+%
+% For an overview of available functionality please see detector/Contents.m
+% and channels/Contents.m. The various detector/acf*.m and channels/chns*.m
+% functions are well documented and worth checking for additional details.
+%
+% Finally, a note about pre-trained models. The detector/models/ directory
+% contains four pre-trained pedestrian models (ACF/LDCF on INRIA/Caltech).
+% Running acfDemoInria/Cal.m with the ACF/LDCF flag toggled gives rise to
+% these models (just delete the existing models to retrain from scratch).
+% Note, however, that results will differ by up to +/-2% MR depending on
+% operating system and random seed (see opts.seed), and the models here are
+% not exactly equivalent to the models in the papers (due to evolution of
+% the code). Small changes in MR should not be considered significant (nor
+% should they be used as a basis for publishing). Whenever making a change
+% I suggest training/testing the same model with multiple random seeds.
+%
+% Enjoy and I hope you find the detectors useful :)

detector/acfTrain.m

@@ -5,7 +5,7 @@
 %  P. Dollár, R. Appel, S. Belongie and P. Perona
 %   "Fast Feature Pyramids for Object Detection", PAMI 2014.
 % The ACF detector is fast (30 fps on a single core) and achieves top
-% accuracy on rigid object detection.
+% accuracy on rigid object detection. Please see acfReadme.m for details.
 %
 % Takes a set of parameters opts (described in detail below) and trains a
 % detector from start to finish including performing multiple rounds of
@@ -106,8 +106,8 @@
 %
 % EXAMPLE
 %
-% See also acfDetect, acfDemoInria, acfModify, acfTest, chnsCompute,
-% chnsPyramid, adaBoostTrain, bbGt, bbNms, jitterImage
+% See also acfReadme, acfDetect, acfDemoInria, acfModify, acfTest,
+% chnsCompute, chnsPyramid, adaBoostTrain, bbGt, bbNms, jitterImage
 %
 % Piotr's Computer Vision Matlab Toolbox      Version NEW
 % Copyright 2014 Piotr Dollar.  [pdollar-at-gmail.com]

external/history.txt

@@ -1,6 +1,7 @@
 Version NEW
- -acfDemo*: updated demos and model files
- -acfTrain, acfTest: minor usability updates
+ -Added LDCF detector described in NIPS14 paper
+ -acfReadme.m: added proper readme for detection code
+ -acf*.m: many updates to support LDCF and improve usability
  -adaBoostApply, binaryTree*: set default max threads to 16 for OMP code
  -minor: toolboxUpdateHeader, savefig