pyrtools.pyramids package

Subpackages

Submodules

pyrtools.pyramids.GaussianPyramid module

class pyrtools.pyramids.GaussianPyramid.GaussianPyramid(image, height='auto', filter_name='binom5', edge_type='reflect1', **kwargs)[source]

Bases: Pyramid

Gaussian pyramid

Parameters:

  • image (array_like) – 1d or 2d image upon which to construct to the pyramid.

  • height (‘auto’ or int.) – The height of the pyramid. If ‘auto’, will automatically determine based on the size of image.

  • filter_name ({'binomN', 'haar', 'qmf8', 'qmf12', 'qmf16', 'daub2', 'daub3', 'daub4', 'qmf5',) –

    ‘qmf9’, ‘qmf13’} name of filter to use when constructing pyramid. All scaled so L-2 norm is 1.0

    • ’binomN’ - binomial coefficient filter of order N-1

    • ’haar’ - Haar wavelet

    • ’qmf8’, ‘qmf12’, ‘qmf16’ - Symmetric Quadrature Mirror Filters [1]

    • ’daub2’, ‘daub3’, ‘daub4’ - Daubechies wavelet [2]

    • ’qmf5’, ‘qmf9’, ‘qmf13’ - Symmetric Quadrature Mirror Filters [3], [4]

  • edge_type ({'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend', 'dont-compute'}) –

    Specifies how to handle edges. Options are:

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and invert

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

image

The input image used to construct the pyramid.

Type:

array_like

image_size

The size of the input image.

Type:

tuple

pyr_type

Human-readable string specifying the type of pyramid. For base class, is None.

Type:

str or None

edge_type

Specifies how edges were handled.

Type:

str

pyr_coeffs

Dictionary containing the coefficients of the pyramid. Keys are (level, band) tuples and values are 1d or 2d numpy arrays (same number of dimensions as the input image)

Type:

dict

pyr_size

Dictionary containing the sizes of the pyramid coefficients. Keys are (level, band) tuples and values are tuples.

Type:

dict

is_complex

Whether the coefficients are complex- or real-valued. Only SteerablePyramidFreq can have a value of True, all others must be False.

Type:

bool

References

[1]

J D Johnston, “A filter family designed for use in quadrature mirror filter banks”, Proc. ICASSP, pp 291-294, 1980.

[2]

I Daubechies, “Orthonormal bases of compactly supported wavelets”, Commun. Pure Appl. Math, vol. 42, pp 909-996, 1988.

[3]

E P Simoncelli, “Orthogonal sub-band image transforms”, PhD Thesis, MIT Dept. of Elec. Eng. and Comp. Sci. May 1988. Also available as: MIT Media Laboratory Vision and Modeling Technical Report #100.

[4]

E P Simoncelli and E H Adelson, “Subband image coding”, Subband Transforms, chapter 4, ed. John W Woods, Kluwer Academic Publishers, Norwell, MA, 1990, pp 143–192.

Methods

recon_pyr(*args)

Reconstruct the pyramid -- NOT NECESSARY FOR GAUSSIANS
recon_pyr(*args)[source]

Reconstruct the pyramid – NOT NECESSARY FOR GAUSSIANS

pyrtools.pyramids.LaplacianPyramid module

class pyrtools.pyramids.LaplacianPyramid.LaplacianPyramid(image, height='auto', downsample_filter_name='binom5', upsample_filter_name=None, edge_type='reflect1')[source]

Bases: GaussianPyramid

Laplacian pyramid

