Machine Perception Primitive: An implementation of a GentleBoost classifier for image patch classification. More...

#include <GentleBoostClassifier2.h>

Inheritance diagram for GentleBoostClassifier2:

Collaboration diagram for GentleBoostClassifier2:

Public Member Functions
	GentleBoostClassifier2 ()
	Constructor.
	GentleBoostClassifier2 (const GentleBoostClassifier2 &copy)
	Copy Constructor.
GentleBoostClassifier2 &	operator= (const GentleBoostClassifier2 &rhs)
	Assignment operator.
virtual	~GentleBoostClassifier2 ()
	Destructor.
void	getProbabilityMap (PatchList2 *patches, cv::Mat &dest) const
	Evaluate every pixel in an image for its probability that an object is located there.
virtual void	searchPatches (const std::vector< ImagePatch2 > &patches, const cv::Mat &labels, cv::Mat &featureSum, cv::Mat &posterior, cv::Mat &predictions, std::vector< cv::Mat > &featureOutputs, double &perf, cv::Mat &weights, cv::Mat &survived) const
	Apply the GentleBoostClasssifier to a classify collection of image patches.
virtual void	setTrainingSet (const std::vector< ImagePatch2 > &trainingPatches, const cv::Mat &trainingLabels)
	Set ImagePatch data and labels used for training the classifier.
virtual void	setTestingSet (const std::vector< ImagePatch2 > &testingPatches, const cv::Mat &testingLabels)
	Set ImagePatch data and labels used for evaluating the classifier.
virtual PerformanceMetrics	trainOneRound (int patience=1, int boostRounds=1)
	Train boosted classifier for one round by searching for one good feature, and adding it.
virtual Feature2 *	getGoodFeature (int patience=1, const std::string &featureType="HaarFeature") const
	Look for a feature that would improve classifier performance.
virtual void	addFeature (const Feature2 *nextFeature)
	Add a feature to the classifier.
virtual void	addFeatureBoosted (const Feature2 *nextFeature, int boostRounds=1)
	Add a feature to the classifier by applying multiple rounds of boosting.
virtual void	getPerformanceMeasures (const Feature2 *candidate, PerformanceMetrics &perf) const
	Compute perfomance measures for this classifier, depending on the Feature* passed in. This is primarily used for finding the best feature to add to the classifier, using addFeature().
virtual int	getNumTrainingPatches () const
	Total number of negative patches currently being used to train the classifier.
virtual int	getNumTestingPatches () const
	Total number of positive patches currently being used to train the classifier.
virtual void	getImageHeaderForTrainingPatch (cv::Mat &dst, int patchNum) const
	Get an IplImage for visualizing the negative patches in the classifier - This must be released using cvReleaseImageHeader, and not cvReleaseImage, or you will destroy the data used for training.
virtual void	getImageHeaderForTestingPatch (cv::Mat &dst, int patchNum) const
	Get an IplImage for visualizing the positive patches in the classifier - This must be released using cvReleaseImageHeader, and not cvReleaseImage, or you will destroy the data used for training.
int	getNumFeaturesUsed () const
	How many of its total features is the classifier currently using? To improve speed or avoid generalization errors, it may be useful to only use the first few features of the classifier.
int	getNumFeaturesTotal () const
	How many total available, trained features does the classifier have?
void	setNumFeaturesUsed (int num)
	Number of trained and available features to use. To improve speed or avoid generalization errors, it may be useful to only use the first few features of the classifier.
FeatureRegressor2	getFeatureAndTuningCurveNumber (int num) const
	Examine the features used by this GentleBoostClassifier2.
cv::Size	getBasePatchSize () const
	Size of patches used for training. All features added must have a size equal to getBasePatchSize().
void	setTrainingFeatureType (const std::string &featureType)
	Change the type of feature added by "train".
void	searchImage (const cv::Mat &gray_image, std::vector< SearchResult > &keptPatches, int NMSRadius=0, double thresh=-INFINITY)
	Search through and image for objects that this classifier was trained to detect. Results are passed back via the SearchResult vector keptPatches.
void	setCurrentImage (const cv::Mat &gray_image)
	Set the current image to search, without actually searching. This allows you to search each scale (size) separately and manually, using searchCurrentImageAtScale().
