Table Of Contents

Previous topic

Dense Optical Flow

Next topic

Optical flow input / output

Motion Templates

Motion templates is alternative technique for detecting motion and computing its direction. See samples/


Updates the motion history image by a moving silhouette.

C++: void updateMotionHistory(InputArray silhouette, InputOutputArray mhi, double timestamp, double duration)
Python: cv2.updateMotionHistory(silhouette, mhi, timestamp, duration) → mhi
  • silhouette – Silhouette mask that has non-zero pixels where the motion occurs.
  • mhi – Motion history image that is updated by the function (single-channel, 32-bit floating-point).
  • timestamp – Current time in milliseconds or other units.
  • duration – Maximal duration of the motion track in the same units as timestamp .

The function updates the motion history image as follows:

\texttt{mhi} (x,y)= \forkthree{\texttt{timestamp}}{if $\texttt{silhouette}(x,y) \ne 0$}{0}{if $\texttt{silhouette}(x,y) = 0$ and $\texttt{mhi} < (\texttt{timestamp} - \texttt{duration})$}{\texttt{mhi}(x,y)}{otherwise}

That is, MHI pixels where the motion occurs are set to the current timestamp , while the pixels where the motion happened last time a long time ago are cleared.

The function, together with calcMotionGradient() and calcGlobalOrientation() , implements a motion templates technique described in [Davis97] and [Bradski00].


Calculates a gradient orientation of a motion history image.

C++: void calcMotionGradient(InputArray mhi, OutputArray mask, OutputArray orientation, double delta1, double delta2, int apertureSize=3 )
Python: cv2.calcMotionGradient(mhi, delta1, delta2[, mask[, orientation[, apertureSize]]]) → mask, orientation
  • mhi – Motion history single-channel floating-point image.
  • mask – Output mask image that has the type CV_8UC1 and the same size as mhi . Its non-zero elements mark pixels where the motion gradient data is correct.
  • orientation – Output motion gradient orientation image that has the same type and the same size as mhi . Each pixel of the image is a motion orientation, from 0 to 360 degrees.
  • delta1 – Minimal (or maximal) allowed difference between mhi values within a pixel neighborhood.
  • delta2

    Maximal (or minimal) allowed difference between mhi values within a pixel neighborhood. That is, the function finds the minimum ( m(x,y) ) and maximum ( M(x,y) ) mhi values over 3 \times 3 neighborhood of each pixel and marks the motion orientation at (x, y) as valid only if

    \min ( \texttt{delta1}  ,  \texttt{delta2}  )  \le  M(x,y)-m(x,y)  \le   \max ( \texttt{delta1}  , \texttt{delta2} ).

  • apertureSize – Aperture size of the Sobel() operator.

The function calculates a gradient orientation at each pixel (x, y) as:

\texttt{orientation} (x,y)= \arctan{\frac{d\texttt{mhi}/dy}{d\texttt{mhi}/dx}}

In fact, fastAtan2() and phase() are used so that the computed angle is measured in degrees and covers the full range 0..360. Also, the mask is filled to indicate pixels where the computed angle is valid.


  • (Python) An example on how to perform a motion template technique can be found at opencv_source_code/samples/python2/


Calculates a global motion orientation in a selected region.

C++: double calcGlobalOrientation(InputArray orientation, InputArray mask, InputArray mhi, double timestamp, double duration)
Python: cv2.calcGlobalOrientation(orientation, mask, mhi, timestamp, duration) → retval

The function calculates an average motion direction in the selected region and returns the angle between 0 degrees and 360 degrees. The average direction is computed from the weighted orientation histogram, where a recent motion has a larger weight and the motion occurred in the past has a smaller weight, as recorded in mhi .


Splits a motion history image into a few parts corresponding to separate independent motions (for example, left hand, right hand).

C++: void segmentMotion(InputArray mhi, OutputArray segmask, vector<Rect>& boundingRects, double timestamp, double segThresh)
Python: cv2.segmentMotion(mhi, timestamp, segThresh[, segmask]) → segmask, boundingRects
  • mhi – Motion history image.
  • segmask – Image where the found mask should be stored, single-channel, 32-bit floating-point.
  • boundingRects – Vector containing ROIs of motion connected components.
  • timestamp – Current time in milliseconds or other units.
  • segThresh – Segmentation threshold that is recommended to be equal to the interval between motion history “steps” or greater.

The function finds all of the motion segments and marks them in segmask with individual values (1,2,...). It also computes a vector with ROIs of motion connected components. After that the motion direction for every component can be calculated with calcGlobalOrientation() using the extracted mask of the particular component.

[Bradski00]Davis, J.W. and Bradski, G.R. “Motion Segmentation and Pose Recognition with Motion History Gradients”, WACV00, 2000
[Davis97]Davis, J.W. and Bobick, A.F. “The Representation and Recognition of Action Using Temporal Templates”, CVPR97, 1997