modules/imgproc/doc/object_detection.rst

   1 Object Detection
   2 ================
   3
   4 .. highlight:: cpp
   5
   6 matchTemplate
   7 -----------------
   8 Compares a template against overlapped image regions.
   9
  10 .. ocv:function:: void matchTemplate( InputArray image, InputArray templ, OutputArray result, int method )
  11
  12 .. ocv:pyfunction:: cv2.matchTemplate(image, templ, method[, result]) -> result
  13
  14 .. ocv:cfunction:: void cvMatchTemplate( const CvArr* image, const CvArr* templ, CvArr* result, int method )
  15 .. ocv:pyoldfunction:: cv.MatchTemplate(image, templ, result, method)-> None
  16
  17     :param image: Image where the search is running. It must be 8-bit or 32-bit floating-point.
  18
  19     :param templ: Searched template. It must be not greater than the source image and have the same data type.
  20
  21     :param result: Map of comparison results. It must be single-channel 32-bit floating-point. If  ``image``  is  :math:`W \times H`  and ``templ``  is  :math:`w \times h` , then  ``result``  is  :math:`(W-w+1) \times (H-h+1)` .
  22
  23     :param method: Parameter specifying the comparison method (see below).
  24
  25 The function slides through ``image`` , compares the
  26 overlapped patches of size
  27 :math:`w \times h` against ``templ`` using the specified method and stores the comparison results in ``result`` . Here are the formulae for the available comparison
  28 methods (
  29 :math:`I` denotes ``image``, :math:`T` ``template``, :math:`R` ``result`` ). The summation is done over template and/or the
  30 image patch:
  31 :math:`x' = 0...w-1, y' = 0...h-1`
  32 * method=CV\_TM\_SQDIFF
  33
  34     .. math::
  35
  36         R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2
  37
  38 * method=CV\_TM\_SQDIFF\_NORMED
  39
  40     .. math::
  41
  42         R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
  43
  44 * method=CV\_TM\_CCORR
  45
  46     .. math::
  47
  48         R(x,y)= \sum _{x',y'} (T(x',y')  \cdot I(x+x',y+y'))
  49
  50 * method=CV\_TM\_CCORR\_NORMED
  51
  52     .. math::
  53
  54         R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y'))}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
  55
  56 * method=CV\_TM\_CCOEFF
  57
  58     .. math::
  59
  60         R(x,y)= \sum _{x',y'} (T'(x',y')  \cdot I'(x+x',y+y'))
  61
  62     where
  63
  64     .. math::
  65
  66         \begin{array}{l} T'(x',y')=T(x',y') - 1/(w  \cdot h)  \cdot \sum _{x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w  \cdot h)  \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}
  67
  68 * method=CV\_TM\_CCOEFF\_NORMED
  69
  70     .. math::
  71
  72         R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{ \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
  73
  74 After the function finishes the comparison, the best matches can be found as global minimums (when ``CV_TM_SQDIFF`` was used) or maximums (when ``CV_TM_CCORR`` or ``CV_TM_CCOEFF`` was used) using the
  75 :ocv:func:`minMaxLoc` function. In case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels and separate mean values are used for each channel. That is, the function can take a color template and a color image. The result will still be a single-channel image, which is easier to analyze.
  76
  77 .. note::
  78
  79    * (Python) An example on how to match mouse selected regions in an image can be found at opencv_source_code/samples/python2/mouse_and_match.py