# PyMatting: A Python Library for Alpha Matting
[](https://opensource.org/licenses/MIT)
[](https://github.com/pymatting/pymatting/actions?query=workflow%3Atests)
[](https://pypi.org/project/PyMatting/)
[](https://joss.theoj.org/papers/9766cab65bfbf07a70c8a835edd3875a)
[](https://gitter.im/pymatting/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
We introduce the PyMatting package for Python which implements various methods to solve the alpha matting problem.
- **Website and Documentation:** [https://pymatting.github.io/](https://pymatting.github.io)
- **Benchmarks:** [https://pymatting.github.io/benchmarks.html](https://pymatting.github.io/benchmarks.html)
Given an input image and a hand-drawn trimap (top row), alpha matting estimates the alpha channel of a foreground object which can then be composed onto a different background (bottom row).
PyMatting provides:
- Alpha matting implementations for:
- Closed Form Alpha Matting [[1]](#1)
- Large Kernel Matting [[2]](#2)
- KNN Matting [[3]](#3)
- Learning Based Digital Matting [[4]](#4)
- Random Walk Matting [[5]](#5)
- Shared Sampling Matting [[6]](#6)
- Foreground estimation implementations for:
- Closed Form Foreground Estimation [[1]](#1)
- Fast Multi-Level Foreground Estimation (CPU, CUDA and OpenCL) [[7]](#7)
- Fast multithreaded KNN search
- Preconditioners to accelerate the convergence rate of conjugate gradient descent:
- The *incomplete thresholded Cholesky decomposition* (*Incomplete* is part of the name. The implementation is quite complete.)
- The V-Cycle Geometric Multigrid preconditioner
- Readable code leveraging [NumPy](https://numpy.org/), [SciPy](https://scipy.org/) and [Numba](http://numba.pydata.org/)
## Getting Started
### Requirements
Minimal requiremens
* numpy>=1.16.0
* pillow>=5.2.0
* numba>=0.47.0
* scipy>=1.1.0
Additional requirements for GPU support
* cupy-cuda90>=6.5.0 or similar
* pyopencl>=2019.1.2
Requirements to run the tests
* pytest>=5.3.4
### Installation with PyPI
```bash
pip3 install pymatting
```
### Installation from Source
```bash
git clone https://github.com/pymatting/pymatting
cd pymatting
pip3 install .
```
## Example
```python
from pymatting import cutout
cutout(
# input image path
"data/lemur/lemur.png",
# input trimap path
"data/lemur/lemur_trimap.png",
# output cutout path
"lemur_cutout.png")
```
[More advanced examples](https://pymatting.github.io/examples.html)
## Trimap Construction
All implemented methods rely on trimaps which roughly classify the image into foreground, background and unknown reagions.
Trimaps are expected to be `numpy.ndarrays` of type `np.float64` having the same shape as the input image with only one color-channel.
Trimap values of 0.0 denote pixels which are 100% background.
Similarly, trimap values of 1.0 denote pixels which are 100% foreground.
All other values indicate unknown pixels which will be estimated by the algorithm.
## Testing
Run the tests from the main directory:
```
python3 tests/download_images.py
pip3 install -r requirements_tests.txt
pytest
```
Currently 89% of the code is covered by tests.
## Upgrade
```bash
pip3 install --upgrade pymatting
python3 -c "import pymatting"
```
## Bug Reports, Questions and Pull-Requests
Please, see [our community guidelines](https://github.com/pymatting/pymatting/blob/master/CONTRIBUTING.md).
## Authors
- **Thomas Germer**
- **Tobias Uelwer**
- **Stefan Conrad**
- **Stefan Harmeling**
See also the list of [contributors](https://github.com/pymatting/pymatting/contributors) who participated in this project.
## Projects using PyMatting
* [Rembg](https://github.com/danielgatis/rembg) - an excellent tool for removing image backgrounds.
* [PaddleSeg](https://github.com/PaddlePaddle/PaddleSeg) - a library for a wide range of image segmentation tasks.
* [chaiNNer](https://github.com/chaiNNer-org/chaiNNer) - a node-based image processing GUI.
* [LSA-Matting](https://github.com/kfeng123/LSA-Matting) - improving deep image matting via local smoothness assumption.
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details
## Citing
If you found PyMatting to be useful for your work, please consider citing our [paper](https://doi.org/10.21105/joss.02481):
```
@article{Germer2020,
doi = {10.21105/joss.02481},
url = {https://doi.org/10.21105/joss.02481},
year = {2020},
publisher = {The Open Journal},
volume = {5},
number = {54},
pages = {2481},
author = {Thomas Germer and Tobias Uelwer and Stefan Conrad and Stefan Harmeling},
title = {PyMatting: A Python Library for Alpha Matting},
journal = {Journal of Open Source Software}
}
```
## References
<a id="1">[1]</a>
Anat Levin, Dani Lischinski, and Yair Weiss. A closed-form solution to natural image matting. IEEE transactions on pattern analysis and machine intelligence, 30(2):228–242, 2007.
<a id="2">[2]</a>
Kaiming He, Jian Sun, and Xiaoou Tang. Fast matting using large kernel matting laplacian matrices. In 2010 IEEE Computer Society Conference on Computer Vision and Pattern Recognition, 2165–2172. IEEE, 2010.
<a id="3">[3]</a>
Qifeng Chen, Dingzeyu Li, and Chi-Keung Tang. Knn matting. IEEE transactions on pattern analysis and machine intelligence, 35(9):2175–2188, 2013.
<a id="4">[4]</a>
Yuanjie Zheng and Chandra Kambhamettu. Learning based digital matting. In 2009 IEEE 12th international conference on computer vision, 889–896. IEEE, 2009.
<a id="5">[5]</a>
Leo Grady, Thomas Schiwietz, Shmuel Aharon, and Rüdiger Westermann. Random walks for interactive alpha-matting. In Proceedings of VIIP, volume 2005, 423–429. 2005.
<a id="6">[6]</a>
Eduardo S. L. Gastal and Manuel M. Oliveira. "Shared Sampling for Real-Time Alpha Matting". Computer Graphics Forum. Volume 29 (2010), Number 2, Proceedings of Eurographics 2010, pp. 575-584.
<a id="7">[7]</a>
Germer, T., Uelwer, T., Conrad, S., & Harmeling, S. (2020). Fast Multi-Level Foreground Estimation. arXiv preprint arXiv:2006.14970.
Lemur image by Mathias Appel from https://www.flickr.com/photos/mathiasappel/25419442300/ licensed under [CC0 1.0 Universal (CC0 1.0) Public Domain License](https://creativecommons.org/publicdomain/zero/1.0/).
Raw data
{
"_id": null,
"home_page": "https://pymatting.github.io",
"name": "PyMatting",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "alpha matting",
"author": "The PyMatting Developers",
"author_email": "pymatting@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/16/e6/a9741c13a5432018170b7f97b997a04e470a0a3b8ab3b5d5d20dde8a9529/PyMatting-1.1.12.tar.gz",
"platform": null,
"description": "# PyMatting: A Python Library for Alpha Matting\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/pymatting/pymatting/actions?query=workflow%3Atests)\n[](https://pypi.org/project/PyMatting/)\n[](https://joss.theoj.org/papers/9766cab65bfbf07a70c8a835edd3875a)\n[](https://gitter.im/pymatting/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)\n\nWe introduce the PyMatting package for Python which implements various methods to solve the alpha matting problem.\n\n- **Website and Documentation:** [https://pymatting.github.io/](https://pymatting.github.io)\n- **Benchmarks:** [https://pymatting.github.io/benchmarks.html](https://pymatting.github.io/benchmarks.html)\n\n\n\nGiven an input image and a hand-drawn trimap (top row), alpha matting estimates the alpha channel of a foreground object which can then be composed onto a different background (bottom row).\n\nPyMatting provides:\n- Alpha matting implementations for:\n - Closed Form Alpha Matting [[1]](#1)\n - Large Kernel Matting [[2]](#2)\n - KNN Matting [[3]](#3)\n - Learning Based Digital Matting [[4]](#4)\n - Random Walk Matting [[5]](#5)\n - Shared Sampling Matting [[6]](#6)\n- Foreground estimation implementations for:\n - Closed Form Foreground Estimation [[1]](#1)\n - Fast Multi-Level Foreground Estimation (CPU, CUDA and OpenCL) [[7]](#7)\n- Fast multithreaded KNN search\n- Preconditioners to accelerate the convergence rate of conjugate gradient descent:\n - The *incomplete thresholded Cholesky decomposition* (*Incomplete* is part of the name. The implementation is quite complete.)\n - The V-Cycle Geometric Multigrid preconditioner\n- Readable code leveraging [NumPy](https://numpy.org/), [SciPy](https://scipy.org/) and [Numba](http://numba.pydata.org/)\n\n## Getting Started\n\n### Requirements\n\nMinimal requiremens\n* numpy>=1.16.0\n* pillow>=5.2.0\n* numba>=0.47.0\n* scipy>=1.1.0\n\nAdditional requirements for GPU support\n* cupy-cuda90>=6.5.0 or similar\n* pyopencl>=2019.1.2\n\nRequirements to run the tests\n* pytest>=5.3.4\n\n### Installation with PyPI\n\n```bash\npip3 install pymatting\n```\n\n### Installation from Source\n\n```bash\ngit clone https://github.com/pymatting/pymatting\ncd pymatting\npip3 install .\n```\n\n## Example\n```python\nfrom pymatting import cutout\n\ncutout(\n # input image path\n \"data/lemur/lemur.png\",\n # input trimap path\n \"data/lemur/lemur_trimap.png\",\n # output cutout path\n \"lemur_cutout.png\")\n```\n\n[More advanced examples](https://pymatting.github.io/examples.html)\n\n## Trimap Construction\n\nAll implemented methods rely on trimaps which roughly classify the image into foreground, background and unknown reagions.\nTrimaps are expected to be `numpy.ndarrays` of type `np.float64` having the same shape as the input image with only one color-channel.\nTrimap values of 0.0 denote pixels which are 100% background.\nSimilarly, trimap values of 1.0 denote pixels which are 100% foreground.\nAll other values indicate unknown pixels which will be estimated by the algorithm.\n\n\n## Testing\n\nRun the tests from the main directory:\n```\n python3 tests/download_images.py\n pip3 install -r requirements_tests.txt\n pytest\n```\n\nCurrently 89% of the code is covered by tests.\n\n## Upgrade\n\n```bash\npip3 install --upgrade pymatting\npython3 -c \"import pymatting\"\n```\n\n## Bug Reports, Questions and Pull-Requests\n\nPlease, see [our community guidelines](https://github.com/pymatting/pymatting/blob/master/CONTRIBUTING.md).\n\n## Authors\n\n- **Thomas Germer**\n- **Tobias Uelwer**\n- **Stefan Conrad**\n- **Stefan Harmeling**\n\nSee also the list of [contributors](https://github.com/pymatting/pymatting/contributors) who participated in this project.\n\n## Projects using PyMatting\n\n* [Rembg](https://github.com/danielgatis/rembg) - an excellent tool for removing image backgrounds.\n* [PaddleSeg](https://github.com/PaddlePaddle/PaddleSeg) - a library for a wide range of image segmentation tasks.\n* [chaiNNer](https://github.com/chaiNNer-org/chaiNNer) - a node-based image processing GUI.\n* [LSA-Matting](https://github.com/kfeng123/LSA-Matting) - improving deep image matting via local smoothness assumption.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details\n\n## Citing\n\nIf you found PyMatting to be useful for your work, please consider citing our [paper](https://doi.org/10.21105/joss.02481):\n\n```\n@article{Germer2020,\n doi = {10.21105/joss.02481},\n url = {https://doi.org/10.21105/joss.02481},\n year = {2020},\n publisher = {The Open Journal},\n volume = {5},\n number = {54},\n pages = {2481},\n author = {Thomas Germer and Tobias Uelwer and Stefan Conrad and Stefan Harmeling},\n title = {PyMatting: A Python Library for Alpha Matting},\n journal = {Journal of Open Source Software}\n}\n```\n\n## References\n\n<a id=\"1\">[1]</a>\nAnat Levin, Dani Lischinski, and Yair Weiss. A closed-form solution to natural image matting. IEEE transactions on pattern analysis and machine intelligence, 30(2):228\u2013242, 2007.\n\n<a id=\"2\">[2]</a>\nKaiming He, Jian Sun, and Xiaoou Tang. Fast matting using large kernel matting laplacian matrices. In 2010 IEEE Computer Society Conference on Computer Vision and Pattern Recognition, 2165\u20132172. IEEE, 2010.\n\n<a id=\"3\">[3]</a>\nQifeng Chen, Dingzeyu Li, and Chi-Keung Tang. Knn matting. IEEE transactions on pattern analysis and machine intelligence, 35(9):2175\u20132188, 2013.\n\n<a id=\"4\">[4]</a>\nYuanjie Zheng and Chandra Kambhamettu. Learning based digital matting. In 2009 IEEE 12th international conference on computer vision, 889\u2013896. IEEE, 2009.\n\n<a id=\"5\">[5]</a>\nLeo Grady, Thomas Schiwietz, Shmuel Aharon, and R\u00fcdiger Westermann. Random walks for interactive alpha-matting. In Proceedings of VIIP, volume 2005, 423\u2013429. 2005.\n\n<a id=\"6\">[6]</a>\nEduardo S. L. Gastal and Manuel M. Oliveira. \"Shared Sampling for Real-Time Alpha Matting\". Computer Graphics Forum. Volume 29 (2010), Number 2, Proceedings of Eurographics 2010, pp. 575-584.\n\n<a id=\"7\">[7]</a>\nGermer, T., Uelwer, T., Conrad, S., & Harmeling, S. (2020). Fast Multi-Level Foreground Estimation. arXiv preprint arXiv:2006.14970.\n\nLemur image by Mathias Appel from https://www.flickr.com/photos/mathiasappel/25419442300/ licensed under [CC0 1.0 Universal (CC0 1.0) Public Domain License](https://creativecommons.org/publicdomain/zero/1.0/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package for alpha matting.",
"version": "1.1.12",
"project_urls": {
"Homepage": "https://pymatting.github.io",
"Source": "https://github.com/pymatting/pymatting"
},
"split_keywords": [
"alpha",
"matting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "46aad7ff530c33c654263d8775ceb50a73f636fc65edbdf09e102c47a3be391b",
"md5": "f4e2144949c19115552a0c12ad610cf3",
"sha256": "f23ad0b8dde0a7e03b8f8dde10d78f9646f3de854eee06f7d87f019c8901dd52"
},
"downloads": -1,
"filename": "PyMatting-1.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4e2144949c19115552a0c12ad610cf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 52988,
"upload_time": "2023-11-30T07:14:17",
"upload_time_iso_8601": "2023-11-30T07:14:17.040769Z",
"url": "https://files.pythonhosted.org/packages/46/aa/d7ff530c33c654263d8775ceb50a73f636fc65edbdf09e102c47a3be391b/PyMatting-1.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16e6a9741c13a5432018170b7f97b997a04e470a0a3b8ab3b5d5d20dde8a9529",
"md5": "324bc45c62a562627d2e155147599127",
"sha256": "639d15d4bcafb26ae21b8648c2630b81c4ecab1756fe24943a911c5ba775c4e5"
},
"downloads": -1,
"filename": "PyMatting-1.1.12.tar.gz",
"has_sig": false,
"md5_digest": "324bc45c62a562627d2e155147599127",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 43848,
"upload_time": "2023-11-30T07:14:19",
"upload_time_iso_8601": "2023-11-30T07:14:19.096327Z",
"url": "https://files.pythonhosted.org/packages/16/e6/a9741c13a5432018170b7f97b997a04e470a0a3b8ab3b5d5d20dde8a9529/PyMatting-1.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-30 07:14:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pymatting",
"github_project": "pymatting",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pymatting"
}
JSON