Parameters:

  • image (array_like) – 1d or 2d image upon which to construct to the pyramid.

  • height (‘auto’ or int.) – The height of the pyramid. If ‘auto’, will automatically determine based on the size of image.

  • downsample_filter_name ({'binomN', 'haar', 'qmf8', 'qmf12', 'qmf16', 'daub2', 'daub3',) –

    ‘daub4’, ‘qmf5’, ‘qmf9’, ‘qmf13’} name of filter to use for (separable) convolution to downsample the image. All scaled so L-2 norm is 1.0

    • ’binomN’ (default: ‘binom5’) - binomial coefficient filter of order N-1

    • ’haar’ - Haar wavelet

    • ’qmf8’, ‘qmf12’, ‘qmf16’ - Symmetric Quadrature Mirror Filters [1]

    • ’daub2’, ‘daub3’, ‘daub4’ - Daubechies wavelet [2]

    • ’qmf5’, ‘qmf9’, ‘qmf13’ - Symmetric Quadrature Mirror Filters [3], [4]

  • upsample_filter_name ({None, 'binomN', 'haar', 'qmf8', 'qmf12', 'qmf16', 'daub2', 'daub3',) –

    ‘daub4’, ‘qmf5’, ‘qmf9’, ‘qmf13’} name of filter to use as the “expansion” filter. All scaled so L-2 norm is 1.0

    • None (default) - same as downsample_filter_name

    • ’binomN’ - binomial coefficient filter of order N-1

    • ’haar’ - Haar wavelet

    • ’qmf8’, ‘qmf12’, ‘qmf16’ - Symmetric Quadrature Mirror Filters [1]

    • ’daub2’, ‘daub3’, ‘daub4’ - Daubechies wavelet [2]

    • ’qmf5’, ‘qmf9’, ‘qmf13’ - Symmetric Quadrature Mirror Filters [3], [4]

  • edge_type ({'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend', 'dont-compute'}) –

    Specifies how to handle edges. Options are:

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and invert

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

image

The input image used to construct the pyramid.

Type:

array_like

image_size

The size of the input image.

Type:

tuple

pyr_type

Human-readable string specifying the type of pyramid. For base class, is None.

Type:

str or None

edge_type

Specifies how edges were handled.

Type:

str

pyr_coeffs

Dictionary containing the coefficients of the pyramid. Keys are (level, band) tuples and values are 1d or 2d numpy arrays (same number of dimensions as the input image)

Type:

dict

pyr_size

Dictionary containing the sizes of the pyramid coefficients. Keys are (level, band) tuples and values are tuples.

Type:

dict

is_complex

Whether the coefficients are complex- or real-valued. Only SteerablePyramidFreq can have a value of True, all others must be False.

Type:

bool

References

[1] (1,2)

J D Johnston, “A filter family designed for use in quadrature mirror filter banks”, Proc. ICASSP, pp 291-294, 1980.

[2] (1,2)

I Daubechies, “Orthonormal bases of compactly supported wavelets”, Commun. Pure Appl. Math, vol. 42, pp 909-996, 1988.

[3] (1,2)

E P Simoncelli, “Orthogonal sub-band image transforms”, PhD Thesis, MIT Dept. of Elec. Eng. and Comp. Sci. May 1988. Also available as: MIT Media Laboratory Vision and Modeling Technical Report #100.

[4] (1,2)

E P Simoncelli and E H Adelson, “Subband image coding”, Subband Transforms, chapter 4, ed. John W Woods, Kluwer Academic Publishers, Norwell, MA, 1990, pp 143–192.

Methods

recon_pyr([upsample_filter_name, edge_type, ...])

Reconstruct the input image using pyramid coefficients
recon_pyr(upsample_filter_name=None, edge_type=None, levels='all')[source]

Reconstruct the input image using pyramid coefficients

Parameters:

  • upsample_filter_name ({None, 'binomN', 'haar', 'qmf8', 'qmf12', 'qmf16', 'daub2', 'daub3',) –

    ‘daub4’, ‘qmf5’, ‘qmf9’, ‘qmf13’} name of filter to use as “expansion” filter. All scaled so L-2 norm is 1.0

    • None (default) - use self.upsample_filter_name, the expansion filter set during

      initialization.

    • ’binomN’ - binomial coefficient filter of order N-1

    • ’haar’ - Haar wavelet

    • ’qmf8’, ‘qmf12’, ‘qmf16’ - Symmetric Quadrature Mirror Filters [1]_

    • ’daub2’, ‘daub3’, ‘daub4’ - Daubechies wavelet [2]_

    • ’qmf5’, ‘qmf9’, ‘qmf13’ - Symmetric Quadrature Mirror Filters [3]_, [4]_

  • edge_type ({None, 'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend',) –

    ‘dont-compute’} Specifies how to handle edges. Options are:

    • None (default) - use self.edge_type, the edge_type used to construct the pyramid

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and invert

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

  • levels (list, int, or {‘all’, ‘residual_highpass’}) – If list should contain some subset of integers from 0 to self.num_scales-1 (inclusive) and ‘residual_lowpass’. If ‘all’, returned value will contain all valid levels. Otherwise, must be one of the valid levels.

