# pyrtools: tools for multi-scale image processing
[![PyPI Version](https://img.shields.io/pypi/v/pyrtools.svg)](https://pypi.org/project/pyrtools/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/LabForComputationalVision/pyrtools/blob/main/LICENSE)
![Python version](https://img.shields.io/badge/python-3.7|3.8|3.9|3.10-blue.svg)
[![Build Status](https://github.com/LabForComputationalVision/pyrtools/workflows/build/badge.svg)](https://github.com/LabForComputationalVision/pyrtools/actions?query=workflow%3Abuild)
[![Documentation Status](https://readthedocs.org/projects/pyrtools/badge/?version=latest)](https://pyrtools.readthedocs.io/en/latest/?badge=latest)
[![DOI](https://zenodo.org/badge/137527035.svg)](https://zenodo.org/doi/10.5281/zenodo.10161031)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/pyrtools/v1.0.4?filepath=TUTORIALS%2F)
[![codecov](https://codecov.io/gh/LabForComputationalVision/pyrtools/branch/main/graph/badge.svg?token=Ei9TYftdYi)](https://codecov.io/gh/LabForComputationalVision/pyrtools)
Briefly, the tools include:
- Recursive multi-scale image decompositions (pyramids), including
Laplacian pyramids, QMFs, Wavelets, and steerable pyramids. These
operate on 1D or 2D signals of arbitrary dimension.
- Fast 2D convolution routines, with subsampling and boundary-handling.
- Fast point-operations, histograms, histogram-matching.
- Fast synthetic image generation: sine gratings, zone plates, fractals, etc.
- Display routines for images and pyramids. These include several
auto-scaling options, rounding to integer zoom factors to avoid
resampling artifacts, and useful labeling (dimensions and gray-range).
This is a python 3 port of Eero Simoncelli's
[matlabPyrTools](https://github.com/LabForComputationalVision/matlabPyrTools),
but it does not attempt to recreate all of the matlab code from matlabPyrTools.
The goal is to create a Python interface for the C code at the heart of
matlabPyrTools.
**NOTE**: If you are only interested in the complex steerable pyramid, we have a
pytorch implementation in the
[plenoptic](https://github.com/LabForComputationalVision/plenoptic/) package;
the implementation in plenoptic is differentiable.
# Citing us
If you use `pyrtools` in a published academic article or presentation, please
cite us! You can find the link to the most recent release on Zenodo
[here](https://zenodo.org/doi/10.5281/zenodo.10161031) (though please specify
the version you used not the most recent one!). You can also get a formatted
citation at the top right of our [GitHub
repo](https://github.com/LabForComputationalVision/pyrtools)
# Installation
It's recommended you install from pip: `pip install pyrtools`.
If you wish to install from the main branch, it's still recommended
to use pip, just run `pip install .` (or `pip install -e .` if you
want the changes you make in the directory to be reflected in your
install) from the root directory of this project. The core of this
code is the C code, and the pip install will compile it nicely.
# Pyramid resources
If you would like to learn more about pyramids and why they're helpful
for image processing, here are some resources to get you started:
- Brian Wandell's [Foundations of
Vision](https://foundationsofvision.stanford.edu/chapter-8-multiresolution-image-representations/),
chapter 8 (the rest of the book is helpful if you want to
understand the basics of the visual system).
- [Adelson et al, 1984, "Pyramid methods in image
processing".](http://persci.mit.edu/pub_pdfs/RCA84.pdf)
- Notes from David Heeger on [steerable
filters](http://www.cns.nyu.edu/~david/handouts/steerable.pdf)
- Notes from Eero Simoncelli on [the Steerable
Pyramid](http://www.cns.nyu.edu/~eero/STEERPYR/)
# Usage:
- load modules:
```
import pyrtools as pt
```
- create pyramid:
```
pyr = pt.pyramids.LaplacianPyramid(img)
```
- reconstruct image from pyramid:
```
recon_img = pyr.recon_pyr()
```
Please see `TUTORIALS/02_pyramids.ipynb` for more examples.
# For developres
## Testing
You can find unit tests in `TESTS/unitTests.py` and run them with `python
TESTS/unitTests.py`.
## Build the documentation
NOTE: If you just want to read the documentation, you do not need to
do this; documentation is built automatically on
[readthedocs](https://pyrtools.readthedocs.io/en/latest/).
However, it can be built locally as well. You would do this if you've
made changes locally to the documentation (or the docstrings) that you
would like to examine before pushing.
```
# create a new virtual environment and then...
# install pyrtools with sphinx and documentation-related dependencies
pip install -e .[docs]
# build documentation
cd docs/
make html
```
The index page of the documentation will then be located at
`docs/_build/html/index.html`, open it in your browser to navigate
around.
Raw data
{
"_id": null,
"home_page": "",
"name": "pyrtools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "image processing,visual information processing,computational models",
"author": "Pyrtools authors",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b6/36/e7c6658c2ca5324883b18ac95b354bf2818f84f090fb47432c652e239373/pyrtools-1.0.4.tar.gz",
"platform": null,
"description": "# pyrtools: tools for multi-scale image processing\n\n[![PyPI Version](https://img.shields.io/pypi/v/pyrtools.svg)](https://pypi.org/project/pyrtools/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/LabForComputationalVision/pyrtools/blob/main/LICENSE)\n![Python version](https://img.shields.io/badge/python-3.7|3.8|3.9|3.10-blue.svg)\n[![Build Status](https://github.com/LabForComputationalVision/pyrtools/workflows/build/badge.svg)](https://github.com/LabForComputationalVision/pyrtools/actions?query=workflow%3Abuild)\n[![Documentation Status](https://readthedocs.org/projects/pyrtools/badge/?version=latest)](https://pyrtools.readthedocs.io/en/latest/?badge=latest)\n[![DOI](https://zenodo.org/badge/137527035.svg)](https://zenodo.org/doi/10.5281/zenodo.10161031)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/pyrtools/v1.0.4?filepath=TUTORIALS%2F)\n[![codecov](https://codecov.io/gh/LabForComputationalVision/pyrtools/branch/main/graph/badge.svg?token=Ei9TYftdYi)](https://codecov.io/gh/LabForComputationalVision/pyrtools)\n\nBriefly, the tools include:\n - Recursive multi-scale image decompositions (pyramids), including\n Laplacian pyramids, QMFs, Wavelets, and steerable pyramids. These\n operate on 1D or 2D signals of arbitrary dimension.\n - Fast 2D convolution routines, with subsampling and boundary-handling.\n - Fast point-operations, histograms, histogram-matching.\n - Fast synthetic image generation: sine gratings, zone plates, fractals, etc.\n - Display routines for images and pyramids. These include several\n auto-scaling options, rounding to integer zoom factors to avoid\n resampling artifacts, and useful labeling (dimensions and gray-range).\n\nThis is a python 3 port of Eero Simoncelli's\n[matlabPyrTools](https://github.com/LabForComputationalVision/matlabPyrTools),\nbut it does not attempt to recreate all of the matlab code from matlabPyrTools.\nThe goal is to create a Python interface for the C code at the heart of\nmatlabPyrTools.\n\n**NOTE**: If you are only interested in the complex steerable pyramid, we have a\npytorch implementation in the\n[plenoptic](https://github.com/LabForComputationalVision/plenoptic/) package;\nthe implementation in plenoptic is differentiable.\n\n# Citing us\n\nIf you use `pyrtools` in a published academic article or presentation, please\ncite us! You can find the link to the most recent release on Zenodo\n[here](https://zenodo.org/doi/10.5281/zenodo.10161031) (though please specify\nthe version you used not the most recent one!). You can also get a formatted\ncitation at the top right of our [GitHub\nrepo](https://github.com/LabForComputationalVision/pyrtools)\n\n# Installation\n\nIt's recommended you install from pip: `pip install pyrtools`.\n\nIf you wish to install from the main branch, it's still recommended\nto use pip, just run `pip install .` (or `pip install -e .` if you\nwant the changes you make in the directory to be reflected in your\ninstall) from the root directory of this project. The core of this\ncode is the C code, and the pip install will compile it nicely.\n\n# Pyramid resources\n\nIf you would like to learn more about pyramids and why they're helpful\nfor image processing, here are some resources to get you started:\n\n - Brian Wandell's [Foundations of\n Vision](https://foundationsofvision.stanford.edu/chapter-8-multiresolution-image-representations/),\n chapter 8 (the rest of the book is helpful if you want to\n understand the basics of the visual system).\n - [Adelson et al, 1984, \"Pyramid methods in image\n processing\".](http://persci.mit.edu/pub_pdfs/RCA84.pdf)\n - Notes from David Heeger on [steerable\n filters](http://www.cns.nyu.edu/~david/handouts/steerable.pdf)\n - Notes from Eero Simoncelli on [the Steerable\n Pyramid](http://www.cns.nyu.edu/~eero/STEERPYR/)\n\n# Usage:\n\n- load modules:\n```\nimport pyrtools as pt\n```\n\n- create pyramid:\n```\npyr = pt.pyramids.LaplacianPyramid(img)\n```\n\n- reconstruct image from pyramid:\n```\nrecon_img = pyr.recon_pyr()\n```\n\nPlease see `TUTORIALS/02_pyramids.ipynb` for more examples.\n\n# For developres\n\n## Testing\n\nYou can find unit tests in `TESTS/unitTests.py` and run them with `python\nTESTS/unitTests.py`.\n\n## Build the documentation\n\nNOTE: If you just want to read the documentation, you do not need to\ndo this; documentation is built automatically on\n[readthedocs](https://pyrtools.readthedocs.io/en/latest/).\n\nHowever, it can be built locally as well. You would do this if you've\nmade changes locally to the documentation (or the docstrings) that you\nwould like to examine before pushing.\n\n```\n# create a new virtual environment and then...\n# install pyrtools with sphinx and documentation-related dependencies\npip install -e .[docs]\n# build documentation\ncd docs/\nmake html\n```\n\nThe index page of the documentation will then be located at\n`docs/_build/html/index.html`, open it in your browser to navigate\naround.\n",
"bugtrack_url": null,
"license": "",
"summary": "Python tools for multi-scale image processing, including Laplacian pyramids, Wavelets, and Steerable Pyramids.",
"version": "1.0.4",
"project_urls": {
"Documentation": "https://pyrtools.readthedocs.io/en/latest/",
"Download": "https://zenodo.org/records/10403034",
"Homepage": "https://github.com/LabForComputationalVision/pyrtools"
},
"split_keywords": [
"image processing",
"visual information processing",
"computational models"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6aaa1183a7aef3ba184360e5a52df906287dda7995a51b3a9724a70d43512017",
"md5": "cf2f96acf546010f070c01f48dbd6530",
"sha256": "814f0277e0cbdfa98cd9498bb00a700be2acea3d0dad88c99f8e2972606d5dd9"
},
"downloads": -1,
"filename": "pyrtools-1.0.4-py3-none-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "cf2f96acf546010f070c01f48dbd6530",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 96056,
"upload_time": "2024-02-14T00:10:20",
"upload_time_iso_8601": "2024-02-14T00:10:20.944103Z",
"url": "https://files.pythonhosted.org/packages/6a/aa/1183a7aef3ba184360e5a52df906287dda7995a51b3a9724a70d43512017/pyrtools-1.0.4-py3-none-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a911e947a654a5fdff5ff30139f8809738652f4e223e3f9ef0d8712645f8d98d",
"md5": "f508a8f8225566e9f2c34fe03a1cb403",
"sha256": "56615b13b65dd889892927822ce66ef4966800aa0142fa79cfafe4aaf4c7ad35"
},
"downloads": -1,
"filename": "pyrtools-1.0.4-py3-none-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "f508a8f8225566e9f2c34fe03a1cb403",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 92809,
"upload_time": "2024-02-14T00:10:22",
"upload_time_iso_8601": "2024-02-14T00:10:22.832513Z",
"url": "https://files.pythonhosted.org/packages/a9/11/e947a654a5fdff5ff30139f8809738652f4e223e3f9ef0d8712645f8d98d/pyrtools-1.0.4-py3-none-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2352e768f66548a0109e8ce5f0a738dc0d7b24f75985a62d4cc09594e9dd5e7c",
"md5": "c0e39a30e3873ef998d793a11bfee25d",
"sha256": "168cc0246cbd9ff1882cb289d85941296ea235bb6234d37ed1689d924927c20a"
},
"downloads": -1,
"filename": "pyrtools-1.0.4-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "c0e39a30e3873ef998d793a11bfee25d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 115437,
"upload_time": "2024-02-14T00:10:24",
"upload_time_iso_8601": "2024-02-14T00:10:24.470938Z",
"url": "https://files.pythonhosted.org/packages/23/52/e768f66548a0109e8ce5f0a738dc0d7b24f75985a62d4cc09594e9dd5e7c/pyrtools-1.0.4-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "468a67682f1657c4740ed501e6ce443b6e130b5f1947e35084fa99ce5f08d824",
"md5": "dcf921400d6d63830e7f2eba6e0b98d9",
"sha256": "c68dc884b17f0860eba42925df4ca7ae0b74aaff623f9f7311d869eb83f50f4f"
},
"downloads": -1,
"filename": "pyrtools-1.0.4-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "dcf921400d6d63830e7f2eba6e0b98d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 98354,
"upload_time": "2024-02-14T00:10:26",
"upload_time_iso_8601": "2024-02-14T00:10:26.203193Z",
"url": "https://files.pythonhosted.org/packages/46/8a/67682f1657c4740ed501e6ce443b6e130b5f1947e35084fa99ce5f08d824/pyrtools-1.0.4-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b636e7c6658c2ca5324883b18ac95b354bf2818f84f090fb47432c652e239373",
"md5": "1dabff698c32d6ce8123205182d89ac6",
"sha256": "c53f636cb0bb071144aa8f1283bf3aa7e53241c0dcd510f64fe594e7a6d74145"
},
"downloads": -1,
"filename": "pyrtools-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "1dabff698c32d6ce8123205182d89ac6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7456158,
"upload_time": "2024-02-14T00:10:27",
"upload_time_iso_8601": "2024-02-14T00:10:27.819198Z",
"url": "https://files.pythonhosted.org/packages/b6/36/e7c6658c2ca5324883b18ac95b354bf2818f84f090fb47432c652e239373/pyrtools-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-14 00:10:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LabForComputationalVision",
"github_project": "pyrtools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyrtools"
}