[](https://mybinder.org/v2/gh/multi-template-matching/MultiTemplateMatching-Python/master?filepath=tutorials)
[](https://saythanks.io/to/laurent132.thomas@laposte.net)
# Multi-Template-Matching
Multi-Template-Matching is a python package to perform object-recognition in images using one or several smaller template images.
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.
The branch opencl contains some test using the UMat object to run on GPU, but it is actually slow, which can be expected for small dataset as the transfer of the data between the CPU and GPU is slow.
# News
- Version 2.0.0 got rid of the dependency on pandas, the list of hit is simply a python list. The new version also features extensive type hints in functions
- 03/03/2023 : Version 1.6.4 contributed by @bartleboeuf comes with speed enhancement thanks to parallelizing of the individual template searches.
Thanks for this first PR !!
- 10/11/2021 : You might be interested to test the newer python implementation which is more object-oriented and only relying on scikit-image and shapely.*
https://github.com/multi-template-matching/mtm-python-oop
# Installation
Using pip in a python environment, `pip install Multi-Template-Matching`
Once installed, `import MTM`should work.
Example jupyter notebooks can be downloaded from the tutorial folder of the github repository and executed in the newly configured python environement.
## Install in dev mode
If you want to contribute or experiment with the source code, you can install the package "from source", by first downloading or cloning the repo.
Then opening a command prompt in the repo's root directory (the one containing this README) and calling `pip install -e .` (mind the final dot).
- the `-e` flag stands for editable and make sure that any change to the source code will be directly reflected when you import the package in your script
- the . just tell pip to look for the package to install in the current directory
# Documentation
The [wiki](https://github.com/multi-template-matching/MultiTemplateMatching-Python/wiki) section of the repo contains a mini API documentation with description of the key functions of the package.
The [website](https://multi-template-matching.github.io/Multi-Template-Matching/) of the project contains some more general documentation.
# Tips and tricks
- `matchTemplates` expects for the template a list of tuples with one tuple per template in the form (a string identifier for the template, array for the template image). You can generate such list of tuples, from separate lists of the label and template images as following
```python
listLabel = [] # this one should have the string identifier for each template
listTemplate = [] # this one should have the image array for each template, both lists should have the same length
listTemplateTuple = zip(listLabel, listTemplate)
```
Similarly, from the list of hits returned by matchTemplates (or NMS), you can get individual lists for the label, bounding-boxes and scores, using `listLabel, listBbox, listScore = zip(*listHit)`
- To have a nicer formatting (one list item per row) when printing the list of detected hits, you can use the `pprint` function from the pprint module (for pretty print).
It's usually not needed in notebooks (see the example notebooks).
```
from pprint import pprint
pprint(listHit)
```
- Before version 2.0.0, most functions were returning or accepting pandas DataFrame for the list of hit.
You can still get such DataFrame from the list of hits returned by MTM v2.0.0 and later, using the command below
```python
import pandas as pd
listLabel, listBbox, listScore = zip(*listHit)
df = pd.DataFrame({"Label":listLabel,
"bounding box":listBbox,
"Score":listScore})
print(df)
```
You can also stick to previous version of MTM by specifying the version to pip install, or in a requirements.txt or environment.yml
`pip install "Multi-Template-Matching < 2.0.0"
# Examples
Check out the [jupyter notebook tutorial](https://github.com/multi-template-matching/MultiTemplateMatching-Python/tree/master/tutorials) for some example of how to use the package.
You can run the tutorials online using Binder, no configuration needed ! (click the Binder banner on top of this page).
To run the tutorials locally, install the package using pip as described above, then clone the repository and unzip it.
Finally open a jupyter-notebook session in the unzipped folder to be able to open and execute the notebook.
The [wiki](https://github.com/multi-template-matching/MultiTemplateMatching-Fiji/wiki) section of this related repository also provides some information about the implementation.
# Citation
If you use this implementation for your research, please cite:
Thomas, L.S.V., Gehrig, J. Multi-template matching: a versatile tool for object-localization in microscopy images.
BMC Bioinformatics 21, 44 (2020). https://doi.org/10.1186/s12859-020-3363-7
Download the citation as a .ris file from the journal website, [here](https://bmcbioinformatics.biomedcentral.com/articles/10.1186/s12859-020-3363-7.ris).
# Releases
Previous github releases were archived to Zenodo, but the best is to use pip to install specific versions.
[](https://zenodo.org/badge/latestdoi/197186256)
# Related projects
See this [repo](https://github.com/multi-template-matching/MultiTemplateMatching-Fiji) for the implementation as a Fiji plugin.
[Here](https://nodepit.com/workflow/com.nodepit.space%2Flthomas%2Fpublic%2FMulti-Template%20Matching.knwf) 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 ACQUIFER.
<img src="https://github.com/multi-template-matching/MultiTemplateMatching-Python/blob/master/images/Acquifer_Logo_60k_cmyk_300dpi.png" alt="ACQUIFER" width="400" height="80">
# Funding
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.
<p float="left">
<img src="https://github.com/multi-template-matching/MultiTemplateMatching-Python/blob/master/images/ImageInlife.png" alt="ImageInLife" width="130" height="100">
<img src="https://github.com/multi-template-matching/MultiTemplateMatching-Python/blob/master/images/MarieCurie.jpg" alt="MarieCurie" width="130" height="130">
</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/multi-template-matching/MultiTemplateMatching-Python",
"name": "Multi-Template-Matching",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "object-recognition object-localization",
"author": "Laurent Thomas",
"author_email": "laurent132.thomas@laposte.net",
"download_url": "https://files.pythonhosted.org/packages/18/e9/f58c73a64a22086b956472ea33ac139956cdf0b4041c8b9df0c1702c081a/multi_template_matching-2.0.0.tar.gz",
"platform": null,
"description": "[](https://mybinder.org/v2/gh/multi-template-matching/MultiTemplateMatching-Python/master?filepath=tutorials)\r\n\r\n[](https://saythanks.io/to/laurent132.thomas@laposte.net)\r\n\r\n# Multi-Template-Matching\r\nMulti-Template-Matching is a python package to perform object-recognition in images using one or several smaller template images. \r\nThe main function `MTM.matchTemplates` returns the best predicted locations provided either a score_threshold and/or the expected number of objects in the image. \r\n\r\nThe branch opencl contains some test using the UMat object to run on GPU, but it is actually slow, which can be expected for small dataset as the transfer of the data between the CPU and GPU is slow.\r\n\r\n# News\r\n- Version 2.0.0 got rid of the dependency on pandas, the list of hit is simply a python list. The new version also features extensive type hints in functions\r\n- 03/03/2023 : Version 1.6.4 contributed by @bartleboeuf comes with speed enhancement thanks to parallelizing of the individual template searches.\r\nThanks for this first PR !!\r\n- 10/11/2021 : You might be interested to test the newer python implementation which is more object-oriented and only relying on scikit-image and shapely.*\r\nhttps://github.com/multi-template-matching/mtm-python-oop \r\n\r\n# Installation\r\nUsing pip in a python environment, `pip install Multi-Template-Matching` \r\nOnce installed, `import MTM`should work. \r\nExample jupyter notebooks can be downloaded from the tutorial folder of the github repository and executed in the newly configured python environement. \r\n\r\n## Install in dev mode\r\nIf you want to contribute or experiment with the source code, you can install the package \"from source\", by first downloading or cloning the repo. \r\nThen opening a command prompt in the repo's root directory (the one containing this README) and calling `pip install -e .` (mind the final dot). \r\n- the `-e` flag stands for editable and make sure that any change to the source code will be directly reflected when you import the package in your script \r\n- the . just tell pip to look for the package to install in the current directory\r\n\r\n# Documentation\r\nThe [wiki](https://github.com/multi-template-matching/MultiTemplateMatching-Python/wiki) section of the repo contains a mini API documentation with description of the key functions of the package. \r\nThe [website](https://multi-template-matching.github.io/Multi-Template-Matching/) of the project contains some more general documentation.\r\n\r\n# Tips and tricks\r\n\r\n- `matchTemplates` expects for the template a list of tuples with one tuple per template in the form (a string identifier for the template, array for the template image). You can generate such list of tuples, from separate lists of the label and template images as following\r\n\r\n```python\r\nlistLabel = [] # this one should have the string identifier for each template\r\nlistTemplate = [] # this one should have the image array for each template, both lists should have the same length\r\nlistTemplateTuple = zip(listLabel, listTemplate)\r\n```\r\n\r\nSimilarly, from the list of hits returned by matchTemplates (or NMS), you can get individual lists for the label, bounding-boxes and scores, using `listLabel, listBbox, listScore = zip(*listHit)`\r\n\r\n- To have a nicer formatting (one list item per row) when printing the list of detected hits, you can use the `pprint` function from the pprint module (for pretty print). \r\nIt's usually not needed in notebooks (see the example notebooks). \r\n```\r\nfrom pprint import pprint\r\npprint(listHit)\r\n```\r\n\r\n- Before version 2.0.0, most functions were returning or accepting pandas DataFrame for the list of hit. \r\nYou can still get such DataFrame from the list of hits returned by MTM v2.0.0 and later, using the command below \r\n\r\n```python\r\nimport pandas as pd\r\n\r\nlistLabel, listBbox, listScore = zip(*listHit)\r\n\r\ndf = pd.DataFrame({\"Label\":listLabel,\r\n\t\t\t\t \"bounding box\":listBbox,\r\n\t\t\t\t \"Score\":listScore})\r\n\r\nprint(df)\r\n```\r\n\r\nYou can also stick to previous version of MTM by specifying the version to pip install, or in a requirements.txt or environment.yml\r\n`pip install \"Multi-Template-Matching < 2.0.0\"\r\n\r\n# Examples\r\nCheck out the [jupyter notebook tutorial](https://github.com/multi-template-matching/MultiTemplateMatching-Python/tree/master/tutorials) for some example of how to use the package. \r\nYou can run the tutorials online using Binder, no configuration needed ! (click the Binder banner on top of this page). \r\nTo run the tutorials locally, install the package using pip as described above, then clone the repository and unzip it. \r\nFinally open a jupyter-notebook session in the unzipped folder to be able to open and execute the notebook. \r\nThe [wiki](https://github.com/multi-template-matching/MultiTemplateMatching-Fiji/wiki) section of this related repository also provides some information about the implementation.\r\n\r\n# Citation\r\nIf you use this implementation for your research, please cite:\r\n \r\nThomas, L.S.V., Gehrig, J. Multi-template matching: a versatile tool for object-localization in microscopy images. \r\nBMC Bioinformatics 21, 44 (2020). https://doi.org/10.1186/s12859-020-3363-7\r\n\r\nDownload the citation as a .ris file from the journal website, [here](https://bmcbioinformatics.biomedcentral.com/articles/10.1186/s12859-020-3363-7.ris).\r\n\r\n# Releases\r\nPrevious github releases were archived to Zenodo, but the best is to use pip to install specific versions. \r\n[](https://zenodo.org/badge/latestdoi/197186256)\r\n\r\n# Related projects\r\nSee this [repo](https://github.com/multi-template-matching/MultiTemplateMatching-Fiji) for the implementation as a Fiji plugin. \r\n[Here](https://nodepit.com/workflow/com.nodepit.space%2Flthomas%2Fpublic%2FMulti-Template%20Matching.knwf) for a KNIME workflow using Multi-Template-Matching.\r\n\r\n\r\n# Origin of the work\r\nThis work has been part of the PhD project of **Laurent Thomas** under supervision of **Dr. Jochen Gehrig** at ACQUIFER. \r\n\r\n<img src=\"https://github.com/multi-template-matching/MultiTemplateMatching-Python/blob/master/images/Acquifer_Logo_60k_cmyk_300dpi.png\" alt=\"ACQUIFER\" width=\"400\" height=\"80\"> \r\n\r\n# Funding\r\nThis project has received funding from the European Union\u00e2\u20ac\u2122s Horizon 2020 research and innovation program under the Marie Sklodowska-Curie grant agreement No 721537 ImageInLife. \r\n\r\n<p float=\"left\">\r\n<img src=\"https://github.com/multi-template-matching/MultiTemplateMatching-Python/blob/master/images/ImageInlife.png\" alt=\"ImageInLife\" width=\"130\" height=\"100\">\r\n<img src=\"https://github.com/multi-template-matching/MultiTemplateMatching-Python/blob/master/images/MarieCurie.jpg\" alt=\"MarieCurie\" width=\"130\" height=\"130\">\r\n</p>\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Object-recognition in images using multiple templates",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/multi-template-matching/MultiTemplateMatching-Python"
},
"split_keywords": [
"object-recognition",
"object-localization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ab6575350b244c570e83f161d36e4dea143d8987389b95c5abc1606fc3edf3c",
"md5": "f2c47db84509b648d3333d5592d7cc39",
"sha256": "2df539edec03518c69a3b7e5b3c86e5ff056e04c51c1bb9b6773d9839ce4ecb6"
},
"downloads": -1,
"filename": "Multi_Template_Matching-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2c47db84509b648d3333d5592d7cc39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12128,
"upload_time": "2024-06-04T16:58:25",
"upload_time_iso_8601": "2024-06-04T16:58:25.061498Z",
"url": "https://files.pythonhosted.org/packages/7a/b6/575350b244c570e83f161d36e4dea143d8987389b95c5abc1606fc3edf3c/Multi_Template_Matching-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "18e9f58c73a64a22086b956472ea33ac139956cdf0b4041c8b9df0c1702c081a",
"md5": "26ccb65bd39e0a90eb24fd695e4a741e",
"sha256": "58d684e60185708895a254723b1de2dac790098377af401e270f13bb18475af2"
},
"downloads": -1,
"filename": "multi_template_matching-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "26ccb65bd39e0a90eb24fd695e4a741e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11343,
"upload_time": "2024-06-04T16:58:26",
"upload_time_iso_8601": "2024-06-04T16:58:26.851237Z",
"url": "https://files.pythonhosted.org/packages/18/e9/f58c73a64a22086b956472ea33ac139956cdf0b4041c8b9df0c1702c081a/multi_template_matching-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-04 16:58:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "multi-template-matching",
"github_project": "MultiTemplateMatching-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "multi-template-matching"
}
JSON