Returns:

recon – The reconstructed image.

Return type:

np.array

pyrtools.pyramids.SteerablePyramidFreq module

class pyrtools.pyramids.SteerablePyramidFreq.SteerablePyramidFreq(image, height='auto', order=3, twidth=1, is_complex=False)[source]

Bases: SteerablePyramidBase

Steerable frequency pyramid.

Construct a steerable pyramid on matrix IM, in the Fourier domain. This is similar to Spyr, except that:

  • Reconstruction is exact (within floating point errors)

  • It can produce any number of orientation bands.

  • Typically slower, especially for non-power-of-two sizes.

  • Boundary-handling is circular.

The squared radial functions tile the Fourier plane with a raised-cosine falloff. Angular functions are cos(theta- k*pi/order+1)^(order).

Note that reconstruction will not be exact if the image has an odd shape (due to boundary-handling issues) or if the pyramid is complex with order=0.

Notes

Transform described in [1], filter kernel design described in [2].

Parameters:

  • image (array_like) – 2d image upon which to construct to the pyramid.

  • height (‘auto’ or int.) – The height of the pyramid. If ‘auto’, will automatically determine based on the size of image. If an int, must be non-negative. When height=0, only returns the residuals.

  • order (int.) – The Gaussian derivative order used for the steerable filters. Default value is 3. Note that to achieve steerability the minimum number of orientation is order + 1, and is used here. To get more orientations at the same order, use the method steer_coeffs

  • twidth (int) – The width of the transition region of the radial lowpass function, in octaves

  • is_complex (bool) – Whether the pyramid coefficients should be complex or not. If True, the real and imaginary parts correspond to a pair of odd and even symmetric filters. If False, the coefficients only include the real part / odd symmetric filter.

image

The input image used to construct the pyramid.

Type:

array_like

image_size

The size of the input image.

Type:

tuple

pyr_type

Human-readable string specifying the type of pyramid. For base class, is None.

Type:

str or None

pyr_coeffs

Dictionary containing the coefficients of the pyramid. Keys are (level, band) tuples and values are 1d or 2d numpy arrays (same number of dimensions as the input image), running from fine to coarse.

Type:

dict

pyr_size

Dictionary containing the sizes of the pyramid coefficients. Keys are (level, band) tuples and values are tuples.

Type:

dict

is_complex

Whether the coefficients are complex- or real-valued.

Type:

bool

References

[1]

E P Simoncelli and W T Freeman, “The Steerable Pyramid: A Flexible Architecture for Multi-Scale Derivative Computation,” Second Int’l Conf on Image Processing, Washington, DC, Oct 1995.

[2]

A Karasaridis and E P Simoncelli, “A Filter Design Technique for Steerable Pyramid Image Transforms”, ICASSP, Atlanta, GA, May 1996.

Methods

recon_pyr([levels, bands, twidth])

Reconstruct the image, optionally using subset of pyramid coefficients.

steer_coeffs(angles[, even_phase])

Steer pyramid coefficients to the specified angles
recon_pyr(levels='all', bands='all', twidth=1)[source]

Reconstruct the image, optionally using subset of pyramid coefficients.

Parameters:

  • levels (list, int, or {‘all’, ‘residual_highpass’}) – If list should contain some subset of integers from 0 to self.num_scales-1 (inclusive) and ‘residual_lowpass’. If ‘all’, returned value will contain all valid levels. Otherwise, must be one of the valid levels.

  • bands (list, int, or ‘all’.) – If list, should contain some subset of integers from 0 to self.num_orientations-1. If ‘all’, returned value will contain all valid orientations. Otherwise, must be one of the valid orientations.

  • twidth (int) – The width of the transition region of the radial lowpass function, in octaves

Returns:

recon – The reconstructed image.

Return type:

np.array

pyrtools.pyramids.SteerablePyramidSpace module

class pyrtools.pyramids.SteerablePyramidSpace.SteerablePyramidSpace(image, height='auto', order=1, edge_type='reflect1')[source]

Bases: SteerablePyramidBase

Steerable pyramid (using spatial convolutions)

Notes

Transform described in [1], filter kernel design described in [2].

