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