Updated documentation

README

@@ -1,6 +1,9 @@
+-------------------------------------------------
 PartsBasedDetector
+-------------------------------------------------
+
 This project implements a Parts Based Detector in C++, described in the
-following paper by Deva Ramanan:
+following paper:
 
     Yi Yang, Deva Ramanan, "Articulated Pose Estimation with 
     Flexible Mixtures-of-Parts," CVPR 2011
@@ -11,8 +14,10 @@ The project has the following dependencies:
     CMake   REQUIRED (for building)
     Doxygen OPTIONAL (for documentation)
     OpenMP  OPTIONAL (for multithreading)
-    CUDA    OPTIONAL (for GPU accelerated support)
+    ROS     OPTIONAL (for publishing detections on a ROS topic)
+    ECTO    OPTIONAL (for building and ECTO cell)
 
+BUILDING
 The project can be built in one of two modes:
 
     A standalone binary (for testing functionality)
@@ -26,4 +31,16 @@ To build the project, follow the normal cmake routine from the root folder:
     >> cmake ..
     >> make
 
+DETECTING
+To run the detector, please consult the Mainpage of the docs, or
+src/demo.cpp. Both contain examples of how the detector can be
+initialised and run
+
+LEARNING
+The learning code is currently only in Octave/Matlab. This is because
+the detector supports a number of learning schema, and porting all of
+these to C++ is not practical at this time.
+Please consult the README within the matlab/ directory for instructions
+on training a model
+
 This package is developed and maintained by Hilton Bristow, Willow Garage

include/Candidate.hpp

@@ -78,6 +78,15 @@ class Candidate {
 	void setComponent(int c) { component_ = c; }
 	//! get the candidate component
 	int component(void) { return component_; }
+	//! rescale the parts
+	void resize(const float factor) {
+		for (unsigned int n = 0; n < parts_.size(); ++n) {
+			parts_[n].height *= factor;
+			parts_[n].width  *= factor;
+			parts_[n].y      *= factor;
+			parts_[n].x      *= factor;
+		}
+	}
 	//! descending comparison method for ordering objects of type Candidate
 	static bool descending(Candidate c1, Candidate c2) { return c1.score() > c2.score(); }
 

matlab/README

@@ -2,12 +2,48 @@
 MATLAB/OCTAVE TRAINING CODE
 -------------------------------------------------
 
-The Matlab and Octave code in this directory can be used to train models
-for the PartsBasedDetector. The code is a mirror of Yi Yang's code 
-available at (with some modifications to support Octave):
+IMPORTANT NOTE!
+The PartsBasedDetector is flexible, and thanks to the help of
+Deva Ramanan, Yi Yang and Xiangxin Zhu, models trained with a 
+range of learning methods can be converted for use with the
+detector. The current methods of learning (and links to code)
+are described in the following papers:
 
+  - Pedro Felzenszwalb, Ross Girshick, David McAllester and 
+    Deva Ramanan, "Object detection with discriminatively
+    trained part based models," PAMI 2010
+    http://people.cs.uchicago.edu/~rbg/latent/
+
+  - Yi Yang and Deva Ramanan, "Articulated pose estimation
+    using flexible mixtures of parts," CVPR 2011
     http://www.ics.uci.edu/~yyang8/research/pose/
 
+  - Xiangxin Zhu and Deva Ramanan, "Face detection, pose 
+    estimation and landmark localization in the wild,"
+    CVPR 2012
+
+Without going into details of how each of the methods differ,
+the discriminating features that concern the end user are
+(in order of appearance above):
+
+  - training only requires bounding boxes around objects
+    (this works well for semi-supervised robotics applications)
+
+  - training requires hand labelling of each part location
+    and controlling the number of mixtures per part
+
+  - training requires hand labelling of each part location,
+    however only a subset of parts may be visible in each
+    image. 
+
+
+SO WHAT IS THIS CODE?
+The Matlab and Octave code in this directory is a mirror of 
+Yi Yang's code with some modifications to support Octave. It
+has the best tradeoff between learning time, labelling complexity
+and performance (for our purposes) and supports our open source
+goals.
+
 Procedure to train a model:
 
     1) Start Octave or Matlab and cd to this matlab directory
@@ -18,3 +54,10 @@ Procedure to train a model:
     4) Create a training script. A sample training script
        training_demo.m is provided to outline the steps involved
     5) Run your script to train your model
+
+
+USING OTHER TRAINING METHODS:
+Using training methods other than this supplied method is as simple
+as running their respective training code, then calling 
+modelTransfer.m (in this root directory) to convert model
+formats.

src/CMakeLists.txt

@@ -39,7 +39,7 @@ install(TARGETS ${PROJECT_NAME}_lib
 
 # as an executable
 if (BUILD_EXECUTABLE)
-    set(SRC_FILES main.cpp)
+    set(SRC_FILES demo.cpp)
     add_executable(${PROJECT_NAME}_bin ${SRC_FILES})
     target_link_libraries(${PROJECT_NAME}_bin ${LIBS} ${PROJECT_NAME}_lib)
     set_target_properties(${PROJECT_NAME}_bin PROPERTIES OUTPUT_NAME ${PROJECT_NAME})

src/Visualize.cpp

@@ -74,7 +74,7 @@ void Visualize::candidates(const Mat& im, const vectorCandidate& candidates, uns
 	}
 
 	// draw each candidate to the canvas
-	const int LINE_THICKNESS = 3;
+	const int LINE_THICKNESS = 1;
 	Scalar black(0,0,0);
 	N = (candidates.size() < N) ? candidates.size() : N;
 	for (unsigned int n = 0; n < N; ++n) {
@@ -85,7 +85,7 @@ void Visualize::candidates(const Mat& im, const vectorCandidate& candidates, uns
 			rectangle(canvas, box, colors[p], LINE_THICKNESS);
 			if (display_confidence && p == 0) putText(canvas, confidence, Point(box.x, box.y-5), FONT_HERSHEY_SIMPLEX, 0.5f, black, 2);
 		}
-		rectangle(canvas, candidate.boundingBox(), Scalar(255, 0, 0), LINE_THICKNESS);
+		//rectangle(canvas, candidate.boundingBox(), Scalar(255, 0, 0), LINE_THICKNESS);
 	}
 }