pyrtools: tools for multi-scale image processing

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, 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 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 (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

Installation

You can install pyrtools using either pip:

pip install pyrtools

or conda:

conda install pyrtools -c conda-forge

You may also install from source, directly from the git repository. This is largely useful if you are seeking to modify the code or make contributions. To do so, clone the repository and run pip install. On Mac or Linux, that looks like:

git clone https://github.com/LabForComputationalVision/pyrtools.git
cd pyrtools/
pip install .

You may also want an editable install, pip install -e ., in which case changes you make in the source code will be reflected in your install.

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, 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”.
• Notes from David Heeger on steerable filters
• Notes from Eero Simoncelli on the Steerable Pyramid

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.

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.