mirror/opencv
1
0
Fork 0
mirror of https://github.com/opencv/opencv.git synced 2024-11-26 04:00:30 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
10065d3321
opencv/modules/haartraining/cvclassifier.h

728 lines
26 KiB
C
Raw Blame History

/*M///////////////////////////////////////////////////////////////////////////////////////
//
// IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
//
// By downloading, copying, installing or using the software you agree to this license.
// If you do not agree to this license, do not download, install,
// copy or use the software.
//
//
// Intel License Agreement
// For Open Source Computer Vision Library
//
// Copyright (C) 2000, Intel Corporation, all rights reserved.
// Third party copyrights are property of their respective owners.
//
// Redistribution and use in source and binary forms, with or without modification,
// are permitted provided that the following conditions are met:
//
// * Redistribution's of source code must retain the above copyright notice,
// this list of conditions and the following disclaimer.
//
// * Redistribution's in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
//
// * The name of Intel Corporation may not be used to endorse or promote products
// derived from this software without specific prior written permission.
//
// This software is provided by the copyright holders and contributors "as is" and
// any express or implied warranties, including, but not limited to, the implied
// warranties of merchantability and fitness for a particular purpose are disclaimed.
// In no event shall the Intel Corporation or contributors be liable for any direct,
// indirect, incidental, special, exemplary, or consequential damages
// (including, but not limited to, procurement of substitute goods or services;
// loss of use, data, or profits; or business interruption) however caused
// and on any theory of liability, whether in contract, strict liability,
// or tort (including negligence or otherwise) arising in any way out of
// the use of this software, even if advised of the possibility of such damage.
//
//M*/
/*
* File cvclassifier.h
*
* Classifier types
*/
#ifndef _CVCLASSIFIER_H_
#define _CVCLASSIFIER_H_
#include <cmath>
#include "cxcore.h"
#define CV_BOOST_API
/* Convert matrix to vector */
#define CV_MAT2VEC( mat, vdata, vstep, num ) \
assert( (mat).rows == 1 || (mat).cols == 1 ); \
(vdata) = ((mat).data.ptr); \
if( (mat).rows == 1 ) \
{ \
(vstep) = CV_ELEM_SIZE( (mat).type ); \
(num) = (mat).cols; \
} \
else \
{ \
(vstep) = (mat).step; \
(num) = (mat).rows; \
}
/* Set up <sample> matrix header to be <num> sample of <trainData> samples matrix */
#define CV_GET_SAMPLE( trainData, tdflags, num, sample ) \
if( CV_IS_ROW_SAMPLE( tdflags ) ) \
{ \
cvInitMatHeader( &(sample), 1, (trainData).cols, \
CV_MAT_TYPE( (trainData).type ), \
((trainData).data.ptr + (num) * (trainData).step), \
(trainData).step ); \
} \
else \
{ \
cvInitMatHeader( &(sample), (trainData).rows, 1, \
CV_MAT_TYPE( (trainData).type ), \
((trainData).data.ptr + (num) * CV_ELEM_SIZE( (trainData).type )), \
(trainData).step ); \
}
#define CV_GET_SAMPLE_STEP( trainData, tdflags, sstep ) \
(sstep) = ( ( CV_IS_ROW_SAMPLE( tdflags ) ) \
? (trainData).step : CV_ELEM_SIZE( (trainData).type ) );
#define CV_LOGRATIO_THRESHOLD 0.00001F
/* log( val / (1 - val ) ) */
CV_INLINE float cvLogRatio( float val );
CV_INLINE float cvLogRatio( float val )
{
float tval;
tval = MAX(CV_LOGRATIO_THRESHOLD, MIN( 1.0F - CV_LOGRATIO_THRESHOLD, (val) ));
return logf( tval / (1.0F - tval) );
}
/* flags values for classifier consturctor flags parameter */
/* each trainData matrix column is a sample */
#define CV_COL_SAMPLE 0
/* each trainData matrix row is a sample */
#define CV_ROW_SAMPLE 1
#define CV_IS_ROW_SAMPLE( flags ) ( ( flags ) & CV_ROW_SAMPLE )
/* Classifier supports tune function */
#define CV_TUNABLE (1 << 1)
#define CV_IS_TUNABLE( flags ) ( (flags) & CV_TUNABLE )
/* classifier fields common to all classifiers */
#define CV_CLASSIFIER_FIELDS() \
int flags; \
float(*eval)( struct CvClassifier*, CvMat* ); \
void (*tune)( struct CvClassifier*, CvMat*, int flags, CvMat*, CvMat*, CvMat*, \
CvMat*, CvMat* ); \
int (*save)( struct CvClassifier*, const char* file_name ); \
void (*release)( struct CvClassifier** );
typedef struct CvClassifier
{
CV_CLASSIFIER_FIELDS()
} CvClassifier;
#define CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
typedef struct CvClassifierTrainParams
{
CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
} CvClassifierTrainParams;
/*
Common classifier constructor:
CvClassifier* cvCreateMyClassifier( CvMat* trainData,
int flags,
CvMat* trainClasses,
CvMat* typeMask,
CvMat* missedMeasurementsMask CV_DEFAULT(0),
CvCompIdx* compIdx CV_DEFAULT(0),
CvMat* sampleIdx CV_DEFAULT(0),
CvMat* weights CV_DEFAULT(0),
CvClassifierTrainParams* trainParams CV_DEFAULT(0)
)
*/
typedef CvClassifier* (*CvClassifierConstructor)( CvMat*, int, CvMat*, CvMat*, CvMat*,
CvMat*, CvMat*, CvMat*,
CvClassifierTrainParams* );
typedef enum CvStumpType
{
CV_CLASSIFICATION = 0,
CV_CLASSIFICATION_CLASS = 1,
CV_REGRESSION = 2
} CvStumpType;
typedef enum CvStumpError
{
CV_MISCLASSIFICATION = 0,
CV_GINI = 1,
CV_ENTROPY = 2,
CV_SQUARE = 3
} CvStumpError;
typedef struct CvStumpTrainParams
{
CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
CvStumpType type;
CvStumpError error;
} CvStumpTrainParams;
typedef struct CvMTStumpTrainParams
{
CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
CvStumpType type;
CvStumpError error;
int portion; /* number of components calculated in each thread */
int numcomp; /* total number of components */
/* callback which fills <mat> with components [first, first+num[ */
void (*getTrainData)( CvMat* mat, CvMat* sampleIdx, CvMat* compIdx,
int first, int num, void* userdata );
CvMat* sortedIdx; /* presorted samples indices */
void* userdata; /* passed to callback */
} CvMTStumpTrainParams;
typedef struct CvStumpClassifier
{
CV_CLASSIFIER_FIELDS()
int compidx;
float lerror; /* impurity of the right node */
float rerror; /* impurity of the left node */
float threshold;
float left;
float right;
} CvStumpClassifier;
typedef struct CvCARTTrainParams
{
CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
/* desired number of internal nodes */
int count;
CvClassifierTrainParams* stumpTrainParams;
CvClassifierConstructor stumpConstructor;
/*
* Split sample indices <idx>
* on the "left" indices <left> and "right" indices <right>
* according to samples components <compidx> values and <threshold>.
*
* NOTE: Matrices <left> and <right> must be allocated using cvCreateMat function
* since they are freed using cvReleaseMat function
*
* If it is NULL then the default implementation which evaluates training
* samples from <trainData> passed to classifier constructor is used
*/
void (*splitIdx)( int compidx, float threshold,
CvMat* idx, CvMat** left, CvMat** right,
void* userdata );
void* userdata;
} CvCARTTrainParams;
typedef struct CvCARTClassifier
{
CV_CLASSIFIER_FIELDS()
/* number of internal nodes */
int count;
/* internal nodes (each array of <count> elements) */
int* compidx;
float* threshold;
int* left;
int* right;
/* leaves (array of <count>+1 elements) */
float* val;
} CvCARTClassifier;
CV_BOOST_API
void cvGetSortedIndices( CvMat* val, CvMat* idx, int sortcols CV_DEFAULT( 0 ) );
CV_BOOST_API
void cvReleaseStumpClassifier( CvClassifier** classifier );
CV_BOOST_API
float cvEvalStumpClassifier( CvClassifier* classifier, CvMat* sample );
CV_BOOST_API
CvClassifier* cvCreateStumpClassifier( CvMat* trainData,
int flags,
CvMat* trainClasses,
CvMat* typeMask,
CvMat* missedMeasurementsMask CV_DEFAULT(0),
CvMat* compIdx CV_DEFAULT(0),
CvMat* sampleIdx CV_DEFAULT(0),
CvMat* weights CV_DEFAULT(0),
CvClassifierTrainParams* trainParams CV_DEFAULT(0) );
/*
* cvCreateMTStumpClassifier
*
* Multithreaded stump classifier constructor
* Includes huge train data support through callback function
*/
CV_BOOST_API
CvClassifier* cvCreateMTStumpClassifier( CvMat* trainData,
int flags,
CvMat* trainClasses,
CvMat* typeMask,
CvMat* missedMeasurementsMask,
CvMat* compIdx,
CvMat* sampleIdx,
CvMat* weights,
CvClassifierTrainParams* trainParams );
/*
* cvCreateCARTClassifier
*
* CART classifier constructor
*/
CV_BOOST_API
CvClassifier* cvCreateCARTClassifier( CvMat* trainData,
int flags,
CvMat* trainClasses,
CvMat* typeMask,
CvMat* missedMeasurementsMask,
CvMat* compIdx,
CvMat* sampleIdx,
CvMat* weights,
CvClassifierTrainParams* trainParams );
CV_BOOST_API
void cvReleaseCARTClassifier( CvClassifier** classifier );
CV_BOOST_API
float cvEvalCARTClassifier( CvClassifier* classifier, CvMat* sample );
/****************************************************************************************\
* Boosting *
\****************************************************************************************/
/*
* CvBoostType
*
* The CvBoostType enumeration specifies the boosting type.
*
* Remarks
* Four different boosting variants for 2 class classification problems are supported:
* Discrete AdaBoost, Real AdaBoost, LogitBoost and Gentle AdaBoost.
* The L2 (2 class classification problems) and LK (K class classification problems)
* algorithms are close to LogitBoost but more numerically stable than last one.
* For regression three different loss functions are supported:
* Least square, least absolute deviation and huber loss.
*/
typedef enum CvBoostType
{
CV_DABCLASS = 0, /* 2 class Discrete AdaBoost */
CV_RABCLASS = 1, /* 2 class Real AdaBoost */
CV_LBCLASS = 2, /* 2 class LogitBoost */
CV_GABCLASS = 3, /* 2 class Gentle AdaBoost */
CV_L2CLASS = 4, /* classification (2 class problem) */
CV_LKCLASS = 5, /* classification (K class problem) */
CV_LSREG = 6, /* least squares regression */
CV_LADREG = 7, /* least absolute deviation regression */
CV_MREG = 8, /* M-regression (Huber loss) */
} CvBoostType;
/****************************************************************************************\
* Iterative training functions *
\****************************************************************************************/
/*
* CvBoostTrainer
*
* The CvBoostTrainer structure represents internal boosting trainer.
*/
typedef struct CvBoostTrainer CvBoostTrainer;
/*
* cvBoostStartTraining
*
* The cvBoostStartTraining function starts training process and calculates
* response values and weights for the first weak classifier training.
*
* Parameters
* trainClasses
* Vector of classes of training samples classes. Each element must be 0 or 1 and
* of type CV_32FC1.
* weakTrainVals
* Vector of response values for the first trained weak classifier.
* Must be of type CV_32FC1.
* weights
* Weight vector of training samples for the first trained weak classifier.
* Must be of type CV_32FC1.
* type
* Boosting type. CV_DABCLASS, CV_RABCLASS, CV_LBCLASS, CV_GABCLASS
* types are supported.
*
* Return Values
* The return value is a pointer to internal trainer structure which is used
* to perform next training iterations.
*
* Remarks
* weakTrainVals and weights must be allocated before calling the function
* and of the same size as trainingClasses. Usually weights should be initialized
* with 1.0 value.
* The function calculates response values and weights for the first weak
* classifier training and stores them into weakTrainVals and weights
* respectively.
* Note, the training of the weak classifier using weakTrainVals, weight,
* trainingData is outside of this function.
*/
CV_BOOST_API
CvBoostTrainer* cvBoostStartTraining( CvMat* trainClasses,
CvMat* weakTrainVals,
CvMat* weights,
CvMat* sampleIdx,
CvBoostType type );
/*
* cvBoostNextWeakClassifier
*
* The cvBoostNextWeakClassifier function performs next training
* iteration and caluclates response values and weights for the next weak
* classifier training.
*
* Parameters
* weakEvalVals
* Vector of values obtained by evaluation of each sample with
* the last trained weak classifier (iteration i). Must be of CV_32FC1 type.
* trainClasses
* Vector of classes of training samples. Each element must be 0 or 1,
* and of type CV_32FC1.
* weakTrainVals
* Vector of response values for the next weak classifier training
* (iteration i+1). Must be of type CV_32FC1.
* weights
* Weight vector of training samples for the next weak classifier training
* (iteration i+1). Must be of type CV_32FC1.
* trainer
* A pointer to internal trainer returned by the cvBoostStartTraining
* function call.
*
* Return Values
* The return value is the coefficient for the last trained weak classifier.
*
* Remarks
* weakTrainVals and weights must be exactly the same vectors as used in
* the cvBoostStartTraining function call and should not be modified.
* The function calculates response values and weights for the next weak
* classifier training and stores them into weakTrainVals and weights
* respectively.
* Note, the training of the weak classifier of iteration i+1 using
* weakTrainVals, weight, trainingData is outside of this function.
*/
CV_BOOST_API
float cvBoostNextWeakClassifier( CvMat* weakEvalVals,
CvMat* trainClasses,
CvMat* weakTrainVals,
CvMat* weights,
CvBoostTrainer* trainer );
/*
* cvBoostEndTraining
*
* The cvBoostEndTraining function finishes training process and releases
* internally allocated memory.
*
* Parameters
* trainer
* A pointer to a pointer to internal trainer returned by the cvBoostStartTraining
* function call.
*/
CV_BOOST_API
void cvBoostEndTraining( CvBoostTrainer** trainer );
/****************************************************************************************\
* Boosted tree models *
\****************************************************************************************/
/*
* CvBtClassifier
*
* The CvBtClassifier structure represents boosted tree model.
*
* Members
* flags
* Flags. If CV_IS_TUNABLE( flags ) != 0 then the model supports tuning.
* eval
* Evaluation function. Returns sample predicted class (0, 1, etc.)
* for classification or predicted value for regression.
* tune
* Tune function. If the model supports tuning then tune call performs
* one more boosting iteration if passed to the function flags parameter
* is CV_TUNABLE otherwise releases internally allocated for tuning memory
* and makes the model untunable.
* NOTE: Since tuning uses the pointers to parameters,
* passed to the cvCreateBtClassifier function, they should not be modified
* or released between tune calls.
* save
* This function stores the model into given file.
* release
* This function releases the model.
* type
* Boosted tree model type.
* numclasses
* Number of classes for CV_LKCLASS type or 1 for all other types.
* numiter
* Number of iterations. Number of weak classifiers is equal to number
* of iterations for all types except CV_LKCLASS. For CV_LKCLASS type
* number of weak classifiers is (numiter * numclasses).
* numfeatures
* Number of features in sample.
* trees
* Stores weak classifiers when the model does not support tuning.
* seq
* Stores weak classifiers when the model supports tuning.
* trainer
* Pointer to internal tuning parameters if the model supports tuning.
*/
typedef struct CvBtClassifier
{
CV_CLASSIFIER_FIELDS()
CvBoostType type;
int numclasses;
int numiter;
int numfeatures;
union
{
CvCARTClassifier** trees;
CvSeq* seq;
};
void* trainer;
} CvBtClassifier;
/*
* CvBtClassifierTrainParams
*
* The CvBtClassifierTrainParams structure stores training parameters for
* boosted tree model.
*
* Members
* type
* Boosted tree model type.
* numiter
* Desired number of iterations.
* param
* Parameter Model Type Parameter Meaning
* param[0] Any Shrinkage factor
* param[1] CV_MREG alpha. (1-alpha) determines "break-down" point of
* the training procedure, i.e. the fraction of samples
* that can be arbitrary modified without serious
* degrading the quality of the result.
* CV_DABCLASS, Weight trimming factor.
* CV_RABCLASS,
* CV_LBCLASS,
* CV_GABCLASS,
* CV_L2CLASS,
* CV_LKCLASS
* numsplits
* Desired number of splits in each tree.
*/
typedef struct CvBtClassifierTrainParams
{
CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
CvBoostType type;
int numiter;
float param[2];
int numsplits;
} CvBtClassifierTrainParams;
/*
* cvCreateBtClassifier
*
* The cvCreateBtClassifier function creates boosted tree model.
*
* Parameters
* trainData
* Matrix of feature values. Must have CV_32FC1 type.
* flags
* Determines how samples are stored in trainData.
* One of CV_ROW_SAMPLE or CV_COL_SAMPLE.
* Optionally may be combined with CV_TUNABLE to make tunable model.
* trainClasses
* Vector of responses for regression or classes (0, 1, 2, etc.) for classification.
* typeMask,
* missedMeasurementsMask,
* compIdx
* Not supported. Must be NULL.
* sampleIdx
* Indices of samples used in training. If NULL then all samples are used.
* For CV_DABCLASS, CV_RABCLASS, CV_LBCLASS and CV_GABCLASS must be NULL.
* weights
* Not supported. Must be NULL.
* trainParams
* A pointer to CvBtClassifierTrainParams structure. Training parameters.
* See CvBtClassifierTrainParams description for details.
*
* Return Values
* The return value is a pointer to created boosted tree model of type CvBtClassifier.
*
* Remarks
* The function performs trainParams->numiter training iterations.
* If CV_TUNABLE flag is specified then created model supports tuning.
* In this case additional training iterations may be performed by
* tune function call.
*/
CV_BOOST_API
CvClassifier* cvCreateBtClassifier( CvMat* trainData,
int flags,
CvMat* trainClasses,
CvMat* typeMask,
CvMat* missedMeasurementsMask,
CvMat* compIdx,
CvMat* sampleIdx,
CvMat* weights,
CvClassifierTrainParams* trainParams );
/*
* cvCreateBtClassifierFromFile
*
* The cvCreateBtClassifierFromFile function restores previously saved
* boosted tree model from file.
*
* Parameters
* filename
* The name of the file with boosted tree model.
*
* Remarks
* The restored model does not support tuning.
*/
CV_BOOST_API
CvClassifier* cvCreateBtClassifierFromFile( const char* filename );
/****************************************************************************************\
* Utility functions *
\****************************************************************************************/
/*
* cvTrimWeights
*
* The cvTrimWeights function performs weight trimming.
*
* Parameters
* weights
* Weights vector.
* idx
* Indices vector of weights that should be considered.
* If it is NULL then all weights are used.
* factor
* Weight trimming factor. Must be in [0, 1] range.
*
* Return Values
* The return value is a vector of indices. If all samples should be used then
* it is equal to idx. In other case the cvReleaseMat function should be called
* to release it.
*
* Remarks
*/
CV_BOOST_API
CvMat* cvTrimWeights( CvMat* weights, CvMat* idx, float factor );
/*
* cvReadTrainData
*
* The cvReadTrainData function reads feature values and responses from file.
*
* Parameters
* filename
* The name of the file to be read.
* flags
* One of CV_ROW_SAMPLE or CV_COL_SAMPLE. Determines how feature values
* will be stored.
* trainData
* A pointer to a pointer to created matrix with feature values.
* cvReleaseMat function should be used to destroy created matrix.
* trainClasses
* A pointer to a pointer to created matrix with response values.
* cvReleaseMat function should be used to destroy created matrix.
*
* Remarks
* File format:
* ============================================
* m n
* value_1_1 value_1_2 ... value_1_n response_1
* value_2_1 value_2_2 ... value_2_n response_2
* ...
* value_m_1 value_m_2 ... value_m_n response_m
* ============================================
* m
* Number of samples
* n
* Number of features in each sample
* value_i_j
* Value of j-th feature of i-th sample
* response_i
* Response value of i-th sample
* For classification problems responses represent classes (0, 1, etc.)
* All values and classes are integer or real numbers.
*/
CV_BOOST_API
void cvReadTrainData( const char* filename,
int flags,
CvMat** trainData,
CvMat** trainClasses );
/*
* cvWriteTrainData
*
* The cvWriteTrainData function stores feature values and responses into file.
*
* Parameters
* filename
* The name of the file.
* flags
* One of CV_ROW_SAMPLE or CV_COL_SAMPLE. Determines how feature values
* are stored.
* trainData
* Feature values matrix.
* trainClasses
* Response values vector.
* sampleIdx
* Vector of idicies of the samples that should be stored. If it is NULL
* then all samples will be stored.
*
* Remarks
* See the cvReadTrainData function for file format description.
*/
CV_BOOST_API
void cvWriteTrainData( const char* filename,
int flags,
CvMat* trainData,
CvMat* trainClasses,
CvMat* sampleIdx );
/*
* cvRandShuffle
*
* The cvRandShuffle function perfroms random shuffling of given vector.
*
* Parameters
* vector
* Vector that should be shuffled.
* Must have CV_8UC1, CV_16SC1, CV_32SC1 or CV_32FC1 type.
*/
CV_BOOST_API
void cvRandShuffleVec( CvMat* vector );
#endif /* _CVCLASSIFIER_H_ */
Reference in New Issue View Git Blame Copy Permalink