Parameters:

  • image (array_like) – 2d image upon which to construct to the pyramid.

  • height (‘auto’ or int.) – The height of the pyramid. If ‘auto’, will automatically determine based on the size of image.

  • order ({0, 1, 3, 5}.) – The Gaussian derivative order used for the steerable filters. If you want a different value, see SteerablePyramidFreq. Note that to achieve steerability the minimum number of orientation is order + 1, and is used here. To get more orientations at the same order, use the method steer_coeffs

  • edge_type ({'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend', 'dont-compute'}) –

    Specifies how to handle edges. Options are:

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and invert

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

image

The input image used to construct the pyramid.

Type:

array_like

image_size

The size of the input image.

Type:

tuple

pyr_type

Human-readable string specifying the type of pyramid. For base class, is None.

Type:

str or None

edge_type

Specifies how edges were handled.

Type:

str

pyr_coeffs

Dictionary containing the coefficients of the pyramid. Keys are (level, band) tuples and values are 1d or 2d numpy arrays (same number of dimensions as the input image)

Type:

dict

pyr_size

Dictionary containing the sizes of the pyramid coefficients. Keys are (level, band) tuples and values are tuples.

Type:

dict

is_complex

Whether the coefficients are complex- or real-valued. Only SteerablePyramidFreq can have a value of True, all others must be False.

Type:

bool

References

[1]

E P Simoncelli and W T Freeman, “The Steerable Pyramid: A Flexible Architecture for Multi-Scale Derivative Computation,” Second Int’l Conf on Image Processing, Washington, DC, Oct 1995.

[2]

A Karasaridis and E P Simoncelli, “A Filter Design Technique for Steerable Pyramid Image Transforms”, ICASSP, Atlanta, GA, May 1996.

Methods

recon_pyr([order, edge_type, levels, bands])

Reconstruct the image, optionally using subset of pyramid coefficients.

steer_coeffs(angles[, even_phase])

Steer pyramid coefficients to the specified angles
recon_pyr(order=None, edge_type=None, levels='all', bands='all')[source]

Reconstruct the image, optionally using subset of pyramid coefficients.

Parameters:

  • order ({None, 0, 1, 3, 5}.) – the Gaussian derivative order you want to use for the steerable pyramid filters used to reconstruct the pyramid. If None, uses the same order as that used to construct the pyramid.

  • edge_type ({None, 'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend',) –

    ‘dont-compute’} Specifies how to handle edges. Options are:

    • None (default) - use self.edge_type, the edge_type used to construct the pyramid

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and inverts

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

  • levels (list, int, or {‘all’, ‘residual_highpass’}) – If list should contain some subset of integers from 0 to self.num_scales-1 (inclusive) and ‘residual_lowpass’. If ‘all’, returned value will contain all valid levels. Otherwise, must be one of the valid levels.

  • bands (list, int, or ‘all’.) – If list, should contain some subset of integers from 0 to self.num_orientations-1. If ‘all’, returned value will contain all valid orientations. Otherwise, must be one of the valid orientations.

Returns:

recon – The reconstructed image.

Return type:

np.array

pyrtools.pyramids.WaveletPyramid module

class pyrtools.pyramids.WaveletPyramid.WaveletPyramid(image, height='auto', filter_name='qmf9', edge_type='reflect1')[source]

Bases: Pyramid

Multiscale wavelet pyramid

Parameters:

  • image (array_like) – 1d or 2d image upon which to construct to the pyramid.

  • height (‘auto’ or int.) – The height of the pyramid. If ‘auto’, will automatically determine based on the size of image.

  • filter_name ({'binomN', 'haar', 'qmf8', 'qmf12', 'qmf16', 'daub2', 'daub3', 'daub4', 'qmf5',) –

    ‘qmf9’, ‘qmf13’} name of filter to use when constructing pyramid. All scaled so L-2 norm is 1.0

    • ’binomN’ - binomial coefficient filter of order N-1

    • ’haar’ - Haar wavelet

    • ’qmf8’, ‘qmf12’, ‘qmf16’ - Symmetric Quadrature Mirror Filters [1]

    • ’daub2’, ‘daub3’, ‘daub4’ - Daubechies wavelet [2]

    • ’qmf5’, ‘qmf9’, ‘qmf13’ - Symmetric Quadrature Mirror Filters [3], [4]

  • edge_type ({'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend', 'dont-compute'}) –

    Specifies how to handle edges. Options are:

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and invert

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

