opencv/src/ml/_ml.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 //
  12 // Copyright (C) 2000, Intel Corporation, all rights reserved.
  13 // Third party copyrights are property of their respective owners.
  14 //
  15 // Redistribution and use in source and binary forms, with or without modification,
  16 // are permitted provided that the following conditions are met:
  17 //
  18 //   * Redistribution's of source code must retain the above copyright notice,
  19 //     this list of conditions and the following disclaimer.
  20 //
  21 //   * Redistribution's in binary form must reproduce the above copyright notice,
  22 //     this list of conditions and the following disclaimer in the documentation
  23 //     and/or other materials provided with the distribution.
  24 //
  25 //   * The name of Intel Corporation may not be used to endorse or promote products
  26 //     derived from this software without specific prior written permission.
  27 //
  28 // This software is provided by the copyright holders and contributors "as is" and
  29 // any express or implied warranties, including, but not limited to, the implied
  30 // warranties of merchantability and fitness for a particular purpose are disclaimed.
  31 // In no event shall the Intel Corporation or contributors be liable for any direct,
  32 // indirect, incidental, special, exemplary, or consequential damages
  33 // (including, but not limited to, procurement of substitute goods or services;
  34 // loss of use, data, or profits; or business interruption) however caused
  35 // and on any theory of liability, whether in contract, strict liability,
  36 // or tort (including negligence or otherwise) arising in any way out of
  37 // the use of this software, even if advised of the possibility of such damage.
  38 //
  39 //M*/
  40
  41 #ifndef __ML_INTERNAL_H__
  42 #define __ML_INTERNAL_H__
  43
  44 #if _MSC_VER >= 1200
  45 #pragma warning( disable: 4251 4514 4710 4711 4710 )
  46 #endif
  47
  48 #include "ml.h"
  49 #include "cxmisc.h"
  50
  51 #include <assert.h>
  52 #include <float.h>
  53 #include <limits.h>
  54 #include <math.h>
  55 #include <stdlib.h>
  56 #include <stdio.h>
  57 #include <string.h>
  58 #include <time.h>
  59 #include "cvinternal.h"
  60
  61 #define ML_IMPL CV_IMPL
  62
  63 #define CV_MAT_ELEM_FLAG( mat, type, comp, vect, tflag )    \
  64     (( tflag == CV_ROW_SAMPLE )                             \
  65     ? (CV_MAT_ELEM( mat, type, comp, vect ))                \
  66     : (CV_MAT_ELEM( mat, type, vect, comp )))
  67
  68 /* Convert matrix to vector */
  69 #define ICV_MAT2VEC( mat, vdata, vstep, num )      \
  70     if( MIN( (mat).rows, (mat).cols ) != 1 )       \
  71         CV_ERROR( CV_StsBadArg, "" );              \
  72     (vdata) = ((mat).data.ptr);                    \
  73     if( (mat).rows == 1 )                          \
  74     {                                              \
  75         (vstep) = CV_ELEM_SIZE( (mat).type );      \
  76         (num) = (mat).cols;                        \
  77     }                                              \
  78     else                                           \
  79     {                                              \
  80         (vstep) = (mat).step;                      \
  81         (num) = (mat).rows;                        \
  82     }
  83
  84 /* get raw data */
  85 #define ICV_RAWDATA( mat, flags, rdata, sstep, cstep, m, n )         \
  86     (rdata) = (mat).data.ptr;                                        \
  87     if( CV_IS_ROW_SAMPLE( flags ) )                                  \
  88     {                                                                \
  89         (sstep) = (mat).step;                                        \
  90         (cstep) = CV_ELEM_SIZE( (mat).type );                        \
  91         (m) = (mat).rows;                                            \
  92         (n) = (mat).cols;                                            \
  93     }                                                                \
  94     else                                                             \
  95     {                                                                \
  96         (cstep) = (mat).step;                                        \
  97         (sstep) = CV_ELEM_SIZE( (mat).type );                        \
  98         (n) = (mat).rows;                                            \
  99         (m) = (mat).cols;                                            \
 100     }
 101
 102 #define ICV_IS_MAT_OF_TYPE( mat, mat_type) \
 103     (CV_IS_MAT( mat ) && CV_MAT_TYPE( mat->type ) == (mat_type) &&   \
 104     (mat)->cols > 0 && (mat)->rows > 0)
 105
 106 /*
 107     uchar* data; int sstep, cstep;      - trainData->data
 108     uchar* classes; int clstep; int ncl;- trainClasses
 109     uchar* tmask; int tmstep; int ntm;  - typeMask
 110     uchar* missed;int msstep, mcstep;   -missedMeasurements...
 111     int mm, mn;                         == m,n == size,dim
 112     uchar* sidx;int sistep;             - sampleIdx
 113     uchar* cidx;int cistep;             - compIdx
 114     int k, l;                           == n,m == dim,size (length of cidx, sidx)
 115     int m, n;                           == size,dim
 116 */
 117 #define ICV_DECLARE_TRAIN_ARGS()                                                    \
 118     uchar* data;                                                                    \
 119     int sstep, cstep;                                                               \
 120     uchar* classes;                                                                 \
 121     int clstep;                                                                     \
 122     int ncl;                                                                        \
 123     uchar* tmask;                                                                   \
 124     int tmstep;                                                                     \
 125     int ntm;                                                                        \
 126     uchar* missed;                                                                  \
 127     int msstep, mcstep;                                                             \
 128     int mm, mn;                                                                     \
 129     uchar* sidx;                                                                    \
 130     int sistep;                                                                     \
 131     uchar* cidx;                                                                    \
 132     int cistep;                                                                     \
 133     int k, l;                                                                       \
 134     int m, n;                                                                       \
 135                                                                                     \
 136     data = classes = tmask = missed = sidx = cidx = NULL;                           \
 137     sstep = cstep = clstep = ncl = tmstep = ntm = msstep = mcstep = mm = mn = 0;    \
 138     sistep = cistep = k = l = m = n = 0;
 139
 140 #define ICV_TRAIN_DATA_REQUIRED( param, flags )                                     \
 141     if( !ICV_IS_MAT_OF_TYPE( (param), CV_32FC1 ) )                                  \
 142     {                                                                               \
 143         CV_ERROR( CV_StsBadArg, "Invalid " #param " parameter" );                   \
 144     }                                                                               \
 145     else                                                                            \
 146     {                                                                               \
 147         ICV_RAWDATA( *(param), (flags), data, sstep, cstep, m, n );                 \
 148         k = n;                                                                      \
 149         l = m;                                                                      \
 150     }
 151
 152 #define ICV_TRAIN_CLASSES_REQUIRED( param )                                         \
 153     if( !ICV_IS_MAT_OF_TYPE( (param), CV_32FC1 ) )                                  \
 154     {                                                                               \
 155         CV_ERROR( CV_StsBadArg, "Invalid " #param " parameter" );                   \
 156     }                                                                               \
 157     else                                                                            \
 158     {                                                                               \
 159         ICV_MAT2VEC( *(param), classes, clstep, ncl );                              \
 160         if( m != ncl )                                                              \
 161         {                                                                           \
 162             CV_ERROR( CV_StsBadArg, "Unmatched sizes" );                            \
 163         }                                                                           \
 164     }
 165
 166 #define ICV_ARG_NULL( param )                                                       \
 167     if( (param) != NULL )                                                           \
 168     {                                                                               \
 169         CV_ERROR( CV_StsBadArg, #param " parameter must be NULL" );                 \
 170     }
 171
 172 #define ICV_MISSED_MEASUREMENTS_OPTIONAL( param, flags )                            \
 173     if( param )                                                                     \
 174     {                                                                               \
 175         if( !ICV_IS_MAT_OF_TYPE( param, CV_8UC1 ) )                                 \
 176         {                                                                           \
 177             CV_ERROR( CV_StsBadArg, "Invalid " #param " parameter" );               \
 178         }                                                                           \
 179         else                                                                        \
 180         {                                                                           \
 181             ICV_RAWDATA( *(param), (flags), missed, msstep, mcstep, mm, mn );       \
 182             if( mm != m || mn != n )                                                \
 183             {                                                                       \
 184                 CV_ERROR( CV_StsBadArg, "Unmatched sizes" );                        \
 185             }                                                                       \
 186         }                                                                           \
 187     }
 188
 189 #define ICV_COMP_IDX_OPTIONAL( param )                                              \
 190     if( param )                                                                     \
 191     {                                                                               \
 192         if( !ICV_IS_MAT_OF_TYPE( param, CV_32SC1 ) )                                \
 193         {                                                                           \
 194             CV_ERROR( CV_StsBadArg, "Invalid " #param " parameter" );               \
 195         }                                                                           \
 196         else                                                                        \
 197         {                                                                           \
 198             ICV_MAT2VEC( *(param), cidx, cistep, k );                               \
 199             if( k > n )                                                             \
 200                 CV_ERROR( CV_StsBadArg, "Invalid " #param " parameter" );           \
 201         }                                                                           \
 202     }
 203
 204 #define ICV_SAMPLE_IDX_OPTIONAL( param )                                            \
 205     if( param )                                                                     \
 206     {                                                                               \
 207         if( !ICV_IS_MAT_OF_TYPE( param, CV_32SC1 ) )                                \
 208         {                                                                           \
 209             CV_ERROR( CV_StsBadArg, "Invalid " #param " parameter" );               \
 210         }                                                                           \
 211         else                                                                        \
 212         {                                                                           \
 213             ICV_MAT2VEC( *sampleIdx, sidx, sistep, l );                             \
 214             if( l > m )                                                             \
 215                 CV_ERROR( CV_StsBadArg, "Invalid " #param " parameter" );           \
 216         }                                                                           \
 217     }
 218
 219 /****************************************************************************************/
 220 #define ICV_CONVERT_FLOAT_ARRAY_TO_MATRICE( array, matrice )        \
 221 {                                                                   \
 222     CvMat a, b;                                                     \
 223     int dims = (matrice)->cols;                                     \
 224     int nsamples = (matrice)->rows;                                 \
 225     int type = CV_MAT_TYPE((matrice)->type);                        \
 226     int i, offset = dims;                                           \
 227                                                                     \
 228     CV_ASSERT( type == CV_32FC1 || type == CV_64FC1 );              \
 229     offset *= ((type == CV_32FC1) ? sizeof(float) : sizeof(double));\
 230                                                                     \
 231     b = cvMat( 1, dims, CV_32FC1 );                                 \
 232     cvGetRow( matrice, &a, 0 );                                     \
 233     for( i = 0; i < nsamples; i++, a.data.ptr += offset )           \
 234     {                                                               \
 235         b.data.fl = (float*)array[i];                               \
 236         CV_CALL( cvConvert( &b, &a ) );                             \
 237     }                                                               \
 238 }
 239
 240 /****************************************************************************************\
 241 *                       Auxiliary functions declarations                                 *
 242 \****************************************************************************************/
 243
 244 /* Generates a set of classes centers in quantity <num_of_clusters> that are generated as
 245    uniform random vectors in parallelepiped, where <data> is concentrated. Vectors in
 246    <data> should have horizontal orientation. If <centers> != NULL, the function doesn't
 247    allocate any memory and stores generated centers in <centers>, returns <centers>.
 248    If <centers> == NULL, the function allocates memory and creates the matrice. Centers
 249    are supposed to be oriented horizontally. */
 250 CvMat* icvGenerateRandomClusterCenters( int seed,
 251                                         const CvMat* data,
 252                                         int num_of_clusters,
 253                                         CvMat* centers CV_DEFAULT(0));
 254
 255 /* Fills the <labels> using <probs> by choosing the maximal probability. Outliers are
 256    fixed by <oulier_tresh> and have cluster label (-1). Function also controls that there
 257    weren't "empty" clusters by filling empty clusters with the maximal probability vector.
 258    If probs_sums != NULL, filles it with the sums of probabilities for each sample (it is
 259    useful for normalizing probabilities' matrice of FCM) */
 260 void icvFindClusterLabels( const CvMat* probs, float outlier_thresh, float r,
 261                            const CvMat* labels );
 262
 263 typedef struct CvSparseVecElem32f
 264 {
 265     int idx;
 266     float val;
 267 }
 268 CvSparseVecElem32f;
 269
 270 /* Prepare training data and related parameters */
 271 #define CV_TRAIN_STATMODEL_DEFRAGMENT_TRAIN_DATA    1
 272 #define CV_TRAIN_STATMODEL_SAMPLES_AS_ROWS          2
 273 #define CV_TRAIN_STATMODEL_SAMPLES_AS_COLUMNS       4
 274 #define CV_TRAIN_STATMODEL_CATEGORICAL_RESPONSE     8
 275 #define CV_TRAIN_STATMODEL_ORDERED_RESPONSE         16
 276 #define CV_TRAIN_STATMODEL_RESPONSES_ON_OUTPUT      32
 277 #define CV_TRAIN_STATMODEL_ALWAYS_COPY_TRAIN_DATA   64
 278 #define CV_TRAIN_STATMODEL_SPARSE_AS_SPARSE         128
 279
 280 int
 281 cvPrepareTrainData( const char* /*funcname*/,
 282                     const CvMat* train_data, int tflag,
 283                     const CvMat* responses, int response_type,
 284                     const CvMat* var_idx,
 285                     const CvMat* sample_idx,
 286                     bool always_copy_data,
 287                     const float*** out_train_samples,
 288                     int* _sample_count,
 289                     int* _var_count,
 290                     int* _var_all,
 291                     CvMat** out_responses,
 292                     CvMat** out_response_map,
 293                     CvMat** out_var_idx,
 294                     CvMat** out_sample_idx=0 );
 295
 296 void
 297 cvSortSamplesByClasses( const float** samples, const CvMat* classes,
 298                         int* class_ranges, const uchar** mask CV_DEFAULT(0) );
 299
 300 void
 301 cvCombineResponseMaps (CvMat*  _responses,
 302                  const CvMat*  old_response_map,
 303                        CvMat*  new_response_map,
 304                        CvMat** out_response_map);
 305
 306 void
 307 cvPreparePredictData( const CvArr* sample, int dims_all, const CvMat* comp_idx,
 308                       int class_count, const CvMat* prob, float** row_sample,
 309                       int as_sparse CV_DEFAULT(0) );
 310
 311 /* copies clustering [or batch "predict"] results
 312    (labels and/or centers and/or probs) back to the output arrays */
 313 void
 314 cvWritebackLabels( const CvMat* labels, CvMat* dst_labels,
 315                    const CvMat* centers, CvMat* dst_centers,
 316                    const CvMat* probs, CvMat* dst_probs,
 317                    const CvMat* sample_idx, int samples_all,
 318                    const CvMat* comp_idx, int dims_all );
 319 #define cvWritebackResponses cvWritebackLabels
 320
 321 #define XML_FIELD_NAME "_name"
 322 CvFileNode* icvFileNodeGetChild(CvFileNode* father, const char* name);
 323 CvFileNode* icvFileNodeGetChildArrayElem(CvFileNode* father, const char* name,int index);
 324 CvFileNode* icvFileNodeGetNext(CvFileNode* n, const char* name);
 325
 326
 327 void cvCheckTrainData( const CvMat* train_data, int tflag,
 328                        const CvMat* missing_mask,
 329                        int* var_all, int* sample_all );
 330
 331 CvMat* cvPreprocessIndexArray( const CvMat* idx_arr, int data_arr_size, bool check_for_duplicates=false );
 332
 333 CvMat* cvPreprocessVarType( const CvMat* type_mask, const CvMat* var_idx,
 334                             int var_all, int* response_type );
 335
 336 CvMat* cvPreprocessOrderedResponses( const CvMat* responses,
 337                 const CvMat* sample_idx, int sample_all );
 338
 339 CvMat* cvPreprocessCategoricalResponses( const CvMat* responses,
 340                 const CvMat* sample_idx, int sample_all,
 341                 CvMat** out_response_map, CvMat** class_counts=0 );
 342
 343 const float** cvGetTrainSamples( const CvMat* train_data, int tflag,
 344                    const CvMat* var_idx, const CvMat* sample_idx,
 345                    int* _var_count, int* _sample_count,
 346                    bool always_copy_data=false );
 347
 348 #endif /* __ML_H__ */