void	searchCurrentImageAtScale (std::vector< SearchResult > &keptPatches, int scale, int NMSRadius=0, double thresh=-INFINITY)
	Search through and image for objects at a single scale (size).
int	getNumScales () const
	Query the number of scales available for searching for objects. See PatchList for further discussion.
cv::Size	getSizeOfScale (int scale) const
	Query the size of object searched for at a given scale. See PatchList for further discussion.
void	sharePatchListWithClassifier (const GentleBoostClassifier2 &otherClassifier)
	Share the patch list of another GentleBoostCascadedClassifier, to increase efficiency of multiple classifiers processing the same image.
Static Public Member Functions
static double	featureCost (const PerformanceMetrics &a)
	Cost function used to compare features: By default, only uses chisq error info.
Friends
cv::FileStorage &	operator<< (cv::FileStorage &fs, const GentleBoostClassifier2 &booster)
	Write to a file.
void	operator>> (const cv::FileNode &fs, GentleBoostClassifier2 &booster)
	Read from a file.

Detailed Description

Machine Perception Primitive: An implementation of a GentleBoost classifier for image patch classification.

The GentleBoost approach is described in Fasel's "Learning Real-Time Object Detectors: Probabilistic Generative Approaches", 2006 (see Related Publications).

GentleBoostClassifier2 is only suitable for whole patch classification. It is not meant to be used to search for objects in scenes. For that application, see GentleBoostCascadedClassifier.

Author:: Nicholas Butko

Date:: 2010

Version:: 0.4

Member Function Documentation

void GentleBoostClassifier2::addFeature ( const Feature2 * nextFeature ) [virtual]

Add a feature to the classifier.

This will create a FeatureRegressor and compute its tuning curve based on the current weighting of the training examples, and then reweight the training examples according to the GentleBoost algorithm.

Parameters:

nextFeature The feature to add.

void GentleBoostClassifier2::addFeatureBoosted	(	const Feature2 *	nextFeature,
		int	boostRounds = `1`
	)		`[virtual]`

Add a feature to the classifier by applying multiple rounds of boosting.

This allows a single feature to have more discriminative power, with the danger of overfitting.

The classification result is equivalent to calling addFeature() multiple times on the same feature, but leads to greater computational efficiency of the overall classifier.

Parameters:

nextFeature	The feature to add.
boostRounds	Number of times to (effectively) call addFeature on this feature.

Size GentleBoostClassifier2::getBasePatchSize ( ) const

Size of patches used for training. All features added must have a size equal to getBasePatchSize().

getBasePatchSize() is set implicitly by the first feature added.

Returns:: Size of the features used by this this classifier.

FeatureRegressor2 GentleBoostClassifier2::getFeatureAndTuningCurveNumber ( int num ) const

Examine the features used by this GentleBoostClassifier2.

Parameters:

num	Index of the feature to query, numbered 0 to getNumFeaturesTotal()-1.

Returns:: A FeatureRegressor, which has the tuning curve as well as the feature.

virtual Feature2* GentleBoostClassifier2::getGoodFeature	(	int	patience = `1`,
		const std::string &	featureType = `"HaarFeature"`
	)		const `[virtual]`

Look for a feature that would improve classifier performance.

Parameters:

patience	How long do you want to wait to find a good feature?
featureType	Type of feature to look for.

void GentleBoostClassifier2::getImageHeaderForTestingPatch	(	cv::Mat &	dst,
		int	patchNum
	)		const `[virtual]`

Get an IplImage for visualizing the positive patches in the classifier - This must be released using cvReleaseImageHeader, and not cvReleaseImage, or you will destroy the data used for training.

This is useful for, for example, seeing what positive examples are currently confusing the classifier.

Parameters:

patchNum Must be between 0 and getNumPosPatches()

Returns:: An IplImage pointing to the actual training data. Memory must be managed by calling cvReleaseImageHeader, rather than cvReleaseImage().

void GentleBoostClassifier2::getImageHeaderForTrainingPatch	(	cv::Mat &	dst,
		int	patchNum
	)		const `[virtual]`

Get an IplImage for visualizing the negative patches in the classifier - This must be released using cvReleaseImageHeader, and not cvReleaseImage, or you will destroy the data used for training.

