Joe Verbout
opencv on mbed
Embed:
(wiki syntax)
Show/hide line numbers
ml.hpp
00001 /*M/////////////////////////////////////////////////////////////////////////////////////// 00002 // 00003 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. 00004 // 00005 // By downloading, copying, installing or using the software you agree to this license. 00006 // If you do not agree to this license, do not download, install, 00007 // copy or use the software. 00008 // 00009 // 00010 // License Agreement 00011 // For Open Source Computer Vision Library 00012 // 00013 // Copyright (C) 2000, Intel Corporation, all rights reserved. 00014 // Copyright (C) 2013, OpenCV Foundation, all rights reserved. 00015 // Copyright (C) 2014, Itseez Inc, all rights reserved. 00016 // Third party copyrights are property of their respective owners. 00017 // 00018 // Redistribution and use in source and binary forms, with or without modification, 00019 // are permitted provided that the following conditions are met: 00020 // 00021 // * Redistribution's of source code must retain the above copyright notice, 00022 // this list of conditions and the following disclaimer. 00023 // 00024 // * Redistribution's in binary form must reproduce the above copyright notice, 00025 // this list of conditions and the following disclaimer in the documentation 00026 // and/or other materials provided with the distribution. 00027 // 00028 // * The name of the copyright holders may not be used to endorse or promote products 00029 // derived from this software without specific prior written permission. 00030 // 00031 // This software is provided by the copyright holders and contributors "as is" and 00032 // any express or implied warranties, including, but not limited to, the implied 00033 // warranties of merchantability and fitness for a particular purpose are disclaimed. 00034 // In no event shall the Intel Corporation or contributors be liable for any direct, 00035 // indirect, incidental, special, exemplary, or consequential damages 00036 // (including, but not limited to, procurement of substitute goods or services; 00037 // loss of use, data, or profits; or business interruption) however caused 00038 // and on any theory of liability, whether in contract, strict liability, 00039 // or tort (including negligence or otherwise) arising in any way out of 00040 // the use of this software, even if advised of the possibility of such damage. 00041 // 00042 //M*/ 00043 00044 #ifndef __OPENCV_ML_HPP__ 00045 #define __OPENCV_ML_HPP__ 00046 00047 #ifdef __cplusplus 00048 # include "opencv2/core.hpp" 00049 #endif 00050 00051 #ifdef __cplusplus 00052 00053 #include <float.h> 00054 #include <map> 00055 #include <iostream> 00056 00057 /** 00058 @defgroup ml Machine Learning 00059 00060 The Machine Learning Library (MLL) is a set of classes and functions for statistical 00061 classification, regression, and clustering of data. 00062 00063 Most of the classification and regression algorithms are implemented as C++ classes. As the 00064 algorithms have different sets of features (like an ability to handle missing measurements or 00065 categorical input variables), there is a little common ground between the classes. This common 00066 ground is defined by the class cv::ml::StatModel that all the other ML classes are derived from. 00067 00068 See detailed overview here: @ref ml_intro. 00069 */ 00070 00071 namespace cv 00072 { 00073 00074 namespace ml 00075 { 00076 00077 //! @addtogroup ml 00078 //! @{ 00079 00080 /** @brief Variable types */ 00081 enum VariableTypes 00082 { 00083 VAR_NUMERICAL =0, //!< same as VAR_ORDERED 00084 VAR_ORDERED =0, //!< ordered variables 00085 VAR_CATEGORICAL =1 //!< categorical variables 00086 }; 00087 00088 /** @brief %Error types */ 00089 enum ErrorTypes 00090 { 00091 TEST_ERROR = 0, 00092 TRAIN_ERROR = 1 00093 }; 00094 00095 /** @brief Sample types */ 00096 enum SampleTypes 00097 { 00098 ROW_SAMPLE = 0, //!< each training sample is a row of samples 00099 COL_SAMPLE = 1 //!< each training sample occupies a column of samples 00100 }; 00101 00102 /** @brief The structure represents the logarithmic grid range of statmodel parameters. 00103 00104 It is used for optimizing statmodel accuracy by varying model parameters, the accuracy estimate 00105 being computed by cross-validation. 00106 */ 00107 class CV_EXPORTS ParamGrid 00108 { 00109 public: 00110 /** @brief Default constructor */ 00111 ParamGrid(); 00112 /** @brief Constructor with parameters */ 00113 ParamGrid(double _minVal, double _maxVal, double _logStep); 00114 00115 double minVal; //!< Minimum value of the statmodel parameter. Default value is 0. 00116 double maxVal; //!< Maximum value of the statmodel parameter. Default value is 0. 00117 /** @brief Logarithmic step for iterating the statmodel parameter. 00118 00119 The grid determines the following iteration sequence of the statmodel parameter values: 00120 \f[(minVal, minVal*step, minVal*{step}^2, \dots, minVal*{logStep}^n),\f] 00121 where \f$n\f$ is the maximal index satisfying 00122 \f[\texttt{minVal} * \texttt{logStep} ^n < \texttt{maxVal}\f] 00123 The grid is logarithmic, so logStep must always be greater then 1. Default value is 1. 00124 */ 00125 double logStep; 00126 }; 00127 00128 /** @brief Class encapsulating training data. 00129 00130 Please note that the class only specifies the interface of training data, but not implementation. 00131 All the statistical model classes in _ml_ module accepts Ptr<TrainData> as parameter. In other 00132 words, you can create your own class derived from TrainData and pass smart pointer to the instance 00133 of this class into StatModel::train. 00134 00135 @sa @ref ml_intro_data 00136 */ 00137 class CV_EXPORTS_W TrainData 00138 { 00139 public: 00140 static inline float missingValue() { return FLT_MAX; } 00141 virtual ~TrainData(); 00142 00143 CV_WRAP virtual int getLayout() const = 0; 00144 CV_WRAP virtual int getNTrainSamples() const = 0; 00145 CV_WRAP virtual int getNTestSamples() const = 0; 00146 CV_WRAP virtual int getNSamples() const = 0; 00147 CV_WRAP virtual int getNVars() const = 0; 00148 CV_WRAP virtual int getNAllVars() const = 0; 00149 00150 CV_WRAP virtual void getSample(InputArray varIdx, int sidx, float* buf) const = 0; 00151 CV_WRAP virtual Mat getSamples() const = 0; 00152 CV_WRAP virtual Mat getMissing() const = 0; 00153 00154 /** @brief Returns matrix of train samples 00155 00156 @param layout The requested layout. If it's different from the initial one, the matrix is 00157 transposed. See ml::SampleTypes. 00158 @param compressSamples if true, the function returns only the training samples (specified by 00159 sampleIdx) 00160 @param compressVars if true, the function returns the shorter training samples, containing only 00161 the active variables. 00162 00163 In current implementation the function tries to avoid physical data copying and returns the 00164 matrix stored inside TrainData (unless the transposition or compression is needed). 00165 */ 00166 CV_WRAP virtual Mat getTrainSamples(int layout=ROW_SAMPLE, 00167 bool compressSamples=true, 00168 bool compressVars=true) const = 0; 00169 00170 /** @brief Returns the vector of responses 00171 00172 The function returns ordered or the original categorical responses. Usually it's used in 00173 regression algorithms. 00174 */ 00175 CV_WRAP virtual Mat getTrainResponses() const = 0; 00176 00177 /** @brief Returns the vector of normalized categorical responses 00178 00179 The function returns vector of responses. Each response is integer from `0` to `<number of 00180 classes>-1`. The actual label value can be retrieved then from the class label vector, see 00181 TrainData::getClassLabels. 00182 */ 00183 CV_WRAP virtual Mat getTrainNormCatResponses() const = 0; 00184 CV_WRAP virtual Mat getTestResponses() const = 0; 00185 CV_WRAP virtual Mat getTestNormCatResponses() const = 0; 00186 CV_WRAP virtual Mat getResponses() const = 0; 00187 CV_WRAP virtual Mat getNormCatResponses() const = 0; 00188 CV_WRAP virtual Mat getSampleWeights() const = 0; 00189 CV_WRAP virtual Mat getTrainSampleWeights() const = 0; 00190 CV_WRAP virtual Mat getTestSampleWeights() const = 0; 00191 CV_WRAP virtual Mat getVarIdx() const = 0; 00192 CV_WRAP virtual Mat getVarType() const = 0; 00193 CV_WRAP virtual int getResponseType() const = 0; 00194 CV_WRAP virtual Mat getTrainSampleIdx() const = 0; 00195 CV_WRAP virtual Mat getTestSampleIdx() const = 0; 00196 CV_WRAP virtual void getValues(int vi, InputArray sidx, float* values) const = 0; 00197 virtual void getNormCatValues(int vi, InputArray sidx, int* values) const = 0; 00198 CV_WRAP virtual Mat getDefaultSubstValues() const = 0; 00199 00200 CV_WRAP virtual int getCatCount(int vi) const = 0; 00201 00202 /** @brief Returns the vector of class labels 00203 00204 The function returns vector of unique labels occurred in the responses. 00205 */ 00206 CV_WRAP virtual Mat getClassLabels() const = 0; 00207 00208 CV_WRAP virtual Mat getCatOfs() const = 0; 00209 CV_WRAP virtual Mat getCatMap() const = 0; 00210 00211 /** @brief Splits the training data into the training and test parts 00212 @sa TrainData::setTrainTestSplitRatio 00213 */ 00214 CV_WRAP virtual void setTrainTestSplit(int count, bool shuffle=true) = 0; 00215 00216 /** @brief Splits the training data into the training and test parts 00217 00218 The function selects a subset of specified relative size and then returns it as the training 00219 set. If the function is not called, all the data is used for training. Please, note that for 00220 each of TrainData::getTrain\* there is corresponding TrainData::getTest\*, so that the test 00221 subset can be retrieved and processed as well. 00222 @sa TrainData::setTrainTestSplit 00223 */ 00224 CV_WRAP virtual void setTrainTestSplitRatio(double ratio, bool shuffle=true) = 0; 00225 CV_WRAP virtual void shuffleTrainTest() = 0; 00226 00227 CV_WRAP static Mat getSubVector(const Mat& vec, const Mat& idx); 00228 00229 /** @brief Reads the dataset from a .csv file and returns the ready-to-use training data. 00230 00231 @param filename The input file name 00232 @param headerLineCount The number of lines in the beginning to skip; besides the header, the 00233 function also skips empty lines and lines staring with `#` 00234 @param responseStartIdx Index of the first output variable. If -1, the function considers the 00235 last variable as the response 00236 @param responseEndIdx Index of the last output variable + 1. If -1, then there is single 00237 response variable at responseStartIdx. 00238 @param varTypeSpec The optional text string that specifies the variables' types. It has the 00239 format `ord[n1-n2,n3,n4-n5,...]cat[n6,n7-n8,...]`. That is, variables from `n1 to n2` 00240 (inclusive range), `n3`, `n4 to n5` ... are considered ordered and `n6`, `n7 to n8` ... are 00241 considered as categorical. The range `[n1..n2] + [n3] + [n4..n5] + ... + [n6] + [n7..n8]` 00242 should cover all the variables. If varTypeSpec is not specified, then algorithm uses the 00243 following rules: 00244 - all input variables are considered ordered by default. If some column contains has non- 00245 numerical values, e.g. 'apple', 'pear', 'apple', 'apple', 'mango', the corresponding 00246 variable is considered categorical. 00247 - if there are several output variables, they are all considered as ordered. Error is 00248 reported when non-numerical values are used. 00249 - if there is a single output variable, then if its values are non-numerical or are all 00250 integers, then it's considered categorical. Otherwise, it's considered ordered. 00251 @param delimiter The character used to separate values in each line. 00252 @param missch The character used to specify missing measurements. It should not be a digit. 00253 Although it's a non-numerical value, it surely does not affect the decision of whether the 00254 variable ordered or categorical. 00255 @note If the dataset only contains input variables and no responses, use responseStartIdx = -2 00256 and responseEndIdx = 0. The output variables vector will just contain zeros. 00257 */ 00258 static Ptr<TrainData> loadFromCSV(const String& filename, 00259 int headerLineCount, 00260 int responseStartIdx=-1, 00261 int responseEndIdx=-1, 00262 const String& varTypeSpec=String(), 00263 char delimiter=',', 00264 char missch='?'); 00265 00266 /** @brief Creates training data from in-memory arrays. 00267 00268 @param samples matrix of samples. It should have CV_32F type. 00269 @param layout see ml::SampleTypes. 00270 @param responses matrix of responses. If the responses are scalar, they should be stored as a 00271 single row or as a single column. The matrix should have type CV_32F or CV_32S (in the 00272 former case the responses are considered as ordered by default; in the latter case - as 00273 categorical) 00274 @param varIdx vector specifying which variables to use for training. It can be an integer vector 00275 (CV_32S) containing 0-based variable indices or byte vector (CV_8U) containing a mask of 00276 active variables. 00277 @param sampleIdx vector specifying which samples to use for training. It can be an integer 00278 vector (CV_32S) containing 0-based sample indices or byte vector (CV_8U) containing a mask 00279 of training samples. 00280 @param sampleWeights optional vector with weights for each sample. It should have CV_32F type. 00281 @param varType optional vector of type CV_8U and size `<number_of_variables_in_samples> + 00282 <number_of_variables_in_responses>`, containing types of each input and output variable. See 00283 ml::VariableTypes. 00284 */ 00285 CV_WRAP static Ptr<TrainData> create(InputArray samples, int layout, InputArray responses, 00286 InputArray varIdx=noArray(), InputArray sampleIdx=noArray(), 00287 InputArray sampleWeights=noArray(), InputArray varType=noArray()); 00288 }; 00289 00290 /** @brief Base class for statistical models in OpenCV ML. 00291 */ 00292 class CV_EXPORTS_W StatModel : public Algorithm 00293 { 00294 public: 00295 /** Predict options */ 00296 enum Flags { 00297 UPDATE_MODEL = 1, 00298 RAW_OUTPUT=1, //!< makes the method return the raw results (the sum), not the class label 00299 COMPRESSED_INPUT=2, 00300 PREPROCESSED_INPUT=4 00301 }; 00302 00303 /** @brief Returns the number of variables in training samples */ 00304 CV_WRAP virtual int getVarCount() const = 0; 00305 00306 CV_WRAP virtual bool empty() const; 00307 00308 /** @brief Returns true if the model is trained */ 00309 CV_WRAP virtual bool isTrained() const = 0; 00310 /** @brief Returns true if the model is classifier */ 00311 CV_WRAP virtual bool isClassifier() const = 0; 00312 00313 /** @brief Trains the statistical model 00314 00315 @param trainData training data that can be loaded from file using TrainData::loadFromCSV or 00316 created with TrainData::create. 00317 @param flags optional flags, depending on the model. Some of the models can be updated with the 00318 new training samples, not completely overwritten (such as NormalBayesClassifier or ANN_MLP). 00319 */ 00320 CV_WRAP virtual bool train( const Ptr<TrainData>& trainData, int flags=0 ); 00321 00322 /** @brief Trains the statistical model 00323 00324 @param samples training samples 00325 @param layout See ml::SampleTypes. 00326 @param responses vector of responses associated with the training samples. 00327 */ 00328 CV_WRAP virtual bool train( InputArray samples, int layout, InputArray responses ); 00329 00330 /** @brief Computes error on the training or test dataset 00331 00332 @param data the training data 00333 @param test if true, the error is computed over the test subset of the data, otherwise it's 00334 computed over the training subset of the data. Please note that if you loaded a completely 00335 different dataset to evaluate already trained classifier, you will probably want not to set 00336 the test subset at all with TrainData::setTrainTestSplitRatio and specify test=false, so 00337 that the error is computed for the whole new set. Yes, this sounds a bit confusing. 00338 @param resp the optional output responses. 00339 00340 The method uses StatModel::predict to compute the error. For regression models the error is 00341 computed as RMS, for classifiers - as a percent of missclassified samples (0%-100%). 00342 */ 00343 CV_WRAP virtual float calcError( const Ptr<TrainData>& data, bool test, OutputArray resp ) const; 00344 00345 /** @brief Predicts response(s) for the provided sample(s) 00346 00347 @param samples The input samples, floating-point matrix 00348 @param results The optional output matrix of results. 00349 @param flags The optional flags, model-dependent. See cv::ml::StatModel::Flags. 00350 */ 00351 CV_WRAP virtual float predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const = 0; 00352 00353 /** @brief Create and train model with default parameters 00354 00355 The class must implement static `create()` method with no parameters or with all default parameter values 00356 */ 00357 template<typename _Tp> static Ptr<_Tp> train(const Ptr<TrainData>& data, int flags=0) 00358 { 00359 Ptr<_Tp> model = _Tp::create(); 00360 return !model.empty() && model->train(data, flags) ? model : Ptr<_Tp>(); 00361 } 00362 }; 00363 00364 /****************************************************************************************\ 00365 * Normal Bayes Classifier * 00366 \****************************************************************************************/ 00367 00368 /** @brief Bayes classifier for normally distributed data. 00369 00370 @sa @ref ml_intro_bayes 00371 */ 00372 class CV_EXPORTS_W NormalBayesClassifier : public StatModel 00373 { 00374 public: 00375 /** @brief Predicts the response for sample(s). 00376 00377 The method estimates the most probable classes for input vectors. Input vectors (one or more) 00378 are stored as rows of the matrix inputs. In case of multiple input vectors, there should be one 00379 output vector outputs. The predicted class for a single input vector is returned by the method. 00380 The vector outputProbs contains the output probabilities corresponding to each element of 00381 result. 00382 */ 00383 CV_WRAP virtual float predictProb( InputArray inputs, OutputArray outputs, 00384 OutputArray outputProbs, int flags=0 ) const = 0; 00385 00386 /** Creates empty model 00387 Use StatModel::train to train the model after creation. */ 00388 CV_WRAP static Ptr<NormalBayesClassifier> create(); 00389 }; 00390 00391 /****************************************************************************************\ 00392 * K-Nearest Neighbour Classifier * 00393 \****************************************************************************************/ 00394 00395 /** @brief The class implements K-Nearest Neighbors model 00396 00397 @sa @ref ml_intro_knn 00398 */ 00399 class CV_EXPORTS_W KNearest : public StatModel 00400 { 00401 public: 00402 00403 /** Default number of neighbors to use in predict method. */ 00404 /** @see setDefaultK */ 00405 CV_WRAP virtual int getDefaultK() const = 0; 00406 /** @copybrief getDefaultK @see getDefaultK */ 00407 CV_WRAP virtual void setDefaultK(int val) = 0; 00408 00409 /** Whether classification or regression model should be trained. */ 00410 /** @see setIsClassifier */ 00411 CV_WRAP virtual bool getIsClassifier() const = 0; 00412 /** @copybrief getIsClassifier @see getIsClassifier */ 00413 CV_WRAP virtual void setIsClassifier(bool val) = 0; 00414 00415 /** Parameter for KDTree implementation. */ 00416 /** @see setEmax */ 00417 CV_WRAP virtual int getEmax() const = 0; 00418 /** @copybrief getEmax @see getEmax */ 00419 CV_WRAP virtual void setEmax(int val) = 0; 00420 00421 /** %Algorithm type, one of KNearest::Types. */ 00422 /** @see setAlgorithmType */ 00423 CV_WRAP virtual int getAlgorithmType() const = 0; 00424 /** @copybrief getAlgorithmType @see getAlgorithmType */ 00425 CV_WRAP virtual void setAlgorithmType(int val) = 0; 00426 00427 /** @brief Finds the neighbors and predicts responses for input vectors. 00428 00429 @param samples Input samples stored by rows. It is a single-precision floating-point matrix of 00430 `<number_of_samples> * k` size. 00431 @param k Number of used nearest neighbors. Should be greater than 1. 00432 @param results Vector with results of prediction (regression or classification) for each input 00433 sample. It is a single-precision floating-point vector with `<number_of_samples>` elements. 00434 @param neighborResponses Optional output values for corresponding neighbors. It is a single- 00435 precision floating-point matrix of `<number_of_samples> * k` size. 00436 @param dist Optional output distances from the input vectors to the corresponding neighbors. It 00437 is a single-precision floating-point matrix of `<number_of_samples> * k` size. 00438 00439 For each input vector (a row of the matrix samples), the method finds the k nearest neighbors. 00440 In case of regression, the predicted result is a mean value of the particular vector's neighbor 00441 responses. In case of classification, the class is determined by voting. 00442 00443 For each input vector, the neighbors are sorted by their distances to the vector. 00444 00445 In case of C++ interface you can use output pointers to empty matrices and the function will 00446 allocate memory itself. 00447 00448 If only a single input vector is passed, all output matrices are optional and the predicted 00449 value is returned by the method. 00450 00451 The function is parallelized with the TBB library. 00452 */ 00453 CV_WRAP virtual float findNearest( InputArray samples, int k, 00454 OutputArray results, 00455 OutputArray neighborResponses=noArray(), 00456 OutputArray dist=noArray() ) const = 0; 00457 00458 /** @brief Implementations of KNearest algorithm 00459 */ 00460 enum Types 00461 { 00462 BRUTE_FORCE=1, 00463 KDTREE=2 00464 }; 00465 00466 /** @brief Creates the empty model 00467 00468 The static method creates empty %KNearest classifier. It should be then trained using StatModel::train method. 00469 */ 00470 CV_WRAP static Ptr<KNearest> create(); 00471 }; 00472 00473 /****************************************************************************************\ 00474 * Support Vector Machines * 00475 \****************************************************************************************/ 00476 00477 /** @brief Support Vector Machines. 00478 00479 @sa @ref ml_intro_svm 00480 */ 00481 class CV_EXPORTS_W SVM : public StatModel 00482 { 00483 public: 00484 00485 class CV_EXPORTS Kernel : public Algorithm 00486 { 00487 public: 00488 virtual int getType() const = 0; 00489 virtual void calc( int vcount, int n, const float* vecs, const float* another, float* results ) = 0; 00490 }; 00491 00492 /** Type of a %SVM formulation. 00493 See SVM::Types. Default value is SVM::C_SVC. */ 00494 /** @see setType */ 00495 CV_WRAP virtual int getType() const = 0; 00496 /** @copybrief getType @see getType */ 00497 CV_WRAP virtual void setType(int val) = 0; 00498 00499 /** Parameter \f$\gamma\f$ of a kernel function. 00500 For SVM::POLY, SVM::RBF, SVM::SIGMOID or SVM::CHI2. Default value is 1. */ 00501 /** @see setGamma */ 00502 CV_WRAP virtual double getGamma() const = 0; 00503 /** @copybrief getGamma @see getGamma */ 00504 CV_WRAP virtual void setGamma(double val) = 0; 00505 00506 /** Parameter _coef0_ of a kernel function. 00507 For SVM::POLY or SVM::SIGMOID. Default value is 0.*/ 00508 /** @see setCoef0 */ 00509 CV_WRAP virtual double getCoef0() const = 0; 00510 /** @copybrief getCoef0 @see getCoef0 */ 00511 CV_WRAP virtual void setCoef0(double val) = 0; 00512 00513 /** Parameter _degree_ of a kernel function. 00514 For SVM::POLY. Default value is 0. */ 00515 /** @see setDegree */ 00516 CV_WRAP virtual double getDegree() const = 0; 00517 /** @copybrief getDegree @see getDegree */ 00518 CV_WRAP virtual void setDegree(double val) = 0; 00519 00520 /** Parameter _C_ of a %SVM optimization problem. 00521 For SVM::C_SVC, SVM::EPS_SVR or SVM::NU_SVR. Default value is 0. */ 00522 /** @see setC */ 00523 CV_WRAP virtual double getC() const = 0; 00524 /** @copybrief getC @see getC */ 00525 CV_WRAP virtual void setC(double val) = 0; 00526 00527 /** Parameter \f$\nu\f$ of a %SVM optimization problem. 00528 For SVM::NU_SVC, SVM::ONE_CLASS or SVM::NU_SVR. Default value is 0. */ 00529 /** @see setNu */ 00530 CV_WRAP virtual double getNu() const = 0; 00531 /** @copybrief getNu @see getNu */ 00532 CV_WRAP virtual void setNu(double val) = 0; 00533 00534 /** Parameter \f$\epsilon\f$ of a %SVM optimization problem. 00535 For SVM::EPS_SVR. Default value is 0. */ 00536 /** @see setP */ 00537 CV_WRAP virtual double getP() const = 0; 00538 /** @copybrief getP @see getP */ 00539 CV_WRAP virtual void setP(double val) = 0; 00540 00541 /** Optional weights in the SVM::C_SVC problem, assigned to particular classes. 00542 They are multiplied by _C_ so the parameter _C_ of class _i_ becomes `classWeights(i) * C`. Thus 00543 these weights affect the misclassification penalty for different classes. The larger weight, 00544 the larger penalty on misclassification of data from the corresponding class. Default value is 00545 empty Mat. */ 00546 /** @see setClassWeights */ 00547 CV_WRAP virtual cv::Mat getClassWeights() const = 0; 00548 /** @copybrief getClassWeights @see getClassWeights */ 00549 CV_WRAP virtual void setClassWeights(const cv::Mat &val) = 0; 00550 00551 /** Termination criteria of the iterative %SVM training procedure which solves a partial 00552 case of constrained quadratic optimization problem. 00553 You can specify tolerance and/or the maximum number of iterations. Default value is 00554 `TermCriteria( TermCriteria::MAX_ITER + TermCriteria::EPS, 1000, FLT_EPSILON )`; */ 00555 /** @see setTermCriteria */ 00556 CV_WRAP virtual cv::TermCriteria getTermCriteria() const = 0; 00557 /** @copybrief getTermCriteria @see getTermCriteria */ 00558 CV_WRAP virtual void setTermCriteria(const cv::TermCriteria &val) = 0; 00559 00560 /** Type of a %SVM kernel. 00561 See SVM::KernelTypes. Default value is SVM::RBF. */ 00562 CV_WRAP virtual int getKernelType() const = 0; 00563 00564 /** Initialize with one of predefined kernels. 00565 See SVM::KernelTypes. */ 00566 CV_WRAP virtual void setKernel(int kernelType) = 0; 00567 00568 /** Initialize with custom kernel. 00569 See SVM::Kernel class for implementation details */ 00570 virtual void setCustomKernel(const Ptr<Kernel> &_kernel) = 0; 00571 00572 //! %SVM type 00573 enum Types { 00574 /** C-Support Vector Classification. n-class classification (n \f$\geq\f$ 2), allows 00575 imperfect separation of classes with penalty multiplier C for outliers. */ 00576 C_SVC=100, 00577 /** \f$\nu\f$-Support Vector Classification. n-class classification with possible 00578 imperfect separation. Parameter \f$\nu\f$ (in the range 0..1, the larger the value, the smoother 00579 the decision boundary) is used instead of C. */ 00580 NU_SVC=101, 00581 /** Distribution Estimation (One-class %SVM). All the training data are from 00582 the same class, %SVM builds a boundary that separates the class from the rest of the feature 00583 space. */ 00584 ONE_CLASS=102, 00585 /** \f$\epsilon\f$-Support Vector Regression. The distance between feature vectors 00586 from the training set and the fitting hyper-plane must be less than p. For outliers the 00587 penalty multiplier C is used. */ 00588 EPS_SVR=103, 00589 /** \f$\nu\f$-Support Vector Regression. \f$\nu\f$ is used instead of p. 00590 See @cite LibSVM for details. */ 00591 NU_SVR=104 00592 }; 00593 00594 /** @brief %SVM kernel type 00595 00596 A comparison of different kernels on the following 2D test case with four classes. Four 00597 SVM::C_SVC SVMs have been trained (one against rest) with auto_train. Evaluation on three 00598 different kernels (SVM::CHI2, SVM::INTER, SVM::RBF). The color depicts the class with max score. 00599 Bright means max-score > 0, dark means max-score < 0. 00600  00601 */ 00602 enum KernelTypes { 00603 /** Returned by SVM::getKernelType in case when custom kernel has been set */ 00604 CUSTOM=-1, 00605 /** Linear kernel. No mapping is done, linear discrimination (or regression) is 00606 done in the original feature space. It is the fastest option. \f$K(x_i, x_j) = x_i^T x_j\f$. */ 00607 LINEAR=0, 00608 /** Polynomial kernel: 00609 \f$K(x_i, x_j) = (\gamma x_i^T x_j + coef0)^{degree}, \gamma > 0\f$. */ 00610 POLY=1, 00611 /** Radial basis function (RBF), a good choice in most cases. 00612 \f$K(x_i, x_j) = e^{-\gamma ||x_i - x_j||^2}, \gamma > 0\f$. */ 00613 RBF=2, 00614 /** Sigmoid kernel: \f$K(x_i, x_j) = \tanh(\gamma x_i^T x_j + coef0)\f$. */ 00615 SIGMOID=3, 00616 /** Exponential Chi2 kernel, similar to the RBF kernel: 00617 \f$K(x_i, x_j) = e^{-\gamma \chi^2(x_i,x_j)}, \chi^2(x_i,x_j) = (x_i-x_j)^2/(x_i+x_j), \gamma > 0\f$. */ 00618 CHI2=4, 00619 /** Histogram intersection kernel. A fast kernel. \f$K(x_i, x_j) = min(x_i,x_j)\f$. */ 00620 INTER=5 00621 }; 00622 00623 //! %SVM params type 00624 enum ParamTypes { 00625 C=0, 00626 GAMMA=1, 00627 P=2, 00628 NU=3, 00629 COEF=4, 00630 DEGREE=5 00631 }; 00632 00633 /** @brief Trains an %SVM with optimal parameters. 00634 00635 @param data the training data that can be constructed using TrainData::create or 00636 TrainData::loadFromCSV. 00637 @param kFold Cross-validation parameter. The training set is divided into kFold subsets. One 00638 subset is used to test the model, the others form the train set. So, the %SVM algorithm is 00639 executed kFold times. 00640 @param Cgrid grid for C 00641 @param gammaGrid grid for gamma 00642 @param pGrid grid for p 00643 @param nuGrid grid for nu 00644 @param coeffGrid grid for coeff 00645 @param degreeGrid grid for degree 00646 @param balanced If true and the problem is 2-class classification then the method creates more 00647 balanced cross-validation subsets that is proportions between classes in subsets are close 00648 to such proportion in the whole train dataset. 00649 00650 The method trains the %SVM model automatically by choosing the optimal parameters C, gamma, p, 00651 nu, coef0, degree. Parameters are considered optimal when the cross-validation 00652 estimate of the test set error is minimal. 00653 00654 If there is no need to optimize a parameter, the corresponding grid step should be set to any 00655 value less than or equal to 1. For example, to avoid optimization in gamma, set `gammaGrid.step 00656 = 0`, `gammaGrid.minVal`, `gamma_grid.maxVal` as arbitrary numbers. In this case, the value 00657 `Gamma` is taken for gamma. 00658 00659 And, finally, if the optimization in a parameter is required but the corresponding grid is 00660 unknown, you may call the function SVM::getDefaultGrid. To generate a grid, for example, for 00661 gamma, call `SVM::getDefaultGrid(SVM::GAMMA)`. 00662 00663 This function works for the classification (SVM::C_SVC or SVM::NU_SVC) as well as for the 00664 regression (SVM::EPS_SVR or SVM::NU_SVR). If it is SVM::ONE_CLASS, no optimization is made and 00665 the usual %SVM with parameters specified in params is executed. 00666 */ 00667 virtual bool trainAuto( const Ptr<TrainData>& data, int kFold = 10, 00668 ParamGrid Cgrid = SVM::getDefaultGrid(SVM::C), 00669 ParamGrid gammaGrid = SVM::getDefaultGrid(SVM::GAMMA), 00670 ParamGrid pGrid = SVM::getDefaultGrid(SVM::P), 00671 ParamGrid nuGrid = SVM::getDefaultGrid(SVM::NU), 00672 ParamGrid coeffGrid = SVM::getDefaultGrid(SVM::COEF), 00673 ParamGrid degreeGrid = SVM::getDefaultGrid(SVM::DEGREE), 00674 bool balanced=false) = 0; 00675 00676 /** @brief Retrieves all the support vectors 00677 00678 The method returns all the support vectors as a floating-point matrix, where support vectors are 00679 stored as matrix rows. 00680 */ 00681 CV_WRAP virtual Mat getSupportVectors() const = 0; 00682 00683 /** @brief Retrieves all the uncompressed support vectors of a linear %SVM 00684 00685 The method returns all the uncompressed support vectors of a linear %SVM that the compressed 00686 support vector, used for prediction, was derived from. They are returned in a floating-point 00687 matrix, where the support vectors are stored as matrix rows. 00688 */ 00689 CV_WRAP Mat getUncompressedSupportVectors() const; 00690 00691 /** @brief Retrieves the decision function 00692 00693 @param i the index of the decision function. If the problem solved is regression, 1-class or 00694 2-class classification, then there will be just one decision function and the index should 00695 always be 0. Otherwise, in the case of N-class classification, there will be \f$N(N-1)/2\f$ 00696 decision functions. 00697 @param alpha the optional output vector for weights, corresponding to different support vectors. 00698 In the case of linear %SVM all the alpha's will be 1's. 00699 @param svidx the optional output vector of indices of support vectors within the matrix of 00700 support vectors (which can be retrieved by SVM::getSupportVectors). In the case of linear 00701 %SVM each decision function consists of a single "compressed" support vector. 00702 00703 The method returns rho parameter of the decision function, a scalar subtracted from the weighted 00704 sum of kernel responses. 00705 */ 00706 CV_WRAP virtual double getDecisionFunction(int i, OutputArray alpha, OutputArray svidx) const = 0; 00707 00708 /** @brief Generates a grid for %SVM parameters. 00709 00710 @param param_id %SVM parameters IDs that must be one of the SVM::ParamTypes. The grid is 00711 generated for the parameter with this ID. 00712 00713 The function generates a grid for the specified parameter of the %SVM algorithm. The grid may be 00714 passed to the function SVM::trainAuto. 00715 */ 00716 static ParamGrid getDefaultGrid( int param_id ); 00717 00718 /** Creates empty model. 00719 Use StatModel::train to train the model. Since %SVM has several parameters, you may want to 00720 find the best parameters for your problem, it can be done with SVM::trainAuto. */ 00721 CV_WRAP static Ptr<SVM> create(); 00722 }; 00723 00724 /****************************************************************************************\ 00725 * Expectation - Maximization * 00726 \****************************************************************************************/ 00727 00728 /** @brief The class implements the Expectation Maximization algorithm. 00729 00730 @sa @ref ml_intro_em 00731 */ 00732 class CV_EXPORTS_W EM : public StatModel 00733 { 00734 public: 00735 //! Type of covariation matrices 00736 enum Types { 00737 /** A scaled identity matrix \f$\mu_k * I\f$. There is the only 00738 parameter \f$\mu_k\f$ to be estimated for each matrix. The option may be used in special cases, 00739 when the constraint is relevant, or as a first step in the optimization (for example in case 00740 when the data is preprocessed with PCA). The results of such preliminary estimation may be 00741 passed again to the optimization procedure, this time with 00742 covMatType=EM::COV_MAT_DIAGONAL. */ 00743 COV_MAT_SPHERICAL=0, 00744 /** A diagonal matrix with positive diagonal elements. The number of 00745 free parameters is d for each matrix. This is most commonly used option yielding good 00746 estimation results. */ 00747 COV_MAT_DIAGONAL=1, 00748 /** A symmetric positively defined matrix. The number of free 00749 parameters in each matrix is about \f$d^2/2\f$. It is not recommended to use this option, unless 00750 there is pretty accurate initial estimation of the parameters and/or a huge number of 00751 training samples. */ 00752 COV_MAT_GENERIC=2, 00753 COV_MAT_DEFAULT=COV_MAT_DIAGONAL 00754 }; 00755 00756 //! Default parameters 00757 enum {DEFAULT_NCLUSTERS=5, DEFAULT_MAX_ITERS=100}; 00758 00759 //! The initial step 00760 enum {START_E_STEP=1, START_M_STEP=2, START_AUTO_STEP=0}; 00761 00762 /** The number of mixture components in the Gaussian mixture model. 00763 Default value of the parameter is EM::DEFAULT_NCLUSTERS=5. Some of %EM implementation could 00764 determine the optimal number of mixtures within a specified value range, but that is not the 00765 case in ML yet. */ 00766 /** @see setClustersNumber */ 00767 CV_WRAP virtual int getClustersNumber() const = 0; 00768 /** @copybrief getClustersNumber @see getClustersNumber */ 00769 CV_WRAP virtual void setClustersNumber(int val) = 0; 00770 00771 /** Constraint on covariance matrices which defines type of matrices. 00772 See EM::Types. */ 00773 /** @see setCovarianceMatrixType */ 00774 CV_WRAP virtual int getCovarianceMatrixType() const = 0; 00775 /** @copybrief getCovarianceMatrixType @see getCovarianceMatrixType */ 00776 CV_WRAP virtual void setCovarianceMatrixType(int val) = 0; 00777 00778 /** The termination criteria of the %EM algorithm. 00779 The %EM algorithm can be terminated by the number of iterations termCrit.maxCount (number of 00780 M-steps) or when relative change of likelihood logarithm is less than termCrit.epsilon. Default 00781 maximum number of iterations is EM::DEFAULT_MAX_ITERS=100. */ 00782 /** @see setTermCriteria */ 00783 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 00784 /** @copybrief getTermCriteria @see getTermCriteria */ 00785 CV_WRAP virtual void setTermCriteria(const TermCriteria &val) = 0; 00786 00787 /** @brief Returns weights of the mixtures 00788 00789 Returns vector with the number of elements equal to the number of mixtures. 00790 */ 00791 CV_WRAP virtual Mat getWeights() const = 0; 00792 /** @brief Returns the cluster centers (means of the Gaussian mixture) 00793 00794 Returns matrix with the number of rows equal to the number of mixtures and number of columns 00795 equal to the space dimensionality. 00796 */ 00797 CV_WRAP virtual Mat getMeans() const = 0; 00798 /** @brief Returns covariation matrices 00799 00800 Returns vector of covariation matrices. Number of matrices is the number of gaussian mixtures, 00801 each matrix is a square floating-point matrix NxN, where N is the space dimensionality. 00802 */ 00803 CV_WRAP virtual void getCovs(CV_OUT std::vector<Mat>& covs) const = 0; 00804 00805 /** @brief Returns a likelihood logarithm value and an index of the most probable mixture component 00806 for the given sample. 00807 00808 @param sample A sample for classification. It should be a one-channel matrix of 00809 \f$1 \times dims\f$ or \f$dims \times 1\f$ size. 00810 @param probs Optional output matrix that contains posterior probabilities of each component 00811 given the sample. It has \f$1 \times nclusters\f$ size and CV_64FC1 type. 00812 00813 The method returns a two-element double vector. Zero element is a likelihood logarithm value for 00814 the sample. First element is an index of the most probable mixture component for the given 00815 sample. 00816 */ 00817 CV_WRAP virtual Vec2d predict2(InputArray sample, OutputArray probs) const = 0; 00818 00819 /** @brief Estimate the Gaussian mixture parameters from a samples set. 00820 00821 This variation starts with Expectation step. Initial values of the model parameters will be 00822 estimated by the k-means algorithm. 00823 00824 Unlike many of the ML models, %EM is an unsupervised learning algorithm and it does not take 00825 responses (class labels or function values) as input. Instead, it computes the *Maximum 00826 Likelihood Estimate* of the Gaussian mixture parameters from an input sample set, stores all the 00827 parameters inside the structure: \f$p_{i,k}\f$ in probs, \f$a_k\f$ in means , \f$S_k\f$ in 00828 covs[k], \f$\pi_k\f$ in weights , and optionally computes the output "class label" for each 00829 sample: \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most 00830 probable mixture component for each sample). 00831 00832 The trained model can be used further for prediction, just like any other classifier. The 00833 trained model is similar to the NormalBayesClassifier. 00834 00835 @param samples Samples from which the Gaussian mixture model will be estimated. It should be a 00836 one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type 00837 it will be converted to the inner matrix of such type for the further computing. 00838 @param logLikelihoods The optional output matrix that contains a likelihood logarithm value for 00839 each sample. It has \f$nsamples \times 1\f$ size and CV_64FC1 type. 00840 @param labels The optional output "class label" for each sample: 00841 \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most probable 00842 mixture component for each sample). It has \f$nsamples \times 1\f$ size and CV_32SC1 type. 00843 @param probs The optional output matrix that contains posterior probabilities of each Gaussian 00844 mixture component given the each sample. It has \f$nsamples \times nclusters\f$ size and 00845 CV_64FC1 type. 00846 */ 00847 CV_WRAP virtual bool trainEM(InputArray samples, 00848 OutputArray logLikelihoods=noArray(), 00849 OutputArray labels=noArray(), 00850 OutputArray probs=noArray()) = 0; 00851 00852 /** @brief Estimate the Gaussian mixture parameters from a samples set. 00853 00854 This variation starts with Expectation step. You need to provide initial means \f$a_k\f$ of 00855 mixture components. Optionally you can pass initial weights \f$\pi_k\f$ and covariance matrices 00856 \f$S_k\f$ of mixture components. 00857 00858 @param samples Samples from which the Gaussian mixture model will be estimated. It should be a 00859 one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type 00860 it will be converted to the inner matrix of such type for the further computing. 00861 @param means0 Initial means \f$a_k\f$ of mixture components. It is a one-channel matrix of 00862 \f$nclusters \times dims\f$ size. If the matrix does not have CV_64F type it will be 00863 converted to the inner matrix of such type for the further computing. 00864 @param covs0 The vector of initial covariance matrices \f$S_k\f$ of mixture components. Each of 00865 covariance matrices is a one-channel matrix of \f$dims \times dims\f$ size. If the matrices 00866 do not have CV_64F type they will be converted to the inner matrices of such type for the 00867 further computing. 00868 @param weights0 Initial weights \f$\pi_k\f$ of mixture components. It should be a one-channel 00869 floating-point matrix with \f$1 \times nclusters\f$ or \f$nclusters \times 1\f$ size. 00870 @param logLikelihoods The optional output matrix that contains a likelihood logarithm value for 00871 each sample. It has \f$nsamples \times 1\f$ size and CV_64FC1 type. 00872 @param labels The optional output "class label" for each sample: 00873 \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most probable 00874 mixture component for each sample). It has \f$nsamples \times 1\f$ size and CV_32SC1 type. 00875 @param probs The optional output matrix that contains posterior probabilities of each Gaussian 00876 mixture component given the each sample. It has \f$nsamples \times nclusters\f$ size and 00877 CV_64FC1 type. 00878 */ 00879 CV_WRAP virtual bool trainE(InputArray samples, InputArray means0, 00880 InputArray covs0=noArray(), 00881 InputArray weights0=noArray(), 00882 OutputArray logLikelihoods=noArray(), 00883 OutputArray labels=noArray(), 00884 OutputArray probs=noArray()) = 0; 00885 00886 /** @brief Estimate the Gaussian mixture parameters from a samples set. 00887 00888 This variation starts with Maximization step. You need to provide initial probabilities 00889 \f$p_{i,k}\f$ to use this option. 00890 00891 @param samples Samples from which the Gaussian mixture model will be estimated. It should be a 00892 one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type 00893 it will be converted to the inner matrix of such type for the further computing. 00894 @param probs0 00895 @param logLikelihoods The optional output matrix that contains a likelihood logarithm value for 00896 each sample. It has \f$nsamples \times 1\f$ size and CV_64FC1 type. 00897 @param labels The optional output "class label" for each sample: 00898 \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most probable 00899 mixture component for each sample). It has \f$nsamples \times 1\f$ size and CV_32SC1 type. 00900 @param probs The optional output matrix that contains posterior probabilities of each Gaussian 00901 mixture component given the each sample. It has \f$nsamples \times nclusters\f$ size and 00902 CV_64FC1 type. 00903 */ 00904 CV_WRAP virtual bool trainM(InputArray samples, InputArray probs0, 00905 OutputArray logLikelihoods=noArray(), 00906 OutputArray labels=noArray(), 00907 OutputArray probs=noArray()) = 0; 00908 00909 /** Creates empty %EM model. 00910 The model should be trained then using StatModel::train(traindata, flags) method. Alternatively, you 00911 can use one of the EM::train\* methods or load it from file using Algorithm::load<EM>(filename). 00912 */ 00913 CV_WRAP static Ptr<EM> create(); 00914 }; 00915 00916 /****************************************************************************************\ 00917 * Decision Tree * 00918 \****************************************************************************************/ 00919 00920 /** @brief The class represents a single decision tree or a collection of decision trees. 00921 00922 The current public interface of the class allows user to train only a single decision tree, however 00923 the class is capable of storing multiple decision trees and using them for prediction (by summing 00924 responses or using a voting schemes), and the derived from DTrees classes (such as RTrees and Boost) 00925 use this capability to implement decision tree ensembles. 00926 00927 @sa @ref ml_intro_trees 00928 */ 00929 class CV_EXPORTS_W DTrees : public StatModel 00930 { 00931 public: 00932 /** Predict options */ 00933 enum Flags { PREDICT_AUTO=0, PREDICT_SUM=(1<<8), PREDICT_MAX_VOTE=(2<<8), PREDICT_MASK=(3<<8) }; 00934 00935 /** Cluster possible values of a categorical variable into K<=maxCategories clusters to 00936 find a suboptimal split. 00937 If a discrete variable, on which the training procedure tries to make a split, takes more than 00938 maxCategories values, the precise best subset estimation may take a very long time because the 00939 algorithm is exponential. Instead, many decision trees engines (including our implementation) 00940 try to find sub-optimal split in this case by clustering all the samples into maxCategories 00941 clusters that is some categories are merged together. The clustering is applied only in n > 00942 2-class classification problems for categorical variables with N > max_categories possible 00943 values. In case of regression and 2-class classification the optimal split can be found 00944 efficiently without employing clustering, thus the parameter is not used in these cases. 00945 Default value is 10.*/ 00946 /** @see setMaxCategories */ 00947 CV_WRAP virtual int getMaxCategories() const = 0; 00948 /** @copybrief getMaxCategories @see getMaxCategories */ 00949 CV_WRAP virtual void setMaxCategories(int val) = 0; 00950 00951 /** The maximum possible depth of the tree. 00952 That is the training algorithms attempts to split a node while its depth is less than maxDepth. 00953 The root node has zero depth. The actual depth may be smaller if the other termination criteria 00954 are met (see the outline of the training procedure @ref ml_intro_trees "here"), and/or if the 00955 tree is pruned. Default value is INT_MAX.*/ 00956 /** @see setMaxDepth */ 00957 CV_WRAP virtual int getMaxDepth() const = 0; 00958 /** @copybrief getMaxDepth @see getMaxDepth */ 00959 CV_WRAP virtual void setMaxDepth(int val) = 0; 00960 00961 /** If the number of samples in a node is less than this parameter then the node will not be split. 00962 00963 Default value is 10.*/ 00964 /** @see setMinSampleCount */ 00965 CV_WRAP virtual int getMinSampleCount() const = 0; 00966 /** @copybrief getMinSampleCount @see getMinSampleCount */ 00967 CV_WRAP virtual void setMinSampleCount(int val) = 0; 00968 00969 /** If CVFolds > 1 then algorithms prunes the built decision tree using K-fold 00970 cross-validation procedure where K is equal to CVFolds. 00971 Default value is 10.*/ 00972 /** @see setCVFolds */ 00973 CV_WRAP virtual int getCVFolds() const = 0; 00974 /** @copybrief getCVFolds @see getCVFolds */ 00975 CV_WRAP virtual void setCVFolds(int val) = 0; 00976 00977 /** If true then surrogate splits will be built. 00978 These splits allow to work with missing data and compute variable importance correctly. 00979 Default value is false. 00980 @note currently it's not implemented.*/ 00981 /** @see setUseSurrogates */ 00982 CV_WRAP virtual bool getUseSurrogates() const = 0; 00983 /** @copybrief getUseSurrogates @see getUseSurrogates */ 00984 CV_WRAP virtual void setUseSurrogates(bool val) = 0; 00985 00986 /** If true then a pruning will be harsher. 00987 This will make a tree more compact and more resistant to the training data noise but a bit less 00988 accurate. Default value is true.*/ 00989 /** @see setUse1SERule */ 00990 CV_WRAP virtual bool getUse1SERule() const = 0; 00991 /** @copybrief getUse1SERule @see getUse1SERule */ 00992 CV_WRAP virtual void setUse1SERule(bool val) = 0; 00993 00994 /** If true then pruned branches are physically removed from the tree. 00995 Otherwise they are retained and it is possible to get results from the original unpruned (or 00996 pruned less aggressively) tree. Default value is true.*/ 00997 /** @see setTruncatePrunedTree */ 00998 CV_WRAP virtual bool getTruncatePrunedTree() const = 0; 00999 /** @copybrief getTruncatePrunedTree @see getTruncatePrunedTree */ 01000 CV_WRAP virtual void setTruncatePrunedTree(bool val) = 0; 01001 01002 /** Termination criteria for regression trees. 01003 If all absolute differences between an estimated value in a node and values of train samples 01004 in this node are less than this parameter then the node will not be split further. Default 01005 value is 0.01f*/ 01006 /** @see setRegressionAccuracy */ 01007 CV_WRAP virtual float getRegressionAccuracy() const = 0; 01008 /** @copybrief getRegressionAccuracy @see getRegressionAccuracy */ 01009 CV_WRAP virtual void setRegressionAccuracy(float val) = 0; 01010 01011 /** @brief The array of a priori class probabilities, sorted by the class label value. 01012 01013 The parameter can be used to tune the decision tree preferences toward a certain class. For 01014 example, if you want to detect some rare anomaly occurrence, the training base will likely 01015 contain much more normal cases than anomalies, so a very good classification performance 01016 will be achieved just by considering every case as normal. To avoid this, the priors can be 01017 specified, where the anomaly probability is artificially increased (up to 0.5 or even 01018 greater), so the weight of the misclassified anomalies becomes much bigger, and the tree is 01019 adjusted properly. 01020 01021 You can also think about this parameter as weights of prediction categories which determine 01022 relative weights that you give to misclassification. That is, if the weight of the first 01023 category is 1 and the weight of the second category is 10, then each mistake in predicting 01024 the second category is equivalent to making 10 mistakes in predicting the first category. 01025 Default value is empty Mat.*/ 01026 /** @see setPriors */ 01027 CV_WRAP virtual cv::Mat getPriors() const = 0; 01028 /** @copybrief getPriors @see getPriors */ 01029 CV_WRAP virtual void setPriors(const cv::Mat &val) = 0; 01030 01031 /** @brief The class represents a decision tree node. 01032 */ 01033 class CV_EXPORTS Node 01034 { 01035 public: 01036 Node(); 01037 double value; //!< Value at the node: a class label in case of classification or estimated 01038 //!< function value in case of regression. 01039 int classIdx; //!< Class index normalized to 0..class_count-1 range and assigned to the 01040 //!< node. It is used internally in classification trees and tree ensembles. 01041 int parent; //!< Index of the parent node 01042 int left; //!< Index of the left child node 01043 int right; //!< Index of right child node 01044 int defaultDir; //!< Default direction where to go (-1: left or +1: right). It helps in the 01045 //!< case of missing values. 01046 int split; //!< Index of the first split 01047 }; 01048 01049 /** @brief The class represents split in a decision tree. 01050 */ 01051 class CV_EXPORTS Split 01052 { 01053 public: 01054 Split(); 01055 int varIdx; //!< Index of variable on which the split is created. 01056 bool inversed; //!< If true, then the inverse split rule is used (i.e. left and right 01057 //!< branches are exchanged in the rule expressions below). 01058 float quality; //!< The split quality, a positive number. It is used to choose the best split. 01059 int next; //!< Index of the next split in the list of splits for the node 01060 float c; /**< The threshold value in case of split on an ordered variable. 01061 The rule is: 01062 @code{.none} 01063 if var_value < c 01064 then next_node <- left 01065 else next_node <- right 01066 @endcode */ 01067 int subsetOfs; /**< Offset of the bitset used by the split on a categorical variable. 01068 The rule is: 01069 @code{.none} 01070 if bitset[var_value] == 1 01071 then next_node <- left 01072 else next_node <- right 01073 @endcode */ 01074 }; 01075 01076 /** @brief Returns indices of root nodes 01077 */ 01078 virtual const std::vector<int>& getRoots() const = 0; 01079 /** @brief Returns all the nodes 01080 01081 all the node indices are indices in the returned vector 01082 */ 01083 virtual const std::vector<Node>& getNodes() const = 0; 01084 /** @brief Returns all the splits 01085 01086 all the split indices are indices in the returned vector 01087 */ 01088 virtual const std::vector<Split>& getSplits() const = 0; 01089 /** @brief Returns all the bitsets for categorical splits 01090 01091 Split::subsetOfs is an offset in the returned vector 01092 */ 01093 virtual const std::vector<int>& getSubsets() const = 0; 01094 01095 /** @brief Creates the empty model 01096 01097 The static method creates empty decision tree with the specified parameters. It should be then 01098 trained using train method (see StatModel::train). Alternatively, you can load the model from 01099 file using Algorithm::load<DTrees>(filename). 01100 */ 01101 CV_WRAP static Ptr<DTrees> create(); 01102 }; 01103 01104 /****************************************************************************************\ 01105 * Random Trees Classifier * 01106 \****************************************************************************************/ 01107 01108 /** @brief The class implements the random forest predictor. 01109 01110 @sa @ref ml_intro_rtrees 01111 */ 01112 class CV_EXPORTS_W RTrees : public DTrees 01113 { 01114 public: 01115 01116 /** If true then variable importance will be calculated and then it can be retrieved by RTrees::getVarImportance. 01117 Default value is false.*/ 01118 /** @see setCalculateVarImportance */ 01119 CV_WRAP virtual bool getCalculateVarImportance() const = 0; 01120 /** @copybrief getCalculateVarImportance @see getCalculateVarImportance */ 01121 CV_WRAP virtual void setCalculateVarImportance(bool val) = 0; 01122 01123 /** The size of the randomly selected subset of features at each tree node and that are used 01124 to find the best split(s). 01125 If you set it to 0 then the size will be set to the square root of the total number of 01126 features. Default value is 0.*/ 01127 /** @see setActiveVarCount */ 01128 CV_WRAP virtual int getActiveVarCount() const = 0; 01129 /** @copybrief getActiveVarCount @see getActiveVarCount */ 01130 CV_WRAP virtual void setActiveVarCount(int val) = 0; 01131 01132 /** The termination criteria that specifies when the training algorithm stops. 01133 Either when the specified number of trees is trained and added to the ensemble or when 01134 sufficient accuracy (measured as OOB error) is achieved. Typically the more trees you have the 01135 better the accuracy. However, the improvement in accuracy generally diminishes and asymptotes 01136 pass a certain number of trees. Also to keep in mind, the number of tree increases the 01137 prediction time linearly. Default value is TermCriteria(TermCriteria::MAX_ITERS + 01138 TermCriteria::EPS, 50, 0.1)*/ 01139 /** @see setTermCriteria */ 01140 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 01141 /** @copybrief getTermCriteria @see getTermCriteria */ 01142 CV_WRAP virtual void setTermCriteria(const TermCriteria &val) = 0; 01143 01144 /** Returns the variable importance array. 01145 The method returns the variable importance vector, computed at the training stage when 01146 CalculateVarImportance is set to true. If this flag was set to false, the empty matrix is 01147 returned. 01148 */ 01149 CV_WRAP virtual Mat getVarImportance() const = 0; 01150 01151 /** Creates the empty model. 01152 Use StatModel::train to train the model, StatModel::train to create and train the model, 01153 Algorithm::load to load the pre-trained model. 01154 */ 01155 CV_WRAP static Ptr<RTrees> create(); 01156 }; 01157 01158 /****************************************************************************************\ 01159 * Boosted tree classifier * 01160 \****************************************************************************************/ 01161 01162 /** @brief Boosted tree classifier derived from DTrees 01163 01164 @sa @ref ml_intro_boost 01165 */ 01166 class CV_EXPORTS_W Boost : public DTrees 01167 { 01168 public: 01169 /** Type of the boosting algorithm. 01170 See Boost::Types. Default value is Boost::REAL. */ 01171 /** @see setBoostType */ 01172 CV_WRAP virtual int getBoostType() const = 0; 01173 /** @copybrief getBoostType @see getBoostType */ 01174 CV_WRAP virtual void setBoostType(int val) = 0; 01175 01176 /** The number of weak classifiers. 01177 Default value is 100. */ 01178 /** @see setWeakCount */ 01179 CV_WRAP virtual int getWeakCount() const = 0; 01180 /** @copybrief getWeakCount @see getWeakCount */ 01181 CV_WRAP virtual void setWeakCount(int val) = 0; 01182 01183 /** A threshold between 0 and 1 used to save computational time. 01184 Samples with summary weight \f$\leq 1 - weight_trim_rate\f$ do not participate in the *next* 01185 iteration of training. Set this parameter to 0 to turn off this functionality. Default value is 0.95.*/ 01186 /** @see setWeightTrimRate */ 01187 CV_WRAP virtual double getWeightTrimRate() const = 0; 01188 /** @copybrief getWeightTrimRate @see getWeightTrimRate */ 01189 CV_WRAP virtual void setWeightTrimRate(double val) = 0; 01190 01191 /** Boosting type. 01192 Gentle AdaBoost and Real AdaBoost are often the preferable choices. */ 01193 enum Types { 01194 DISCRETE=0, //!< Discrete AdaBoost. 01195 REAL=1, //!< Real AdaBoost. It is a technique that utilizes confidence-rated predictions 01196 //!< and works well with categorical data. 01197 LOGIT=2, //!< LogitBoost. It can produce good regression fits. 01198 GENTLE=3 //!< Gentle AdaBoost. It puts less weight on outlier data points and for that 01199 //!<reason is often good with regression data. 01200 }; 01201 01202 /** Creates the empty model. 01203 Use StatModel::train to train the model, Algorithm::load<Boost>(filename) to load the pre-trained model. */ 01204 CV_WRAP static Ptr<Boost> create(); 01205 }; 01206 01207 /****************************************************************************************\ 01208 * Gradient Boosted Trees * 01209 \****************************************************************************************/ 01210 01211 /*class CV_EXPORTS_W GBTrees : public DTrees 01212 { 01213 public: 01214 struct CV_EXPORTS_W_MAP Params : public DTrees::Params 01215 { 01216 CV_PROP_RW int weakCount; 01217 CV_PROP_RW int lossFunctionType; 01218 CV_PROP_RW float subsamplePortion; 01219 CV_PROP_RW float shrinkage; 01220 01221 Params(); 01222 Params( int lossFunctionType, int weakCount, float shrinkage, 01223 float subsamplePortion, int maxDepth, bool useSurrogates ); 01224 }; 01225 01226 enum {SQUARED_LOSS=0, ABSOLUTE_LOSS, HUBER_LOSS=3, DEVIANCE_LOSS}; 01227 01228 virtual void setK(int k) = 0; 01229 01230 virtual float predictSerial( InputArray samples, 01231 OutputArray weakResponses, int flags) const = 0; 01232 01233 static Ptr<GBTrees> create(const Params& p); 01234 };*/ 01235 01236 /****************************************************************************************\ 01237 * Artificial Neural Networks (ANN) * 01238 \****************************************************************************************/ 01239 01240 /////////////////////////////////// Multi-Layer Perceptrons ////////////////////////////// 01241 01242 /** @brief Artificial Neural Networks - Multi-Layer Perceptrons. 01243 01244 Unlike many other models in ML that are constructed and trained at once, in the MLP model these 01245 steps are separated. First, a network with the specified topology is created using the non-default 01246 constructor or the method ANN_MLP::create. All the weights are set to zeros. Then, the network is 01247 trained using a set of input and output vectors. The training procedure can be repeated more than 01248 once, that is, the weights can be adjusted based on the new training data. 01249 01250 Additional flags for StatModel::train are available: ANN_MLP::TrainFlags. 01251 01252 @sa @ref ml_intro_ann 01253 */ 01254 class CV_EXPORTS_W ANN_MLP : public StatModel 01255 { 01256 public: 01257 /** Available training methods */ 01258 enum TrainingMethods { 01259 BACKPROP=0, //!< The back-propagation algorithm. 01260 RPROP=1 //!< The RPROP algorithm. See @cite RPROP93 for details. 01261 }; 01262 01263 /** Sets training method and common parameters. 01264 @param method Default value is ANN_MLP::RPROP. See ANN_MLP::TrainingMethods. 01265 @param param1 passed to setRpropDW0 for ANN_MLP::RPROP and to setBackpropWeightScale for ANN_MLP::BACKPROP 01266 @param param2 passed to setRpropDWMin for ANN_MLP::RPROP and to setBackpropMomentumScale for ANN_MLP::BACKPROP. 01267 */ 01268 CV_WRAP virtual void setTrainMethod(int method, double param1 = 0, double param2 = 0) = 0; 01269 01270 /** Returns current training method */ 01271 CV_WRAP virtual int getTrainMethod() const = 0; 01272 01273 /** Initialize the activation function for each neuron. 01274 Currently the default and the only fully supported activation function is ANN_MLP::SIGMOID_SYM. 01275 @param type The type of activation function. See ANN_MLP::ActivationFunctions. 01276 @param param1 The first parameter of the activation function, \f$\alpha\f$. Default value is 0. 01277 @param param2 The second parameter of the activation function, \f$\beta\f$. Default value is 0. 01278 */ 01279 CV_WRAP virtual void setActivationFunction(int type, double param1 = 0, double param2 = 0) = 0; 01280 01281 /** Integer vector specifying the number of neurons in each layer including the input and output layers. 01282 The very first element specifies the number of elements in the input layer. 01283 The last element - number of elements in the output layer. Default value is empty Mat. 01284 @sa getLayerSizes */ 01285 CV_WRAP virtual void setLayerSizes(InputArray _layer_sizes) = 0; 01286 01287 /** Integer vector specifying the number of neurons in each layer including the input and output layers. 01288 The very first element specifies the number of elements in the input layer. 01289 The last element - number of elements in the output layer. 01290 @sa setLayerSizes */ 01291 CV_WRAP virtual cv::Mat getLayerSizes() const = 0; 01292 01293 /** Termination criteria of the training algorithm. 01294 You can specify the maximum number of iterations (maxCount) and/or how much the error could 01295 change between the iterations to make the algorithm continue (epsilon). Default value is 01296 TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 1000, 0.01).*/ 01297 /** @see setTermCriteria */ 01298 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 01299 /** @copybrief getTermCriteria @see getTermCriteria */ 01300 CV_WRAP virtual void setTermCriteria(TermCriteria val) = 0; 01301 01302 /** BPROP: Strength of the weight gradient term. 01303 The recommended value is about 0.1. Default value is 0.1.*/ 01304 /** @see setBackpropWeightScale */ 01305 CV_WRAP virtual double getBackpropWeightScale() const = 0; 01306 /** @copybrief getBackpropWeightScale @see getBackpropWeightScale */ 01307 CV_WRAP virtual void setBackpropWeightScale(double val) = 0; 01308 01309 /** BPROP: Strength of the momentum term (the difference between weights on the 2 previous iterations). 01310 This parameter provides some inertia to smooth the random fluctuations of the weights. It can 01311 vary from 0 (the feature is disabled) to 1 and beyond. The value 0.1 or so is good enough. 01312 Default value is 0.1.*/ 01313 /** @see setBackpropMomentumScale */ 01314 CV_WRAP virtual double getBackpropMomentumScale() const = 0; 01315 /** @copybrief getBackpropMomentumScale @see getBackpropMomentumScale */ 01316 CV_WRAP virtual void setBackpropMomentumScale(double val) = 0; 01317 01318 /** RPROP: Initial value \f$\Delta_0\f$ of update-values \f$\Delta_{ij}\f$. 01319 Default value is 0.1.*/ 01320 /** @see setRpropDW0 */ 01321 CV_WRAP virtual double getRpropDW0() const = 0; 01322 /** @copybrief getRpropDW0 @see getRpropDW0 */ 01323 CV_WRAP virtual void setRpropDW0(double val) = 0; 01324 01325 /** RPROP: Increase factor \f$\eta^+\f$. 01326 It must be >1. Default value is 1.2.*/ 01327 /** @see setRpropDWPlus */ 01328 CV_WRAP virtual double getRpropDWPlus() const = 0; 01329 /** @copybrief getRpropDWPlus @see getRpropDWPlus */ 01330 CV_WRAP virtual void setRpropDWPlus(double val) = 0; 01331 01332 /** RPROP: Decrease factor \f$\eta^-\f$. 01333 It must be <1. Default value is 0.5.*/ 01334 /** @see setRpropDWMinus */ 01335 CV_WRAP virtual double getRpropDWMinus() const = 0; 01336 /** @copybrief getRpropDWMinus @see getRpropDWMinus */ 01337 CV_WRAP virtual void setRpropDWMinus(double val) = 0; 01338 01339 /** RPROP: Update-values lower limit \f$\Delta_{min}\f$. 01340 It must be positive. Default value is FLT_EPSILON.*/ 01341 /** @see setRpropDWMin */ 01342 CV_WRAP virtual double getRpropDWMin() const = 0; 01343 /** @copybrief getRpropDWMin @see getRpropDWMin */ 01344 CV_WRAP virtual void setRpropDWMin(double val) = 0; 01345 01346 /** RPROP: Update-values upper limit \f$\Delta_{max}\f$. 01347 It must be >1. Default value is 50.*/ 01348 /** @see setRpropDWMax */ 01349 CV_WRAP virtual double getRpropDWMax() const = 0; 01350 /** @copybrief getRpropDWMax @see getRpropDWMax */ 01351 CV_WRAP virtual void setRpropDWMax(double val) = 0; 01352 01353 /** possible activation functions */ 01354 enum ActivationFunctions { 01355 /** Identity function: \f$f(x)=x\f$ */ 01356 IDENTITY = 0, 01357 /** Symmetrical sigmoid: \f$f(x)=\beta*(1-e^{-\alpha x})/(1+e^{-\alpha x}\f$ 01358 @note 01359 If you are using the default sigmoid activation function with the default parameter values 01360 fparam1=0 and fparam2=0 then the function used is y = 1.7159\*tanh(2/3 \* x), so the output 01361 will range from [-1.7159, 1.7159], instead of [0,1].*/ 01362 SIGMOID_SYM = 1, 01363 /** Gaussian function: \f$f(x)=\beta e^{-\alpha x*x}\f$ */ 01364 GAUSSIAN = 2 01365 }; 01366 01367 /** Train options */ 01368 enum TrainFlags { 01369 /** Update the network weights, rather than compute them from scratch. In the latter case 01370 the weights are initialized using the Nguyen-Widrow algorithm. */ 01371 UPDATE_WEIGHTS = 1, 01372 /** Do not normalize the input vectors. If this flag is not set, the training algorithm 01373 normalizes each input feature independently, shifting its mean value to 0 and making the 01374 standard deviation equal to 1. If the network is assumed to be updated frequently, the new 01375 training data could be much different from original one. In this case, you should take care 01376 of proper normalization. */ 01377 NO_INPUT_SCALE = 2, 01378 /** Do not normalize the output vectors. If the flag is not set, the training algorithm 01379 normalizes each output feature independently, by transforming it to the certain range 01380 depending on the used activation function. */ 01381 NO_OUTPUT_SCALE = 4 01382 }; 01383 01384 CV_WRAP virtual Mat getWeights(int layerIdx) const = 0; 01385 01386 /** @brief Creates empty model 01387 01388 Use StatModel::train to train the model, Algorithm::load<ANN_MLP>(filename) to load the pre-trained model. 01389 Note that the train method has optional flags: ANN_MLP::TrainFlags. 01390 */ 01391 CV_WRAP static Ptr<ANN_MLP> create(); 01392 }; 01393 01394 /****************************************************************************************\ 01395 * Logistic Regression * 01396 \****************************************************************************************/ 01397 01398 /** @brief Implements Logistic Regression classifier. 01399 01400 @sa @ref ml_intro_lr 01401 */ 01402 class CV_EXPORTS_W LogisticRegression : public StatModel 01403 { 01404 public: 01405 01406 /** Learning rate. */ 01407 /** @see setLearningRate */ 01408 CV_WRAP virtual double getLearningRate() const = 0; 01409 /** @copybrief getLearningRate @see getLearningRate */ 01410 CV_WRAP virtual void setLearningRate(double val) = 0; 01411 01412 /** Number of iterations. */ 01413 /** @see setIterations */ 01414 CV_WRAP virtual int getIterations() const = 0; 01415 /** @copybrief getIterations @see getIterations */ 01416 CV_WRAP virtual void setIterations(int val) = 0; 01417 01418 /** Kind of regularization to be applied. See LogisticRegression::RegKinds. */ 01419 /** @see setRegularization */ 01420 CV_WRAP virtual int getRegularization() const = 0; 01421 /** @copybrief getRegularization @see getRegularization */ 01422 CV_WRAP virtual void setRegularization(int val) = 0; 01423 01424 /** Kind of training method used. See LogisticRegression::Methods. */ 01425 /** @see setTrainMethod */ 01426 CV_WRAP virtual int getTrainMethod() const = 0; 01427 /** @copybrief getTrainMethod @see getTrainMethod */ 01428 CV_WRAP virtual void setTrainMethod(int val) = 0; 01429 01430 /** Specifies the number of training samples taken in each step of Mini-Batch Gradient 01431 Descent. Will only be used if using LogisticRegression::MINI_BATCH training algorithm. It 01432 has to take values less than the total number of training samples. */ 01433 /** @see setMiniBatchSize */ 01434 CV_WRAP virtual int getMiniBatchSize() const = 0; 01435 /** @copybrief getMiniBatchSize @see getMiniBatchSize */ 01436 CV_WRAP virtual void setMiniBatchSize(int val) = 0; 01437 01438 /** Termination criteria of the algorithm. */ 01439 /** @see setTermCriteria */ 01440 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 01441 /** @copybrief getTermCriteria @see getTermCriteria */ 01442 CV_WRAP virtual void setTermCriteria(TermCriteria val) = 0; 01443 01444 //! Regularization kinds 01445 enum RegKinds { 01446 REG_DISABLE = -1, //!< Regularization disabled 01447 REG_L1 = 0, //!< %L1 norm 01448 REG_L2 = 1 //!< %L2 norm 01449 }; 01450 01451 //! Training methods 01452 enum Methods { 01453 BATCH = 0, 01454 MINI_BATCH = 1 //!< Set MiniBatchSize to a positive integer when using this method. 01455 }; 01456 01457 /** @brief Predicts responses for input samples and returns a float type. 01458 01459 @param samples The input data for the prediction algorithm. Matrix [m x n], where each row 01460 contains variables (features) of one object being classified. Should have data type CV_32F. 01461 @param results Predicted labels as a column matrix of type CV_32S. 01462 @param flags Not used. 01463 */ 01464 CV_WRAP virtual float predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const = 0; 01465 01466 /** @brief This function returns the trained paramters arranged across rows. 01467 01468 For a two class classifcation problem, it returns a row matrix. It returns learnt paramters of 01469 the Logistic Regression as a matrix of type CV_32F. 01470 */ 01471 CV_WRAP virtual Mat get_learnt_thetas() const = 0; 01472 01473 /** @brief Creates empty model. 01474 01475 Creates Logistic Regression model with parameters given. 01476 */ 01477 CV_WRAP static Ptr<LogisticRegression> create(); 01478 }; 01479 01480 /****************************************************************************************\ 01481 * Auxilary functions declarations * 01482 \****************************************************************************************/ 01483 01484 /** @brief Generates _sample_ from multivariate normal distribution 01485 01486 @param mean an average row vector 01487 @param cov symmetric covariation matrix 01488 @param nsamples returned samples count 01489 @param samples returned samples array 01490 */ 01491 CV_EXPORTS void randMVNormal( InputArray mean, InputArray cov, int nsamples, OutputArray samples); 01492 01493 /** @brief Creates test set */ 01494 CV_EXPORTS void createConcentricSpheresTestSet( int nsamples, int nfeatures, int nclasses, 01495 OutputArray samples, OutputArray responses); 01496 01497 //! @} ml 01498 01499 } 01500 } 01501 01502 #endif // __cplusplus 01503 #endif // __OPENCV_ML_HPP__ 01504 01505 /* End of file. */ 01506
Generated on Tue Jul 12 2022 16:42:39 by
1.7.2