image

The input image used to construct the pyramid.

Type:

array_like

image_size

The size of the input image.

Type:

tuple

pyr_type

Human-readable string specifying the type of pyramid. For base class, is None.

Type:

str or None

edge_type

Specifies how edges were handled.

Type:

str

pyr_coeffs

Dictionary containing the coefficients of the pyramid. Keys are (level, band) tuples and values are 1d or 2d numpy arrays (same number of dimensions as the input image)

Type:

dict

pyr_size

Dictionary containing the sizes of the pyramid coefficients. Keys are (level, band) tuples and values are tuples.

Type:

dict

is_complex

Whether the coefficients are complex- or real-valued. Only SteerablePyramidFreq can have a value of True, all others must be False.

Type:

bool

References

[1]

J D Johnston, “A filter family designed for use in quadrature mirror filter banks”, Proc. ICASSP, pp 291-294, 1980.

[2]

I Daubechies, “Orthonormal bases of compactly supported wavelets”, Commun. Pure Appl. Math, vol. 42, pp 909-996, 1988.

[3]

E P Simoncelli, “Orthogonal sub-band image transforms”, PhD Thesis, MIT Dept. of Elec. Eng. and Comp. Sci. May 1988. Also available as: MIT Media Laboratory Vision and Modeling Technical Report #100.

[4]

E P Simoncelli and E H Adelson, “Subband image coding”, Subband Transforms, chapter 4, ed. John W Woods, Kluwer Academic Publishers, Norwell, MA, 1990, pp 143–192.

Methods

recon_pyr([filter_name, edge_type, levels, ...])

Reconstruct the input image using pyramid coefficients.
recon_pyr(filter_name=None, edge_type=None, levels='all', bands='all')[source]

Reconstruct the input image using pyramid coefficients.

This function reconstructs the input image using pyramid coefficients.

Parameters:

  • filter_name ({None, 'binomN', 'haar', 'qmf8', 'qmf12', 'qmf16', 'daub2', 'daub3', 'daub4',) –

    ‘qmf5’, ‘qmf9’, ‘qmf13’} name of filter to use for reconstruction. All scaled so L-2 norm is 1.0

    • None (default) - use self.filter_name, the filter used to construct the pyramid.

    • ’binomN’ - binomial coefficient filter of order N-1

    • ’haar’ - Haar wavelet

    • ’qmf8’, ‘qmf12’, ‘qmf16’ - Symmetric Quadrature Mirror Filters [1]_

    • ’daub2’, ‘daub3’, ‘daub4’ - Daubechies wavelet [2]_

    • ’qmf5’, ‘qmf9’, ‘qmf13’ - Symmetric Quadrature Mirror Filters [3]_, [4]_

  • edge_type ({None, 'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend',) –

    ‘dont-compute’} Specifies how to handle edges. Options are:

    • None (default) - use self.edge_type, the edge_type used to construct the pyramid

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and inverts

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

  • levels (list, int, or {‘all’, ‘residual_highpass’}) – If list should contain some subset of integers from 0 to self.num_scales-1 (inclusive) and ‘residual_lowpass’. If ‘all’, returned value will contain all valid levels. Otherwise, must be one of the valid levels.

  • bands (list, int, or ‘all’.) – If list, should contain some subset of integers from 0 to self.num_orientations-1. If ‘all’, returned value will contain all valid orientations. Otherwise, must be one of the valid orientations.

Returns:

recon – The reconstructed image.

Return type:

np.array

pyrtools.pyramids.filters module

pyrtools.pyramids.filters.binomial_filter(order_plus_one)[source]

returns a vector of binomial coefficients of order (order_plus_one-1)

pyrtools.pyramids.filters.named_filter(name)[source]

Some standard 1D filter kernels.

These are returned as column vectors (shape [N, 1]) and scaled such that their L2-norm is 1.0 (except for ‘binomN’)

  • ‘binomN’ - binomial coefficient filter of order N-1

  • ‘haar’ - Haar wavelet

  • ‘qmf8’, ‘qmf12’, ‘qmf16’ - Symmetric Quadrature Mirror Filters [1]

  • ‘daub2’, ‘daub3’, ‘daub4’ - Daubechies wavelet [2]

  • ‘qmf5’, ‘qmf9’, ‘qmf13’ - Symmetric Quadrature Mirror Filters [3], [4]

  • ‘spN_filters’ - steerable pyramid filters of order N (N must be one of {0, 1, 3, 5}) [5],

    [6]

