Skip to main content

Object-recognition in images using multiple templates

Project description


Multi-Template-Matching is a package to perform object-recognition in images using one or several smaller template images.
The template and images should have the same bitdepth (8,16,32-bit) and number of channels (single/Grayscale or RGB).
The main function MTM.matchTemplates returns the best predicted locations provided either a score_threshold and/or the expected number of objects in the image.


Using pip, pip install Multi-Template-Matching
Once installed, import MTMshould work.


The package MTM contains mostly 2 important functions:


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.


  • listTemplates:
    list of tuples (LabelString, Grayscale or RGB numpy array) templates to search in each image, associated to a label

  • 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
    one of OpenCV template matching method (0 to 5), default 5=0-mean cross-correlation

  • N_object: int
    expected number of objects in the image

  • score_threshold: float in range [0,1]
    if N>1, returns local minima/maxima respectively below/above the score_threshold

  • 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


  • bestHits:list of match as dictionaries {"TemplateName":string, "BBox":(X, Y, Width, Height), "Score":float} if N=1, return the best matches independently of the score_threshold if N<inf, returns up to N best matches that passed the score_threshold if N=inf, returns all matches that passed the score_threshold

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


The 2nd important function is drawBoxes to display the detections as rectangular bounding boxes on the initial image.
drawBoxes(image, listHit, boxThickness=2, boxColor=(255, 255, 00), showLabel=True, labelColor=(255, 255, 0)

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.


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

  • listHit :
    list of hit as returned by matchTemplates or findMatches

  • boxThickness: int
    thickness of bounding box contour in pixels

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

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

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


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


Check out the jupyter notebook tutorial for some example of how to use the package.
The wiki section of this related repository also provides some information about the implementation.


If you use this implementation for your research, please cite:

Multi-Template Matching: a versatile tool for object-localization in microscopy images;
Laurent SV Thomas, Jochen Gehrig
bioRxiv 619338; doi:


New github releases are automatically archived to Zenodo.

Related projects

See this repo for the implementation as a Fiji plugin.
Here for a KNIME workflow using Multi-Template-Matching.

Origin of the work

This work has been part of the PhD project of Laurent Thomas under supervision of Dr. Jochen Gehrig at:

Digital Biomedical Imaging Systems AG
Freiburger Str. 3
75179 Pforzheim



This project has received funding from the European Union’s Horizon 2020 research and innovation program under the Marie Sklodowska-Curie grant agreement No 721537 ImageInLife.

ImageInLife MarieCurie

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Multi-Template-Matching-1.3.tar.gz (9.5 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page