opencv/doc/cv_motion_tracking.tex

   1 \section{Motion Analysis and Object Tracking}
   2
   3 \ifCPy
   4
   5 \cvCPyFunc{Acc}
   6 Adds a frame to an accumulator.
   7
   8 \cvdefC{
   9 void cvAcc( \par const CvArr* image,\par CvArr* sum,\par const CvArr* mask=NULL );
  10 }
  11 \cvdefPy{Acc(image,sum,mask=NULL)-> None}
  12
  13 \begin{description}
  14 \cvarg{image}{Input image, 1- or 3-channel, 8-bit or 32-bit floating point. (each channel of multi-channel image is processed independently)}
  15 \cvarg{sum}{Accumulator with the same number of channels as input image, 32-bit or 64-bit floating-point}
  16 \cvarg{mask}{Optional operation mask}
  17 \end{description}
  18
  19 The function adds the whole image \texttt{image} or its selected region to the accumulator \texttt{sum}:
  20
  21 \[ \texttt{sum}(x,y) \leftarrow \texttt{sum}(x,y) + \texttt{image}(x,y) \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
  22
  23 \cvCPyFunc{CalcGlobalOrientation}
  24 Calculates the global motion orientation of some selected region.
  25
  26 \cvdefC{
  27 double cvCalcGlobalOrientation( \par const CvArr* orientation,\par const CvArr* mask,\par const CvArr* mhi,\par double timestamp,\par double duration );
  28 }\cvdefPy{CalcGlobalOrientation(orientation,mask,mhi,timestamp,duration)-> float}
  29
  30 \begin{description}
  31 \cvarg{orientation}{Motion gradient orientation image; calculated by the function \cvCPyCross{CalcMotionGradient}}
  32 \cvarg{mask}{Mask image. It may be a conjunction of a valid gradient mask, obtained with \cvCPyCross{CalcMotionGradient} and the mask of the region, whose direction needs to be calculated}
  33 \cvarg{mhi}{Motion history image}
  34 \cvarg{timestamp}{Current time in milliseconds or other units, it is better to store time passed to \cvCPyCross{UpdateMotionHistory} before and reuse it here, because running \cvCPyCross{UpdateMotionHistory} and \cvCPyCross{CalcMotionGradient} on large images may take some time}
  35 \cvarg{duration}{Maximal duration of motion track in milliseconds, the same as \cvCPyCross{UpdateMotionHistory}}
  36 \end{description}
  37
  38 The function calculates the general
  39 motion direction in the selected region and returns the angle between
  40 0 degrees  and 360 degrees . At first the function builds the orientation histogram
  41 and finds the basic orientation as a coordinate of the histogram
  42 maximum. After that the function calculates the shift relative to the
  43 basic orientation as a weighted sum of all of the orientation vectors: the more
  44 recent the motion, the greater the weight. The resultant angle is
  45 a circular sum of the basic orientation and the shift.
  46
  47 \cvCPyFunc{CalcMotionGradient}
  48 Calculates the gradient orientation of a motion history image.
  49
  50 \cvdefC{
  51 void cvCalcMotionGradient( \par const CvArr* mhi,\par CvArr* mask,\par CvArr* orientation,\par double delta1,\par double delta2,\par int apertureSize=3 );
  52 }\cvdefPy{CalcMotionGradient(mhi,mask,orientation,delta1,delta2,apertureSize=3)-> None}
  53
  54 \begin{description}
  55 \cvarg{mhi}{Motion history image}
  56 \cvarg{mask}{Mask image; marks pixels where the motion gradient data is correct; output parameter}
  57 \cvarg{orientation}{Motion gradient orientation image; contains angles from 0 to ~360 degrees }
  58 \cvarg{delta1}{See below}
  59 \cvarg{delta2}{See below}
  60 \cvarg{apertureSize}{Aperture size of derivative operators used by the function: CV\_SCHARR, 1, 3, 5 or 7 (see \cvCPyCross{Sobel})}
  61 \end{description}
  62
  63 The function calculates the derivatives $Dx$ and $Dy$ of \texttt{mhi} and then calculates gradient orientation as:
  64
  65 \[
  66 \texttt{orientation}(x,y)=\arctan{\frac{Dy(x,y)}{Dx(x,y)}}
  67 \]
  68
  69 where both $Dx(x,y)$ and $Dy(x,y)$ signs are taken into account (as in the \cvCPyCross{CartToPolar} function). After that \texttt{mask} is filled to indicate where the orientation is valid (see the \texttt{delta1} and \texttt{delta2} description).
  70
  71 The function finds the minimum ($m(x,y)$) and maximum ($M(x,y)$) mhi values over each pixel $(x,y)$ neighborhood and assumes the gradient is valid only if
  72 \[
  73 \min(\texttt{delta1} , \texttt{delta2} ) \le M(x,y)-m(x,y) \le \max(\texttt{delta1} ,\texttt{delta2} ).
  74 \]
  75
  76 \cvCPyFunc{CalcOpticalFlowBM}
  77 Calculates the optical flow for two images by using the block matching method.
  78
  79 \cvdefC{
  80 void cvCalcOpticalFlowBM( \par const CvArr* prev,\par const CvArr* curr,\par CvSize blockSize,\par CvSize shiftSize,\par CvSize max\_range,\par int usePrevious,\par CvArr* velx,\par CvArr* vely );
  81 }\cvdefPy{CalcOpticalFlowBM(prev,curr,blockSize,shiftSize,max\_range,usePrevious,velx,vely)-> None}
  82
  83 \begin{description}
  84 \cvarg{prev}{First image, 8-bit, single-channel}
  85 \cvarg{curr}{Second image, 8-bit, single-channel}
  86 \cvarg{blockSize}{Size of basic blocks that are compared}
  87 \cvarg{shiftSize}{Block coordinate increments}
  88 \cvarg{max\_range}{Size of the scanned neighborhood in pixels around the block}
  89 \cvarg{usePrevious}{Uses the previous (input) velocity field}
  90 \cvarg{velx}{Horizontal component of the optical flow of
  91 \[
  92 \left\lfloor \frac{\texttt{prev->width} - \texttt{blockSize.width}}{\texttt{shiftSize.width}} \right\rfloor
  93 \times
  94 \left\lfloor \frac{\texttt{prev->height} - \texttt{blockSize.height}}{\texttt{shiftSize.height}} \right\rfloor
  95 \]
  96 size, 32-bit floating-point, single-channel}
  97 \cvarg{vely}{Vertical component of the optical flow of the same size \texttt{velx}, 32-bit floating-point, single-channel}
  98 \end{description}
  99
 100 The function calculates the optical
 101 flow for overlapped blocks $\texttt{blockSize.width} \times \texttt{blockSize.height}$ pixels each, thus the velocity
 102 fields are smaller than the original images. For every block in \texttt{prev} the functions tries to find a similar block in
 103 \texttt{curr} in some neighborhood of the original block or shifted by (velx(x0,y0),vely(x0,y0)) block as has been calculated by previous
 104 function call (if \texttt{usePrevious=1})
 105
 106 \cvCPyFunc{CalcOpticalFlowHS}
 107 Calculates the optical flow for two images.
 108
 109 \cvdefC{
 110 void cvCalcOpticalFlowHS( \par const CvArr* prev,\par const CvArr* curr,\par int usePrevious,\par CvArr* velx,\par CvArr* vely,\par double lambda,\par CvTermCriteria criteria );
 111 }\cvdefPy{CalcOpticalFlowHS(prev,curr,usePrevious,velx,vely,lambda,criteria)-> None}
 112
 113 \begin{description}
 114 \cvarg{prev}{First image, 8-bit, single-channel}
 115 \cvarg{curr}{Second image, 8-bit, single-channel}
 116 \cvarg{usePrevious}{Uses the previous (input) velocity field}
 117 \cvarg{velx}{Horizontal component of the optical flow of the same size as input images, 32-bit floating-point, single-channel}
 118 \cvarg{vely}{Vertical component of the optical flow of the same size as input images, 32-bit floating-point, single-channel}
 119 \cvarg{lambda}{Lagrangian multiplier}
 120 \cvarg{criteria}{Criteria of termination of velocity computing}
 121 \end{description}
 122
 123 The function computes the flow for every pixel of the first input image using the Horn and Schunck algorithm
 124 \cite{Horn81}.
 125
 126 \cvCPyFunc{CalcOpticalFlowLK}
 127 Calculates the optical flow for two images.
 128
 129 \cvdefC{
 130 void cvCalcOpticalFlowLK( \par const CvArr* prev,\par const CvArr* curr,\par CvSize winSize,\par CvArr* velx,\par CvArr* vely );
 131 }\cvdefPy{CalcOpticalFlowLK(prev,curr,winSize,velx,vely)-> None}
 132 \begin{description}
 133
 134 \cvarg{prev}{First image, 8-bit, single-channel}
 135 \cvarg{curr}{Second image, 8-bit, single-channel}
 136 \cvarg{winSize}{Size of the averaging window used for grouping pixels}
 137 \cvarg{velx}{Horizontal component of the optical flow of the same size as input images, 32-bit floating-point, single-channel}
 138 \cvarg{vely}{Vertical component of the optical flow of the same size as input images, 32-bit floating-point, single-channel}
 139 \end{description}
 140
 141 The function computes the flow for every pixel of the first input image using the Lucas and Kanade algorithm
 142 \cite{Lucas81}.
 143
 144 \cvCPyFunc{CalcOpticalFlowPyrLK}
 145 Calculates the optical flow for a sparse feature set using the iterative Lucas-Kanade method with pyramids.
 146
 147 \cvdefC{
 148 void cvCalcOpticalFlowPyrLK( \par const CvArr* prev,\par const CvArr* curr,\par CvArr* prevPyr,\par CvArr* currPyr,\par const CvPoint2D32f* prevFeatures,\par CvPoint2D32f* currFeatures,\par int count,\par CvSize winSize,\par int level,\par char* status,\par float* track\_error,\par CvTermCriteria criteria,\par int flags );
 149 }
 150 \cvdefPy{
 151 CalcOpticalFlowPyrLK(  prev, curr, prevPyr, currPyr, prevFeatures, winSize, level, criteria, flags, guesses = None) -> (currFeatures, status, track\_error)
 152 }
 153
 154 \begin{description}
 155 \cvarg{prev}{First frame, at time \texttt{t}}
 156 \cvarg{curr}{Second frame, at time \texttt{t + dt} }
 157 \cvarg{prevPyr}{Buffer for the pyramid for the first frame. If the pointer is not \texttt{NULL} , the buffer must have a sufficient size to store the pyramid from level \texttt{1} to level \texttt{level} ; the total size of \texttt{(image\_width+8)*image\_height/3} bytes is sufficient}
 158 \cvarg{currPyr}{Similar to \texttt{prevPyr}, used for the second frame}
 159 \cvarg{prevFeatures}{Array of points for which the flow needs to be found}
 160 \cvarg{currFeatures}{Array of 2D points containing the calculated new positions of the input features in the second image}
 161 \ifC
 162 \cvarg{count}{Number of feature points}
 163 \fi
 164 \cvarg{winSize}{Size of the search window of each pyramid level}
 165 \cvarg{level}{Maximal pyramid level number. If \texttt{0} , pyramids are not used (single level), if \texttt{1} , two levels are used, etc}
 166 \cvarg{status}{Array. Every element of the array is set to \texttt{1} if the flow for the corresponding feature has been found, \texttt{0} otherwise}
 167 \cvarg{track\_error}{Array of double numbers containing the difference between patches around the original and moved points. Optional parameter; can be \texttt{NULL}}
 168 \cvarg{criteria}{Specifies when the iteration process of finding the flow for each point on each pyramid level should be stopped}
 169 \cvarg{flags}{Miscellaneous flags:
 170 \begin{description}
 171   \cvarg{CV\_LKFLOWPyr\_A\_READY}{pyramid for the first frame is precalculated before the call}
 172   \cvarg{CV\_LKFLOWPyr\_B\_READY}{ pyramid for the second frame is precalculated before the call}
 173   \cvC{\cvarg{CV\_LKFLOW\_INITIAL\_GUESSES}{array B contains initial coordinates of features before the function call}}
 174 \end{description}}
 175 \cvPy{\cvarg{guesses}{optional array of estimated coordinates of features in second frame, with same length as \texttt{prevFeatures}}}
 176 \end{description}
 177
 178 The function implements the sparse iterative version of the Lucas-Kanade optical flow in pyramids
 179 \cite{Bouguet00}
 180 . It calculates the coordinates of the feature points on the current video
 181 frame given their coordinates on the previous frame. The function finds
 182 the coordinates with sub-pixel accuracy.
 183
 184 Both parameters \texttt{prevPyr} and \texttt{currPyr} comply with the
 185 following rules: if the image pointer is 0, the function allocates the
 186 buffer internally, calculates the pyramid, and releases the buffer after
 187 processing. Otherwise, the function calculates the pyramid and stores
 188 it in the buffer unless the flag \texttt{CV\_LKFLOWPyr\_A[B]\_READY}
 189 is set. The image should be large enough to fit the Gaussian pyramid
 190 data. After the function call both pyramids are calculated and the
 191 readiness flag for the corresponding image can be set in the next call
 192 (i.e., typically, for all the image pairs except the very first one
 193 \texttt{CV\_LKFLOWPyr\_A\_READY} is set).
 194
 195
 196 \cvCPyFunc{CamShift}
 197 Finds the object center, size, and orientation.
 198
 199 \cvdefC{
 200 int cvCamShift( \par const CvArr* prob\_image,\par CvRect window,\par CvTermCriteria criteria,\par CvConnectedComp* comp,\par CvBox2D* box=NULL );
 201 }
 202 \cvdefPy{CamShift(prob\_image,window,criteria)-> (int, comp, box)}
 203
 204 \begin{description}
 205 \cvarg{prob\_image}{Back projection of object histogram (see \cvCPyCross{CalcBackProject})}
 206 \cvarg{window}{Initial search window}
 207 \cvarg{criteria}{Criteria applied to determine when the window search should be finished}
 208 \cvarg{comp}{Resultant structure that contains the converged search window coordinates (\texttt{comp->rect} field) and the sum of all of the pixels inside the window (\texttt{comp->area} field)}
 209 \ifC % {
 210 \cvarg{box}{Circumscribed box for the object. If not \texttt{NULL}, it contains object size and orientation}
 211 \else % }{
 212 \cvarg{box}{Circumscribed box for the object.}
 213 \fi % }
 214 \end{description}
 215
 216 The function implements the CAMSHIFT object tracking algrorithm
 217 \cite{Bradski98}.
 218 First, it finds an object center using \cvCPyCross{MeanShift} and, after that, calculates the object size and orientation. The function returns number of iterations made within \cvCPyCross{MeanShift}.
 219
 220 The \texttt{CamShiftTracker} class declared in cv.hpp implements the color object tracker that uses the function.
 221
 222 \ifC % {
 223 \subsection{CvConDensation}
 224 ConDenstation state.
 225
 226 \begin{lstlisting}
 227     typedef struct CvConDensation
 228     {
 229         int MP;     //Dimension of measurement vector
 230         int DP;     // Dimension of state vector
 231         float* DynamMatr;       // Matrix of the linear Dynamics system
 232         float* State;           // Vector of State
 233         int SamplesNum;         // Number of the Samples
 234         float** flSamples;      // array of the Sample Vectors
 235         float** flNewSamples;   // temporary array of the Sample Vectors
 236         float* flConfidence;    // Confidence for each Sample
 237         float* flCumulative;    // Cumulative confidence
 238         float* Temp;            // Temporary vector
 239         float* RandomSample;    // RandomVector to update sample set
 240         CvRandState* RandS;     // Array of structures to generate random vectors
 241     } CvConDensation;
 242
 243 \end{lstlisting}
 244 The structure \texttt{CvConDensation} stores the CONditional DENSity propagATION tracker state. The information about the algorithm can be found at \url{http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/ISARD1/condensation.html}.
 245
 246 \cvCPyFunc{CreateConDensation}
 247 Allocates the ConDensation filter structure.
 248
 249 \cvdefC{
 250 CvConDensation* cvCreateConDensation( \par int dynam\_params,\par int measure\_params,\par int sample\_count );
 251 }
 252
 253 \begin{description}
 254 \cvarg{dynam\_params}{Dimension of the state vector}
 255 \cvarg{measure\_params}{Dimension of the measurement vector}
 256 \cvarg{sample\_count}{Number of samples}
 257 \end{description}
 258
 259 The function creates a \texttt{CvConDensation} structure and returns a pointer to the structure.
 260
 261 \cvCPyFunc{ConDensInitSampleSet}
 262 Initializes the sample set for the ConDensation algorithm.
 263
 264 \cvdefC{
 265 void cvConDensInitSampleSet( CvConDensation* condens, \par CvMat* lower\_bound, \par CvMat* upper\_bound );
 266 }
 267
 268 \begin{description}
 269 \cvarg{condens}{Pointer to a structure to be initialized}
 270 \cvarg{lower\_bound}{Vector of the lower boundary for each dimension}
 271 \cvarg{upper\_bound}{Vector of the upper boundary for each dimension}
 272 \end{description}
 273
 274 The function fills the samples arrays in the structure \texttt{condens} with values within the specified ranges.
 275 \fi
 276
 277 \cvclass{CvKalman}\label{CvKalman}
 278 Kalman filter state.
 279
 280 \ifC
 281 \begin{lstlisting}
 282 typedef struct CvKalman
 283 {
 284     int MP;                     /* number of measurement vector dimensions */
 285     int DP;                     /* number of state vector dimensions */
 286     int CP;                     /* number of control vector dimensions */
 287
 288     /* backward compatibility fields */
 289 #if 1
 290     float* PosterState;         /* =state_pre->data.fl */
 291     float* PriorState;          /* =state_post->data.fl */
 292     float* DynamMatr;           /* =transition_matrix->data.fl */
 293     float* MeasurementMatr;     /* =measurement_matrix->data.fl */
 294     float* MNCovariance;        /* =measurement_noise_cov->data.fl */
 295     float* PNCovariance;        /* =process_noise_cov->data.fl */
 296     float* KalmGainMatr;        /* =gain->data.fl */
 297     float* PriorErrorCovariance;/* =error_cov_pre->data.fl */
 298     float* PosterErrorCovariance;/* =error_cov_post->data.fl */
 299     float* Temp1;               /* temp1->data.fl */
 300     float* Temp2;               /* temp2->data.fl */
 301 #endif
 302
 303     CvMat* state_pre;           /* predicted state (x'(k)):
 304                                     x(k)=A*x(k-1)+B*u(k) */
 305     CvMat* state_post;          /* corrected state (x(k)):
 306                                     x(k)=x'(k)+K(k)*(z(k)-H*x'(k)) */
 307     CvMat* transition_matrix;   /* state transition matrix (A) */
 308     CvMat* control_matrix;      /* control matrix (B)
 309                                    (it is not used if there is no control)*/
 310     CvMat* measurement_matrix;  /* measurement matrix (H) */
 311     CvMat* process_noise_cov;   /* process noise covariance matrix (Q) */
 312     CvMat* measurement_noise_cov; /* measurement noise covariance matrix (R) */
 313     CvMat* error_cov_pre;       /* priori error estimate covariance matrix (P'(k)):
 314                                     P'(k)=A*P(k-1)*At + Q*/
 315     CvMat* gain;                /* Kalman gain matrix (K(k)):
 316                                     K(k)=P'(k)*Ht*inv(H*P'(k)*Ht+R)*/
 317     CvMat* error_cov_post;      /* posteriori error estimate covariance matrix (P(k)):
 318                                     P(k)=(I-K(k)*H)*P'(k) */
 319     CvMat* temp1;               /* temporary matrices */
 320     CvMat* temp2;
 321     CvMat* temp3;
 322     CvMat* temp4;
 323     CvMat* temp5;
 324 }
 325 CvKalman;
 326 \end{lstlisting}
 327 \else
 328 \begin{description}
 329 \cvarg{MP}{number of measurement vector dimensions}
 330 \cvarg{DP}{number of state vector dimensions}
 331 \cvarg{CP}{number of control vector dimensions}
 332 \cvarg{state\_pre}{predicted state (x'(k)): x(k)=A*x(k-1)+B*u(k)}
 333 \cvarg{state\_post}{corrected state (x(k)): x(k)=x'(k)+K(k)*(z(k)-H*x'(k))}
 334 \cvarg{transition\_matrix}{state transition matrix (A)}
 335 \cvarg{control\_matrix}{control matrix (B) (it is not used if there is no control)}
 336 \cvarg{measurement\_matrix}{measurement matrix (H)}
 337 \cvarg{process\_noise\_cov}{process noise covariance matrix (Q)}
 338 \cvarg{measurement\_noise\_cov}{measurement noise covariance matrix (R)}
 339 \cvarg{error\_cov\_pre}{priori error estimate covariance matrix (P'(k)):  P'(k)=A*P(k-1)*At + Q}
 340 \cvarg{gain}{Kalman gain matrix (K(k)): K(k)=P'(k)*Ht*inv(H*P'(k)*Ht+R)}
 341 \cvarg{error\_cov\_post}{posteriori error estimate covariance matrix (P(k)): P(k)=(I-K(k)*H)*P'(k)}
 342 \end{description}
 343 \fi
 344
 345 The structure \texttt{CvKalman} is used to keep the Kalman filter
 346 state. It is created by the \cvCPyCross{CreateKalman} function, updated
 347 by the \cvCPyCross{KalmanPredict} and \cvCPyCross{KalmanCorrect} functions
 348 and released by the \cvCPyCross{ReleaseKalman} function. Normally, the
 349 structure is used for the standard Kalman filter (notation and the
 350 formulas below are borrowed from the excellent Kalman tutorial
 351 \cite{Welch95})
 352
 353 \[
 354 \begin{array}{l}
 355 x_k=A \cdot x_{k-1}+B \cdot u_k+w_k\\
 356 z_k=H \cdot x_k+v_k
 357 \end{array}
 358 \]
 359
 360 where:
 361
 362 \[
 363 \begin{array}{l l}
 364 x_k\;(x_{k-1})& \text{state of the system at the moment \emph{k} (\emph{k-1})}\\
 365 z_k & \text{measurement of the system state at the moment \emph{k}}\\
 366 u_k & \text{external control applied at the moment \emph{k}}
 367 \end{array}
 368 \]
 369
 370 $w_k$ and $v_k$ are normally-distributed process and measurement noise, respectively:
 371
 372 \[
 373 \begin{array}{l}
 374 p(w) \sim N(0,Q)\\
 375 p(v) \sim N(0,R)
 376 \end{array}
 377 \]
 378
 379 that is,
 380
 381 $Q$ process noise covariance matrix, constant or variable,
 382
 383 $R$ measurement noise covariance matrix, constant or variable
 384
 385 In the case of the standard Kalman filter, all of the matrices: A, B, H, Q and R are initialized once after the \cvCPyCross{CvKalman} structure is allocated via \cvCPyCross{CreateKalman}. However, the same structure and the same functions may be used to simulate the extended Kalman filter by linearizing the extended Kalman filter equation in the current system state neighborhood, in this case A, B, H (and, probably, Q and R) should be updated on every step.
 386
 387 \cvCPyFunc{CreateKalman}
 388 Allocates the Kalman filter structure.
 389
 390 \cvdefC{
 391 CvKalman* cvCreateKalman( \par int dynam\_params,\par int measure\_params,\par int control\_params=0 );
 392 }
 393
 394 \cvdefPy{
 395 CreateKalman(dynam\_params, measure\_params, control\_params=0) -> CvKalman
 396 }
 397
 398 \begin{description}
 399 \cvarg{dynam\_params}{dimensionality of the state vector}
 400 \cvarg{measure\_params}{dimensionality of the measurement vector}
 401 \cvarg{control\_params}{dimensionality of the control vector}
 402 \end{description}
 403
 404 The function allocates \cvCPyCross{CvKalman} and all its matrices and initializes them somehow.
 405
 406
 407 \cvCPyFunc{KalmanCorrect}
 408 Adjusts the model state.
 409
 410 \cvdefC{
 411 const CvMat* cvKalmanCorrect( CvKalman* kalman, const CvMat* measurement );
 412 }
 413 \cvdefPy{
 414 KalmanCorrect(kalman, measurement) -> cvmat
 415 }
 416
 417 \begin{description}
 418 \ifC
 419 \cvarg{kalman}{Pointer to the structure to be updated}
 420 \else
 421 \cvarg{kalman}{Kalman filter object returned by \cvCPyCross{CreateKalman}}
 422 \fi
 423 \cvarg{measurement}{CvMat containing the measurement vector}
 424 \end{description}
 425
 426 The function adjusts the stochastic model state on the basis of the given measurement of the model state:
 427
 428 \[
 429 \begin{array}{l}
 430 K_k=P'_k \cdot H^T \cdot (H \cdot P'_k \cdot H^T+R)^{-1}\\
 431 x_k=x'_k+K_k \cdot (z_k-H \cdot x'_k)\\
 432 P_k=(I-K_k \cdot H) \cdot P'_k
 433 \end{array}
 434 \]
 435
 436 where
 437
 438 \begin{tabular}{l p{4 in}}
 439 \hline
 440 $z_k$ & given measurement (\texttt{mesurement} parameter)\\ \hline
 441 $K_k$ & Kalman "gain" matrix.\\ \hline
 442 \end{tabular}
 443
 444 The function stores the adjusted state at \texttt{kalman->state\_post} and returns it on output.
 445
 446 \ifC
 447 Example. Using Kalman filter to track a rotating point
 448 \begin{lstlisting}
 449 #include "cv.h"
 450 #include "highgui.h"
 451 #include <math.h>
 452
 453 int main(int argc, char** argv)
 454 {
 455     /* A matrix data */
 456     const float A[] = { 1, 1, 0, 1 };
 457
 458     IplImage* img = cvCreateImage( cvSize(500,500), 8, 3 );
 459     CvKalman* kalman = cvCreateKalman( 2, 1, 0 );
 460     /* state is (phi, delta_phi) - angle and angle increment */
 461     CvMat* state = cvCreateMat( 2, 1, CV_32FC1 );
 462     CvMat* process_noise = cvCreateMat( 2, 1, CV_32FC1 );
 463     /* only phi (angle) is measured */
 464     CvMat* measurement = cvCreateMat( 1, 1, CV_32FC1 );
 465     CvRandState rng;
 466     int code = -1;
 467
 468     cvRandInit( &rng, 0, 1, -1, CV_RAND_UNI );
 469
 470     cvZero( measurement );
 471     cvNamedWindow( "Kalman", 1 );
 472
 473     for(;;)
 474     {
 475         cvRandSetRange( &rng, 0, 0.1, 0 );
 476         rng.disttype = CV_RAND_NORMAL;
 477
 478         cvRand( &rng, state );
 479
 480         memcpy( kalman->transition_matrix->data.fl, A, sizeof(A));
 481         cvSetIdentity( kalman->measurement_matrix, cvRealScalar(1) );
 482         cvSetIdentity( kalman->process_noise_cov, cvRealScalar(1e-5) );
 483         cvSetIdentity( kalman->measurement_noise_cov, cvRealScalar(1e-1) );
 484         cvSetIdentity( kalman->error_cov_post, cvRealScalar(1));
 485         /* choose random initial state */
 486         cvRand( &rng, kalman->state_post );
 487
 488         rng.disttype = CV_RAND_NORMAL;
 489
 490         for(;;)
 491         {
 492             #define calc_point(angle)                                      \
 493                 cvPoint( cvRound(img->width/2 + img->width/3*cos(angle)),  \
 494                          cvRound(img->height/2 - img->width/3*sin(angle)))
 495
 496             float state_angle = state->data.fl[0];
 497             CvPoint state_pt = calc_point(state_angle);
 498
 499             /* predict point position */
 500             const CvMat* prediction = cvKalmanPredict( kalman, 0 );
 501             float predict_angle = prediction->data.fl[0];
 502             CvPoint predict_pt = calc_point(predict_angle);
 503             float measurement_angle;
 504             CvPoint measurement_pt;
 505
 506             cvRandSetRange( &rng,
 507                             0,
 508                             sqrt(kalman->measurement_noise_cov->data.fl[0]),
 509                             0 );
 510             cvRand( &rng, measurement );
 511
 512             /* generate measurement */
 513             cvMatMulAdd( kalman->measurement_matrix, state, measurement, measurement );
 514
 515             measurement_angle = measurement->data.fl[0];
 516             measurement_pt = calc_point(measurement_angle);
 517
 518             /* plot points */
 519             #define draw_cross( center, color, d )                        \
 520                 cvLine( img, cvPoint( center.x - d, center.y - d ),       \
 521                              cvPoint( center.x + d, center.y + d ),       \
 522                              color, 1, 0 );                               \
 523                 cvLine( img, cvPoint( center.x + d, center.y - d ),       \
 524                              cvPoint( center.x - d, center.y + d ),       \
 525                              color, 1, 0 )
 526
 527             cvZero( img );
 528             draw_cross( state_pt, CV_RGB(255,255,255), 3 );
 529             draw_cross( measurement_pt, CV_RGB(255,0,0), 3 );
 530             draw_cross( predict_pt, CV_RGB(0,255,0), 3 );
 531             cvLine( img, state_pt, predict_pt, CV_RGB(255,255,0), 3, 0 );
 532
 533             /* adjust Kalman filter state */
 534             cvKalmanCorrect( kalman, measurement );
 535
 536             cvRandSetRange( &rng,
 537                             0,
 538                             sqrt(kalman->process_noise_cov->data.fl[0]),
 539                             0 );
 540             cvRand( &rng, process_noise );
 541             cvMatMulAdd( kalman->transition_matrix,
 542                          state,
 543                          process_noise,
 544                          state );
 545
 546             cvShowImage( "Kalman", img );
 547             code = cvWaitKey( 100 );
 548
 549             if( code > 0 ) /* break current simulation by pressing a key */
 550                 break;
 551         }
 552         if( code == 27 ) /* exit by ESCAPE */
 553             break;
 554     }
 555
 556     return 0;
 557 }
 558 \end{lstlisting}
 559 \fi
 560
 561 \cvCPyFunc{KalmanPredict}
 562 Estimates the subsequent model state.
 563
 564 \cvdefC{
 565 const CvMat* cvKalmanPredict( \par CvKalman* kalman, \par const CvMat* control=NULL );
 566 }
 567 \cvdefPy{
 568 KalmanPredict(kalman, control=None) -> cvmat
 569 }
 570
 571 \begin{description}
 572 \ifC
 573 \cvarg{kalman}{Kalman filter state}
 574 \else
 575 \cvarg{kalman}{Kalman filter object returned by \cvCPyCross{CreateKalman}}
 576 \fi
 577 \cvarg{control}{Control vector $u_k$, should be NULL iff there is no external control (\texttt{control\_params} =0)}
 578 \end{description}
 579
 580 The function estimates the subsequent stochastic model state by its current state and stores it at \texttt{kalman->state\_pre}:
 581
 582 \[
 583 \begin{array}{l}
 584 x'_k=A \cdot x_{k-1}+B \cdot u_k\\
 585 P'_k=A \cdot P_{k-1}+A^T + Q
 586 \end{array}
 587 \]
 588
 589 where
 590
 591 \begin{tabular}{l p{5 in}}
 592 \hline
 593 $x'_k$ & is predicted state \texttt{kalman->state\_pre},\\ \hline
 594 $x_{k-1}$ & is corrected state on the previous step \texttt{kalman->state\_post}
 595                 (should be initialized somehow in the beginning, zero vector by default),\\ \hline
 596 $u_k$ & is external control (\texttt{control} parameter),\\ \hline
 597 $P'_k$ & is priori error covariance matrix \texttt{kalman->error\_cov\_pre}\\ \hline
 598 $P_{k-1}$ & is posteriori error covariance matrix on the previous step \texttt{kalman->error\_cov\_post}
 599                 (should be initialized somehow in the beginning, identity matrix by default),
 600 \end{tabular}
 601
 602 The function returns the estimated state.
 603
 604 \subsection{KalmanUpdateByMeasurement}
 605
 606 Synonym for \cross{KalmanCorrect}
 607
 608 \subsection{KalmanUpdateByTime}
 609
 610 Synonym for \cross{KalmanPredict}
 611
 612 \cvCPyFunc{MeanShift}
 613 Finds the object center on back projection.
 614
 615 \cvdefC{
 616 int cvMeanShift( \par const CvArr* prob\_image,\par CvRect window,\par CvTermCriteria criteria,\par CvConnectedComp* comp );
 617 }\cvdefPy{MeanShift(prob\_image,window,criteria)-> comp}
 618
 619 \begin{description}
 620 \cvarg{prob\_image}{Back projection of the object histogram (see \cvCPyCross{CalcBackProject})}
 621 \cvarg{window}{Initial search window}
 622 \cvarg{criteria}{Criteria applied to determine when the window search should be finished}
 623 \cvarg{comp}{Resultant structure that contains the converged search window coordinates (\texttt{comp->rect} field) and the sum of all of the pixels inside the window (\texttt{comp->area} field)}
 624 \end{description}
 625
 626 The function iterates to find the object center
 627 given its back projection and initial position of search window. The
 628 iterations are made until the search window center moves by less than
 629 the given value and/or until the function has done the maximum number
 630 of iterations. The function returns the number of iterations made.
 631
 632 \cvCPyFunc{MultiplyAcc}
 633 Adds the product of two input images to the accumulator.
 634
 635 \cvdefC{
 636 void cvMultiplyAcc( \par const CvArr* image1,\par const CvArr* image2,\par CvArr* acc,\par const CvArr* mask=NULL );
 637 }
 638 \cvdefPy{MultiplyAcc(image1,image2,acc,mask=NULL)-> None}
 639
 640 \begin{description}
 641 \cvarg{image1}{First input image, 1- or 3-channel, 8-bit or 32-bit floating point (each channel of multi-channel image is processed independently)}
 642 \cvarg{image2}{Second input image, the same format as the first one}
 643 \cvarg{acc}{Accumulator with the same number of channels as input images, 32-bit or 64-bit floating-point}
 644 \cvarg{mask}{Optional operation mask}
 645 \end{description}
 646
 647 The function adds the product of 2 images or their selected regions to the accumulator \texttt{acc}:
 648
 649 \[ \texttt{acc}(x,y) \leftarrow \texttt{acc}(x,y) + \texttt{image1}(x,y) \cdot \texttt{image2}(x,y) \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
 650
 651 \ifC % {
 652 \cvCPyFunc{ReleaseConDensation}
 653 Deallocates the ConDensation filter structure.
 654
 655 \cvdefC{
 656 void cvReleaseConDensation( CvConDensation** condens );
 657
 658 }
 659 \begin{description}
 660 \cvarg{condens}{Pointer to the pointer to the structure to be released}
 661 \end{description}
 662
 663 The function releases the structure \texttt{condens}) and frees all memory previously allocated for the structure.
 664
 665 \fi % }
 666
 667 \ifC % {
 668
 669 \cvCPyFunc{ReleaseKalman}
 670 Deallocates the Kalman filter structure.
 671
 672 \cvdefC{
 673 void cvReleaseKalman( \par CvKalman** kalman );
 674 }
 675
 676 \begin{description}
 677 \cvarg{kalman}{double pointer to the Kalman filter structure}
 678 \end{description}
 679
 680 The function releases the structure \cvCPyCross{CvKalman} and all of the underlying matrices.
 681
 682 \fi % }
 683
 684 \cvCPyFunc{RunningAvg}
 685 Updates the running average.
 686
 687 \cvdefC{
 688 void cvRunningAvg( \par const CvArr* image,\par CvArr* acc,\par double alpha,\par const CvArr* mask=NULL );
 689 }
 690 \cvdefPy{RunningAvg(image,acc,alpha,mask=NULL)-> None}
 691
 692 \begin{description}
 693 \cvarg{image}{Input image, 1- or 3-channel, 8-bit or 32-bit floating point (each channel of multi-channel image is processed independently)}
 694 \cvarg{acc}{Accumulator with the same number of channels as input image, 32-bit or 64-bit floating-point}
 695 \cvarg{alpha}{Weight of input image}
 696 \cvarg{mask}{Optional operation mask}
 697 \end{description}
 698
 699 The function calculates the weighted sum of the input image
 700 \texttt{image} and the accumulator \texttt{acc} so that \texttt{acc}
 701 becomes a running average of frame sequence:
 702
 703 \[ \texttt{acc}(x,y) \leftarrow (1-\alpha) \cdot \texttt{acc}(x,y) + \alpha \cdot \texttt{image}(x,y) \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
 704
 705 where $\alpha$ regulates the update speed (how fast the accumulator forgets about previous frames).
 706
 707
 708 \cvCPyFunc{SegmentMotion}
 709 Segments a whole motion into separate moving parts.
 710
 711 \cvdefC{
 712 CvSeq* cvSegmentMotion( \par const CvArr* mhi,\par CvArr* seg\_mask,\par CvMemStorage* storage,\par double timestamp,\par double seg\_thresh );
 713 }\cvdefPy{SegmentMotion(mhi,seg\_mask,storage,timestamp,seg\_thresh)-> None}
 714
 715 \begin{description}
 716 \cvarg{mhi}{Motion history image}
 717 \cvarg{seg\_mask}{Image where the mask found should be stored, single-channel, 32-bit floating-point}
 718 \cvarg{storage}{Memory storage that will contain a sequence of motion connected components}
 719 \cvarg{timestamp}{Current time in milliseconds or other units}
 720 \cvarg{seg\_thresh}{Segmentation threshold; recommended to be equal to the interval between motion history "steps" or greater}
 721 \end{description}
 722
 723 The function finds all of the motion segments and
 724 marks them in \texttt{seg\_mask} with individual values (1,2,...). It
 725 also returns a sequence of \cvCPyCross{CvConnectedComp}
 726 structures, one for each motion component. After that the
 727 motion direction for every component can be calculated with
 728 \cvCPyCross{CalcGlobalOrientation} using the extracted mask of the particular
 729 component \cvCPyCross{Cmp}.
 730
 731 \cvCPyFunc{SnakeImage}
 732 Changes the contour position to minimize its energy.
 733
 734 \cvdefC{
 735 void cvSnakeImage( \par const IplImage* image,\par CvPoint* points,\par int length,\par float* alpha,\par float* beta,\par float* gamma,\par int coeff\_usage,\par CvSize win,\par CvTermCriteria criteria,\par int calc\_gradient=1 );
 736 }\cvdefPy{SnakeImage(image,points,alpha,beta,gamma,coeff\_usage,win,criteria,calc\_gradient=1)-> None}
 737
 738 \begin{description}
 739 \cvarg{image}{The source image or external energy field}
 740 \cvarg{points}{Contour points (snake)}
 741 \ifC
 742 \cvarg{length}{Number of points in the contour}
 743 \fi
 744 \cvarg{alpha}{Weight[s] of continuity energy, single float or array of \texttt{length} floats, one for each contour point}
 745 \cvarg{beta}{Weight[s] of curvature energy, similar to \texttt{alpha}}
 746 \cvarg{gamma}{Weight[s] of image energy, similar to \texttt{alpha}}
 747 \cvarg{coeff\_usage}{Different uses of the previous three parameters:
 748 \begin{description}
 749   \cvarg{CV\_VALUE}{indicates that each of \texttt{alpha, beta, gamma} is a pointer to a single value to be used for all points;}
 750   \cvarg{CV\_ARRAY}{indicates that each of \texttt{alpha, beta, gamma} is a pointer to an array of coefficients different for all the points of the snake. All the arrays must have the size equal to the contour size.}
 751 \end{description}}
 752 \cvarg{win}{Size of neighborhood of every point used to search the minimum, both \texttt{win.width} and \texttt{win.height} must be odd}
 753 \cvarg{criteria}{Termination criteria}
 754 \cvarg{calc\_gradient}{Gradient flag; if not 0, the function calculates the gradient magnitude for every image pixel and consideres it as the energy field, otherwise the input image itself is considered}
 755 \end{description}
 756
 757 The function updates the snake in order to minimize its
 758 total energy that is a sum of internal energy that depends on the contour
 759 shape (the smoother contour is, the smaller internal energy is) and
 760 external energy that depends on the energy field and reaches minimum at
 761 the local energy extremums that correspond to the image edges in the case
 762 of using an image gradient.
 763
 764 The parameter \texttt{criteria.epsilon} is used to define the minimal
 765 number of points that must be moved during any iteration to keep the
 766 iteration process running.
 767
 768 If at some iteration the number of moved points is less
 769 than \texttt{criteria.epsilon} or the function performed
 770 \texttt{criteria.max\_iter} iterations, the function terminates.
 771
 772 \cvCPyFunc{SquareAcc}
 773 Adds the square of the source image to the accumulator.
 774
 775 \cvdefC{
 776 void cvSquareAcc( \par const CvArr* image,\par CvArr* sqsum,\par const CvArr* mask=NULL );
 777 }\cvdefPy{SquareAcc(image,sqsum,mask=NULL)-> None}
 778
 779 \begin{description}
 780 \cvarg{image}{Input image, 1- or 3-channel, 8-bit or 32-bit floating point (each channel of multi-channel image is processed independently)}
 781 \cvarg{sqsum}{Accumulator with the same number of channels as input image, 32-bit or 64-bit floating-point}
 782 \cvarg{mask}{Optional operation mask}
 783 \end{description}
 784
 785 The function adds the input image \texttt{image} or its selected region, raised to power 2, to the accumulator \texttt{sqsum}:
 786
 787 \[ \texttt{sqsum}(x,y) \leftarrow \texttt{sqsum}(x,y) + \texttt{image}(x,y)^2 \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
 788
 789 \cvCPyFunc{UpdateMotionHistory}
 790 Updates the motion history image by a moving silhouette.
 791
 792 \cvdefC{
 793 void cvUpdateMotionHistory( \par const CvArr* silhouette,\par CvArr* mhi,\par double timestamp,\par double duration );
 794 }\cvdefPy{UpdateMotionHistory(silhouette,mhi,timestamp,duration)-> None}
 795
 796 \begin{description}
 797 \cvarg{silhouette}{Silhouette mask that has non-zero pixels where the motion occurs}
 798 \cvarg{mhi}{Motion history image, that is updated by the function (single-channel, 32-bit floating-point)}
 799 \cvarg{timestamp}{Current time in milliseconds or other units}
 800 \cvarg{duration}{Maximal duration of the motion track in the same units as \texttt{timestamp}}
 801 \end{description}
 802
 803 The function updates the motion history image as following:
 804
 805 \[
 806 \texttt{mhi}(x,y)=\forkthree
 807 {\texttt{timestamp}}{if $\texttt{silhouette}(x,y) \ne 0$}
 808 {0}{if $\texttt{silhouette}(x,y) = 0$ and $\texttt{mhi} < (\texttt{timestamp} - \texttt{duration})$}
 809 {\texttt{mhi}(x,y)}{otherwise}
 810 \]
 811 That is, MHI pixels where motion occurs are set to the current timestamp, while the pixels where motion happened far ago are cleared.
 812
 813 \fi
 814
 815 \ifCpp
 816
 817 \cvCppFunc{accumulate}
 818 Adds image to the accumulator.
 819
 820 \cvdefCpp{void accumulate( const Mat\& src, Mat\& dst, const Mat\& mask=Mat() );}
 821 \begin{description}
 822 \cvarg{src}{The input image, 1- or 3-channel, 8-bit or 32-bit floating point}
 823 \cvarg{dst}{The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point}
 824 \cvarg{mask}{Optional operation mask}
 825 \end{description}
 826
 827 The function adds \texttt{src}, or some of its elements, to \texttt{dst}:
 828
 829 \[ \texttt{dst}(x,y) \leftarrow \texttt{dst}(x,y) + \texttt{src}(x,y) \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
 830
 831 The function supports multi-channel images; each channel is processed independently.
 832
 833 The functions \texttt{accumulate*} can be used, for example, to collect statistic of background of a scene, viewed by a still camera, for the further foreground-background segmentation.
 834
 835 See also: \cvCppCross{accumulateSquare}, \cvCppCross{accumulateProduct}, \cvCppCross{accumulateWeighted}
 836
 837 \cvCppFunc{accumulateSquare}
 838 Adds the square of the source image to the accumulator.
 839
 840 \cvdefCpp{void accumulateSquare( const Mat\& src, Mat\& dst, \par const Mat\& mask=Mat() );}
 841 \begin{description}
 842 \cvarg{src}{The input image, 1- or 3-channel, 8-bit or 32-bit floating point}
 843 \cvarg{dst}{The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point}
 844 \cvarg{mask}{Optional operation mask}
 845 \end{description}
 846
 847 The function adds the input image \texttt{src} or its selected region, raised to power 2, to the accumulator \texttt{dst}:
 848
 849 \[ \texttt{dst}(x,y) \leftarrow \texttt{dst}(x,y) + \texttt{src}(x,y)^2 \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
 850
 851 The function supports multi-channel images; each channel is processed independently.
 852
 853 See also: \cvCppCross{accumulateSquare}, \cvCppCross{accumulateProduct}, \cvCppCross{accumulateWeighted}
 854
 855 \cvCppFunc{accumulateProduct}
 856 Adds the per-element product of two input images to the accumulator.
 857
 858 \cvdefCpp{void accumulateProduct( const Mat\& src1, const Mat\& src2,\par
 859                         Mat\& dst, const Mat\& mask=Mat() );}
 860 \begin{description}
 861 \cvarg{src1}{The first input image, 1- or 3-channel, 8-bit or 32-bit floating point}
 862 \cvarg{src2}{The second input image of the same type and the same size as \texttt{src1}}
 863 \cvarg{dst}{Accumulator with the same number of channels as input images, 32-bit or 64-bit floating-point}
 864 \cvarg{mask}{Optional operation mask}
 865 \end{description}
 866
 867 The function adds the product of 2 images or their selected regions to the accumulator \texttt{dst}:
 868
 869 \[ \texttt{dst}(x,y) \leftarrow \texttt{dst}(x,y) + \texttt{src1}(x,y) \cdot \texttt{src2}(x,y) \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
 870
 871 The function supports multi-channel images; each channel is processed independently.
 872
 873 See also: \cvCppCross{accumulate}, \cvCppCross{accumulateSquare}, \cvCppCross{accumulateWeighted}
 874
 875 \cvCppFunc{accumulateWeighted}
 876 Updates the running average.
 877
 878 \cvdefCpp{void accumulateWeighted( const Mat\& src, Mat\& dst,\par
 879                          double alpha, const Mat\& mask=Mat() );}
 880 \begin{description}
 881 \cvarg{src}{The input image, 1- or 3-channel, 8-bit or 32-bit floating point}
 882 \cvarg{dst}{The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point}
 883 \cvarg{alpha}{Weight of the input image}
 884 \cvarg{mask}{Optional operation mask}
 885 \end{description}
 886
 887 The function calculates the weighted sum of the input image
 888 \texttt{src} and the accumulator \texttt{dst} so that \texttt{dst}
 889 becomes a running average of frame sequence:
 890
 891 \[ \texttt{dst}(x,y) \leftarrow (1-\texttt{alpha}) \cdot \texttt{dst}(x,y) + \texttt{alpha} \cdot \texttt{src}(x,y) \quad \text{if} \quad \texttt{mask}(x,y) \ne 0 \]
 892
 893 that is, \texttt{alpha} regulates the update speed (how fast the accumulator "forgets" about earlier images).
 894 The function supports multi-channel images; each channel is processed independently.
 895
 896 See also: \cvCppCross{accumulate}, \cvCppCross{accumulateSquare}, \cvCppCross{accumulateProduct}
 897
 898 \cvCppFunc{calcOpticalFlowPyrLK}
 899 Calculates the optical flow for a sparse feature set using the iterative Lucas-Kanade method with pyramids
 900
 901 \cvdefCpp{void calcOpticalFlowPyrLK( const Mat\& prevImg, const Mat\& nextImg,\par
 902         const vector<Point2f>\& prevPts, vector<Point2f>\& nextPts,\par
 903         vector<uchar>\& status, vector<float>\& err, \par
 904         Size winSize=Size(15,15), int maxLevel=3,\par
 905         TermCriteria criteria=TermCriteria(\par
 906             TermCriteria::COUNT+TermCriteria::EPS, 30, 0.01),\par
 907         double derivLambda=0.5, int flags=0 );}
 908 \begin{description}
 909 \cvarg{prevImg}{The first 8-bit single-channel or 3-channel input image}
 910 \cvarg{nextImg}{The second input image of the same size and the same type as \texttt{prevImg}}
 911 \cvarg{prevPts}{Vector of points for which the flow needs to be found}
 912 \cvarg{nextPts}{The output vector of points containing the calculated new positions of the input features in the second image}
 913 \cvarg{status}{The output status vector. Each element of the vector is set to 1 if the flow for the corresponding features has been found, 0 otherwise}
 914 \cvarg{err}{The output vector that will contain the difference between patches around the original and moved points}
 915 \cvarg{winSize}{Size of the search window at each pyramid level}
 916 \cvarg{maxLevel}{0-based maximal pyramid level number. If 0, pyramids are not used (single level), if 1, two levels are used etc.}
 917 \cvarg{criteria}{Specifies the termination criteria of the iterative search algorithm (after the specified maximum number of iterations \texttt{criteria.maxCount} or when the search window moves by less than \texttt{criteria.epsilon}}
 918 \cvarg{derivLambda}{The relative weight of the spatial image derivatives impact to the optical flow estimation. If \texttt{derivLambda=0}, only the image intensity is used, if \texttt{derivLambda=1}, only derivatives are used. Any other values between 0 and 1 means that both derivatives and the image intensity are used (in the corresponding proportions).}
 919 \cvarg{flags}{The operation flags:
 920 \begin{description}
 921   \cvarg{OPTFLOW\_USE\_INITIAL\_FLOW}{use initial estimations stored in \texttt{nextPts}. If the flag is not set, then initially $\texttt{nextPts}\leftarrow\texttt{prevPts}$}
 922 \end{description}}
 923 \end{description}
 924
 925 The function implements the sparse iterative version of the Lucas-Kanade optical flow in pyramids, see \cite{Bouguet00}.
 926
 927 \cvCppFunc{calcOpticalFlowFarneback}
 928 Computes dense optical flow using Gunnar Farneback's algorithm
 929
 930 \cvdefCpp{void calcOpticalFlowFarneback( const Mat\& prevImg, const Mat\& nextImg,\par
 931                                Mat\& flow, double pyrScale, int levels, int winsize,\par
 932                                int iterations, int polyN, double polySigma, int flags );}
 933 \begin{description}
 934 \cvarg{prevImg}{The first 8-bit single-channel input image}
 935 \cvarg{nextImg}{The second input image of the same size and the same type as \texttt{prevImg}}
 936 \cvarg{flow}{The computed flow image; will have the same size as \texttt{prevImg} and type \texttt{CV\_32FC2}}
 937 \cvarg{pyrScale}{Specifies the image scale (<1) to build the pyramids for each image. \texttt{pyrScale=0.5} means the classical pyramid, where each next layer is twice smaller than the previous}
 938 \cvarg{levels}{The number of pyramid layers, including the initial image. \texttt{levels=1} means that no extra layers are created and only the original images are used}
 939 \cvarg{winsize}{The averaging window size; The larger values increase the algorithm robustness to image noise and give more chances for fast motion detection, but yield more blurred motion field}
 940 \cvarg{iterations}{The number of iterations the algorithm does at each pyramid level}
 941 \cvarg{polyN}{Size of the pixel neighborhood used to find polynomial expansion in each pixel. The larger values mean that the image will be approximated with smoother surfaces, yielding more robust algorithm and more blurred  motion field. Typically, \texttt{polyN}=5 or 7}
 942 \cvarg{polySigma}{Standard deviation of the Gaussian that is used to smooth derivatives that are used as a basis for the polynomial expansion. For \texttt{polyN=5} you can set \texttt{polySigma=1.1}, for \texttt{polyN=7} a good value would be \texttt{polySigma=1.5}}
 943 \cvarg{flags}{The operation flags; can be a combination of the following:
 944 \begin{description}
 945     \cvarg{OPTFLOW\_USE\_INITIAL\_FLOW}{Use the input \texttt{flow} as the initial flow approximation}
 946     \cvarg{OPTFLOW\_FARNEBACK\_GAUSSIAN}{Use a Gaussian $\texttt{winsize}\times\texttt{winsize}$ filter instead of box filter of the same size for optical flow estimation. Usually, this option gives more accurate flow than with a box filter, at the cost of lower speed (and normally \texttt{winsize} for a Gaussian window should be set to a larger value to achieve the same level of robustness)}
 947 \end{description}}
 948 \end{description}
 949
 950 The function finds optical flow for each \texttt{prevImg} pixel using the alorithm so that
 951
 952 \[\texttt{prevImg}(x,y) \sim \texttt{nextImg}(\texttt{flow}(x,y)[0], \texttt{flow}(x,y)[1])\]
 953
 954
 955 \cvCppFunc{updateMotionHistory}
 956 Updates the motion history image by a moving silhouette.
 957
 958 \cvdefCpp{void updateMotionHistory( const Mat\& silhouette, Mat\& mhi,\par
 959                           double timestamp, double duration );}
 960 \begin{description}
 961 \cvarg{silhouette}{Silhouette mask that has non-zero pixels where the motion occurs}
 962 \cvarg{mhi}{Motion history image, that is updated by the function (single-channel, 32-bit floating-point)}
 963 \cvarg{timestamp}{Current time in milliseconds or other units}
 964 \cvarg{duration}{Maximal duration of the motion track in the same units as \texttt{timestamp}}
 965 \end{description}
 966
 967 The function updates the motion history image as following:
 968
 969 \[
 970 \texttt{mhi}(x,y)=\forkthree
 971 {\texttt{timestamp}}{if $\texttt{silhouette}(x,y) \ne 0$}
 972 {0}{if $\texttt{silhouette}(x,y) = 0$ and $\texttt{mhi} < (\texttt{timestamp} - \texttt{duration})$}
 973 {\texttt{mhi}(x,y)}{otherwise}
 974 \]
 975 That is, MHI pixels where motion occurs are set to the current \texttt{timestamp}, while the pixels where motion happened last time a long time ago are cleared.
 976
 977 The function, together with \cvCppCross{calcMotionGradient} and \cvCppCross{calcGlobalOrientation}, implements the motion templates technique, described in \cite{Davis97} and \cite{Bradski00}.
 978 See also the OpenCV sample \texttt{motempl.c} that demonstrates the use of all the motion template functions.
 979
 980 \cvCppFunc{calcMotionGradient}
 981 Calculates the gradient orientation of a motion history image.
 982
 983 \cvdefCpp{void calcMotionGradient( const Mat\& mhi, Mat\& mask,\par
 984                          Mat\& orientation,\par
 985                          double delta1, double delta2,\par
 986                          int apertureSize=3 );}
 987 \begin{description}
 988 \cvarg{mhi}{Motion history single-channel floating-point image}
 989 \cvarg{mask}{The output mask image; will have the type \texttt{CV\_8UC1} and the same size as \texttt{mhi}. Its non-zero elements will mark pixels where the motion gradient data is correct}
 990 \cvarg{orientation}{The output motion gradient orientation image; will have the same type and the same size as \texttt{mhi}. Each pixel of it will the motion orientation in degrees, from 0 to 360.}
 991 \cvarg{delta1, delta2}{The minimal and maximal allowed difference between \texttt{mhi} values within a pixel neighorhood. That is, the function finds the minimum ($m(x,y)$) and maximum ($M(x,y)$) \texttt{mhi} values over $3 \times 3$ neighborhood of each pixel and marks the motion orientation at $(x, y)$ as valid only if
 992 \[
 993 \min(\texttt{delta1} , \texttt{delta2} ) \le M(x,y)-m(x,y) \le \max(\texttt{delta1} ,\texttt{delta2}).
 994 \]}
 995 \cvarg{apertureSize}{The aperture size of \cvCppCross{Sobel} operator}
 996 \end{description}
 997
 998 The function calculates the gradient orientation at each pixel $(x, y)$ as:
 999
1000 \[
1001 \texttt{orientation}(x,y)=\arctan{\frac{d\texttt{mhi}/dy}{d\texttt{mhi}/dx}}
1002 \]
1003
1004 (in fact, \cvCppCross{fastArctan} and \cvCppCross{phase} are used, so that the computed angle is measured in degrees and covers the full range 0..360). Also, the \texttt{mask} is filled to indicate pixels where the computed angle is valid.
1005
1006 \cvCppFunc{calcGlobalOrientation}
1007 Calculates the global motion orientation in some selected region.
1008
1009 \cvdefCpp{double calcGlobalOrientation( const Mat\& orientation, const Mat\& mask,\par
1010                               const Mat\& mhi, double timestamp,\par
1011                               double duration );}
1012 \begin{description}
1013 \cvarg{orientation}{Motion gradient orientation image, calculated by the function \cvCppCross{calcMotionGradient}}
1014 \cvarg{mask}{Mask image. It may be a conjunction of a valid gradient mask, also calculated by \cvCppCross{calcMotionGradient}, and the mask of the region, whose direction needs to be calculated}
1015 \cvarg{mhi}{The motion history image, calculated by \cvCppCross{updateMotionHistory}}
1016 \cvarg{timestamp}{The timestamp passed to \cvCppCross{updateMotionHistory}}
1017 \cvarg{duration}{Maximal duration of motion track in milliseconds, passed to \cvCppCross{updateMotionHistory}}
1018 \end{description}
1019
1020 The function calculates the average
1021 motion direction in the selected region and returns the angle between
1022 0 degrees  and 360 degrees. The average direction is computed from
1023 the weighted orientation histogram, where a recent motion has larger
1024 weight and the motion occurred in the past has smaller weight, as recorded in \texttt{mhi}.
1025
1026 \cvCppFunc{CamShift}
1027 Finds the object center, size, and orientation
1028
1029 \cvdefCpp{RotatedRect CamShift( const Mat\& probImage, Rect\& window,\par
1030                       TermCriteria criteria );}
1031 \begin{description}
1032 \cvarg{probImage}{Back projection of the object histogram; see \cvCppCross{calcBackProject}}
1033 \cvarg{window}{Initial search window}
1034 \cvarg{criteria}{Stop criteria for the underlying \cvCppCross{meanShift}}
1035 \end{description}
1036
1037 The function implements the CAMSHIFT object tracking algrorithm
1038 \cite{Bradski98}.
1039 First, it finds an object center using \cvCppCross{meanShift} and then adjust the window size and finds the optimal rotation. The function returns the rotated rectangle structure that includes the object position, size and the orientation. The next position of the search window can be obtained with \texttt{RotatedRect::boundingRect()}.
1040
1041 See the OpenCV sample \texttt{camshiftdemo.c} that tracks colored objects.
1042
1043 \cvCppFunc{meanShift}
1044 Finds the object on a back projection image.
1045
1046 \cvdefCpp{int meanShift( const Mat\& probImage, Rect\& window,\par
1047                TermCriteria criteria );}
1048 \begin{description}
1049 \cvarg{probImage}{Back projection of the object histogram; see \cvCppCross{calcBackProject}}
1050 \cvarg{window}{Initial search window}
1051 \cvarg{criteria}{The stop criteria for the iterative search algorithm}
1052 \end{description}
1053
1054 The function implements iterative object search algorithm. It takes the object back projection on input and the initial position. The mass center in \texttt{window} of the back projection image is computed and the search window center shifts to the mass center. The procedure is repeated until the specified number of iterations \texttt{criteria.maxCount} is done or until the window center shifts by less than \texttt{criteria.epsilon}. The algorithm is used inside \cvCppCross{CamShift} and, unlike \cvCppCross{CamShift}, the search window size or orientation do not change during the search. You can simply pass the output of \cvCppCross{calcBackProject} to this function, but better results can be obtained if you pre-filter the back projection and remove the noise (e.g. by retrieving connected components with \cvCppCross{findContours}, throwing away contours with small area (\cvCppCross{contourArea}) and rendering the  remaining contours with \cvCppCross{drawContours})
1055
1056
1057 \cvclass{KalmanFilter}
1058 Kalman filter class
1059
1060 \begin{lstlisting}
1061 class KalmanFilter
1062 {
1063 public:
1064     KalmanFilter();newline
1065     KalmanFilter(int dynamParams, int measureParams, int controlParams=0);newline
1066     void init(int dynamParams, int measureParams, int controlParams=0);newline
1067     // predicts statePre from statePost
1068     const Mat& predict(const Mat& control=Mat());newline
1069     // corrects statePre based on the input measurement vector
1070     // and stores the result to statePost.
1071     const Mat& correct(const Mat& measurement);newline
1072
1073     Mat statePre;           // predicted state (x'(k)):
1074                             //    x(k)=A*x(k-1)+B*u(k)
1075     Mat statePost;          // corrected state (x(k)):
1076                             //    x(k)=x'(k)+K(k)*(z(k)-H*x'(k))
1077     Mat transitionMatrix;   // state transition matrix (A)
1078     Mat controlMatrix;      // control matrix (B)
1079                             //   (it is not used if there is no control)
1080     Mat measurementMatrix;  // measurement matrix (H)
1081     Mat processNoiseCov;    // process noise covariance matrix (Q)
1082     Mat measurementNoiseCov;// measurement noise covariance matrix (R)
1083     Mat errorCovPre;        // priori error estimate covariance matrix (P'(k)):
1084                             //    P'(k)=A*P(k-1)*At + Q)*/
1085     Mat gain;               // Kalman gain matrix (K(k)):
1086                             //    K(k)=P'(k)*Ht*inv(H*P'(k)*Ht+R)
1087     Mat errorCovPost;       // posteriori error estimate covariance matrix (P(k)):
1088                             //    P(k)=(I-K(k)*H)*P'(k)
1089     ...
1090 };
1091 \end{lstlisting}
1092
1093 The class implements standard Kalman filter \url{http://en.wikipedia.org/wiki/Kalman_filter}. However, you can modify \texttt{transitionMatrix}, \texttt{controlMatrix} and \texttt{measurementMatrix} to get the extended Kalman filter functionality. See the OpenCV sample \texttt{kalman.c}
1094
1095 \fi