Sparse-matrix based Inverse Fast Wavelet Transform (iFWT)

1d reconstrucion using MatrixWaverec

class ptwt.MatrixWaverec(wavelet: Wavelet | str, *, axis: int = -1, orthogonalization: Literal['qr', 'gramschmidt'] = 'qr')

Matrix-based inverse fast wavelet transform.

Example

>>> import ptwt, torch
>>> # generate an input of even length.
>>> data = torch.arange(8, dtype=torch.float32)
>>> matrix_wavedec = ptwt.MatrixWavedec('haar', level=2)
>>> coefficients = matrix_wavedec(data)
>>> matrix_waverec = ptwt.MatrixWaverec('haar')
>>> reconstruction = matrix_waverec(coefficients)

Create the inverse matrix-based fast wavelet transformation.

Parameters:

• wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Refer to the output from pywt.wavelist(kind='discrete') for possible choices.

• axis (int) – The axis transformed by the original decomposition defaults to -1 or the last axis.

• orthogonalization – The method used to orthogonalize boundary filters, see ptwt.constants.OrthogonalizeMethod. Defaults to qr.

Changed in version 1.10: The argument boundary has been renamed to orthogonalization.

Raises:

• NotImplementedError – If the selected orthogonalization mode is not supported.

• ValueError – If the wavelet filters have different lengths or if axis is not an integer.

__call__(coefficients: Sequence[Tensor]) → Tensor

Run the synthesis or inverse matrix FWT.

Parameters:

coefficients – The coefficients produced by the forward transform MatrixWavedec. See ptwt.constants.WaveletCoeff1d.

Returns:

The input signal reconstruction.

Raises:

ValueError – If the decomposition level is not a positive integer or if the coefficients are not in the shape as it is returned from a MatrixWavedec object.

property sparse_ifwt_operator: Tensor

The sparse transformation operator.

If the input signal at all levels is divisible by two, the whole operation is padding-free and can be expressed as a single matrix multiply.

Having concatenated the analysis coefficients,

torch.sparse.mm(sparse_ifwt_operator, coefficients.T)

to computes a batched iFWT.

This functionality is mainly here to make the operator-matrix transparent. Calling the object handles padding for odd inputs.

Raises:

• NotImplementedError – if padding had to be used in the creation of the transformation matrices.

• ValueError – If no level transformation matrices are stored (most likely since the object was not called yet).

2d reconstrucion using MatrixWaverec2

class ptwt.MatrixWaverec2(wavelet: Wavelet | str, *, axes: tuple[int, int] = (-2, -1), orthogonalization: ptwt.constants.OrthogonalizeMethod = 'qr', separable: bool = True)

Synthesis or inverse matrix based-wavelet transformation object.

Example

>>> import ptwt, torch, pywt
>>> import numpy as np
>>> from scipy import datasets
>>> face = datasets.face()[:256, :256, :].astype(np.float32)
>>> pt_face = torch.tensor(face).permute([2, 0, 1])
>>> matrixfwt = ptwt.MatrixWavedec2(pywt.Wavelet("haar"), level=2)
>>> mat_coeff = matrixfwt(pt_face)
>>> matrixifwt = ptwt.MatrixWaverec2(pywt.Wavelet("haar"))
>>> reconstruction = matrixifwt(mat_coeff)

Create the inverse matrix-based fast wavelet transformation.

Parameters:

• wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Refer to the output from pywt.wavelist(kind='discrete') for possible choices.

• axes (tuple[int, int]) – Compute the transform over these axes. Defaults to (-2, -1).

• orthogonalization – The method used to orthogonalize boundary filters, see ptwt.constants.OrthogonalizeMethod. Defaults to qr.

• separable (bool) – If this flag is set, a separable transformation is used, i.e. a 1d transformation along each axis. This is significantly faster than a non-separable transformation since only a small constant- size part of the matrices must be orthogonalized. For invertibility, the analysis and synthesis values must be identical! Defaults to True.

Changed in version 1.10: The argument boundary has been renamed to orthogonalization.

Raises:

• NotImplementedError – If the selected orthogonalization mode is not supported.

• ValueError – If the wavelet filters have different lengths.

__call__(coefficients: ptwt.constants.WaveletCoeff2d) → Tensor

Compute the inverse matrix 2d fast wavelet transform.

Parameters:

coefficients (WaveletCoeff2d) – The coefficient tuple as returned by the MatrixWavedec2 object, see ptwt.constants.WaveletCoeff2d.

Returns:

The original signal reconstruction. Its shape depends on the shape of the input to ptwt.MatrixWavedec2.

Raises:

ValueError – If the decomposition level is not a positive integer or if the coefficients are not in the shape as it is returned from a MatrixWavedec2 object.

property sparse_ifwt_operator: Tensor

Compute the iFWT operator matrix for pad-free cases.

Returns:

The sparse 2d iFWT operator matrix.

Raises:

• NotImplementedError – if a separable transformation was used or if padding had to be used in the creation of the transformation matrices.

• ValueError – If no level transformation matrices are stored (most likely since the object was not called yet).

3d reconstrucion using MatrixWaverec3

class ptwt.MatrixWaverec3(wavelet: Wavelet | str, *, axes: tuple[int, int, int] = (-3, -2, -1), orthogonalization: ptwt.constants.OrthogonalizeMethod = 'qr')

Reconstruct a signal from 3d separable FWT coefficients.

Compute a three-dimensional separable boundary wavelet synthesis transform.

Parameters:

• wavelet (Wavelet or str) – A pywt wavelet compatible object or the name of a pywt wavelet. Refer to the output from pywt.wavelist(kind='discrete') for possible choices.

• axes (tuple[int, int, int]) – Compute the transform over these axes of the data tensor. Defaults to (-3, -2, -1).

• orthogonalization – The method used to orthogonalize boundary filters, see ptwt.constants.OrthogonalizeMethod. Defaults to qr.

Changed in version 1.10: The argument boundary has been renamed to orthogonalization.

Raises:

• NotImplementedError – If the selected orthogonalization mode is not supported.

• ValueError – If the wavelet filters have different lengths.

__call__(coefficients: ptwt.constants.WaveletCoeffNd) → Tensor

Reconstruct a batched 3d-signal from its coefficients.

Parameters:

coefficients – The output from the MatrixWavedec3 object, see ptwt.constants.WaveletCoeffNd.

Returns:

A reconstruction of the original signal.

Return type:

torch.Tensor

Raises:

ValueError – If the data structure is inconsistent.