References

[1]

J D Johnston, “A filter family designed for use in quadrature mirror filter banks”, Proc. ICASSP, pp 291-294, 1980.

[2]

I Daubechies, “Orthonormal bases of compactly supported wavelets”, Commun. Pure Appl. Math, vol. 42, pp 909-996, 1988.

[3]

E P Simoncelli, “Orthogonal sub-band image transforms”, PhD Thesis, MIT Dept. of Elec. Eng. and Comp. Sci. May 1988. Also available as: MIT Media Laboratory Vision and Modeling Technical Report #100.

[4]

E P Simoncelli and E H Adelson, “Subband image coding”, Subband Transforms, chapter 4, ed. John W Woods, Kluwer Academic Publishers, Norwell, MA, 1990, pp 143–192.

[5]

E P Simoncelli and W T Freeman, “The Steerable Pyramid: A Flexible Architecture for Multi-Scale Derivative Computation,” Second Int’l Conf on Image Processing, Washington, DC, Oct 1995.

[6]

A Karasaridis and E P Simoncelli, “A Filter Design Technique for Steerable Pyramid Image Transforms”, ICASSP, Atlanta, GA, May 1996.

pyrtools.pyramids.filters.parse_filter(filt, normalize=True)[source]

Parse the name or array like, and return a column shaped filter (which is normalized by default)

Used during pyramid construction.

Parameters:

filt (str or array_like.) – Name of the filter, as accepted by named_filter, or array to use as a filter. See that function for acceptable names.

Returns:

filt – If filt was one of the steerable pyramids, then this will be a dictionary containing the various steerable pyramid filters. Else, it will be an array containing the specified filter.

Return type:

array or dict

See also

named_filter

function that converts filter_name str into an array or dict of arrays.

pyrtools.pyramids.filters.steerable_filters(filter_name)[source]

Steerable pyramid filters.

Transform described in [1], filter kernel design described in [2].

References

[1]

E P Simoncelli and W T Freeman, “The Steerable Pyramid: A Flexible Architecture for Multi-Scale Derivative Computation,” Second Int’l Conf on Image Processing, Washington, DC, Oct 1995.

[2]

A Karasaridis and E P Simoncelli, “A Filter Design Technique for Steerable Pyramid Image Transforms”, ICASSP, Atlanta, GA, May 1996.

pyrtools.pyramids.pyr_utils module

pyrtools.pyramids.pyr_utils.convert_pyr_coeffs_to_pyr(pyr_coeffs)[source]

this function takes a ‘new pyramid’ and returns the coefficients as a list

this is to enable backwards compatibility

Parameters:

pyr_coeffs (dict) – The pyr_coeffs attribute of a pyramid.

Returns:

  • coeffs (list) – list of np.array, which contains the pyramid coefficients in each band, in order from bottom of the pyramid to top (going through the orientations in order)

  • highpass (np.array or None) – either the residual highpass from the pyramid or, if that doesn’t exist, None

  • lowpass (np.array or None) – either the residual lowpass from the pyramid or, if that doesn’t exist, None

pyrtools.pyramids.pyr_utils.max_pyr_height(imsz, filtsz)[source]

Compute maximum pyramid height for given image and filter sizes.

Specifically, this computes the number of corrDn operations that can be sequentially performed when subsampling by a factor of 2.

Parameters:

  • imsz (tuple or int) – the size of the image (should be 2-tuple if image is 2d, int if it’s 1d)

  • filtsz (tuple or int) – the size of the filter (should be 2-tuple if image is 2d, int if it’s 1d)

Returns:

max_pyr_height – The maximum height of the pyramid

Return type:

int

pyrtools.pyramids.pyramid module

class pyrtools.pyramids.pyramid.Pyramid(image, edge_type)[source]

Bases: object

Base class for multiscale pyramids

You should not instantiate this base class, it is instead inherited by the other classes found in this module.

