git.maemo.org Git - opencv/blob - docs/ref/opencvref_cvaux.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html><head>
   3 <link rel="STYLESHEET" href="opencvref.css" charset="ISO-8859-1" type="text/css">
   4 <title>OpenCV: Experimental and Obsolete Functionality</title>
   5 </head><body>
   6
   7 <h1>Experimental and Obsolete Functionality Reference</h1>
   8
   9 <p>
  10 The functionality resides in cvaux library. To use it in your application, place
  11 #include "cvaux.h" in your source files and:<ul>
  12 <li>In case of Win32 link the app against cvaux.lib that is import library for cvaux.dll
  13 <li>In case of Linux use -lcvaux compiler option
  14 </ul></p>
  15
  16 <hr><p><ul>
  17 <li><a href="#aux_stereo">Stereo Correspondence Functions</a>
  18 <ul>
  19 <li><a href="#decl_cvFindStereoCorrespondence">FindStereoCorrespondence</a>
  20 </ul>
  21 <li><a href="#aux_viewmorphing">View Morphing Functions</a>
  22 <ul>
  23 <li><a href="#decl_cvMakeScanlines">MakeScanlines</a>
  24 <li><a href="#decl_cvPreWarpImage">PreWarpImage</a>
  25 <li><a href="#decl_cvFindRuns">FindRuns</a>
  26 <li><a href="#decl_cvDynamicCorrespondMulti">DynamicCorrespondMulti</a>
  27 <li><a href="#decl_cvMakeAlphaScanlines">MakeAlphaScanlines</a>
  28 <li><a href="#decl_cvMorphEpilinesMulti">MorphEpilinesMulti</a>
  29 <li><a href="#decl_cvPostWarpImage">PostWarpImage</a>
  30 <li><a href="#decl_cvDeleteMoire">DeleteMoire</a>
  31 </ul>
  32 <li><a href="#aux_3dTracking">3D Tracking Functions</a>
  33 <ul>
  34 <li><a href="#decl_cv3dTrackerCalibrateCameras">3dTrackerCalibrateCameras</a>
  35 <li><a href="#decl_cv3dTrackerLocateObjects">3dTrackerLocateObjects</a>
  36 </ul>
  37 <li><a href="#aux_pca">Eigen Objects (PCA) Functions</a>
  38 <ul>
  39 <li><a href="#decl_cvCalcCovarMatrixEx">CalcCovarMatrixEx</a>
  40 <li><a href="#decl_cvCalcEigenObjects">CalcEigenObjects</a>
  41 <li><a href="#decl_cvCalcDecompCoeff">CalcDecompCoeff</a>
  42 <li><a href="#decl_cvEigenDecomposite">EigenDecomposite</a>
  43 <li><a href="#decl_cvEigenProjection">EigenProjection</a>
  44 </ul>
  45 <li><a href="#aux_hmm">Embedded Hidden Markov Models Functions</a>
  46 <ul>
  47 <li><a href="#decl_CvHMM">HMM</a>
  48 <li><a href="#decl_CvImgObsInfo">ImgObsInfo</a>
  49 <li><a href="#decl_cvCreate2DHMM">Create2DHMM</a>
  50 <li><a href="#decl_cvRelease2DHMM">Release2DHMM</a>
  51 <li><a href="#decl_cvCreateObsInfo">CreateObsInfo</a>
  52 <li><a href="#decl_cvReleaseObsInfo">ReleaseObsInfo</a>
  53 <li><a href="#decl_cvImgToObs_DCT">ImgToObs_DCT</a>
  54 <li><a href="#decl_cvUniformImgSegm">UniformImgSegm</a>
  55 <li><a href="#decl_cvInitMixSegm">InitMixSegm</a>
  56 <li><a href="#decl_cvEstimateHMMStateParams">EstimateHMMStateParams</a>
  57 <li><a href="#decl_cvEstimateTransProb">EstimateTransProb</a>
  58 <li><a href="#decl_cvEstimateObsProb">EstimateObsProb</a>
  59 <li><a href="#decl_cvEViterbi">EViterbi</a>
  60 <li><a href="#decl_cvMixSegmL2">MixSegmL2</a>
  61 </ul>
  62 </ul></p>
  63
  64 <hr><h2><a name="aux_stereo">Stereo Correspondence Functions</a></h2>
  65
  66 <hr><h3><a name="decl_cvFindStereoCorrespondence">FindStereoCorrespondence</a></h3>
  67 <p class="Blurb">Calculates disparity for stereo-pair</p>
  68 <pre>
  69 cvFindStereoCorrespondence(
  70                    const  CvArr* leftImage, const  CvArr* rightImage,
  71                    int     mode, CvArr*  depthImage,
  72                    int     maxDisparity,
  73                    double  param1, double  param2, double  param3,
  74                    double  param4, double  param5  );
  75 </pre><p><dl>
  76
  77 <dt>leftImage<dd>Left image of stereo pair, rectified grayscale 8-bit image
  78 <dt>rightImage<dd>Right image of stereo pair, rectified grayscale 8-bit image
  79 <dt>mode<dd>Algorithm used to find a disparity (now only CV_DISPARITY_BIRCHFIELD is supported)
  80 <dt>depthImage<dd>Destination depth image, grayscale 8-bit image that codes the scaled disparity,
  81                   so that the zero disparity (corresponding to the points that are very far from the cameras)
  82                   maps to 0, maximum disparity maps to 255.
  83 <dt>maxDisparity<dd>Maximum possible disparity. The closer the objects to the cameras, the larger value should be specified here.
  84                     Too big values slow down the process significantly.
  85 <dt>param1, param2, param3, param4, param5<dd> - parameters of algorithm.
  86 For example, param1 is the constant occlusion penalty,
  87 param2 is the constant match reward, param3 defines a highly reliable region
  88 (set of contiguous pixels whose reliability is at least param3),
  89 param4 defines a moderately reliable region, param5 defines a slightly reliable region.
  90 If some parameter is omitted default value is used.
  91 In Birchfield's algorithm param1 = 25,  param2 = 5, param3 = 12, param4 = 15, param5 = 25
  92 (These values have been taken from
  93 "Depth Discontinuities by Pixel-to-Pixel Stereo" Stanford University Technical Report STAN-CS-TR-96-1573, July 1996.)
  94 </dl></p><p>
  95
  96 The function <code>cvFindStereoCorrespondence</code> calculates disparity map
  97 for two rectified grayscale images.
  98
  99 <p>Example. Calculating disparity for pair of 8-bit color images</h4>
 100 <pre>
 101 /*---------------------------------------------------------------------------------*/
 102 IplImage* srcLeft = cvLoadImage("left.jpg",1);
 103 IplImage* srcRight = cvLoadImage("right.jpg",1);
 104 IplImage* leftImage = cvCreateImage(cvGetSize(srcLeft), IPL_DEPTH_8U, 1);
 105 IplImage* rightImage = cvCreateImage(cvGetSize(srcRight), IPL_DEPTH_8U, 1);
 106 IplImage* depthImage = cvCreateImage(cvGetSize(srcRight), IPL_DEPTH_8U, 1);
 107
 108 cvCvtColor(srcLeft, leftImage, CV_BGR2GRAY);
 109 cvCvtColor(srcRight, rightImage, CV_BGR2GRAY);
 110
 111 cvFindStereoCorrespondence( leftImage, rightImage, CV_DISPARITY_BIRCHFIELD, depthImage, 50, 15, 3, 6, 8, 15 );
 112 /*---------------------------------------------------------------------------------*/
 113 </pre>
 114 <p>And here is the example stereo pair that can be used to test the example</p>
 115 <p>
 116 <img src="pics/left.jpg">
 117 <img src="pics/right.jpg">
 118 </p>
 119
 120
 121 <hr><h2><a name="aux_viewmorphing">View Morphing Functions</a></h2>
 122
 123 <hr><h3><a name="decl_cvMakeScanlines">MakeScanlines</a></h3>
 124 <p class="Blurb">Calculates scanlines coordinates for two cameras by fundamental matrix</p>
 125 <pre>
 126 void cvMakeScanlines( const CvMatrix3* matrix, CvSize img_size, int* scanlines1,
 127                       int* scanlines2, int* lengths1, int* lengths2, int* line_count );
 128 </pre><p><dl>
 129 <dt>matrix<dd>Fundamental matrix.
 130 <dt>imgSize<dd>Size of the image.
 131 <dt>scanlines1<dd>Pointer to the array of calculated scanlines of the first image.
 132 <dt>scanlines2<dd>Pointer to the array of calculated scanlines of the second image.
 133 <dt>lengths1<dd>Pointer to the array of calculated lengths (in pixels) of the first image
 134 scanlines.
 135 <dt>lengths2<dd>Pointer to the array of calculated lengths (in pixels) of the second image
 136 scanlines.
 137 <dt>line_count<dd>Pointer to the variable that stores the number of scanlines.
 138 </dl></p><p>
 139 The function <code>cvMakeScanlines</code> finds coordinates of scanlines for two images.
 140 <p>
 141 This function returns the number of scanlines. The function does nothing except
 142 calculating the number of scanlines if the pointers <code>scanlines1</code> or <code>scanlines2</code> are
 143 equal to zero.
 144 </p>
 145
 146 </p><hr><h3><a name="decl_cvPreWarpImage">PreWarpImage</a></h3>
 147 <p class="Blurb">Rectifies image</p>
 148 <pre>
 149 void cvPreWarpImage( int line_count, IplImage* img, uchar* dst,
 150                      int* dst_nums, int* scanlines );
 151 </pre><p><dl>
 152 <dt>line_count<dd>Number of scanlines for the image.
 153 <dt>img<dd>Image to prewarp.
 154 <dt>dst<dd>Data to store for the prewarp image.
 155 <dt>dst_nums<dd>Pointer to the array of lengths of scanlines.
 156 <dt>scanlines<dd>Pointer to the array of coordinates of scanlines.
 157 </dl></p><p>
 158 The function <code>cvPreWarpImage</code> rectifies the image so that the scanlines in the
 159 rectified image are horizontal. The output buffer of size
 160 <code>max(width,height)*line_count*3</code> must be allocated before calling the function.
 161
 162 </p><hr><h3><a name="decl_cvFindRuns">FindRuns</a></h3>
 163 <p class="Blurb">Retrieves scanlines from rectified image and breaks them down into runs</p>
 164 <pre>
 165 void cvFindRuns( int line_count, uchar* prewarp1, uchar* prewarp2,
 166                  int* line_lengths1, int* line_lengths2,
 167                  int* runs1, int* runs2,
 168                  int* num_runs1, int* num_runs2 );
 169 </pre><p><dl>
 170 <dt>line_count<dd>Number of the scanlines.
 171 <dt>prewarp1<dd>Prewarp data of the first image.
 172 <dt>prewarp2<dd>Prewarp data of the second image.
 173 <dt>line_lengths1<dd>Array of lengths of scanlines in the first image.
 174 <dt>line_lengths2<dd>Array of lengths of scanlines in the second image.
 175 <dt>runs1<dd>Array of runs in each scanline in the first image.
 176 <dt>runs2<dd>Array of runs in each scanline in the second image.
 177 <dt>num_runs1<dd>Array of numbers of runs in each scanline in the first image.
 178 <dt>num_runs2<dd>Array of numbers of runs in each scanline in the second image.
 179 </dl></p><p>
 180 The function <code>cvFindRuns</code> retrieves scanlines from the rectified image and breaks
 181 each scanline down into several runs, that is, series of pixels of almost the
 182 same brightness.
 183
 184 </p><hr><h3><a name="decl_cvDynamicCorrespondMulti">DynamicCorrespondMulti</a></h3>
 185 <p class="Blurb">Finds correspondence between two sets of runs of two warped images</p>
 186 <pre>
 187 void cvDynamicCorrespondMulti( int line_count, int* first, int* first_runs,
 188                                int* second, int* second_runs,
 189                                int* first_corr, int* second_corr );
 190 </pre><p><dl>
 191 <dt>line_count<dd>Number of scanlines.
 192 <dt>first<dd>Array of runs of the first image.
 193 <dt>first_runs<dd>Array of numbers of runs in each scanline of the first image.
 194 <dt>second<dd>Array of runs of the second image.
 195 <dt>second_runs<dd>Array of numbers of runs in each scanline of the second image.
 196 <dt>first_corr<dd>Pointer to the array of correspondence information found for the first
 197 runs.
 198 <dt>second_corr<dd>Pointer to the array of correspondence information found for the
 199 second runs.
 200 </dl></p><p>
 201 The function <code>cvDynamicCorrespondMulti</code> finds correspondence between two sets of
 202 runs of two images. Memory must be allocated before calling this function.
 203 Memory size for one array of correspondence information is
 204 <div><code>max( width,height )* numscanlines*3*sizeof ( int )</code> .
 205
 206 </p><hr><h3><a name="decl_cvMakeAlphaScanlines">MakeAlphaScanlines</a></h3>
 207 <p class="Blurb">Calculates coordinates of scanlines of image from virtual camera</p>
 208 <pre>
 209 void cvMakeAlphaScanlines( int* scanlines1, int* scanlines2,
 210                            int* scanlinesA, int* lengths,
 211                            int line_count, float alpha );
 212 </pre><p><dl>
 213 <dt>scanlines1<dd>Pointer to the array of the first scanlines.
 214 <dt>scanlines2<dd>Pointer to the array of the second scanlines.
 215 <dt>scanlinesA<dd>Pointer to the array of the scanlines found in the virtual image.
 216 <dt>lengths<dd>Pointer to the array of lengths of the scanlines found in the virtual
 217 image.
 218 <dt>line_count<dd>Number of scanlines.
 219 <dt>alpha<dd>Position of virtual camera <code>(0.0 - 1.0)</code> .
 220 </dl></p><p>
 221 The function <code>cvMakeAlphaScanlines</code> finds coordinates of scanlines for the virtual
 222 camera with the given camera position.
 223 <p>
 224 Memory must be allocated before calling this function. Memory size for the array
 225 of correspondence runs is <code>numscanlines*2*4*sizeof(int)</code> . Memory size for the
 226 array of the scanline lengths is <code>numscanlines*2*4*sizeof(int)</code> .
 227 </p>
 228
 229 </p><hr><h3><a name="decl_cvMorphEpilinesMulti">MorphEpilinesMulti</a></h3>
 230 <p class="Blurb">Morphs two pre-warped images using information about stereo correspondence</p>
 231 <pre>
 232 void cvMorphEpilinesMulti( int line_count, uchar* first_pix, int* first_num,
 233                            uchar* second_pix, int* second_num,
 234                            uchar* dst_pix, int* dst_num,
 235                            float alpha, int* first, int* first_runs,
 236                            int* second, int* second_runs,
 237                            int* first_corr, int* second_corr );
 238 </pre><p><dl>
 239 <dt>line_count<dd>Number of scanlines in the prewarp image.
 240 <dt>first_pix<dd>Pointer to the first prewarp image.
 241 <dt>first_num<dd>Pointer to the array of numbers of points in each scanline in the first
 242 image.
 243 <dt>second_pix<dd>Pointer to the second prewarp image.
 244 <dt>second_num<dd>Pointer to the array of numbers of points in each scanline in the
 245 second image.
 246 <dt>dst_pix<dd>Pointer to the resulting morphed warped image.
 247 <dt>dst_num<dd>Pointer to the array of numbers of points in each line.
 248 <dt>alpha<dd>Virtual camera position <code>(0.0 - 1.0)</code> .
 249 <dt>first<dd>First sequence of runs.
 250 <dt>first_runs<dd>Pointer to the number of runs in each scanline in the first image.
 251 <dt>second<dd>Second sequence of runs.
 252 <dt>second_runs<dd>Pointer to the number of runs in each scanline in the second image.
 253 <dt>first_corr<dd>Pointer to the array of correspondence information found for the first
 254 runs.
 255 <dt>second_corr<dd>Pointer to the array of correspondence information found for the
 256 second runs.
 257 </dl></p><p>
 258 The function <code>cvMorphEpilinesMulti</code> morphs two pre-warped images using information
 259 about correspondence between the scanlines of two images.
 260
 261 </p><hr><h3><a name="decl_cvPostWarpImage">PostWarpImage</a></h3>
 262 <p class="Blurb">Warps rectified morphed image back</p>
 263 <pre>
 264 void cvPostWarpImage( int line_count, uchar* src, int* src_nums,
 265                       IplImage* img, int* scanlines );
 266 </pre><p><dl>
 267 <dt>line_count<dd>Number of the scanlines.
 268 <dt>src<dd>Pointer to the prewarp image virtual image.
 269 <dt>src_nums<dd>Number of the scanlines in the image.
 270 <dt>img<dd>Resulting unwarp image.
 271 <dt>scanlines<dd>Pointer to the array of scanlines data.
 272 </dl></p><p>
 273 The function <code>cvPostWarpImage</code> warps the resultant image from the virtual camera by
 274 storing its rows across the scanlines whose coordinates are calculated by
 275 <a href="#decl_cvMakeAlphaScanlines">cvMakeAlphaScanlines</a>.
 276
 277 </p><hr><h3><a name="decl_cvDeleteMoire">DeleteMoire</a></h3>
 278 <p class="Blurb">Deletes moire in given image</p>
 279 <pre>
 280 void cvDeleteMoire( IplImage* img );
 281 </pre><p><dl>
 282 <dt>img<dd>Image.
 283 </dl></p><p>
 284 The function <code>cvDeleteMoire</code> deletes moire from the given image. The post-warped
 285 image may have black (un-covered) points because of possible holes between
 286 neighboring scanlines. The function deletes moire (black pixels) from the image
 287 by substituting neighboring pixels for black pixels. If all the scanlines are
 288 horizontal, the function may be omitted.</p>
 289
 290 <hr><h2><a name="aux_3dTracking">3D Tracking Functions</a></h2>
 291
 292 <p>The section discusses functions for tracking objects in 3d space using a stereo camera.
 293 Besides C API, there is DirectShow <a href="../appPage/3dTracker/3dTrackerFilter.htm">3dTracker</a> filter
 294 and the wrapper application <a href="../appPage/3dTracker/3dTracker.htm">3dTracker</a>.
 295 <a href="../appPage/3dTracker/3dTrackerTesting.htm">Here</a> you may find a description how to test the filter on sample data.</p>
 296
 297 <hr><h3><a name="decl_cv3dTrackerCalibrateCameras">3dTrackerCalibrateCameras</a></h3>
 298 <p class="Blurb">Simultaneously determines position and orientation of multiple cameras</p>
 299 <pre>
 300 CvBool cv3dTrackerCalibrateCameras(int num_cameras,
 301            const Cv3dTrackerCameraIntrinsics camera_intrinsics[],
 302            CvSize checkerboard_size,
 303            IplImage *samples[],
 304            Cv3dTrackerCameraInfo camera_info[]);
 305 </pre><p><dl>
 306 <dt>num_cameras<dd>the number of cameras to calibrate. This is the size of each of the
 307 three array parameters.
 308 <dt>camera_intrinsics<dd>camera intrinsics for each camera, such as determined by CalibFilter.
 309 <dt>checkerboard_size<dd>the width and height (in number of squares) of the checkerboard.
 310 <dt>samples<dd>images from each camera, with a view of the checkerboard.
 311 <dt>camera_info<dd>filled in with the results of the camera calibration. This is passed into
 312 <a href="#decl_cv3dTrackerLocateObjects">3dTrackerLocateObjects</a> to do tracking.
 313 </dl></p>
 314 <p>
 315 The function <code>cv3dTrackerCalibrateCameras</code>
 316 searches for a checkerboard of the specified size in each
 317 of the images. For each image in which it finds the checkerboard, it fills
 318 in the corresponding slot in <code>camera_info</code> with the position
 319 and orientation of the camera
 320 relative to the checkerboard and sets the <code>valid</code> flag.
 321 If it finds the checkerboard in all the images, it returns true;
 322 otherwise it returns false.
 323 </p><p>
 324 This function does not change the members of the <code>camera_info</code> array
 325 that correspond to images in which the checkerboard was not found.
 326 This allows you to calibrate each camera independently, instead of
 327 simultaneously.
 328 To accomplish this, do the following:
 329 <ol>
 330 <li>clear all the <code>valid</code> flags before calling this function the first time;</LI>
 331 <li>call this function with each set of images;</LI>
 332 <li> check all the <code>valid</code> flags after each call.
 333 When all the <code>valid</code> flags are set, calibration is complete.
 334 </li>
 335 </ol>
 336 Note that this method works well only if the checkerboard is rigidly mounted;
 337 if it is handheld, all the cameras should be calibrated simultaneously
 338 to get an accurate result.
 339 To ensure that all cameras are calibrated simultaneously,
 340 ignore the <code>valid</code> flags and
 341 use the return value to decide when calibration is complete.
 342 </p>
 343
 344 <hr><h3><a name="decl_cv3dTrackerLocateObjects">3dTrackerLocateObjects</a></h3>
 345 <p class="Blurb">Determines 3d location of tracked objects</p>
 346 <pre>
 347 int  cv3dTrackerLocateObjects(int num_cameras,
 348          int num_objects,
 349          const Cv3dTrackerCameraInfo camera_info[],
 350          const Cv3dTracker2dTrackedObject tracking_info[],
 351          Cv3dTrackerTrackedObject tracked_objects[]);
 352 </pre><p><dl>
 353 <dt>num_cameras<dd>the number of cameras.
 354 <dt>num_objects<dd>the maximum number of objects found by any camera. (Also the
 355 maximum number of objects returned in <code>tracked_objects</code>.)
 356 <dt>camera_info<dd>camera position and location information for each camera,
 357 as determined by <a href="#decl_cv3dTrackerCalibrateCameras">3dTrackerCalibrateCameras</a>.
 358 <dt>tracking_info<dd>the 2d position of each object as seen by each camera. Although
 359 this is specified as a one-dimensional array, it is actually a
 360 two-dimensional array:
 361 <code>const Cv3dTracker2dTrackedObject tracking_info[num_cameras][num_objects]</code>.
 362 The <code>id</code> field of any unused slots must be -1. Ids need not
 363 be ordered or consecutive.
 364 <dt>tracked_objects<dd>filled in with the results.
 365 </dl></p>
 366 <p>
 367 The function <code>cv3dTrackerLocateObjects</code>
 368 determines the 3d position of tracked objects
 369 based on the 2d tracking information from multiple cameras and
 370 the camera position and orientation information computed by
 371 <a href="#decl_3dTrackerCalibrateCameras">3dTrackerCalibrateCameras</a>.
 372 It locates any objects with the same <code>id</code> that are tracked by more
 373 than one camera.
 374 It fills in the <code>tracked_objects</code> array and
 375 returns the number of objects located. The <code>id</code> fields of
 376 any unused slots in <code>tracked_objects</code> are set to -1.
 377 </p>
 378
 379
 380
 381 <hr><h2><a name="aux_pca">Eigen Objects (PCA) Functions</a></h2>
 382
 383 <p>The functions described in this section do PCA analysis and compression for
 384 a set of 8-bit images that may not fit into memory all together.
 385 If your data fits into memory and the vectors are not 8-bit (or you want a simpler
 386 interface), use
 387 <a href="OpenCVRef_BasicFuncs.htm#decl_cvCalcCovarMatrix">cvCalcCovarMatrix</a>,
 388 <a href="OpenCVRef_BasicFuncs.htm#decl_cvSVD">cvSVD</a> and
 389 <a href="OpenCVRef_BasicFuncs.htm#decl_cvGEMM">cvGEMM</a>
 390 to do PCA</p>
 391
 392 <hr><h3><a name="decl_cvCalcCovarMatrixEx">CalcCovarMatrixEx</a></h3>
 393 <p class="Blurb">Calculates covariance matrix for group of input objects</p>
 394 <pre>
 395 void cvCalcCovarMatrixEx( int object_count, void* input, int io_flags,
 396                           int iobuf_size, uchar* buffer, void* userdata,
 397                           IplImage* avg, float* covar_matrix );
 398 </pre><p><dl>
 399 <dt>object_count<dd>Number of source objects.
 400 <dt>input<dd>Pointer either to the array of <code>IplImage</code> input objects or to the read
 401 callback function according to the value of the parameter <code>ioFlags</code>.
 402 <dt>io_flags<dd>Input/output flags.
 403 <dt>iobuf_size<dd>Input/output buffer size.
 404 <dt>buffer<dd>Pointer to the input/output buffer.
 405 <dt>userdata<dd>Pointer to the structure that contains all necessary data for the
 406 <dt>callback<dd>functions.
 407 <dt>avg<dd>Averaged object.
 408 <dt>covar_matrix<dd>Covariance matrix. An output parameter; must be allocated before the
 409 call.
 410 </dl><p>
 411 The function <code>cvCalcCovarMatrixEx</code> calculates a covariance matrix of the input
 412 objects group using previously calculated averaged object. Depending on <code>ioFlags</code>
 413 parameter it may be used either in direct access or callback mode. If <code>ioFlags</code> is
 414 not <code>CV_EIGOBJ_NO_CALLBACK</code>, buffer must be allocated before calling the
 415 function.
 416
 417 </p><hr><h3><a name="decl_cvCalcEigenObjects">CalcEigenObjects</a></h3>
 418 <p class="Blurb">Calculates orthonormal eigen basis and averaged object for group of input
 419 objects</p>
 420 <pre>
 421 void cvCalcEigenObjects( int nObjects, void* input, void* output, int ioFlags,
 422                          int ioBufSize, void* userData, CvTermCriteria* calcLimit,
 423                          IplImage* avg, float* eigVals );
 424 </pre><p><dl>
 425 <dt>nObjects<dd>Number of source objects.
 426 <dt>input<dd>Pointer either to the array of <code>IplImage</code> input objects or to the read
 427 callback function according to the value of the parameter <code>ioFlags</code>.
 428 <dt>output<dd>Pointer either to the array of eigen objects or to the write callback
 429 function according to the value of the parameter ioFlags .
 430 <dt>ioFlags<dd>Input/output flags.
 431 <dt>ioBufSize<dd>Input/output buffer size in bytes. The size is zero, if unknown.
 432 <dt>userData<dd>Pointer to the structure that contains all necessary data for the
 433 callback functions.
 434 <dt>calcLimit<dd>Criteria that determine when to stop calculation of eigen objects.
 435 <dt>avg<dd>Averaged object.
 436 <dt>eigVals<dd>Pointer to the eigenvalues array in the descending order; may be <code>NULL</code> .
 437 </dl><p>
 438 The function <code>cvCalcEigenObjects</code> calculates orthonormal eigen basis and the
 439 averaged object for a group of the input objects. Depending on <code>ioFlags</code> parameter
 440 it may be used either in direct access or callback mode. Depending on the
 441 parameter <code>calcLimit</code>, calculations are finished either after first
 442 <code>calcLimit.max_iter</code> dominating eigen objects are retrieved or if the ratio of the
 443 current eigenvalue to the largest eigenvalue comes down to <code>calcLimit.epsilon</code>
 444 threshold. The value <code>calcLimit -> type</code> must be <code>CV_TERMCRIT_NUMB,
 445 CV_TERMCRIT_EPS</code>, or <code>CV_TERMCRIT_NUMB | CV_TERMCRIT_EPS</code> . The function returns
 446 the real values <code>calcLimit->max_iter</code> and <code>calcLimit->epsilon</code> .
 447 <p>
 448 The function also calculates the averaged object, which must be created
 449 previously. Calculated eigen objects are arranged according to the corresponding
 450 eigenvalues in the descending order.
 451 </p>
 452 The parameter <code>eigVals</code> may be equal to <code>NULL</code>, if eigenvalues are not needed.
 453 <p>
 454 The function <code>cvCalcEigenObjects</code> uses the function
 455 <a href="#decl_cvCalcCovarMatrixEx">cvCalcCovarMatrixEx</a>.
 456 </p>
 457
 458 <hr><h3><a name="decl_cvCalcDecompCoeff">CalcDecompCoeff</a></h3>
 459 <p class="Blurb">Calculates decomposition coefficient of input object</p>
 460 <pre>
 461 double cvCalcDecompCoeff( IplImage* obj, IplImage* eigObj, IplImage* avg );
 462 </pre><p><dl>
 463 <dt>obj<dd>Input object.
 464 <dt>eigObj<dd>Eigen object.
 465 <dt>avg<dd>Averaged object.
 466 </dl><p>
 467 The function <code>cvCalcDecompCoeff</code> calculates one decomposition coefficient of the
 468 input object using the previously calculated eigen object and the averaged
 469 object.
 470 </p>
 471
 472
 473 <hr><h3><a name="decl_cvEigenDecomposite">EigenDecomposite</a></h3>
 474 <p class="Blurb">Calculates all decomposition coefficients for input object</p>
 475 <pre>
 476 void cvEigenDecomposite( IplImage* obj, int eigenvec_count, void* eigInput,
 477                          int ioFlags, void* userData, IplImage* avg, float* coeffs );
 478 </pre><p><dl>
 479 <dt>obj<dd>Input object.
 480 <dt>eigenvec_count<dd>Number of eigen objects.
 481 <dt>eigInput<dd>Pointer either to the array of <code>IplImage</code> input objects or to the read
 482 callback function according to the value of the parameter <code>ioFlags</code>.
 483 <dt>ioFlags<dd>Input/output flags.
 484 <dt>userData<dd>Pointer to the structure that contains all necessary data for the
 485 callback functions.
 486 <dt>avg<dd>Averaged object.
 487 <dt>coeffs<dd>Calculated coefficients; an output parameter.
 488 </dl><p>
 489 The function <code>cvEigenDecomposite</code> calculates all decomposition coefficients for the
 490 input object using the previously calculated eigen objects basis and the
 491 averaged object. Depending on <code>ioFlags</code> parameter it may be used either in direct
 492 access or callback mode.
 493 </p>
 494
 495
 496 <hr><h3><a name="decl_cvEigenProjection">EigenProjection</a></h3>
 497 <p class="Blurb">Calculates object projection to the eigen sub-space</p>
 498 <pre>
 499 void cvEigenProjection( void* input_vecs, int eigenvec_count, int io_flags, void* userdata,
 500                         float* coeffs, IplImage* avg, IplImage* proj );
 501 </pre><p><dl>
 502 <dt>input_vec<dd>Pointer to either an array of <code>IplImage</code> input objects or to a
 503 callback function, depending on <code>io_flags</code>.
 504 <dt>eigenvec_count<dd>Number of eigenvectors.
 505 <dt>io_flags<dd>Input/output flags; see <a href="#decl_cvCalcEigenObjects">cvCalcEigenObjects</a>.
 506 <dt>userdata<dd>Pointer to the structure that contains all necessary data for the
 507 callback functions.
 508 <dt>coeffs<dd>Previously calculated decomposition coefficients.
 509 <dt>avg<dd>Average vector, calculated by <a href="#decl_cvCalcEigenObjects">cvCalcEigenObjects</a>.
 510 <dt>proj<dd>Projection to the eigen sub-space.
 511 </dl><p>
 512 The function <code>cvEigenProjection</code> calculates an object projection to the eigen
 513 sub-space or, in other words, restores an object using previously calculated
 514 eigen objects basis, averaged object, and decomposition coefficients of the
 515 restored object. Depending on <code>io_flags</code> parameter it may be used either in direct
 516 access or callback mode.</p>
 517
 518 <hr><h2><a name="aux_hmm">Embedded Hidden Markov Models Functions</a></h2>
 519
 520 <p>
 521 In order to support embedded models the user must define structures to represent
 522 1D HMM and 2D embedded HMM model.
 523 </p>
 524 <hr><h3><a name="decl_CvHMM">CvHMM</a></h3>
 525 <p class="Blurb">Embedded HMM Structure</p>
 526 <pre>
 527     typedef struct _CvEHMM
 528     {
 529         int level;
 530         int num_states;
 531         float* transP;
 532         float** obsProb;
 533         union
 534         {
 535             CvEHMMState* state;
 536             struct _CvEHMM* ehmm;
 537         } u;
 538     } CvEHMM;
 539 </pre><p><dl>
 540 <dt>level<dd>Level of embedded HMM. If <code>level ==0</code>, HMM is most external. In 2D HMM
 541 there are two types of HMM: 1 external and several embedded. External HMM has
 542 <code>level ==1</code>, embedded HMMs have <code>level ==0</code> .
 543 <dt>num_states<dd>Number of states in 1D HMM.
 544 <dt>transP<dd>State-to-state transition probability, square matrix <code>(num_state&times;num_state )</code>.
 545 <dt>obsProb<dd>Observation probability matrix.
 546 <dt>state<dd>Array of HMM states. For the last-level HMM, that is, an HMM without
 547 embedded HMMs, HMM states are real.
 548 <dt>ehmm<dd>Array of embedded HMMs. If HMM is not last-level, then HMM states are not
 549 real and they are HMMs.
 550 </dl></p>
 551 <p>For representation of observations the following structure is defined:</p>
 552
 553 <hr><h3><a name="decl_CvImgObsInfo">CvImgObsInfo</a></h3>
 554 <p class="Blurb">Image Observation Structure</p>
 555 <pre>
 556     typedef struct CvImgObsInfo
 557     {
 558         int obs_x;
 559         int obs_y;
 560         int obs_size;
 561         float** obs;
 562         int* state;
 563         int* mix;
 564     } CvImgObsInfo;
 565 </pre><p><dl>
 566 <dt>obs_x<dd>Number of observations in the horizontal direction.
 567 <dt>obs_y<dd>Number of observations in the vertical direction.
 568 <dt>obs_size<dd>Length of every observation vector.
 569 <dt>obs<dd>Pointer to observation vectors stored consequently. Number of vectors is
 570 <code>obs_x*obs_y</code> .
 571 <dt>state<dd>Array of indices of states, assigned to every observation vector.
 572 <dt>mix<dd>Index of mixture component, corresponding to the observation vector within
 573 an assigned state.
 574 </dl></p>
 575
 576
 577 <hr><h3><a name="decl_cvCreate2DHMM">Create2DHMM</a></h3>
 578 <p class="Blurb">Creates 2D embedded HMM</p>
 579 <pre>
 580 CvEHMM* cvCreate2DHMM( int* stateNumber, int* numMix, int obsSize );
 581 </pre><p><dl>
 582 <dt>stateNumber<dd>Array, the first element of the which specifies the number of
 583 superstates in the HMM. All subsequent elements specify the number of states in
 584 every embedded HMM, corresponding to each superstate. So, the length of the
 585 array is <code>stateNumber [0]+1</code> .
 586 <dt>numMix<dd>Array with numbers of Gaussian mixture components per each internal
 587 state. The number of elements in the array is equal to number of internal states
 588 in the HMM, that is, superstates are not counted here.
 589 <dt>obsSize<dd>Size of observation vectors to be used with created HMM.
 590 </dl><p>
 591 The function <code>cvCreate2DHMM</code> returns the created structure of the type <a href="#decl_CvEHMM">CvEHMM</a> with
 592 specified parameters.
 593
 594 </p><hr><h3><a name="decl_cvRelease2DHMM">Release2DHMM</a></h3>
 595 <p class="Blurb">Releases 2D embedded HMM</p>
 596 <pre>
 597 void cvRelease2DHMM(CvEHMM** hmm );
 598 </pre><p><dl>
 599 <dt>hmm<dd>Address of pointer to HMM to be released.
 600 </dl><p>
 601 The function <code>cvRelease2DHMM</code> frees all the memory used by HMM and clears the
 602 pointer to HMM.
 603
 604 </p><hr><h3><a name="decl_cvCreateObsInfo">CreateObsInfo</a></h3>
 605 <p class="Blurb">Creates structure to store image observation vectors</p>
 606 <pre>
 607 CvImgObsInfo* cvCreateObsInfo( CvSize numObs, int obsSize );
 608 </pre><p><dl>
 609 <dt>numObs<dd>Numbers of observations in the horizontal and vertical directions. For
 610 the given image and scheme of extracting observations the parameter can be
 611 computed via the macro <code>CV_COUNT_OBS( roi, dctSize, delta, numObs )</code>, where <code>roi,
 612 dctSize, delta, numObs</code> are the pointers to structures of the type <a href="#decl_CvSize ">CvSize </a>. The
 613 pointer <code>roi</code> means size of <code>roi</code> of image observed, <code>numObs</code> is the output parameter
 614 of the macro.
 615 <dt>obsSize<dd>Size of observation vectors to be stored in the structure.
 616 </dl><p>
 617 The function <code>cvCreateObsInfo</code> creates new structures to store image observation
 618 vectors. For definitions of the parameters <code>roi, dctSize</code>, and <code>delta</code> see the
 619 specification of The function <code>cvImgToObs_DCT</code>.
 620
 621 </p><hr><h3><a name="decl_cvReleaseObsInfo">ReleaseObsInfo</a></h3>
 622 <p class="Blurb">Releases observation vectors structure</p>
 623 <pre>
 624 void cvReleaseObsInfo( CvImgObsInfo** obsInfo );
 625 </pre><p><dl>
 626 <dt>obsInfo<dd>Address of the pointer to the structure <a href="#decl_CvImgObsInfo">CvImgObsInfo</a> .
 627 </dl><p>
 628 The function <code>cvReleaseObsInfo</code> frees all memory used by observations and clears
 629 pointer to the structure <a href="#decl_CvImgObsInfo">CvImgObsInfo</a> .
 630
 631 </p><hr><h3><a name="decl_cvImgToObs_DCT">ImgToObs_DCT</a></h3>
 632 <p class="Blurb">Extracts observation vectors from image</p>
 633 <pre>
 634 void cvImgToObs_DCT( IplImage* image, float* obs, CvSize dctSize,
 635                      CvSize obsSize, CvSize delta );
 636 </pre><p><dl>
 637 <dt>image<dd>Input image.
 638 <dt>obs<dd>Pointer to consequently stored observation vectors.
 639 <dt>dctSize<dd>Size of image blocks for which DCT (Discrete Cosine Transform)
 640 coefficients are to be computed.
 641 <dt>obsSize<dd>Number of the lowest DCT coefficients in the horizontal and vertical
 642 directions to be put into the observation vector.
 643 <dt>delta<dd>Shift in pixels between two consecutive image blocks in the horizontal and
 644 vertical directions.
 645 </dl><p>
 646 The function <code>cvImgToObs_DCT</code> extracts observation vectors, that is, DCT
 647 coefficients, from the image. The user must pass <code>obsInfo.obs</code> as the parameter
 648 <code>obs</code> to use this function with other HMM functions and use the structure <code>obsInfo</code>
 649 of the <a href="#decl_CvImgObsInfo">CvImgObsInfo</a> type.
 650 </p><p>
 651 <code>Calculating Observations for HMM</code>
 652 <pre>
 653     CvImgObsInfo* obs_info;
 654
 655         ...
 656
 657         cvImgToObs_DCT( image,obs_info->obs, //!!!
 658
 659         dctSize, obsSize, delta );
 660 </pre>
 661
 662 </p><hr><h3><a name="decl_cvUniformImgSegm">UniformImgSegm</a></h3>
 663 <p class="Blurb">Performs uniform segmentation of image observations by HMM states</p>
 664 <pre>
 665 void cvUniformImgSegm( CvImgObsInfo* obsInfo, CvEHMM* hmm );
 666 </pre><p><dl>
 667 <dt>obsInfo<dd>Observations structure.
 668 <dt>hmm<dd>HMM structure.
 669 </dl><p>
 670 The function <code>cvUniformImgSegm</code> segments image observations by HMM states uniformly
 671 (see <u><font color=blue>Initial Segmentation</font></u> for 2D Embedded HMM for 2D embedded HMM with 5
 672 superstates and 3, 6, 6, 6, 3 internal states of every corresponding
 673 superstate).
 674 <p>
 675 <font color=blue>  Initial Segmentation for 2D Embedded HMM </font>
 676 </p>
 677 <p>
 678 <img align=center src="pics/face.png">
 679 </p>
 680
 681 </p><hr><h3><a name="decl_cvInitMixSegm">InitMixSegm</a></h3>
 682 <p class="Blurb">Segments all observations within every internal state of HMM by state mixture
 683 components</p>
 684 <pre>
 685 void cvInitMixSegm( CvImgObsInfo** obsInfoArray, int numImg, CvEHMM* hmm );
 686 </pre><p><dl>
 687 <dt>obsInfoArray<dd>Array of pointers to the observation structures.
 688 <dt>numImg<dd>Length of above array.
 689 <dt>hmm<dd>HMM.
 690 </dl><p>
 691 The function <code>cvInitMixSegm</code> takes a group of observations from several training
 692 images already segmented by states and splits a set of observation vectors
 693 within every internal HMM state into as many clusters as the number of mixture
 694 components in the state.
 695
 696 </p><hr><h3><a name="decl_cvEstimateHMMStateParams">EstimateHMMStateParams</a></h3>
 697 <p class="Blurb">Estimates all parameters of every HMM state</p>
 698 <pre>
 699 void cvEstimateHMMStateParams( CvImgObsInfo** obsInfoArray, int numImg, CvEHMM* hmm );
 700 </pre><p><dl>
 701 <dt>obsInfoArray<dd>Array of pointers to the observation structures.
 702 <dt>numImg<dd>Length of the array.
 703 <dt>hmm<dd>HMM.
 704 </dl><p>
 705 The function <code>cvEstimateHMMStateParams</code> computes all inner parameters of every HMM
 706 state, including Gaussian means, variances, etc.
 707
 708 </p><hr><h3><a name="decl_cvEstimateTransProb">EstimateTransProb</a></h3>
 709 <p class="Blurb">Computes transition probability matrices for embedded HMM</p>
 710 <pre>
 711 void cvEstimateTransProb( CvImgObsInfo** obsInfoArray, int numImg, CvEHMM* hmm );
 712 </pre><p><dl>
 713 <dt>obsInfoArray<dd>Array of pointers to the observation structures.
 714 <dt>numImg<dd>Length of the above array.
 715 <dt>hmm<dd>HMM.
 716 </dl><p>
 717 The function <code>cvEstimateTransProb</code> uses current segmentation of image observations
 718 to compute transition probability matrices for all embedded and external HMMs.
 719
 720 </p><hr><h3><a name="decl_cvEstimateObsProb">EstimateObsProb</a></h3>
 721 <p class="Blurb">Computes probability of every observation of several images</p>
 722 <pre>
 723 void cvEstimateObsProb( CvImgObsInfo* obsInfo, CvEHMM* hmm );
 724 </pre><p><dl>
 725 <dt>obsInfo<dd>Observation structure.
 726 <dt>hmm<dd>HMM structure.
 727 </dl><p>
 728 The function <code>cvEstimateObsProb</code> computes Gaussian probabilities of each observation
 729 to occur in each of the internal HMM states.
 730
 731 </p><hr><h3><a name="decl_cvEViterbi">EViterbi</a></h3>
 732 <p class="Blurb">Executes Viterbi algorithm for embedded HMM</p>
 733 <pre>
 734 float cvEViterbi( CvImgObsInfo* obsInfo, CvEHMM* hmm );
 735 </pre><p><dl>
 736 <dt>obsInfo<dd>Observation structure.
 737 <dt>hmm<dd>HMM structure.
 738 </dl><p>
 739 The function <code>cvEViterbi</code> executes Viterbi algorithm for embedded HMM. Viterbi
 740 algorithm evaluates the likelihood of the best match between the given image
 741 observations and the given HMM and performs segmentation of image observations
 742 by HMM states. The segmentation is done on the basis of the match found.
 743
 744 </p><hr><h3><a name="decl_cvMixSegmL2">MixSegmL2</a></h3>
 745 <p class="Blurb">Segments observations from all training images by mixture components of newly
 746 assigned states</p>
 747 <pre>
 748 void cvMixSegmL2( CvImgObsInfo** obsInfoArray, int numImg, CvEHMM* hmm );
 749 </pre><p><dl>
 750 <dt>obsInfoArray<dd>Array of pointers to the observation structures.
 751 <dt>numImg<dd>Length of the array.
 752 <dt>hmm<dd>HMM.
 753 </dl><p>
 754 The function <code>cvMixSegmL2</code> segments observations from all training images by mixture
 755 components of newly Viterbi algorithm-assigned states. The function uses
 756 Euclidean distance to group vectors around the existing mixtures centers.
 757 </p>
 758
 759
 760 </body>
 761 </html>
 762