git.maemo.org Git - opencv/blob - apps/haartraining/src/cvclassifier.h

   1 /*M///////////////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
   4 //
   5 //  By downloading, copying, installing or using the software you agree to this license.
   6 //  If you do not agree to this license, do not download, install,
   7 //  copy or use the software.
   8 //
   9 //
  10 //                        Intel License Agreement
  11 //                For Open Source Computer Vision Library
  12 //
  13 // Copyright (C) 2000, Intel Corporation, all rights reserved.
  14 // Third party copyrights are property of their respective owners.
  15 //
  16 // Redistribution and use in source and binary forms, with or without modification,
  17 // are permitted provided that the following conditions are met:
  18 //
  19 //   * Redistribution's of source code must retain the above copyright notice,
  20 //     this list of conditions and the following disclaimer.
  21 //
  22 //   * Redistribution's in binary form must reproduce the above copyright notice,
  23 //     this list of conditions and the following disclaimer in the documentation
  24 //     and/or other materials provided with the distribution.
  25 //
  26 //   * The name of Intel Corporation may not be used to endorse or promote products
  27 //     derived from this software without specific prior written permission.
  28 //
  29 // This software is provided by the copyright holders and contributors "as is" and
  30 // any express or implied warranties, including, but not limited to, the implied
  31 // warranties of merchantability and fitness for a particular purpose are disclaimed.
  32 // In no event shall the Intel Corporation or contributors be liable for any direct,
  33 // indirect, incidental, special, exemplary, or consequential damages
  34 // (including, but not limited to, procurement of substitute goods or services;
  35 // loss of use, data, or profits; or business interruption) however caused
  36 // and on any theory of liability, whether in contract, strict liability,
  37 // or tort (including negligence or otherwise) arising in any way out of
  38 // the use of this software, even if advised of the possibility of such damage.
  39 //
  40 //M*/
  41
  42 /*
  43  * File cvclassifier.h
  44  *
  45  * Classifier types
  46  */
  47
  48 #ifndef _CVCLASSIFIER_H_
  49 #define _CVCLASSIFIER_H_
  50
  51 #include <cxcore.h>
  52 #include <math.h>
  53
  54 #define CV_BOOST_API
  55
  56 /* Convert matrix to vector */
  57 #define CV_MAT2VEC( mat, vdata, vstep, num )       \
  58     assert( (mat).rows == 1 || (mat).cols == 1 );  \
  59     (vdata) = ((mat).data.ptr);                    \
  60     if( (mat).rows == 1 )                          \
  61     {                                              \
  62         (vstep) = CV_ELEM_SIZE( (mat).type );      \
  63         (num) = (mat).cols;                        \
  64     }                                              \
  65     else                                           \
  66     {                                              \
  67         (vstep) = (mat).step;                      \
  68         (num) = (mat).rows;                        \
  69     }
  70
  71 /* Set up <sample> matrix header to be <num> sample of <trainData> samples matrix */
  72 #define CV_GET_SAMPLE( trainData, tdflags, num, sample )                                 \
  73 if( CV_IS_ROW_SAMPLE( tdflags ) )                                                        \
  74 {                                                                                        \
  75     cvInitMatHeader( &(sample), 1, (trainData).cols,                                     \
  76                      CV_MAT_TYPE( (trainData).type ),                                    \
  77                      ((trainData).data.ptr + (num) * (trainData).step),                  \
  78                      (trainData).step );                                                 \
  79 }                                                                                        \
  80 else                                                                                     \
  81 {                                                                                        \
  82     cvInitMatHeader( &(sample), (trainData).rows, 1,                                     \
  83                      CV_MAT_TYPE( (trainData).type ),                                    \
  84                      ((trainData).data.ptr + (num) * CV_ELEM_SIZE( (trainData).type )),  \
  85                      (trainData).step );                                                 \
  86 }
  87
  88 #define CV_GET_SAMPLE_STEP( trainData, tdflags, sstep )                                  \
  89 (sstep) = ( ( CV_IS_ROW_SAMPLE( tdflags ) )                                              \
  90            ? (trainData).step : CV_ELEM_SIZE( (trainData).type ) );
  91
  92
  93 #define CV_LOGRATIO_THRESHOLD 0.00001F
  94
  95 /* log( val / (1 - val ) ) */
  96 CV_INLINE float cvLogRatio( float val );
  97
  98 CV_INLINE float cvLogRatio( float val )
  99 {
 100     float tval;
 101
 102     tval = MAX(CV_LOGRATIO_THRESHOLD, MIN( 1.0F - CV_LOGRATIO_THRESHOLD, (val) ));
 103     return logf( tval / (1.0F - tval) );
 104 }
 105
 106
 107 /* flags values for classifier consturctor flags parameter */
 108
 109 /* each trainData matrix column is a sample */
 110 #define CV_COL_SAMPLE 0
 111
 112 /* each trainData matrix row is a sample */
 113 #define CV_ROW_SAMPLE 1
 114
 115 #define CV_IS_ROW_SAMPLE( flags ) ( ( flags ) & CV_ROW_SAMPLE )
 116
 117 /* Classifier supports tune function */
 118 #define CV_TUNABLE    (1 << 1)
 119
 120 #define CV_IS_TUNABLE( flags ) ( (flags) & CV_TUNABLE )
 121
 122
 123 /* classifier fields common to all classifiers */
 124 #define CV_CLASSIFIER_FIELDS()                                                           \
 125     int flags;                                                                           \
 126     float(*eval)( struct CvClassifier*, CvMat* );                                        \
 127     void (*tune)( struct CvClassifier*, CvMat*, int flags, CvMat*, CvMat*, CvMat*,       \
 128                   CvMat*, CvMat* );                                                      \
 129     int  (*save)( struct CvClassifier*, const char* file_name );                         \
 130     void (*release)( struct CvClassifier** );
 131
 132 typedef struct CvClassifier
 133 {
 134     CV_CLASSIFIER_FIELDS()
 135 } CvClassifier;
 136
 137 #define CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
 138 typedef struct CvClassifierTrainParams
 139 {
 140     CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
 141 } CvClassifierTrainParams;
 142
 143
 144 /*
 145  Common classifier constructor:
 146  CvClassifier* cvCreateMyClassifier( CvMat* trainData,
 147                      int flags,
 148                      CvMat* trainClasses,
 149                      CvMat* typeMask,
 150                       CvMat* missedMeasurementsMask CV_DEFAULT(0),
 151                       CvCompIdx* compIdx CV_DEFAULT(0),
 152                       CvMat* sampleIdx CV_DEFAULT(0),
 153                       CvMat* weights CV_DEFAULT(0),
 154                       CvClassifierTrainParams* trainParams CV_DEFAULT(0)
 155                     )
 156
 157  */
 158
 159 typedef CvClassifier* (*CvClassifierConstructor)( CvMat*, int, CvMat*, CvMat*, CvMat*,
 160                                                   CvMat*, CvMat*, CvMat*,
 161                                                   CvClassifierTrainParams* );
 162
 163 typedef enum CvStumpType
 164 {
 165     CV_CLASSIFICATION       = 0,
 166     CV_CLASSIFICATION_CLASS = 1,
 167     CV_REGRESSION           = 2
 168 } CvStumpType;
 169
 170 typedef enum CvStumpError
 171 {
 172     CV_MISCLASSIFICATION = 0,
 173     CV_GINI              = 1,
 174     CV_ENTROPY           = 2,
 175     CV_SQUARE            = 3
 176 } CvStumpError;
 177
 178
 179 typedef struct CvStumpTrainParams
 180 {
 181     CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
 182     CvStumpType  type;
 183     CvStumpError error;
 184 } CvStumpTrainParams;
 185
 186 typedef struct CvMTStumpTrainParams
 187 {
 188     CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
 189     CvStumpType  type;
 190     CvStumpError error;
 191     int portion; /* number of components calculated in each thread */
 192     int numcomp; /* total number of components */
 193
 194     /* callback which fills <mat> with components [first, first+num[ */
 195     void (*getTrainData)( CvMat* mat, CvMat* sampleIdx, CvMat* compIdx,
 196                           int first, int num, void* userdata );
 197     CvMat* sortedIdx; /* presorted samples indices */
 198     void* userdata; /* passed to callback */
 199 } CvMTStumpTrainParams;
 200
 201 typedef struct CvStumpClassifier
 202 {
 203     CV_CLASSIFIER_FIELDS()
 204     int compidx;
 205
 206     float lerror; /* impurity of the right node */
 207     float rerror; /* impurity of the left  node */
 208
 209     float threshold;
 210     float left;
 211     float right;
 212 } CvStumpClassifier;
 213
 214 typedef struct CvCARTTrainParams
 215 {
 216     CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
 217     /* desired number of internal nodes */
 218     int count;
 219     CvClassifierTrainParams* stumpTrainParams;
 220     CvClassifierConstructor  stumpConstructor;
 221
 222     /*
 223      * Split sample indices <idx>
 224      * on the "left" indices <left> and "right" indices <right>
 225      * according to samples components <compidx> values and <threshold>.
 226      *
 227      * NOTE: Matrices <left> and <right> must be allocated using cvCreateMat function
 228      *   since they are freed using cvReleaseMat function
 229      *
 230      * If it is NULL then the default implementation which evaluates training
 231      * samples from <trainData> passed to classifier constructor is used
 232      */
 233     void (*splitIdx)( int compidx, float threshold,
 234                       CvMat* idx, CvMat** left, CvMat** right,
 235                       void* userdata );
 236     void* userdata;
 237 } CvCARTTrainParams;
 238
 239 typedef struct CvCARTClassifier
 240 {
 241     CV_CLASSIFIER_FIELDS()
 242     /* number of internal nodes */
 243     int count;
 244
 245     /* internal nodes (each array of <count> elements) */
 246     int* compidx;
 247     float* threshold;
 248     int* left;
 249     int* right;
 250
 251     /* leaves (array of <count>+1 elements) */
 252     float* val;
 253 } CvCARTClassifier;
 254
 255 CV_BOOST_API
 256 void cvGetSortedIndices( CvMat* val, CvMat* idx, int sortcols CV_DEFAULT( 0 ) );
 257
 258 CV_BOOST_API
 259 void cvReleaseStumpClassifier( CvClassifier** classifier );
 260
 261 CV_BOOST_API
 262 float cvEvalStumpClassifier( CvClassifier* classifier, CvMat* sample );
 263
 264 CV_BOOST_API
 265 CvClassifier* cvCreateStumpClassifier( CvMat* trainData,
 266                                        int flags,
 267                                        CvMat* trainClasses,
 268                                        CvMat* typeMask,
 269                                        CvMat* missedMeasurementsMask CV_DEFAULT(0),
 270                                        CvMat* compIdx CV_DEFAULT(0),
 271                                        CvMat* sampleIdx CV_DEFAULT(0),
 272                                        CvMat* weights CV_DEFAULT(0),
 273                                        CvClassifierTrainParams* trainParams CV_DEFAULT(0) );
 274
 275 /*
 276  * cvCreateMTStumpClassifier
 277  *
 278  * Multithreaded stump classifier constructor
 279  * Includes huge train data support through callback function
 280  */
 281 CV_BOOST_API
 282 CvClassifier* cvCreateMTStumpClassifier( CvMat* trainData,
 283                                          int flags,
 284                                          CvMat* trainClasses,
 285                                          CvMat* typeMask,
 286                                          CvMat* missedMeasurementsMask,
 287                                          CvMat* compIdx,
 288                                          CvMat* sampleIdx,
 289                                          CvMat* weights,
 290                                          CvClassifierTrainParams* trainParams );
 291
 292 /*
 293  * cvCreateCARTClassifier
 294  *
 295  * CART classifier constructor
 296  */
 297 CV_BOOST_API
 298 CvClassifier* cvCreateCARTClassifier( CvMat* trainData,
 299                                       int flags,
 300                                       CvMat* trainClasses,
 301                                       CvMat* typeMask,
 302                                       CvMat* missedMeasurementsMask,
 303                                       CvMat* compIdx,
 304                                       CvMat* sampleIdx,
 305                                       CvMat* weights,
 306                                       CvClassifierTrainParams* trainParams );
 307
 308 CV_BOOST_API
 309 void cvReleaseCARTClassifier( CvClassifier** classifier );
 310
 311 CV_BOOST_API
 312 float cvEvalCARTClassifier( CvClassifier* classifier, CvMat* sample );
 313
 314 /****************************************************************************************\
 315 *                                        Boosting                                        *
 316 \****************************************************************************************/
 317
 318 /*
 319  * CvBoostType
 320  *
 321  * The CvBoostType enumeration specifies the boosting type.
 322  *
 323  * Remarks
 324  *   Four different boosting variants for 2 class classification problems are supported:
 325  *   Discrete AdaBoost, Real AdaBoost, LogitBoost and Gentle AdaBoost.
 326  *   The L2 (2 class classification problems) and LK (K class classification problems)
 327  *   algorithms are close to LogitBoost but more numerically stable than last one.
 328  *   For regression three different loss functions are supported:
 329  *   Least square, least absolute deviation and huber loss.
 330  */
 331 typedef enum CvBoostType
 332 {
 333     CV_DABCLASS = 0, /* 2 class Discrete AdaBoost           */
 334     CV_RABCLASS = 1, /* 2 class Real AdaBoost               */
 335     CV_LBCLASS  = 2, /* 2 class LogitBoost                  */
 336     CV_GABCLASS = 3, /* 2 class Gentle AdaBoost             */
 337     CV_L2CLASS  = 4, /* classification (2 class problem)    */
 338     CV_LKCLASS  = 5, /* classification (K class problem)    */
 339     CV_LSREG    = 6, /* least squares regression            */
 340     CV_LADREG   = 7, /* least absolute deviation regression */
 341     CV_MREG     = 8, /* M-regression (Huber loss)           */
 342 } CvBoostType;
 343
 344 /****************************************************************************************\
 345 *                             Iterative training functions                               *
 346 \****************************************************************************************/
 347
 348 /*
 349  * CvBoostTrainer
 350  *
 351  * The CvBoostTrainer structure represents internal boosting trainer.
 352  */
 353 typedef struct CvBoostTrainer CvBoostTrainer;
 354
 355 /*
 356  * cvBoostStartTraining
 357  *
 358  * The cvBoostStartTraining function starts training process and calculates
 359  * response values and weights for the first weak classifier training.
 360  *
 361  * Parameters
 362  *   trainClasses
 363  *     Vector of classes of training samples classes. Each element must be 0 or 1 and
 364  *     of type CV_32FC1.
 365  *   weakTrainVals
 366  *     Vector of response values for the first trained weak classifier.
 367  *     Must be of type CV_32FC1.
 368  *   weights
 369  *     Weight vector of training samples for the first trained weak classifier.
 370  *     Must be of type CV_32FC1.
 371  *   type
 372  *     Boosting type. CV_DABCLASS, CV_RABCLASS, CV_LBCLASS, CV_GABCLASS
 373  *     types are supported.
 374  *
 375  * Return Values
 376  *   The return value is a pointer to internal trainer structure which is used
 377  *   to perform next training iterations.
 378  *
 379  * Remarks
 380  *   weakTrainVals and weights must be allocated before calling the function
 381  *   and of the same size as trainingClasses. Usually weights should be initialized
 382  *   with 1.0 value.
 383  *   The function calculates response values and weights for the first weak
 384  *   classifier training and stores them into weakTrainVals and weights
 385  *   respectively.
 386  *   Note, the training of the weak classifier using weakTrainVals, weight,
 387  *   trainingData is outside of this function.
 388  */
 389 CV_BOOST_API
 390 CvBoostTrainer* cvBoostStartTraining( CvMat* trainClasses,
 391                                       CvMat* weakTrainVals,
 392                                       CvMat* weights,
 393                                       CvMat* sampleIdx,
 394                                       CvBoostType type );
 395 /*
 396  * cvBoostNextWeakClassifier
 397  *
 398  * The cvBoostNextWeakClassifier function performs next training
 399  * iteration and caluclates response values and weights for the next weak
 400  * classifier training.
 401  *
 402  * Parameters
 403  *   weakEvalVals
 404  *     Vector of values obtained by evaluation of each sample with
 405  *     the last trained weak classifier (iteration i). Must be of CV_32FC1 type.
 406  *   trainClasses
 407  *     Vector of classes of training samples. Each element must be 0 or 1,
 408  *     and of type CV_32FC1.
 409  *   weakTrainVals
 410  *     Vector of response values for the next weak classifier training
 411  *     (iteration i+1). Must be of type CV_32FC1.
 412  *   weights
 413  *     Weight vector of training samples for the next weak classifier training
 414  *     (iteration i+1). Must be of type CV_32FC1.
 415  *   trainer
 416  *     A pointer to internal trainer returned by the cvBoostStartTraining
 417  *     function call.
 418  *
 419  * Return Values
 420  *   The return value is the coefficient for the last trained weak classifier.
 421  *
 422  * Remarks
 423  *   weakTrainVals and weights must be exactly the same vectors as used in
 424  *   the cvBoostStartTraining function call and should not be modified.
 425  *   The function calculates response values and weights for the next weak
 426  *   classifier training and stores them into weakTrainVals and weights
 427  *   respectively.
 428  *   Note, the training of the weak classifier of iteration i+1 using
 429  *   weakTrainVals, weight, trainingData is outside of this function.
 430  */
 431 CV_BOOST_API
 432 float cvBoostNextWeakClassifier( CvMat* weakEvalVals,
 433                                  CvMat* trainClasses,
 434                                  CvMat* weakTrainVals,
 435                                  CvMat* weights,
 436                                  CvBoostTrainer* trainer );
 437
 438 /*
 439  * cvBoostEndTraining
 440  *
 441  * The cvBoostEndTraining function finishes training process and releases
 442  * internally allocated memory.
 443  *
 444  * Parameters
 445  *   trainer
 446  *     A pointer to a pointer to internal trainer returned by the cvBoostStartTraining
 447  *     function call.
 448  */
 449 CV_BOOST_API
 450 void cvBoostEndTraining( CvBoostTrainer** trainer );
 451
 452 /****************************************************************************************\
 453 *                                    Boosted tree models                                 *
 454 \****************************************************************************************/
 455
 456 /*
 457  * CvBtClassifier
 458  *
 459  * The CvBtClassifier structure represents boosted tree model.
 460  *
 461  * Members
 462  *   flags
 463  *     Flags. If CV_IS_TUNABLE( flags ) != 0 then the model supports tuning.
 464  *   eval
 465  *     Evaluation function. Returns sample predicted class (0, 1, etc.)
 466  *     for classification or predicted value for regression.
 467  *   tune
 468  *     Tune function. If the model supports tuning then tune call performs
 469  *     one more boosting iteration if passed to the function flags parameter
 470  *     is CV_TUNABLE otherwise releases internally allocated for tuning memory
 471  *     and makes the model untunable.
 472  *     NOTE: Since tuning uses the pointers to parameters,
 473  *     passed to the cvCreateBtClassifier function, they should not be modified
 474  *     or released between tune calls.
 475  *   save
 476  *     This function stores the model into given file.
 477  *   release
 478  *     This function releases the model.
 479  *   type
 480  *     Boosted tree model type.
 481  *   numclasses
 482  *     Number of classes for CV_LKCLASS type or 1 for all other types.
 483  *   numiter
 484  *     Number of iterations. Number of weak classifiers is equal to number
 485  *     of iterations for all types except CV_LKCLASS. For CV_LKCLASS type
 486  *     number of weak classifiers is (numiter * numclasses).
 487  *   numfeatures
 488  *     Number of features in sample.
 489  *   trees
 490  *     Stores weak classifiers when the model does not support tuning.
 491  *   seq
 492  *     Stores weak classifiers when the model supports tuning.
 493  *   trainer
 494  *     Pointer to internal tuning parameters if the model supports tuning.
 495  */
 496 typedef struct CvBtClassifier
 497 {
 498     CV_CLASSIFIER_FIELDS()
 499
 500     CvBoostType type;
 501     int numclasses;
 502     int numiter;
 503     int numfeatures;
 504     union
 505     {
 506         CvCARTClassifier** trees;
 507         CvSeq* seq;
 508     };
 509     void* trainer;
 510 } CvBtClassifier;
 511
 512 /*
 513  * CvBtClassifierTrainParams
 514  *
 515  * The CvBtClassifierTrainParams structure stores training parameters for
 516  * boosted tree model.
 517  *
 518  * Members
 519  *   type
 520  *     Boosted tree model type.
 521  *   numiter
 522  *     Desired number of iterations.
 523  *   param
 524  *     Parameter   Model Type    Parameter Meaning
 525  *     param[0]    Any           Shrinkage factor
 526  *     param[1]    CV_MREG       alpha. (1-alpha) determines "break-down" point of
 527  *                               the training procedure, i.e. the fraction of samples
 528  *                               that can be arbitrary modified without serious
 529  *                               degrading the quality of the result.
 530  *                 CV_DABCLASS,  Weight trimming factor.
 531  *                 CV_RABCLASS,
 532  *                 CV_LBCLASS,
 533  *                 CV_GABCLASS,
 534  *                 CV_L2CLASS,
 535  *                 CV_LKCLASS
 536  *   numsplits
 537  *     Desired number of splits in each tree.
 538  */
 539 typedef struct CvBtClassifierTrainParams
 540 {
 541     CV_CLASSIFIER_TRAIN_PARAM_FIELDS()
 542
 543     CvBoostType type;
 544     int numiter;
 545     float param[2];
 546     int numsplits;
 547 } CvBtClassifierTrainParams;
 548
 549 /*
 550  * cvCreateBtClassifier
 551  *
 552  * The cvCreateBtClassifier function creates boosted tree model.
 553  *
 554  * Parameters
 555  *   trainData
 556  *     Matrix of feature values. Must have CV_32FC1 type.
 557  *   flags
 558  *     Determines how samples are stored in trainData.
 559  *     One of CV_ROW_SAMPLE or CV_COL_SAMPLE.
 560  *     Optionally may be combined with CV_TUNABLE to make tunable model.
 561  *   trainClasses
 562  *     Vector of responses for regression or classes (0, 1, 2, etc.) for classification.
 563  *   typeMask,
 564  *   missedMeasurementsMask,
 565  *   compIdx
 566  *     Not supported. Must be NULL.
 567  *   sampleIdx
 568  *     Indices of samples used in training. If NULL then all samples are used.
 569  *     For CV_DABCLASS, CV_RABCLASS, CV_LBCLASS and CV_GABCLASS must be NULL.
 570  *   weights
 571  *     Not supported. Must be NULL.
 572  *   trainParams
 573  *     A pointer to CvBtClassifierTrainParams structure. Training parameters.
 574  *     See CvBtClassifierTrainParams description for details.
 575  *
 576  * Return Values
 577  *   The return value is a pointer to created boosted tree model of type CvBtClassifier.
 578  *
 579  * Remarks
 580  *     The function performs trainParams->numiter training iterations.
 581  *     If CV_TUNABLE flag is specified then created model supports tuning.
 582  *     In this case additional training iterations may be performed by
 583  *     tune function call.
 584  */
 585 CV_BOOST_API
 586 CvClassifier* cvCreateBtClassifier( CvMat* trainData,
 587                                     int flags,
 588                                     CvMat* trainClasses,
 589                                     CvMat* typeMask,
 590                                     CvMat* missedMeasurementsMask,
 591                                     CvMat* compIdx,
 592                                     CvMat* sampleIdx,
 593                                     CvMat* weights,
 594                                     CvClassifierTrainParams* trainParams );
 595
 596 /*
 597  * cvCreateBtClassifierFromFile
 598  *
 599  * The cvCreateBtClassifierFromFile function restores previously saved
 600  * boosted tree model from file.
 601  *
 602  * Parameters
 603  *   filename
 604  *     The name of the file with boosted tree model.
 605  *
 606  * Remarks
 607  *   The restored model does not support tuning.
 608  */
 609 CV_BOOST_API
 610 CvClassifier* cvCreateBtClassifierFromFile( const char* filename );
 611
 612 /****************************************************************************************\
 613 *                                    Utility functions                                   *
 614 \****************************************************************************************/
 615
 616 /*
 617  * cvTrimWeights
 618  *
 619  * The cvTrimWeights function performs weight trimming.
 620  *
 621  * Parameters
 622  *   weights
 623  *     Weights vector.
 624  *   idx
 625  *     Indices vector of weights that should be considered.
 626  *     If it is NULL then all weights are used.
 627  *   factor
 628  *     Weight trimming factor. Must be in [0, 1] range.
 629  *
 630  * Return Values
 631  *   The return value is a vector of indices. If all samples should be used then
 632  *   it is equal to idx. In other case the cvReleaseMat function should be called
 633  *   to release it.
 634  *
 635  * Remarks
 636  */
 637 CV_BOOST_API
 638 CvMat* cvTrimWeights( CvMat* weights, CvMat* idx, float factor );
 639
 640 /*
 641  * cvReadTrainData
 642  *
 643  * The cvReadTrainData function reads feature values and responses from file.
 644  *
 645  * Parameters
 646  *   filename
 647  *     The name of the file to be read.
 648  *   flags
 649  *     One of CV_ROW_SAMPLE or CV_COL_SAMPLE. Determines how feature values
 650  *     will be stored.
 651  *   trainData
 652  *     A pointer to a pointer to created matrix with feature values.
 653  *     cvReleaseMat function should be used to destroy created matrix.
 654  *   trainClasses
 655  *     A pointer to a pointer to created matrix with response values.
 656  *     cvReleaseMat function should be used to destroy created matrix.
 657  *
 658  * Remarks
 659  *   File format:
 660  *   ============================================
 661  *   m n
 662  *   value_1_1 value_1_2 ... value_1_n response_1
 663  *   value_2_1 value_2_2 ... value_2_n response_2
 664  *   ...
 665  *   value_m_1 value_m_2 ... value_m_n response_m
 666  *   ============================================
 667  *   m
 668  *     Number of samples
 669  *   n
 670  *     Number of features in each sample
 671  *   value_i_j
 672  *     Value of j-th feature of i-th sample
 673  *   response_i
 674  *     Response value of i-th sample
 675  *     For classification problems responses represent classes (0, 1, etc.)
 676  *   All values and classes are integer or real numbers.
 677  */
 678 CV_BOOST_API
 679 void cvReadTrainData( const char* filename,
 680                       int flags,
 681                       CvMat** trainData,
 682                       CvMat** trainClasses );
 683
 684
 685 /*
 686  * cvWriteTrainData
 687  *
 688  * The cvWriteTrainData function stores feature values and responses into file.
 689  *
 690  * Parameters
 691  *   filename
 692  *     The name of the file.
 693  *   flags
 694  *     One of CV_ROW_SAMPLE or CV_COL_SAMPLE. Determines how feature values
 695  *     are stored.
 696  *   trainData
 697  *     Feature values matrix.
 698  *   trainClasses
 699  *     Response values vector.
 700  *   sampleIdx
 701  *     Vector of idicies of the samples that should be stored. If it is NULL
 702  *     then all samples will be stored.
 703  *
 704  * Remarks
 705  *   See the cvReadTrainData function for file format description.
 706  */
 707 CV_BOOST_API
 708 void cvWriteTrainData( const char* filename,
 709                        int flags,
 710                        CvMat* trainData,
 711                        CvMat* trainClasses,
 712                        CvMat* sampleIdx );
 713
 714 /*
 715  * cvRandShuffle
 716  *
 717  * The cvRandShuffle function perfroms random shuffling of given vector.
 718  *
 719  * Parameters
 720  *   vector
 721  *     Vector that should be shuffled.
 722  *     Must have CV_8UC1, CV_16SC1, CV_32SC1 or CV_32FC1 type.
 723  */
 724 CV_BOOST_API
 725 void cvRandShuffleVec( CvMat* vector );
 726
 727 #endif /* _CVCLASSIFIER_H_ */