Home

Welcome to the MultiTemplateMatching-Python wiki!

Below is a description of some key function of the package.

The package MTM contains mostly 2 important functions:

matchTemplates

matchTemplates(listTemplates,  
               image,  
               method=cv2.TM_CCOEFF_NORMED,  
               N_object=float("inf"),   
               score_threshold=0.5,   
               maxOverlap=0.25,   
               searchBox=None)

This function searches each template in the image, and return the best N_object location which offer the best scores and which do not overlap above the maxOverlap threshold.

Parameters

• listTemplates:
  list of tuples (LabelString, Grayscale/RGB numpy array) templates to search in each image, associated to a label
  example for 2 templates to search: [("template1", array1), ("template2", array2)]

• image : Grayscale or RGB numpy array
  image in which to perform the search, it should be the same bitDepth and number of channels than the templates

• method : int, default 5 = 0-mean cross-correlation
  one of OpenCV template matching method (1 to 5)
  the method 0/TM_SQDIFF is not supported. I advise to use one of the normalised score (1,3 or 5), as it's easier to define a threshold (bound to [0;1])

• N_object: int, default to infinity
  expected number of objects in the image. If you don't know, then leave it to infinity and use the score and overlap threshold to filter the hits

• score_threshold: float (in range [0,1] if you use one of the normalised score)
  used if N_object>1, to keep local minima/maxima respectively below/above the score_threshold.
  if N_object=1, then the score threshold is ignored, the highest maxima/lowest minima is returned depending on the score_method.

• maxOverlap: float in range [0,1]
  This is the maximal value for the ratio of the Intersection Over Union (IoU) area between a pair of bounding boxes. If the ratio is over the maxOverlap, the lower score bounding box is discarded.

• searchBox : tuple (X, Y, Width, Height) in pixel unit
  optional rectangular search region as a tuple

Returns

• Pandas DataFrame with 1 row per hit and column "TemplateName"(string), "BBox":(X, Y, Width, Height), "Score":float
  - if N=1, return the best match independently of the score_threshold for version >= 1.6, below version 1.6 it is like for N<inf - if N<inf, returns up to N best matches that passed the score_threshold and maxOverlap - if N=inf, returns all matches that passed the score_threshold and maxOverlap

The function findMatches performs the same detection without the Non-Maxima Suppression.

drawBoxesOnRGB

The 2nd important function is drawBoxesOnRGB to display the detections as rectangular bounding boxes on the initial image.
To be able to visualise the detection as colored bounding boxes, the function return a RGB copy of the image if a grayscale image is provided.
It is also possible to draw the detection bounding boxes on the grayscale image using drawBoxesOnGray (for instance to generate a mask of the detections).

drawBoxesOnRGB(image, 
               hits, 
               boxThickness=2, 
               boxColor=(255, 255, 00), 
               showLabel=True,  
               labelColor=(255, 255, 0), 
               labelScale=0.5 )

This function returns a copy of the image with predicted template locations as bounding boxes overlaid on the image The name of the template can also be displayed on top of the bounding boxes with showLabel=True.

Parameters

• image : numpy array
  image in which the search was performed

• hits : pandas dataframe
  hits as returned by matchTemplates or findMatches

• boxThickness: int
  thickness of bounding box contour in pixels. -1 will fill the bounding box (useful for masks).

• boxColor: (int, int, int)
  RGB color for the bounding box

• showLabel: Boolean, default True
  Display label of the bounding box (field TemplateName)

• labelColor: (int, int, int)
  RGB color for the label

• labelScale: float, default=0.5 scale for the label sizes

Returns

• outImage: RGB image
  original image with predicted template locations depicted as bounding boxes