This is useful for, for example, seeing what negative examples are currently confusing the classifier.

Parameters:

patchNum Must be between 0 and getNumNegPatches()

Returns:: An IplImage pointing to the actual training data. Memory must be managed by calling cvReleaseImageHeader, rather than cvReleaseImage().

int GentleBoostClassifier2::getNumFeaturesTotal ( ) const

How many total available, trained features does the classifier have?

Returns:: Number of features trained and available for use.

int GentleBoostClassifier2::getNumFeaturesUsed ( ) const

How many of its total features is the classifier currently using? To improve speed or avoid generalization errors, it may be useful to only use the first few features of the classifier.

Returns:: Number of features currently being used.

int GentleBoostClassifier2::getNumScales ( ) const

Query the number of scales available for searching for objects. See PatchList for further discussion.

Returns:: Number of scales available for searching objects.

void GentleBoostClassifier2::getPerformanceMeasures	(	const Feature2 *	candidate,
		PerformanceMetrics &	perf
	)		const `[virtual]`

Compute perfomance measures for this classifier, depending on the Feature* passed in. This is primarily used for finding the best feature to add to the classifier, using addFeature().

getPerformanceMeasures has three modes depending on the candidate feature:

If the feature is NULL, calculates the current chi-squared error
If the feature is currently in the classifier, calculates the error if we remove the feature
Otherwise, calculates the error if we were to add this feature.

Parameters:

candidate	Can be NULL, one of the features in the classifier, or a candidate feature to add to the classifier.
chiSq	The computed error measure.

void GentleBoostClassifier2::getProbabilityMap	(	PatchList2 *	patches,
		cv::Mat &	dest
	)		const

Evaluate every pixel in an image for its probability that an object is located there.

Since GentleBoostClassifier2 is not a cascade, this process is somewhat slow. Also, GentleBoostClassifier2 has no notion of "rejection," so it cannot "find" patches containing the object. It can only give a patch-by-patch estimate of the likelihood that that patch is the object.

Parameters:

patches A PatchList that has had setImage() called, and also resetListToScale(). Only the current search scale is evaluated.

Returns:: An image with size patches->getImageSizeAtScale(), containing probability estimates. Each pixel represents the probability that the image patch with its top-left pixel at that probability map location contains an object.

Size GentleBoostClassifier2::getSizeOfScale ( int scale ) const

Query the size of object searched for at a given scale. See PatchList for further discussion.

Parameters:

scale Search scale.

Returns:: Patch size (object size) searched at that scale.

void GentleBoostClassifier2::searchCurrentImageAtScale	(	std::vector< SearchResult > &	keptPatches,
		int	scale,
		int	NMSRadius = `0`,
		double	thresh = `-INFINITY`
	)

Search through and image for objects at a single scale (size).

Parameters:

keptPatches	Results of the search are recorded in this vector. This is faster than returning a vector.
scale	Scale to search at. Must be between 0 and getNumScales()-1.
NMSRadius	Suppress object detection results if there is a another SearchResult with higher value nearby (within radius NMSRadius pixels).
thresh	Suppress object detection results with a value lower than thresh. Using -INFINITY returns all results. Using thresh=0 returns only SearchResult records that the cascade has at least 50% confidence in.

void GentleBoostClassifier2::searchImage	(	const cv::Mat &	gray_image,
		std::vector< SearchResult > &	keptPatches,
		int	NMSRadius = `0`,
		double	thresh = `-INFINITY`
	)

Search through and image for objects that this classifier was trained to detect. Results are passed back via the SearchResult vector keptPatches.

Parameters:

gray_image	Image or Frame to search. Must be single-channel, with depth IPL_DEPTH_8U.
keptPatches	Results of the search are recorded in this vector. This is faster than returning a vector.
NMSRadius	Suppress object detection results if there is a another SearchResult with higher value nearby (within radius NMSRadius pixels).
thresh	Suppress object detection results with a value lower than thresh. Using -INFINITY returns all results. Using thresh=0 returns only SearchResult records that the cascade has at least 50% confidence in.

