Renesas
/
opencv-lib
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: RZ_A2M_Mbed_samples
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 Mat getVarSymbolFlags() const; 00194 CV_WRAP virtual int getResponseType() const = 0; 00195 CV_WRAP virtual Mat getTrainSampleIdx() const = 0; 00196 CV_WRAP virtual Mat getTestSampleIdx() const = 0; 00197 CV_WRAP virtual void getValues(int vi, InputArray sidx, float* values) const = 0; 00198 virtual void getNormCatValues(int vi, InputArray sidx, int* values) const = 0; 00199 CV_WRAP virtual Mat getDefaultSubstValues() const = 0; 00200 00201 CV_WRAP virtual int getCatCount(int vi) const = 0; 00202 00203 /** @brief Returns the vector of class labels 00204 00205 The function returns vector of unique labels occurred in the responses. 00206 */ 00207 CV_WRAP virtual Mat getClassLabels() const = 0; 00208 00209 CV_WRAP virtual Mat getCatOfs() const = 0; 00210 CV_WRAP virtual Mat getCatMap() const = 0; 00211 00212 /** @brief Splits the training data into the training and test parts 00213 @sa TrainData::setTrainTestSplitRatio 00214 */ 00215 CV_WRAP virtual void setTrainTestSplit(int count, bool shuffle=true) = 0; 00216 00217 /** @brief Splits the training data into the training and test parts 00218 00219 The function selects a subset of specified relative size and then returns it as the training 00220 set. If the function is not called, all the data is used for training. Please, note that for 00221 each of TrainData::getTrain\* there is corresponding TrainData::getTest\*, so that the test 00222 subset can be retrieved and processed as well. 00223 @sa TrainData::setTrainTestSplit 00224 */ 00225 CV_WRAP virtual void setTrainTestSplitRatio(double ratio, bool shuffle=true) = 0; 00226 CV_WRAP virtual void shuffleTrainTest() = 0; 00227 00228 /** @brief Returns matrix of test samples */ 00229 CV_WRAP Mat getTestSamples() const; 00230 00231 /** @brief Returns vector of symbolic names captured in loadFromCSV() */ 00232 CV_WRAP void getNames(std::vector<String>& names) const; 00233 00234 CV_WRAP static Mat getSubVector(const Mat& vec, const Mat& idx); 00235 00236 /** @brief Reads the dataset from a .csv file and returns the ready-to-use training data. 00237 00238 @param filename The input file name 00239 @param headerLineCount The number of lines in the beginning to skip; besides the header, the 00240 function also skips empty lines and lines staring with `#` 00241 @param responseStartIdx Index of the first output variable. If -1, the function considers the 00242 last variable as the response 00243 @param responseEndIdx Index of the last output variable + 1. If -1, then there is single 00244 response variable at responseStartIdx. 00245 @param varTypeSpec The optional text string that specifies the variables' types. It has the 00246 format `ord[n1-n2,n3,n4-n5,...]cat[n6,n7-n8,...]`. That is, variables from `n1 to n2` 00247 (inclusive range), `n3`, `n4 to n5` ... are considered ordered and `n6`, `n7 to n8` ... are 00248 considered as categorical. The range `[n1..n2] + [n3] + [n4..n5] + ... + [n6] + [n7..n8]` 00249 should cover all the variables. If varTypeSpec is not specified, then algorithm uses the 00250 following rules: 00251 - all input variables are considered ordered by default. If some column contains has non- 00252 numerical values, e.g. 'apple', 'pear', 'apple', 'apple', 'mango', the corresponding 00253 variable is considered categorical. 00254 - if there are several output variables, they are all considered as ordered. Error is 00255 reported when non-numerical values are used. 00256 - if there is a single output variable, then if its values are non-numerical or are all 00257 integers, then it's considered categorical. Otherwise, it's considered ordered. 00258 @param delimiter The character used to separate values in each line. 00259 @param missch The character used to specify missing measurements. It should not be a digit. 00260 Although it's a non-numerical value, it surely does not affect the decision of whether the 00261 variable ordered or categorical. 00262 @note If the dataset only contains input variables and no responses, use responseStartIdx = -2 00263 and responseEndIdx = 0. The output variables vector will just contain zeros. 00264 */ 00265 static Ptr<TrainData> loadFromCSV(const String& filename, 00266 int headerLineCount, 00267 int responseStartIdx=-1, 00268 int responseEndIdx=-1, 00269 const String& varTypeSpec=String(), 00270 char delimiter=',', 00271 char missch='?'); 00272 00273 /** @brief Creates training data from in-memory arrays. 00274 00275 @param samples matrix of samples. It should have CV_32F type. 00276 @param layout see ml::SampleTypes. 00277 @param responses matrix of responses. If the responses are scalar, they should be stored as a 00278 single row or as a single column. The matrix should have type CV_32F or CV_32S (in the 00279 former case the responses are considered as ordered by default; in the latter case - as 00280 categorical) 00281 @param varIdx vector specifying which variables to use for training. It can be an integer vector 00282 (CV_32S) containing 0-based variable indices or byte vector (CV_8U) containing a mask of 00283 active variables. 00284 @param sampleIdx vector specifying which samples to use for training. It can be an integer 00285 vector (CV_32S) containing 0-based sample indices or byte vector (CV_8U) containing a mask 00286 of training samples. 00287 @param sampleWeights optional vector with weights for each sample. It should have CV_32F type. 00288 @param varType optional vector of type CV_8U and size `<number_of_variables_in_samples> + 00289 <number_of_variables_in_responses>`, containing types of each input and output variable. See 00290 ml::VariableTypes. 00291 */ 00292 CV_WRAP static Ptr<TrainData> create(InputArray samples, int layout, InputArray responses, 00293 InputArray varIdx=noArray(), InputArray sampleIdx=noArray(), 00294 InputArray sampleWeights=noArray(), InputArray varType=noArray()); 00295 }; 00296 00297 /** @brief Base class for statistical models in OpenCV ML. 00298 */ 00299 class CV_EXPORTS_W StatModel : public Algorithm 00300 { 00301 public: 00302 /** Predict options */ 00303 enum Flags { 00304 UPDATE_MODEL = 1, 00305 RAW_OUTPUT=1, //!< makes the method return the raw results (the sum), not the class label 00306 COMPRESSED_INPUT=2, 00307 PREPROCESSED_INPUT=4 00308 }; 00309 00310 /** @brief Returns the number of variables in training samples */ 00311 CV_WRAP virtual int getVarCount() const = 0; 00312 00313 CV_WRAP virtual bool empty() const; 00314 00315 /** @brief Returns true if the model is trained */ 00316 CV_WRAP virtual bool isTrained() const = 0; 00317 /** @brief Returns true if the model is classifier */ 00318 CV_WRAP virtual bool isClassifier() const = 0; 00319 00320 /** @brief Trains the statistical model 00321 00322 @param trainData training data that can be loaded from file using TrainData::loadFromCSV or 00323 created with TrainData::create. 00324 @param flags optional flags, depending on the model. Some of the models can be updated with the 00325 new training samples, not completely overwritten (such as NormalBayesClassifier or ANN_MLP). 00326 */ 00327 CV_WRAP virtual bool train( const Ptr<TrainData>& trainData, int flags=0 ); 00328 00329 /** @brief Trains the statistical model 00330 00331 @param samples training samples 00332 @param layout See ml::SampleTypes. 00333 @param responses vector of responses associated with the training samples. 00334 */ 00335 CV_WRAP virtual bool train( InputArray samples, int layout, InputArray responses ); 00336 00337 /** @brief Computes error on the training or test dataset 00338 00339 @param data the training data 00340 @param test if true, the error is computed over the test subset of the data, otherwise it's 00341 computed over the training subset of the data. Please note that if you loaded a completely 00342 different dataset to evaluate already trained classifier, you will probably want not to set 00343 the test subset at all with TrainData::setTrainTestSplitRatio and specify test=false, so 00344 that the error is computed for the whole new set. Yes, this sounds a bit confusing. 00345 @param resp the optional output responses. 00346 00347 The method uses StatModel::predict to compute the error. For regression models the error is 00348 computed as RMS, for classifiers - as a percent of missclassified samples (0%-100%). 00349 */ 00350 CV_WRAP virtual float calcError( const Ptr<TrainData>& data, bool test, OutputArray resp ) const; 00351 00352 /** @brief Predicts response(s) for the provided sample(s) 00353 00354 @param samples The input samples, floating-point matrix 00355 @param results The optional output matrix of results. 00356 @param flags The optional flags, model-dependent. See cv::ml::StatModel::Flags. 00357 */ 00358 CV_WRAP virtual float predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const = 0; 00359 00360 /** @brief Create and train model with default parameters 00361 00362 The class must implement static `create()` method with no parameters or with all default parameter values 00363 */ 00364 template<typename _Tp> static Ptr<_Tp> train(const Ptr<TrainData>& data, int flags=0) 00365 { 00366 Ptr<_Tp> model = _Tp::create(); 00367 return !model.empty() && model->train(data, flags) ? model : Ptr<_Tp>(); 00368 } 00369 }; 00370 00371 /****************************************************************************************\ 00372 * Normal Bayes Classifier * 00373 \****************************************************************************************/ 00374 00375 /** @brief Bayes classifier for normally distributed data. 00376 00377 @sa @ref ml_intro_bayes 00378 */ 00379 class CV_EXPORTS_W NormalBayesClassifier : public StatModel 00380 { 00381 public: 00382 /** @brief Predicts the response for sample(s). 00383 00384 The method estimates the most probable classes for input vectors. Input vectors (one or more) 00385 are stored as rows of the matrix inputs. In case of multiple input vectors, there should be one 00386 output vector outputs. The predicted class for a single input vector is returned by the method. 00387 The vector outputProbs contains the output probabilities corresponding to each element of 00388 result. 00389 */ 00390 CV_WRAP virtual float predictProb( InputArray inputs, OutputArray outputs, 00391 OutputArray outputProbs, int flags=0 ) const = 0; 00392 00393 /** Creates empty model 00394 Use StatModel::train to train the model after creation. */ 00395 CV_WRAP static Ptr<NormalBayesClassifier> create(); 00396 }; 00397 00398 /****************************************************************************************\ 00399 * K-Nearest Neighbour Classifier * 00400 \****************************************************************************************/ 00401 00402 /** @brief The class implements K-Nearest Neighbors model 00403 00404 @sa @ref ml_intro_knn 00405 */ 00406 class CV_EXPORTS_W KNearest : public StatModel 00407 { 00408 public: 00409 00410 /** Default number of neighbors to use in predict method. */ 00411 /** @see setDefaultK */ 00412 CV_WRAP virtual int getDefaultK() const = 0; 00413 /** @copybrief getDefaultK @see getDefaultK */ 00414 CV_WRAP virtual void setDefaultK(int val) = 0; 00415 00416 /** Whether classification or regression model should be trained. */ 00417 /** @see setIsClassifier */ 00418 CV_WRAP virtual bool getIsClassifier() const = 0; 00419 /** @copybrief getIsClassifier @see getIsClassifier */ 00420 CV_WRAP virtual void setIsClassifier(bool val) = 0; 00421 00422 /** Parameter for KDTree implementation. */ 00423 /** @see setEmax */ 00424 CV_WRAP virtual int getEmax() const = 0; 00425 /** @copybrief getEmax @see getEmax */ 00426 CV_WRAP virtual void setEmax(int val) = 0; 00427 00428 /** %Algorithm type, one of KNearest::Types. */ 00429 /** @see setAlgorithmType */ 00430 CV_WRAP virtual int getAlgorithmType() const = 0; 00431 /** @copybrief getAlgorithmType @see getAlgorithmType */ 00432 CV_WRAP virtual void setAlgorithmType(int val) = 0; 00433 00434 /** @brief Finds the neighbors and predicts responses for input vectors. 00435 00436 @param samples Input samples stored by rows. It is a single-precision floating-point matrix of 00437 `<number_of_samples> * k` size. 00438 @param k Number of used nearest neighbors. Should be greater than 1. 00439 @param results Vector with results of prediction (regression or classification) for each input 00440 sample. It is a single-precision floating-point vector with `<number_of_samples>` elements. 00441 @param neighborResponses Optional output values for corresponding neighbors. It is a single- 00442 precision floating-point matrix of `<number_of_samples> * k` size. 00443 @param dist Optional output distances from the input vectors to the corresponding neighbors. It 00444 is a single-precision floating-point matrix of `<number_of_samples> * k` size. 00445 00446 For each input vector (a row of the matrix samples), the method finds the k nearest neighbors. 00447 In case of regression, the predicted result is a mean value of the particular vector's neighbor 00448 responses. In case of classification, the class is determined by voting. 00449 00450 For each input vector, the neighbors are sorted by their distances to the vector. 00451 00452 In case of C++ interface you can use output pointers to empty matrices and the function will 00453 allocate memory itself. 00454 00455 If only a single input vector is passed, all output matrices are optional and the predicted 00456 value is returned by the method. 00457 00458 The function is parallelized with the TBB library. 00459 */ 00460 CV_WRAP virtual float findNearest( InputArray samples, int k, 00461 OutputArray results, 00462 OutputArray neighborResponses=noArray(), 00463 OutputArray dist=noArray() ) const = 0; 00464 00465 /** @brief Implementations of KNearest algorithm 00466 */ 00467 enum Types 00468 { 00469 BRUTE_FORCE=1, 00470 KDTREE=2 00471 }; 00472 00473 /** @brief Creates the empty model 00474 00475 The static method creates empty %KNearest classifier. It should be then trained using StatModel::train method. 00476 */ 00477 CV_WRAP static Ptr<KNearest> create(); 00478 }; 00479 00480 /****************************************************************************************\ 00481 * Support Vector Machines * 00482 \****************************************************************************************/ 00483 00484 /** @brief Support Vector Machines. 00485 00486 @sa @ref ml_intro_svm 00487 */ 00488 class CV_EXPORTS_W SVM : public StatModel 00489 { 00490 public: 00491 00492 class CV_EXPORTS Kernel : public Algorithm 00493 { 00494 public: 00495 virtual int getType() const = 0; 00496 virtual void calc( int vcount, int n, const float* vecs, const float* another, float* results ) = 0; 00497 }; 00498 00499 /** Type of a %SVM formulation. 00500 See SVM::Types. Default value is SVM::C_SVC. */ 00501 /** @see setType */ 00502 CV_WRAP virtual int getType() const = 0; 00503 /** @copybrief getType @see getType */ 00504 CV_WRAP virtual void setType(int val) = 0; 00505 00506 /** Parameter \f$\gamma\f$ of a kernel function. 00507 For SVM::POLY, SVM::RBF, SVM::SIGMOID or SVM::CHI2. Default value is 1. */ 00508 /** @see setGamma */ 00509 CV_WRAP virtual double getGamma() const = 0; 00510 /** @copybrief getGamma @see getGamma */ 00511 CV_WRAP virtual void setGamma(double val) = 0; 00512 00513 /** Parameter _coef0_ of a kernel function. 00514 For SVM::POLY or SVM::SIGMOID. Default value is 0.*/ 00515 /** @see setCoef0 */ 00516 CV_WRAP virtual double getCoef0() const = 0; 00517 /** @copybrief getCoef0 @see getCoef0 */ 00518 CV_WRAP virtual void setCoef0(double val) = 0; 00519 00520 /** Parameter _degree_ of a kernel function. 00521 For SVM::POLY. Default value is 0. */ 00522 /** @see setDegree */ 00523 CV_WRAP virtual double getDegree() const = 0; 00524 /** @copybrief getDegree @see getDegree */ 00525 CV_WRAP virtual void setDegree(double val) = 0; 00526 00527 /** Parameter _C_ of a %SVM optimization problem. 00528 For SVM::C_SVC, SVM::EPS_SVR or SVM::NU_SVR. Default value is 0. */ 00529 /** @see setC */ 00530 CV_WRAP virtual double getC() const = 0; 00531 /** @copybrief getC @see getC */ 00532 CV_WRAP virtual void setC(double val) = 0; 00533 00534 /** Parameter \f$\nu\f$ of a %SVM optimization problem. 00535 For SVM::NU_SVC, SVM::ONE_CLASS or SVM::NU_SVR. Default value is 0. */ 00536 /** @see setNu */ 00537 CV_WRAP virtual double getNu() const = 0; 00538 /** @copybrief getNu @see getNu */ 00539 CV_WRAP virtual void setNu(double val) = 0; 00540 00541 /** Parameter \f$\epsilon\f$ of a %SVM optimization problem. 00542 For SVM::EPS_SVR. Default value is 0. */ 00543 /** @see setP */ 00544 CV_WRAP virtual double getP() const = 0; 00545 /** @copybrief getP @see getP */ 00546 CV_WRAP virtual void setP(double val) = 0; 00547 00548 /** Optional weights in the SVM::C_SVC problem, assigned to particular classes. 00549 They are multiplied by _C_ so the parameter _C_ of class _i_ becomes `classWeights(i) * C`. Thus 00550 these weights affect the misclassification penalty for different classes. The larger weight, 00551 the larger penalty on misclassification of data from the corresponding class. Default value is 00552 empty Mat. */ 00553 /** @see setClassWeights */ 00554 CV_WRAP virtual cv::Mat getClassWeights() const = 0; 00555 /** @copybrief getClassWeights @see getClassWeights */ 00556 CV_WRAP virtual void setClassWeights(const cv::Mat &val) = 0; 00557 00558 /** Termination criteria of the iterative %SVM training procedure which solves a partial 00559 case of constrained quadratic optimization problem. 00560 You can specify tolerance and/or the maximum number of iterations. Default value is 00561 `TermCriteria( TermCriteria::MAX_ITER + TermCriteria::EPS, 1000, FLT_EPSILON )`; */ 00562 /** @see setTermCriteria */ 00563 CV_WRAP virtual cv::TermCriteria getTermCriteria() const = 0; 00564 /** @copybrief getTermCriteria @see getTermCriteria */ 00565 CV_WRAP virtual void setTermCriteria(const cv::TermCriteria &val) = 0; 00566 00567 /** Type of a %SVM kernel. 00568 See SVM::KernelTypes. Default value is SVM::RBF. */ 00569 CV_WRAP virtual int getKernelType() const = 0; 00570 00571 /** Initialize with one of predefined kernels. 00572 See SVM::KernelTypes. */ 00573 CV_WRAP virtual void setKernel(int kernelType) = 0; 00574 00575 /** Initialize with custom kernel. 00576 See SVM::Kernel class for implementation details */ 00577 virtual void setCustomKernel(const Ptr<Kernel> &_kernel) = 0; 00578 00579 //! %SVM type 00580 enum Types { 00581 /** C-Support Vector Classification. n-class classification (n \f$\geq\f$ 2), allows 00582 imperfect separation of classes with penalty multiplier C for outliers. */ 00583 C_SVC=100, 00584 /** \f$\nu\f$-Support Vector Classification. n-class classification with possible 00585 imperfect separation. Parameter \f$\nu\f$ (in the range 0..1, the larger the value, the smoother 00586 the decision boundary) is used instead of C. */ 00587 NU_SVC=101, 00588 /** Distribution Estimation (One-class %SVM). All the training data are from 00589 the same class, %SVM builds a boundary that separates the class from the rest of the feature 00590 space. */ 00591 ONE_CLASS=102, 00592 /** \f$\epsilon\f$-Support Vector Regression. The distance between feature vectors 00593 from the training set and the fitting hyper-plane must be less than p. For outliers the 00594 penalty multiplier C is used. */ 00595 EPS_SVR=103, 00596 /** \f$\nu\f$-Support Vector Regression. \f$\nu\f$ is used instead of p. 00597 See @cite LibSVM for details. */ 00598 NU_SVR=104 00599 }; 00600 00601 /** @brief %SVM kernel type 00602 00603 A comparison of different kernels on the following 2D test case with four classes. Four 00604 SVM::C_SVC SVMs have been trained (one against rest) with auto_train. Evaluation on three 00605 different kernels (SVM::CHI2, SVM::INTER, SVM::RBF). The color depicts the class with max score. 00606 Bright means max-score > 0, dark means max-score < 0. 00607  00608 */ 00609 enum KernelTypes { 00610 /** Returned by SVM::getKernelType in case when custom kernel has been set */ 00611 CUSTOM=-1, 00612 /** Linear kernel. No mapping is done, linear discrimination (or regression) is 00613 done in the original feature space. It is the fastest option. \f$K(x_i, x_j) = x_i^T x_j\f$. */ 00614 LINEAR=0, 00615 /** Polynomial kernel: 00616 \f$K(x_i, x_j) = (\gamma x_i^T x_j + coef0)^{degree}, \gamma > 0\f$. */ 00617 POLY=1, 00618 /** Radial basis function (RBF), a good choice in most cases. 00619 \f$K(x_i, x_j) = e^{-\gamma ||x_i - x_j||^2}, \gamma > 0\f$. */ 00620 RBF=2, 00621 /** Sigmoid kernel: \f$K(x_i, x_j) = \tanh(\gamma x_i^T x_j + coef0)\f$. */ 00622 SIGMOID=3, 00623 /** Exponential Chi2 kernel, similar to the RBF kernel: 00624 \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$. */ 00625 CHI2=4, 00626 /** Histogram intersection kernel. A fast kernel. \f$K(x_i, x_j) = min(x_i,x_j)\f$. */ 00627 INTER=5 00628 }; 00629 00630 //! %SVM params type 00631 enum ParamTypes { 00632 C=0, 00633 GAMMA=1, 00634 P=2, 00635 NU=3, 00636 COEF=4, 00637 DEGREE=5 00638 }; 00639 00640 /** @brief Trains an %SVM with optimal parameters. 00641 00642 @param data the training data that can be constructed using TrainData::create or 00643 TrainData::loadFromCSV. 00644 @param kFold Cross-validation parameter. The training set is divided into kFold subsets. One 00645 subset is used to test the model, the others form the train set. So, the %SVM algorithm is 00646 executed kFold times. 00647 @param Cgrid grid for C 00648 @param gammaGrid grid for gamma 00649 @param pGrid grid for p 00650 @param nuGrid grid for nu 00651 @param coeffGrid grid for coeff 00652 @param degreeGrid grid for degree 00653 @param balanced If true and the problem is 2-class classification then the method creates more 00654 balanced cross-validation subsets that is proportions between classes in subsets are close 00655 to such proportion in the whole train dataset. 00656 00657 The method trains the %SVM model automatically by choosing the optimal parameters C, gamma, p, 00658 nu, coef0, degree. Parameters are considered optimal when the cross-validation 00659 estimate of the test set error is minimal. 00660 00661 If there is no need to optimize a parameter, the corresponding grid step should be set to any 00662 value less than or equal to 1. For example, to avoid optimization in gamma, set `gammaGrid.step 00663 = 0`, `gammaGrid.minVal`, `gamma_grid.maxVal` as arbitrary numbers. In this case, the value 00664 `Gamma` is taken for gamma. 00665 00666 And, finally, if the optimization in a parameter is required but the corresponding grid is 00667 unknown, you may call the function SVM::getDefaultGrid. To generate a grid, for example, for 00668 gamma, call `SVM::getDefaultGrid(SVM::GAMMA)`. 00669 00670 This function works for the classification (SVM::C_SVC or SVM::NU_SVC) as well as for the 00671 regression (SVM::EPS_SVR or SVM::NU_SVR). If it is SVM::ONE_CLASS, no optimization is made and 00672 the usual %SVM with parameters specified in params is executed. 00673 */ 00674 virtual bool trainAuto( const Ptr<TrainData>& data, int kFold = 10, 00675 ParamGrid Cgrid = SVM::getDefaultGrid(SVM::C), 00676 ParamGrid gammaGrid = SVM::getDefaultGrid(SVM::GAMMA), 00677 ParamGrid pGrid = SVM::getDefaultGrid(SVM::P), 00678 ParamGrid nuGrid = SVM::getDefaultGrid(SVM::NU), 00679 ParamGrid coeffGrid = SVM::getDefaultGrid(SVM::COEF), 00680 ParamGrid degreeGrid = SVM::getDefaultGrid(SVM::DEGREE), 00681 bool balanced=false) = 0; 00682 00683 /** @brief Retrieves all the support vectors 00684 00685 The method returns all the support vectors as a floating-point matrix, where support vectors are 00686 stored as matrix rows. 00687 */ 00688 CV_WRAP virtual Mat getSupportVectors() const = 0; 00689 00690 /** @brief Retrieves all the uncompressed support vectors of a linear %SVM 00691 00692 The method returns all the uncompressed support vectors of a linear %SVM that the compressed 00693 support vector, used for prediction, was derived from. They are returned in a floating-point 00694 matrix, where the support vectors are stored as matrix rows. 00695 */ 00696 CV_WRAP Mat getUncompressedSupportVectors() const; 00697 00698 /** @brief Retrieves the decision function 00699 00700 @param i the index of the decision function. If the problem solved is regression, 1-class or 00701 2-class classification, then there will be just one decision function and the index should 00702 always be 0. Otherwise, in the case of N-class classification, there will be \f$N(N-1)/2\f$ 00703 decision functions. 00704 @param alpha the optional output vector for weights, corresponding to different support vectors. 00705 In the case of linear %SVM all the alpha's will be 1's. 00706 @param svidx the optional output vector of indices of support vectors within the matrix of 00707 support vectors (which can be retrieved by SVM::getSupportVectors). In the case of linear 00708 %SVM each decision function consists of a single "compressed" support vector. 00709 00710 The method returns rho parameter of the decision function, a scalar subtracted from the weighted 00711 sum of kernel responses. 00712 */ 00713 CV_WRAP virtual double getDecisionFunction(int i, OutputArray alpha, OutputArray svidx) const = 0; 00714 00715 /** @brief Generates a grid for %SVM parameters. 00716 00717 @param param_id %SVM parameters IDs that must be one of the SVM::ParamTypes. The grid is 00718 generated for the parameter with this ID. 00719 00720 The function generates a grid for the specified parameter of the %SVM algorithm. The grid may be 00721 passed to the function SVM::trainAuto. 00722 */ 00723 static ParamGrid getDefaultGrid( int param_id ); 00724 00725 /** Creates empty model. 00726 Use StatModel::train to train the model. Since %SVM has several parameters, you may want to 00727 find the best parameters for your problem, it can be done with SVM::trainAuto. */ 00728 CV_WRAP static Ptr<SVM> create(); 00729 00730 /** @brief Loads and creates a serialized svm from a file 00731 * 00732 * Use SVM::save to serialize and store an SVM to disk. 00733 * Load the SVM from this file again, by calling this function with the path to the file. 00734 * 00735 * @param filepath path to serialized svm 00736 */ 00737 CV_WRAP static Ptr<SVM> load(const String& filepath); 00738 }; 00739 00740 /****************************************************************************************\ 00741 * Expectation - Maximization * 00742 \****************************************************************************************/ 00743 00744 /** @brief The class implements the Expectation Maximization algorithm. 00745 00746 @sa @ref ml_intro_em 00747 */ 00748 class CV_EXPORTS_W EM : public StatModel 00749 { 00750 public: 00751 //! Type of covariation matrices 00752 enum Types { 00753 /** A scaled identity matrix \f$\mu_k * I\f$. There is the only 00754 parameter \f$\mu_k\f$ to be estimated for each matrix. The option may be used in special cases, 00755 when the constraint is relevant, or as a first step in the optimization (for example in case 00756 when the data is preprocessed with PCA). The results of such preliminary estimation may be 00757 passed again to the optimization procedure, this time with 00758 covMatType=EM::COV_MAT_DIAGONAL. */ 00759 COV_MAT_SPHERICAL=0, 00760 /** A diagonal matrix with positive diagonal elements. The number of 00761 free parameters is d for each matrix. This is most commonly used option yielding good 00762 estimation results. */ 00763 COV_MAT_DIAGONAL=1, 00764 /** A symmetric positively defined matrix. The number of free 00765 parameters in each matrix is about \f$d^2/2\f$. It is not recommended to use this option, unless 00766 there is pretty accurate initial estimation of the parameters and/or a huge number of 00767 training samples. */ 00768 COV_MAT_GENERIC=2, 00769 COV_MAT_DEFAULT=COV_MAT_DIAGONAL 00770 }; 00771 00772 //! Default parameters 00773 enum {DEFAULT_NCLUSTERS=5, DEFAULT_MAX_ITERS=100}; 00774 00775 //! The initial step 00776 enum {START_E_STEP=1, START_M_STEP=2, START_AUTO_STEP=0}; 00777 00778 /** The number of mixture components in the Gaussian mixture model. 00779 Default value of the parameter is EM::DEFAULT_NCLUSTERS=5. Some of %EM implementation could 00780 determine the optimal number of mixtures within a specified value range, but that is not the 00781 case in ML yet. */ 00782 /** @see setClustersNumber */ 00783 CV_WRAP virtual int getClustersNumber() const = 0; 00784 /** @copybrief getClustersNumber @see getClustersNumber */ 00785 CV_WRAP virtual void setClustersNumber(int val) = 0; 00786 00787 /** Constraint on covariance matrices which defines type of matrices. 00788 See EM::Types. */ 00789 /** @see setCovarianceMatrixType */ 00790 CV_WRAP virtual int getCovarianceMatrixType() const = 0; 00791 /** @copybrief getCovarianceMatrixType @see getCovarianceMatrixType */ 00792 CV_WRAP virtual void setCovarianceMatrixType(int val) = 0; 00793 00794 /** The termination criteria of the %EM algorithm. 00795 The %EM algorithm can be terminated by the number of iterations termCrit.maxCount (number of 00796 M-steps) or when relative change of likelihood logarithm is less than termCrit.epsilon. Default 00797 maximum number of iterations is EM::DEFAULT_MAX_ITERS=100. */ 00798 /** @see setTermCriteria */ 00799 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 00800 /** @copybrief getTermCriteria @see getTermCriteria */ 00801 CV_WRAP virtual void setTermCriteria(const TermCriteria &val) = 0; 00802 00803 /** @brief Returns weights of the mixtures 00804 00805 Returns vector with the number of elements equal to the number of mixtures. 00806 */ 00807 CV_WRAP virtual Mat getWeights() const = 0; 00808 /** @brief Returns the cluster centers (means of the Gaussian mixture) 00809 00810 Returns matrix with the number of rows equal to the number of mixtures and number of columns 00811 equal to the space dimensionality. 00812 */ 00813 CV_WRAP virtual Mat getMeans() const = 0; 00814 /** @brief Returns covariation matrices 00815 00816 Returns vector of covariation matrices. Number of matrices is the number of gaussian mixtures, 00817 each matrix is a square floating-point matrix NxN, where N is the space dimensionality. 00818 */ 00819 CV_WRAP virtual void getCovs(CV_OUT std::vector<Mat>& covs) const = 0; 00820 00821 /** @brief Returns a likelihood logarithm value and an index of the most probable mixture component 00822 for the given sample. 00823 00824 @param sample A sample for classification. It should be a one-channel matrix of 00825 \f$1 \times dims\f$ or \f$dims \times 1\f$ size. 00826 @param probs Optional output matrix that contains posterior probabilities of each component 00827 given the sample. It has \f$1 \times nclusters\f$ size and CV_64FC1 type. 00828 00829 The method returns a two-element double vector. Zero element is a likelihood logarithm value for 00830 the sample. First element is an index of the most probable mixture component for the given 00831 sample. 00832 */ 00833 CV_WRAP virtual Vec2d predict2(InputArray sample, OutputArray probs) const = 0; 00834 00835 /** @brief Estimate the Gaussian mixture parameters from a samples set. 00836 00837 This variation starts with Expectation step. Initial values of the model parameters will be 00838 estimated by the k-means algorithm. 00839 00840 Unlike many of the ML models, %EM is an unsupervised learning algorithm and it does not take 00841 responses (class labels or function values) as input. Instead, it computes the *Maximum 00842 Likelihood Estimate* of the Gaussian mixture parameters from an input sample set, stores all the 00843 parameters inside the structure: \f$p_{i,k}\f$ in probs, \f$a_k\f$ in means , \f$S_k\f$ in 00844 covs[k], \f$\pi_k\f$ in weights , and optionally computes the output "class label" for each 00845 sample: \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most 00846 probable mixture component for each sample). 00847 00848 The trained model can be used further for prediction, just like any other classifier. The 00849 trained model is similar to the NormalBayesClassifier. 00850 00851 @param samples Samples from which the Gaussian mixture model will be estimated. It should be a 00852 one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type 00853 it will be converted to the inner matrix of such type for the further computing. 00854 @param logLikelihoods The optional output matrix that contains a likelihood logarithm value for 00855 each sample. It has \f$nsamples \times 1\f$ size and CV_64FC1 type. 00856 @param labels The optional output "class label" for each sample: 00857 \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most probable 00858 mixture component for each sample). It has \f$nsamples \times 1\f$ size and CV_32SC1 type. 00859 @param probs The optional output matrix that contains posterior probabilities of each Gaussian 00860 mixture component given the each sample. It has \f$nsamples \times nclusters\f$ size and 00861 CV_64FC1 type. 00862 */ 00863 CV_WRAP virtual bool trainEM(InputArray samples, 00864 OutputArray logLikelihoods=noArray(), 00865 OutputArray labels=noArray(), 00866 OutputArray probs=noArray()) = 0; 00867 00868 /** @brief Estimate the Gaussian mixture parameters from a samples set. 00869 00870 This variation starts with Expectation step. You need to provide initial means \f$a_k\f$ of 00871 mixture components. Optionally you can pass initial weights \f$\pi_k\f$ and covariance matrices 00872 \f$S_k\f$ of mixture components. 00873 00874 @param samples Samples from which the Gaussian mixture model will be estimated. It should be a 00875 one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type 00876 it will be converted to the inner matrix of such type for the further computing. 00877 @param means0 Initial means \f$a_k\f$ of mixture components. It is a one-channel matrix of 00878 \f$nclusters \times dims\f$ size. If the matrix does not have CV_64F type it will be 00879 converted to the inner matrix of such type for the further computing. 00880 @param covs0 The vector of initial covariance matrices \f$S_k\f$ of mixture components. Each of 00881 covariance matrices is a one-channel matrix of \f$dims \times dims\f$ size. If the matrices 00882 do not have CV_64F type they will be converted to the inner matrices of such type for the 00883 further computing. 00884 @param weights0 Initial weights \f$\pi_k\f$ of mixture components. It should be a one-channel 00885 floating-point matrix with \f$1 \times nclusters\f$ or \f$nclusters \times 1\f$ size. 00886 @param logLikelihoods The optional output matrix that contains a likelihood logarithm value for 00887 each sample. It has \f$nsamples \times 1\f$ size and CV_64FC1 type. 00888 @param labels The optional output "class label" for each sample: 00889 \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most probable 00890 mixture component for each sample). It has \f$nsamples \times 1\f$ size and CV_32SC1 type. 00891 @param probs The optional output matrix that contains posterior probabilities of each Gaussian 00892 mixture component given the each sample. It has \f$nsamples \times nclusters\f$ size and 00893 CV_64FC1 type. 00894 */ 00895 CV_WRAP virtual bool trainE(InputArray samples, InputArray means0, 00896 InputArray covs0=noArray(), 00897 InputArray weights0=noArray(), 00898 OutputArray logLikelihoods=noArray(), 00899 OutputArray labels=noArray(), 00900 OutputArray probs=noArray()) = 0; 00901 00902 /** @brief Estimate the Gaussian mixture parameters from a samples set. 00903 00904 This variation starts with Maximization step. You need to provide initial probabilities 00905 \f$p_{i,k}\f$ to use this option. 00906 00907 @param samples Samples from which the Gaussian mixture model will be estimated. It should be a 00908 one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type 00909 it will be converted to the inner matrix of such type for the further computing. 00910 @param probs0 00911 @param logLikelihoods The optional output matrix that contains a likelihood logarithm value for 00912 each sample. It has \f$nsamples \times 1\f$ size and CV_64FC1 type. 00913 @param labels The optional output "class label" for each sample: 00914 \f$\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\f$ (indices of the most probable 00915 mixture component for each sample). It has \f$nsamples \times 1\f$ size and CV_32SC1 type. 00916 @param probs The optional output matrix that contains posterior probabilities of each Gaussian 00917 mixture component given the each sample. It has \f$nsamples \times nclusters\f$ size and 00918 CV_64FC1 type. 00919 */ 00920 CV_WRAP virtual bool trainM(InputArray samples, InputArray probs0, 00921 OutputArray logLikelihoods=noArray(), 00922 OutputArray labels=noArray(), 00923 OutputArray probs=noArray()) = 0; 00924 00925 /** Creates empty %EM model. 00926 The model should be trained then using StatModel::train(traindata, flags) method. Alternatively, you 00927 can use one of the EM::train\* methods or load it from file using Algorithm::load<EM>(filename). 00928 */ 00929 CV_WRAP static Ptr<EM> create(); 00930 }; 00931 00932 /****************************************************************************************\ 00933 * Decision Tree * 00934 \****************************************************************************************/ 00935 00936 /** @brief The class represents a single decision tree or a collection of decision trees. 00937 00938 The current public interface of the class allows user to train only a single decision tree, however 00939 the class is capable of storing multiple decision trees and using them for prediction (by summing 00940 responses or using a voting schemes), and the derived from DTrees classes (such as RTrees and Boost) 00941 use this capability to implement decision tree ensembles. 00942 00943 @sa @ref ml_intro_trees 00944 */ 00945 class CV_EXPORTS_W DTrees : public StatModel 00946 { 00947 public: 00948 /** Predict options */ 00949 enum Flags { PREDICT_AUTO=0, PREDICT_SUM=(1<<8), PREDICT_MAX_VOTE=(2<<8), PREDICT_MASK=(3<<8) }; 00950 00951 /** Cluster possible values of a categorical variable into K<=maxCategories clusters to 00952 find a suboptimal split. 00953 If a discrete variable, on which the training procedure tries to make a split, takes more than 00954 maxCategories values, the precise best subset estimation may take a very long time because the 00955 algorithm is exponential. Instead, many decision trees engines (including our implementation) 00956 try to find sub-optimal split in this case by clustering all the samples into maxCategories 00957 clusters that is some categories are merged together. The clustering is applied only in n > 00958 2-class classification problems for categorical variables with N > max_categories possible 00959 values. In case of regression and 2-class classification the optimal split can be found 00960 efficiently without employing clustering, thus the parameter is not used in these cases. 00961 Default value is 10.*/ 00962 /** @see setMaxCategories */ 00963 CV_WRAP virtual int getMaxCategories() const = 0; 00964 /** @copybrief getMaxCategories @see getMaxCategories */ 00965 CV_WRAP virtual void setMaxCategories(int val) = 0; 00966 00967 /** The maximum possible depth of the tree. 00968 That is the training algorithms attempts to split a node while its depth is less than maxDepth. 00969 The root node has zero depth. The actual depth may be smaller if the other termination criteria 00970 are met (see the outline of the training procedure @ref ml_intro_trees "here"), and/or if the 00971 tree is pruned. Default value is INT_MAX.*/ 00972 /** @see setMaxDepth */ 00973 CV_WRAP virtual int getMaxDepth() const = 0; 00974 /** @copybrief getMaxDepth @see getMaxDepth */ 00975 CV_WRAP virtual void setMaxDepth(int val) = 0; 00976 00977 /** If the number of samples in a node is less than this parameter then the node will not be split. 00978 00979 Default value is 10.*/ 00980 /** @see setMinSampleCount */ 00981 CV_WRAP virtual int getMinSampleCount() const = 0; 00982 /** @copybrief getMinSampleCount @see getMinSampleCount */ 00983 CV_WRAP virtual void setMinSampleCount(int val) = 0; 00984 00985 /** If CVFolds > 1 then algorithms prunes the built decision tree using K-fold 00986 cross-validation procedure where K is equal to CVFolds. 00987 Default value is 10.*/ 00988 /** @see setCVFolds */ 00989 CV_WRAP virtual int getCVFolds() const = 0; 00990 /** @copybrief getCVFolds @see getCVFolds */ 00991 CV_WRAP virtual void setCVFolds(int val) = 0; 00992 00993 /** If true then surrogate splits will be built. 00994 These splits allow to work with missing data and compute variable importance correctly. 00995 Default value is false. 00996 @note currently it's not implemented.*/ 00997 /** @see setUseSurrogates */ 00998 CV_WRAP virtual bool getUseSurrogates() const = 0; 00999 /** @copybrief getUseSurrogates @see getUseSurrogates */ 01000 CV_WRAP virtual void setUseSurrogates(bool val) = 0; 01001 01002 /** If true then a pruning will be harsher. 01003 This will make a tree more compact and more resistant to the training data noise but a bit less 01004 accurate. Default value is true.*/ 01005 /** @see setUse1SERule */ 01006 CV_WRAP virtual bool getUse1SERule() const = 0; 01007 /** @copybrief getUse1SERule @see getUse1SERule */ 01008 CV_WRAP virtual void setUse1SERule(bool val) = 0; 01009 01010 /** If true then pruned branches are physically removed from the tree. 01011 Otherwise they are retained and it is possible to get results from the original unpruned (or 01012 pruned less aggressively) tree. Default value is true.*/ 01013 /** @see setTruncatePrunedTree */ 01014 CV_WRAP virtual bool getTruncatePrunedTree() const = 0; 01015 /** @copybrief getTruncatePrunedTree @see getTruncatePrunedTree */ 01016 CV_WRAP virtual void setTruncatePrunedTree(bool val) = 0; 01017 01018 /** Termination criteria for regression trees. 01019 If all absolute differences between an estimated value in a node and values of train samples 01020 in this node are less than this parameter then the node will not be split further. Default 01021 value is 0.01f*/ 01022 /** @see setRegressionAccuracy */ 01023 CV_WRAP virtual float getRegressionAccuracy() const = 0; 01024 /** @copybrief getRegressionAccuracy @see getRegressionAccuracy */ 01025 CV_WRAP virtual void setRegressionAccuracy(float val) = 0; 01026 01027 /** @brief The array of a priori class probabilities, sorted by the class label value. 01028 01029 The parameter can be used to tune the decision tree preferences toward a certain class. For 01030 example, if you want to detect some rare anomaly occurrence, the training base will likely 01031 contain much more normal cases than anomalies, so a very good classification performance 01032 will be achieved just by considering every case as normal. To avoid this, the priors can be 01033 specified, where the anomaly probability is artificially increased (up to 0.5 or even 01034 greater), so the weight of the misclassified anomalies becomes much bigger, and the tree is 01035 adjusted properly. 01036 01037 You can also think about this parameter as weights of prediction categories which determine 01038 relative weights that you give to misclassification. That is, if the weight of the first 01039 category is 1 and the weight of the second category is 10, then each mistake in predicting 01040 the second category is equivalent to making 10 mistakes in predicting the first category. 01041 Default value is empty Mat.*/ 01042 /** @see setPriors */ 01043 CV_WRAP virtual cv::Mat getPriors() const = 0; 01044 /** @copybrief getPriors @see getPriors */ 01045 CV_WRAP virtual void setPriors(const cv::Mat &val) = 0; 01046 01047 /** @brief The class represents a decision tree node. 01048 */ 01049 class CV_EXPORTS Node 01050 { 01051 public: 01052 Node(); 01053 double value; //!< Value at the node: a class label in case of classification or estimated 01054 //!< function value in case of regression. 01055 int classIdx; //!< Class index normalized to 0..class_count-1 range and assigned to the 01056 //!< node. It is used internally in classification trees and tree ensembles. 01057 int parent; //!< Index of the parent node 01058 int left; //!< Index of the left child node 01059 int right; //!< Index of right child node 01060 int defaultDir; //!< Default direction where to go (-1: left or +1: right). It helps in the 01061 //!< case of missing values. 01062 int split; //!< Index of the first split 01063 }; 01064 01065 /** @brief The class represents split in a decision tree. 01066 */ 01067 class CV_EXPORTS Split 01068 { 01069 public: 01070 Split(); 01071 int varIdx; //!< Index of variable on which the split is created. 01072 bool inversed; //!< If true, then the inverse split rule is used (i.e. left and right 01073 //!< branches are exchanged in the rule expressions below). 01074 float quality; //!< The split quality, a positive number. It is used to choose the best split. 01075 int next; //!< Index of the next split in the list of splits for the node 01076 float c; /**< The threshold value in case of split on an ordered variable. 01077 The rule is: 01078 @code{.none} 01079 if var_value < c 01080 then next_node <- left 01081 else next_node <- right 01082 @endcode */ 01083 int subsetOfs; /**< Offset of the bitset used by the split on a categorical variable. 01084 The rule is: 01085 @code{.none} 01086 if bitset[var_value] == 1 01087 then next_node <- left 01088 else next_node <- right 01089 @endcode */ 01090 }; 01091 01092 /** @brief Returns indices of root nodes 01093 */ 01094 virtual const std::vector<int>& getRoots() const = 0; 01095 /** @brief Returns all the nodes 01096 01097 all the node indices are indices in the returned vector 01098 */ 01099 virtual const std::vector<Node>& getNodes() const = 0; 01100 /** @brief Returns all the splits 01101 01102 all the split indices are indices in the returned vector 01103 */ 01104 virtual const std::vector<Split>& getSplits() const = 0; 01105 /** @brief Returns all the bitsets for categorical splits 01106 01107 Split::subsetOfs is an offset in the returned vector 01108 */ 01109 virtual const std::vector<int>& getSubsets() const = 0; 01110 01111 /** @brief Creates the empty model 01112 01113 The static method creates empty decision tree with the specified parameters. It should be then 01114 trained using train method (see StatModel::train). Alternatively, you can load the model from 01115 file using Algorithm::load<DTrees>(filename). 01116 */ 01117 CV_WRAP static Ptr<DTrees> create(); 01118 }; 01119 01120 /****************************************************************************************\ 01121 * Random Trees Classifier * 01122 \****************************************************************************************/ 01123 01124 /** @brief The class implements the random forest predictor. 01125 01126 @sa @ref ml_intro_rtrees 01127 */ 01128 class CV_EXPORTS_W RTrees : public DTrees 01129 { 01130 public: 01131 01132 /** If true then variable importance will be calculated and then it can be retrieved by RTrees::getVarImportance. 01133 Default value is false.*/ 01134 /** @see setCalculateVarImportance */ 01135 CV_WRAP virtual bool getCalculateVarImportance() const = 0; 01136 /** @copybrief getCalculateVarImportance @see getCalculateVarImportance */ 01137 CV_WRAP virtual void setCalculateVarImportance(bool val) = 0; 01138 01139 /** The size of the randomly selected subset of features at each tree node and that are used 01140 to find the best split(s). 01141 If you set it to 0 then the size will be set to the square root of the total number of 01142 features. Default value is 0.*/ 01143 /** @see setActiveVarCount */ 01144 CV_WRAP virtual int getActiveVarCount() const = 0; 01145 /** @copybrief getActiveVarCount @see getActiveVarCount */ 01146 CV_WRAP virtual void setActiveVarCount(int val) = 0; 01147 01148 /** The termination criteria that specifies when the training algorithm stops. 01149 Either when the specified number of trees is trained and added to the ensemble or when 01150 sufficient accuracy (measured as OOB error) is achieved. Typically the more trees you have the 01151 better the accuracy. However, the improvement in accuracy generally diminishes and asymptotes 01152 pass a certain number of trees. Also to keep in mind, the number of tree increases the 01153 prediction time linearly. Default value is TermCriteria(TermCriteria::MAX_ITERS + 01154 TermCriteria::EPS, 50, 0.1)*/ 01155 /** @see setTermCriteria */ 01156 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 01157 /** @copybrief getTermCriteria @see getTermCriteria */ 01158 CV_WRAP virtual void setTermCriteria(const TermCriteria &val) = 0; 01159 01160 /** Returns the variable importance array. 01161 The method returns the variable importance vector, computed at the training stage when 01162 CalculateVarImportance is set to true. If this flag was set to false, the empty matrix is 01163 returned. 01164 */ 01165 CV_WRAP virtual Mat getVarImportance() const = 0; 01166 01167 /** Creates the empty model. 01168 Use StatModel::train to train the model, StatModel::train to create and train the model, 01169 Algorithm::load to load the pre-trained model. 01170 */ 01171 CV_WRAP static Ptr<RTrees> create(); 01172 }; 01173 01174 /****************************************************************************************\ 01175 * Boosted tree classifier * 01176 \****************************************************************************************/ 01177 01178 /** @brief Boosted tree classifier derived from DTrees 01179 01180 @sa @ref ml_intro_boost 01181 */ 01182 class CV_EXPORTS_W Boost : public DTrees 01183 { 01184 public: 01185 /** Type of the boosting algorithm. 01186 See Boost::Types. Default value is Boost::REAL. */ 01187 /** @see setBoostType */ 01188 CV_WRAP virtual int getBoostType() const = 0; 01189 /** @copybrief getBoostType @see getBoostType */ 01190 CV_WRAP virtual void setBoostType(int val) = 0; 01191 01192 /** The number of weak classifiers. 01193 Default value is 100. */ 01194 /** @see setWeakCount */ 01195 CV_WRAP virtual int getWeakCount() const = 0; 01196 /** @copybrief getWeakCount @see getWeakCount */ 01197 CV_WRAP virtual void setWeakCount(int val) = 0; 01198 01199 /** A threshold between 0 and 1 used to save computational time. 01200 Samples with summary weight \f$\leq 1 - weight_trim_rate\f$ do not participate in the *next* 01201 iteration of training. Set this parameter to 0 to turn off this functionality. Default value is 0.95.*/ 01202 /** @see setWeightTrimRate */ 01203 CV_WRAP virtual double getWeightTrimRate() const = 0; 01204 /** @copybrief getWeightTrimRate @see getWeightTrimRate */ 01205 CV_WRAP virtual void setWeightTrimRate(double val) = 0; 01206 01207 /** Boosting type. 01208 Gentle AdaBoost and Real AdaBoost are often the preferable choices. */ 01209 enum Types { 01210 DISCRETE=0, //!< Discrete AdaBoost. 01211 REAL=1, //!< Real AdaBoost. It is a technique that utilizes confidence-rated predictions 01212 //!< and works well with categorical data. 01213 LOGIT=2, //!< LogitBoost. It can produce good regression fits. 01214 GENTLE=3 //!< Gentle AdaBoost. It puts less weight on outlier data points and for that 01215 //!<reason is often good with regression data. 01216 }; 01217 01218 /** Creates the empty model. 01219 Use StatModel::train to train the model, Algorithm::load<Boost>(filename) to load the pre-trained model. */ 01220 CV_WRAP static Ptr<Boost> create(); 01221 }; 01222 01223 /****************************************************************************************\ 01224 * Gradient Boosted Trees * 01225 \****************************************************************************************/ 01226 01227 /*class CV_EXPORTS_W GBTrees : public DTrees 01228 { 01229 public: 01230 struct CV_EXPORTS_W_MAP Params : public DTrees::Params 01231 { 01232 CV_PROP_RW int weakCount; 01233 CV_PROP_RW int lossFunctionType; 01234 CV_PROP_RW float subsamplePortion; 01235 CV_PROP_RW float shrinkage; 01236 01237 Params(); 01238 Params( int lossFunctionType, int weakCount, float shrinkage, 01239 float subsamplePortion, int maxDepth, bool useSurrogates ); 01240 }; 01241 01242 enum {SQUARED_LOSS=0, ABSOLUTE_LOSS, HUBER_LOSS=3, DEVIANCE_LOSS}; 01243 01244 virtual void setK(int k) = 0; 01245 01246 virtual float predictSerial( InputArray samples, 01247 OutputArray weakResponses, int flags) const = 0; 01248 01249 static Ptr<GBTrees> create(const Params& p); 01250 };*/ 01251 01252 /****************************************************************************************\ 01253 * Artificial Neural Networks (ANN) * 01254 \****************************************************************************************/ 01255 01256 /////////////////////////////////// Multi-Layer Perceptrons ////////////////////////////// 01257 01258 /** @brief Artificial Neural Networks - Multi-Layer Perceptrons. 01259 01260 Unlike many other models in ML that are constructed and trained at once, in the MLP model these 01261 steps are separated. First, a network with the specified topology is created using the non-default 01262 constructor or the method ANN_MLP::create. All the weights are set to zeros. Then, the network is 01263 trained using a set of input and output vectors. The training procedure can be repeated more than 01264 once, that is, the weights can be adjusted based on the new training data. 01265 01266 Additional flags for StatModel::train are available: ANN_MLP::TrainFlags. 01267 01268 @sa @ref ml_intro_ann 01269 */ 01270 class CV_EXPORTS_W ANN_MLP : public StatModel 01271 { 01272 public: 01273 /** Available training methods */ 01274 enum TrainingMethods { 01275 BACKPROP=0, //!< The back-propagation algorithm. 01276 RPROP=1 //!< The RPROP algorithm. See @cite RPROP93 for details. 01277 }; 01278 01279 /** Sets training method and common parameters. 01280 @param method Default value is ANN_MLP::RPROP. See ANN_MLP::TrainingMethods. 01281 @param param1 passed to setRpropDW0 for ANN_MLP::RPROP and to setBackpropWeightScale for ANN_MLP::BACKPROP 01282 @param param2 passed to setRpropDWMin for ANN_MLP::RPROP and to setBackpropMomentumScale for ANN_MLP::BACKPROP. 01283 */ 01284 CV_WRAP virtual void setTrainMethod(int method, double param1 = 0, double param2 = 0) = 0; 01285 01286 /** Returns current training method */ 01287 CV_WRAP virtual int getTrainMethod() const = 0; 01288 01289 /** Initialize the activation function for each neuron. 01290 Currently the default and the only fully supported activation function is ANN_MLP::SIGMOID_SYM. 01291 @param type The type of activation function. See ANN_MLP::ActivationFunctions. 01292 @param param1 The first parameter of the activation function, \f$\alpha\f$. Default value is 0. 01293 @param param2 The second parameter of the activation function, \f$\beta\f$. Default value is 0. 01294 */ 01295 CV_WRAP virtual void setActivationFunction(int type, double param1 = 0, double param2 = 0) = 0; 01296 01297 /** Integer vector specifying the number of neurons in each layer including the input and output layers. 01298 The very first element specifies the number of elements in the input layer. 01299 The last element - number of elements in the output layer. Default value is empty Mat. 01300 @sa getLayerSizes */ 01301 CV_WRAP virtual void setLayerSizes(InputArray _layer_sizes) = 0; 01302 01303 /** Integer vector specifying the number of neurons in each layer including the input and output layers. 01304 The very first element specifies the number of elements in the input layer. 01305 The last element - number of elements in the output layer. 01306 @sa setLayerSizes */ 01307 CV_WRAP virtual cv::Mat getLayerSizes() const = 0; 01308 01309 /** Termination criteria of the training algorithm. 01310 You can specify the maximum number of iterations (maxCount) and/or how much the error could 01311 change between the iterations to make the algorithm continue (epsilon). Default value is 01312 TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 1000, 0.01).*/ 01313 /** @see setTermCriteria */ 01314 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 01315 /** @copybrief getTermCriteria @see getTermCriteria */ 01316 CV_WRAP virtual void setTermCriteria(TermCriteria val) = 0; 01317 01318 /** BPROP: Strength of the weight gradient term. 01319 The recommended value is about 0.1. Default value is 0.1.*/ 01320 /** @see setBackpropWeightScale */ 01321 CV_WRAP virtual double getBackpropWeightScale() const = 0; 01322 /** @copybrief getBackpropWeightScale @see getBackpropWeightScale */ 01323 CV_WRAP virtual void setBackpropWeightScale(double val) = 0; 01324 01325 /** BPROP: Strength of the momentum term (the difference between weights on the 2 previous iterations). 01326 This parameter provides some inertia to smooth the random fluctuations of the weights. It can 01327 vary from 0 (the feature is disabled) to 1 and beyond. The value 0.1 or so is good enough. 01328 Default value is 0.1.*/ 01329 /** @see setBackpropMomentumScale */ 01330 CV_WRAP virtual double getBackpropMomentumScale() const = 0; 01331 /** @copybrief getBackpropMomentumScale @see getBackpropMomentumScale */ 01332 CV_WRAP virtual void setBackpropMomentumScale(double val) = 0; 01333 01334 /** RPROP: Initial value \f$\Delta_0\f$ of update-values \f$\Delta_{ij}\f$. 01335 Default value is 0.1.*/ 01336 /** @see setRpropDW0 */ 01337 CV_WRAP virtual double getRpropDW0() const = 0; 01338 /** @copybrief getRpropDW0 @see getRpropDW0 */ 01339 CV_WRAP virtual void setRpropDW0(double val) = 0; 01340 01341 /** RPROP: Increase factor \f$\eta^+\f$. 01342 It must be >1. Default value is 1.2.*/ 01343 /** @see setRpropDWPlus */ 01344 CV_WRAP virtual double getRpropDWPlus() const = 0; 01345 /** @copybrief getRpropDWPlus @see getRpropDWPlus */ 01346 CV_WRAP virtual void setRpropDWPlus(double val) = 0; 01347 01348 /** RPROP: Decrease factor \f$\eta^-\f$. 01349 It must be <1. Default value is 0.5.*/ 01350 /** @see setRpropDWMinus */ 01351 CV_WRAP virtual double getRpropDWMinus() const = 0; 01352 /** @copybrief getRpropDWMinus @see getRpropDWMinus */ 01353 CV_WRAP virtual void setRpropDWMinus(double val) = 0; 01354 01355 /** RPROP: Update-values lower limit \f$\Delta_{min}\f$. 01356 It must be positive. Default value is FLT_EPSILON.*/ 01357 /** @see setRpropDWMin */ 01358 CV_WRAP virtual double getRpropDWMin() const = 0; 01359 /** @copybrief getRpropDWMin @see getRpropDWMin */ 01360 CV_WRAP virtual void setRpropDWMin(double val) = 0; 01361 01362 /** RPROP: Update-values upper limit \f$\Delta_{max}\f$. 01363 It must be >1. Default value is 50.*/ 01364 /** @see setRpropDWMax */ 01365 CV_WRAP virtual double getRpropDWMax() const = 0; 01366 /** @copybrief getRpropDWMax @see getRpropDWMax */ 01367 CV_WRAP virtual void setRpropDWMax(double val) = 0; 01368 01369 /** possible activation functions */ 01370 enum ActivationFunctions { 01371 /** Identity function: \f$f(x)=x\f$ */ 01372 IDENTITY = 0, 01373 /** Symmetrical sigmoid: \f$f(x)=\beta*(1-e^{-\alpha x})/(1+e^{-\alpha x}\f$ 01374 @note 01375 If you are using the default sigmoid activation function with the default parameter values 01376 fparam1=0 and fparam2=0 then the function used is y = 1.7159\*tanh(2/3 \* x), so the output 01377 will range from [-1.7159, 1.7159], instead of [0,1].*/ 01378 SIGMOID_SYM = 1, 01379 /** Gaussian function: \f$f(x)=\beta e^{-\alpha x*x}\f$ */ 01380 GAUSSIAN = 2 01381 }; 01382 01383 /** Train options */ 01384 enum TrainFlags { 01385 /** Update the network weights, rather than compute them from scratch. In the latter case 01386 the weights are initialized using the Nguyen-Widrow algorithm. */ 01387 UPDATE_WEIGHTS = 1, 01388 /** Do not normalize the input vectors. If this flag is not set, the training algorithm 01389 normalizes each input feature independently, shifting its mean value to 0 and making the 01390 standard deviation equal to 1. If the network is assumed to be updated frequently, the new 01391 training data could be much different from original one. In this case, you should take care 01392 of proper normalization. */ 01393 NO_INPUT_SCALE = 2, 01394 /** Do not normalize the output vectors. If the flag is not set, the training algorithm 01395 normalizes each output feature independently, by transforming it to the certain range 01396 depending on the used activation function. */ 01397 NO_OUTPUT_SCALE = 4 01398 }; 01399 01400 CV_WRAP virtual Mat getWeights(int layerIdx) const = 0; 01401 01402 /** @brief Creates empty model 01403 01404 Use StatModel::train to train the model, Algorithm::load<ANN_MLP>(filename) to load the pre-trained model. 01405 Note that the train method has optional flags: ANN_MLP::TrainFlags. 01406 */ 01407 CV_WRAP static Ptr<ANN_MLP> create(); 01408 01409 /** @brief Loads and creates a serialized ANN from a file 01410 * 01411 * Use ANN::save to serialize and store an ANN to disk. 01412 * Load the ANN from this file again, by calling this function with the path to the file. 01413 * 01414 * @param filepath path to serialized ANN 01415 */ 01416 CV_WRAP static Ptr<ANN_MLP> load(const String& filepath); 01417 01418 }; 01419 01420 /****************************************************************************************\ 01421 * Logistic Regression * 01422 \****************************************************************************************/ 01423 01424 /** @brief Implements Logistic Regression classifier. 01425 01426 @sa @ref ml_intro_lr 01427 */ 01428 class CV_EXPORTS_W LogisticRegression : public StatModel 01429 { 01430 public: 01431 01432 /** Learning rate. */ 01433 /** @see setLearningRate */ 01434 CV_WRAP virtual double getLearningRate() const = 0; 01435 /** @copybrief getLearningRate @see getLearningRate */ 01436 CV_WRAP virtual void setLearningRate(double val) = 0; 01437 01438 /** Number of iterations. */ 01439 /** @see setIterations */ 01440 CV_WRAP virtual int getIterations() const = 0; 01441 /** @copybrief getIterations @see getIterations */ 01442 CV_WRAP virtual void setIterations(int val) = 0; 01443 01444 /** Kind of regularization to be applied. See LogisticRegression::RegKinds. */ 01445 /** @see setRegularization */ 01446 CV_WRAP virtual int getRegularization() const = 0; 01447 /** @copybrief getRegularization @see getRegularization */ 01448 CV_WRAP virtual void setRegularization(int val) = 0; 01449 01450 /** Kind of training method used. See LogisticRegression::Methods. */ 01451 /** @see setTrainMethod */ 01452 CV_WRAP virtual int getTrainMethod() const = 0; 01453 /** @copybrief getTrainMethod @see getTrainMethod */ 01454 CV_WRAP virtual void setTrainMethod(int val) = 0; 01455 01456 /** Specifies the number of training samples taken in each step of Mini-Batch Gradient 01457 Descent. Will only be used if using LogisticRegression::MINI_BATCH training algorithm. It 01458 has to take values less than the total number of training samples. */ 01459 /** @see setMiniBatchSize */ 01460 CV_WRAP virtual int getMiniBatchSize() const = 0; 01461 /** @copybrief getMiniBatchSize @see getMiniBatchSize */ 01462 CV_WRAP virtual void setMiniBatchSize(int val) = 0; 01463 01464 /** Termination criteria of the algorithm. */ 01465 /** @see setTermCriteria */ 01466 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 01467 /** @copybrief getTermCriteria @see getTermCriteria */ 01468 CV_WRAP virtual void setTermCriteria(TermCriteria val) = 0; 01469 01470 //! Regularization kinds 01471 enum RegKinds { 01472 REG_DISABLE = -1, //!< Regularization disabled 01473 REG_L1 = 0, //!< %L1 norm 01474 REG_L2 = 1 //!< %L2 norm 01475 }; 01476 01477 //! Training methods 01478 enum Methods { 01479 BATCH = 0, 01480 MINI_BATCH = 1 //!< Set MiniBatchSize to a positive integer when using this method. 01481 }; 01482 01483 /** @brief Predicts responses for input samples and returns a float type. 01484 01485 @param samples The input data for the prediction algorithm. Matrix [m x n], where each row 01486 contains variables (features) of one object being classified. Should have data type CV_32F. 01487 @param results Predicted labels as a column matrix of type CV_32S. 01488 @param flags Not used. 01489 */ 01490 CV_WRAP virtual float predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const = 0; 01491 01492 /** @brief This function returns the trained paramters arranged across rows. 01493 01494 For a two class classifcation problem, it returns a row matrix. It returns learnt paramters of 01495 the Logistic Regression as a matrix of type CV_32F. 01496 */ 01497 CV_WRAP virtual Mat get_learnt_thetas() const = 0; 01498 01499 /** @brief Creates empty model. 01500 01501 Creates Logistic Regression model with parameters given. 01502 */ 01503 CV_WRAP static Ptr<LogisticRegression> create(); 01504 }; 01505 01506 01507 /****************************************************************************************\ 01508 * Stochastic Gradient Descent SVM Classifier * 01509 \****************************************************************************************/ 01510 01511 /*! 01512 @brief Stochastic Gradient Descent SVM classifier 01513 01514 SVMSGD provides a fast and easy-to-use implementation of the SVM classifier using the Stochastic Gradient Descent approach, 01515 as presented in @cite bottou2010large. 01516 01517 The classifier has following parameters: 01518 - model type, 01519 - margin type, 01520 - margin regularization (\f$\lambda\f$), 01521 - initial step size (\f$\gamma_0\f$), 01522 - step decreasing power (\f$c\f$), 01523 - and termination criteria. 01524 01525 The model type may have one of the following values: \ref SGD and \ref ASGD. 01526 01527 - \ref SGD is the classic version of SVMSGD classifier: every next step is calculated by the formula 01528 \f[w_{t+1} = w_t - \gamma(t) \frac{dQ_i}{dw} |_{w = w_t}\f] 01529 where 01530 - \f$w_t\f$ is the weights vector for decision function at step \f$t\f$, 01531 - \f$\gamma(t)\f$ is the step size of model parameters at the iteration \f$t\f$, it is decreased on each step by the formula 01532 \f$\gamma(t) = \gamma_0 (1 + \lambda \gamma_0 t) ^ {-c}\f$ 01533 - \f$Q_i\f$ is the target functional from SVM task for sample with number \f$i\f$, this sample is chosen stochastically on each step of the algorithm. 01534 01535 - \ref ASGD is Average Stochastic Gradient Descent SVM Classifier. ASGD classifier averages weights vector on each step of algorithm by the formula 01536 \f$\widehat{w}_{t+1} = \frac{t}{1+t}\widehat{w}_{t} + \frac{1}{1+t}w_{t+1}\f$ 01537 01538 The recommended model type is ASGD (following @cite bottou2010large). 01539 01540 The margin type may have one of the following values: \ref SOFT_MARGIN or \ref HARD_MARGIN. 01541 01542 - You should use \ref HARD_MARGIN type, if you have linearly separable sets. 01543 - You should use \ref SOFT_MARGIN type, if you have non-linearly separable sets or sets with outliers. 01544 - In the general case (if you know nothing about linear separability of your sets), use SOFT_MARGIN. 01545 01546 The other parameters may be described as follows: 01547 - Margin regularization parameter is responsible for weights decreasing at each step and for the strength of restrictions on outliers 01548 (the less the parameter, the less probability that an outlier will be ignored). 01549 Recommended value for SGD model is 0.0001, for ASGD model is 0.00001. 01550 01551 - Initial step size parameter is the initial value for the step size \f$\gamma(t)\f$. 01552 You will have to find the best initial step for your problem. 01553 01554 - Step decreasing power is the power parameter for \f$\gamma(t)\f$ decreasing by the formula, mentioned above. 01555 Recommended value for SGD model is 1, for ASGD model is 0.75. 01556 01557 - Termination criteria can be TermCriteria::COUNT, TermCriteria::EPS or TermCriteria::COUNT + TermCriteria::EPS. 01558 You will have to find the best termination criteria for your problem. 01559 01560 Note that the parameters margin regularization, initial step size, and step decreasing power should be positive. 01561 01562 To use SVMSGD algorithm do as follows: 01563 01564 - first, create the SVMSGD object. The algoorithm will set optimal parameters by default, but you can set your own parameters via functions setSvmsgdType(), 01565 setMarginType(), setMarginRegularization(), setInitialStepSize(), and setStepDecreasingPower(). 01566 01567 - then the SVM model can be trained using the train features and the correspondent labels by the method train(). 01568 01569 - after that, the label of a new feature vector can be predicted using the method predict(). 01570 01571 @code 01572 // Create empty object 01573 cv::Ptr<SVMSGD> svmsgd = SVMSGD::create(); 01574 01575 // Train the Stochastic Gradient Descent SVM 01576 svmsgd->train(trainData); 01577 01578 // Predict labels for the new samples 01579 svmsgd->predict(samples, responses); 01580 @endcode 01581 01582 */ 01583 01584 class CV_EXPORTS_W SVMSGD : public cv::ml::StatModel 01585 { 01586 public: 01587 01588 /** SVMSGD type. 01589 ASGD is often the preferable choice. */ 01590 enum SvmsgdType 01591 { 01592 SGD, //!< Stochastic Gradient Descent 01593 ASGD //!< Average Stochastic Gradient Descent 01594 }; 01595 01596 /** Margin type.*/ 01597 enum MarginType 01598 { 01599 SOFT_MARGIN, //!< General case, suits to the case of non-linearly separable sets, allows outliers. 01600 HARD_MARGIN //!< More accurate for the case of linearly separable sets. 01601 }; 01602 01603 /** 01604 * @return the weights of the trained model (decision function f(x) = weights * x + shift). 01605 */ 01606 CV_WRAP virtual Mat getWeights() = 0; 01607 01608 /** 01609 * @return the shift of the trained model (decision function f(x) = weights * x + shift). 01610 */ 01611 CV_WRAP virtual float getShift() = 0; 01612 01613 /** @brief Creates empty model. 01614 * Use StatModel::train to train the model. Since %SVMSGD has several parameters, you may want to 01615 * find the best parameters for your problem or use setOptimalParameters() to set some default parameters. 01616 */ 01617 CV_WRAP static Ptr<SVMSGD> create(); 01618 01619 /** @brief Function sets optimal parameters values for chosen SVM SGD model. 01620 * @param svmsgdType is the type of SVMSGD classifier. 01621 * @param marginType is the type of margin constraint. 01622 */ 01623 CV_WRAP virtual void setOptimalParameters(int svmsgdType = SVMSGD::ASGD, int marginType = SVMSGD::SOFT_MARGIN) = 0; 01624 01625 /** @brief %Algorithm type, one of SVMSGD::SvmsgdType. */ 01626 /** @see setSvmsgdType */ 01627 CV_WRAP virtual int getSvmsgdType() const = 0; 01628 /** @copybrief getSvmsgdType @see getSvmsgdType */ 01629 CV_WRAP virtual void setSvmsgdType(int svmsgdType) = 0; 01630 01631 /** @brief %Margin type, one of SVMSGD::MarginType. */ 01632 /** @see setMarginType */ 01633 CV_WRAP virtual int getMarginType() const = 0; 01634 /** @copybrief getMarginType @see getMarginType */ 01635 CV_WRAP virtual void setMarginType(int marginType) = 0; 01636 01637 /** @brief Parameter marginRegularization of a %SVMSGD optimization problem. */ 01638 /** @see setMarginRegularization */ 01639 CV_WRAP virtual float getMarginRegularization() const = 0; 01640 /** @copybrief getMarginRegularization @see getMarginRegularization */ 01641 CV_WRAP virtual void setMarginRegularization(float marginRegularization) = 0; 01642 01643 /** @brief Parameter initialStepSize of a %SVMSGD optimization problem. */ 01644 /** @see setInitialStepSize */ 01645 CV_WRAP virtual float getInitialStepSize() const = 0; 01646 /** @copybrief getInitialStepSize @see getInitialStepSize */ 01647 CV_WRAP virtual void setInitialStepSize(float InitialStepSize) = 0; 01648 01649 /** @brief Parameter stepDecreasingPower of a %SVMSGD optimization problem. */ 01650 /** @see setStepDecreasingPower */ 01651 CV_WRAP virtual float getStepDecreasingPower() const = 0; 01652 /** @copybrief getStepDecreasingPower @see getStepDecreasingPower */ 01653 CV_WRAP virtual void setStepDecreasingPower(float stepDecreasingPower) = 0; 01654 01655 /** @brief Termination criteria of the training algorithm. 01656 You can specify the maximum number of iterations (maxCount) and/or how much the error could 01657 change between the iterations to make the algorithm continue (epsilon).*/ 01658 /** @see setTermCriteria */ 01659 CV_WRAP virtual TermCriteria getTermCriteria() const = 0; 01660 /** @copybrief getTermCriteria @see getTermCriteria */ 01661 CV_WRAP virtual void setTermCriteria(const cv::TermCriteria &val) = 0; 01662 }; 01663 01664 01665 /****************************************************************************************\ 01666 * Auxilary functions declarations * 01667 \****************************************************************************************/ 01668 01669 /** @brief Generates _sample_ from multivariate normal distribution 01670 01671 @param mean an average row vector 01672 @param cov symmetric covariation matrix 01673 @param nsamples returned samples count 01674 @param samples returned samples array 01675 */ 01676 CV_EXPORTS void randMVNormal( InputArray mean, InputArray cov, int nsamples, OutputArray samples); 01677 01678 /** @brief Creates test set */ 01679 CV_EXPORTS void createConcentricSpheresTestSet( int nsamples, int nfeatures, int nclasses, 01680 OutputArray samples, OutputArray responses); 01681 01682 //! @} ml 01683 01684 } 01685 } 01686 01687 #endif // __cplusplus 01688 #endif // OPENCV_ML_HPP 01689 01690 /* End of file. */
Generated on Tue Jul 12 2022 18:20:18 by
1.7.2