Parameters:

  • image (array_like) – 1d or 2d image upon which to construct to the pyramid.

  • edge_type ({'circular', 'reflect1', 'reflect2', 'repeat', 'zero', 'extend', 'dont-compute'}) –

    Specifies how to handle edges. Options are:

    • ’circular’ - circular convolution

    • ’reflect1’ - reflect about the edge pixels

    • ’reflect2’ - reflect, doubling the edge pixels

    • ’repeat’ - repeat the edge pixels

    • ’zero’ - assume values of zero outside image boundary

    • ’extend’ - reflect and invert

    • ’dont-compute’ - zero output when filter overhangs imput boundaries.

image

The input image used to construct the pyramid.

Type:

array_like

image_size

The size of the input image.

Type:

tuple

pyr_type

Human-readable string specifying the type of pyramid. For base class, is None.

Type:

str or None

edge_type

Specifies how edges were handled.

Type:

str

pyr_coeffs

Dictionary containing the coefficients of the pyramid. Keys are (level, band) tuples and values are 1d or 2d numpy arrays (same number of dimensions as the input image)

Type:

dict

pyr_size

Dictionary containing the sizes of the pyramid coefficients. Keys are (level, band) tuples and values are tuples.

Type:

dict

is_complex

Whether the coefficients are complex- or real-valued. Only SteerablePyramidFreq can have a value of True, all others must be False.

Type:

bool

class pyrtools.pyramids.pyramid.SteerablePyramidBase(image, edge_type)[source]

Bases: Pyramid

base class for steerable pyramid

should not be called directly, we just use it so we can make both SteerablePyramidFreq and SteerablePyramidSpace inherit the steer_coeffs function

Methods

steer_coeffs(angles[, even_phase])

Steer pyramid coefficients to the specified angles
steer_coeffs(angles, even_phase=True)[source]

Steer pyramid coefficients to the specified angles

This allows you to have filters that have the Gaussian derivative order specified in construction, but arbitrary angles or number of orientations.

Parameters:

  • angles (list) – list of angles (in radians) to steer the pyramid coefficients to

  • even_phase (bool) – specifies whether the harmonics are cosine or sine phase aligned about those positions.

Returns:

  • resteered_coeffs (dict) – dictionary of re-steered pyramid coefficients. will have the same number of scales as the original pyramid (though it will not contain the residual highpass or lowpass). like self.pyr_coeffs, keys are 2-tuples of ints indexing the scale and orientation, but now we’re indexing angles instead of self.num_orientations.

  • resteering_weights (dict) – dictionary of weights used to re-steer the pyramid coefficients. will have the same keys as resteered_coeffs.

pyrtools.pyramids.steer module

pyrtools.pyramids.steer.steer(basis, angle, harmonics=None, steermtx=None, return_weights=False, even_phase=True)[source]

Steer BASIS to the specfied ANGLE.

Parameters:

  • basis (array_like) – array whose columns are vectorized rotated copies of a steerable function, or the responses of a set of steerable filters.

  • angle (array_like or int) – scalar or column vector the size of the basis. specifies the angle(s) (in radians) to steer to

  • harmonics (list or None) – a list of harmonic numbers indicating the angular harmonic content of the basis. if None (default), N even or odd low frequencies, as for derivative filters

  • steermtx (array_like or None.) – matrix which maps the filters onto Fourier series components (ordered [cos0 cos1 sin1 cos2 sin2 … sinN]). See steer_to_harmonics_mtx function for more details. If None (default), assumes cosine phase harmonic components, and filter positions at 2pi*n/N.

  • return_weights (bool) – whether to return the weights or not.

  • even_phase (bool) – specifies whether the harmonics are cosine or sine phase aligned about those positions.

Returns:

  • res (np.array) – the resteered basis

  • steervect (np.array) – the weights used to resteer the basis. only returned if return_weights is True

pyrtools.pyramids.steer.steer_to_harmonics_mtx(harmonics, angles=None, even_phase=True)[source]

Compute a steering matrix

This maps a directional basis set onto the angular Fourier harmonics.

Parameters:

  • harmonics (array_like) – array specifying the angular harmonics contained in the steerable basis/filters.

  • angles (array_like or None) – vector specifying the angular position of each filter (in radians). If None, defaults to pi * np.arange(numh) / numh, where numh = harmonics.size + np.count_nonzero(harmonics)

  • even_phase (bool) – specifies whether the harmonics are cosine or sine phase aligned about those positions.

Returns:

imtx – This matrix is suitable for passing to the function steer.

Return type:

np.array

Module contents