virtual void GentleBoostClassifier2::searchPatches	(	const std::vector< ImagePatch2 > &	patches,
		const cv::Mat &	labels,
		cv::Mat &	featureSum,
		cv::Mat &	posterior,
		cv::Mat &	predictions,
		std::vector< cv::Mat > &	featureOutputs,
		double &	perf,
		cv::Mat &	weights,
		cv::Mat &	survived
	)		const `[virtual]`

Apply the GentleBoostClasssifier to a classify collection of image patches.

This classification requires a lot of scratch memory, which you can provide. The behavior of this function depends on which provided pointers are NULL. For example, perf and weights are only computed if labels is not NULL, whereas featureSum, posterior, and predictions are always computed. If any matrices that are required are NULL or incorrectly sized, they will be (re)allocated, and the caller of the function is responsible for managing that memory.

Parameters:

patches	A list of patches to classify.
labels	Optional labels for the patches, to evaluate classifier performance.
featureSum	The accumulated feature output that is used to predict the label of the patch.
posterior	The probability estimate that the patch was generated by the trained class.
predictions	Binary (+1/-1) classification labels applied by the classifier.
featureOutputs	The output of each individual FeatureRegressor applied to each patch.
perf	Chi-Squared error in predicting labels (only set if labels are provided).
weights	Weights based on boosting that can be used for training the next feature.

void GentleBoostClassifier2::setCurrentImage ( const cv::Mat & gray_image )

Set the current image to search, without actually searching. This allows you to search each scale (size) separately and manually, using searchCurrentImageAtScale().

Parameters:

gray_image Image or Frame to search. Must be single-channel, with depth IPL_DEPTH_8U.

void GentleBoostClassifier2::setNumFeaturesUsed ( int num )

Number of trained and available features to use. To improve speed or avoid generalization errors, it may be useful to only use the first few features of the classifier.

Parameters:

num	Number of features to use. Should be less than or equal to getNumFeaturesTotal().

virtual void GentleBoostClassifier2::setTestingSet	(	const std::vector< ImagePatch2 > &	testingPatches,
		const cv::Mat &	testingLabels
	)		`[virtual]`

Set ImagePatch data and labels used for evaluating the classifier.

Parameters:

testingPatches	A collection of positive and negative examples that the classifier's discrimination will be evaluated on.
testingLabels	Binary (+1/-1) indicating the label of each patch. This should be a matrix of type CV_64FC1 with size numPatches x 1.

virtual void GentleBoostClassifier2::setTrainingSet	(	const std::vector< ImagePatch2 > &	trainingPatches,
		const cv::Mat &	trainingLabels
	)		`[virtual]`

Set ImagePatch data and labels used for training the classifier.

Parameters:

trainingPatches	A collection of positive and negative examples that the classifier should learn to discriminate.
trainingLabels	Binary (+1/-1) indicating the label of each patch. This should be a matrix of type CV_64FC1 with size numPatches x 1.

void GentleBoostClassifier2::sharePatchListWithClassifier ( const GentleBoostClassifier2 & otherClassifier )

Share the patch list of another GentleBoostCascadedClassifier, to increase efficiency of multiple classifiers processing the same image.

By sharing a patch list, calling "setImage" on one classifier will set it for all of them. Thus different classifiers can share processing on the same image data.

However, be careful with this. It cannot be undone (within the lifetime of a single object -- reloading the classifier from disk will undo it).

Parameters:

otherClassifier Classifier to share a PatchList with.

PerformanceMetrics GentleBoostClassifier2::trainOneRound	(	int	patience = `1`,
		int	boostRounds = `1`
	)		`[virtual]`

Train boosted classifier for one round by searching for one good feature, and adding it.

Parameters:

patience	How long do you want to wait to find a good feature?
boostRounds	Train for multiple rounds of boosting on one feature: makes the classifier more discriminative but more prone to overfit.

Reimplemented in GentleBoostCascadedClassifier2.

The documentation for this class was generated from the following files:

/Users/nick/projects/NickThesis/Code/OpenCV/src/GentleBoostClassifier2.h
/Users/nick/projects/NickThesis/Code/OpenCV/src/GentleBoostClassifier2.cpp

GentleBoostClassifier2 Class Reference [Machine Perception Primitives]

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

GentleBoostClassifier2 Class Reference
[Machine Perception Primitives]