Sparse-matrix based Fast Wavelet Transform (FWT)

Sparse-matrix based Fast Wavelet Transform (FWT)#

1d decomposition using MatrixWavedec#

class ptwt.MatrixWavedec(wavelet: Wavelet | str, level: int | None = None, *, axis: int = -1, orthogonalization: Literal['qr', 'gramschmidt'] = 'qr', odd_coeff_padding_mode: Literal['constant', 'zero', 'reflect', 'periodic', 'symmetric'] = 'zero')[source]#

Bases: BaseMatrixWaveDec

Compute the 1d fast wavelet transform using sparse matrices.

This transform is the sparse matrix correspondant to ptwt.wavedec(). The convolution operations are implemented as a matrix-vector product between a sparse transformation matrix and the input signal. This transform uses boundary wavelets instead of padding to handle the signal boundaries, see the boundary wavelet docs.

Note

Constructing the sparse FWT matrix can be expensive. For longer wavelets, high-level transforms, and large input images this may take a while. The matrix is therefore constructed only once and reused in further calls. The sparse transformation matrix can be accessed via the sparse_fwt_operator property.

Note

On each level of the transform the convolved signal is required to be of even length. This transform uses padding to transform coefficients with an odd length, with the padding mode specified by odd_coeff_padding_mode. To avoid padding consider transforming signals with a length divisable by \(2^L\) for a \(L\)-level transform.

Example

>>> import ptwt, torch
>>> # generate an input of even length.
>>> data = torch.arange(8, dtype=torch.float32)
>>> # First, construct the transformation object
>>> matrix_wavedec = ptwt.MatrixWavedec('haar', level=2)
>>> # Then, the FWT is computed by calling the object.
>>> coefficients = matrix_wavedec(data)

Create a sparse matrix fast wavelet transform object.

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.

  • level (int, optional) – The level up to which to compute the FWT. If None, the maximum level based on the signal length is chosen. Defaults to None.

  • axis (int) – The axis we would like to transform. Defaults to -1.

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

  • odd_coeff_padding_mode – The constructed FWT matrices require inputs with even lengths. Thus, any odd-length approximation coefficients are padded to an even length using this mode, see ptwt.constants.BoundaryMode. Defaults to zero.

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__(input_signal: Tensor) → list[Tensor][source]#

Compute the matrix FWT for the given input signal.

Matrix FWTs are used to avoid padding.

Parameters:

input_signal (torch.Tensor) – Input data to transform. This transform affects the last axis by default. Use the axis argument in the constructor to choose another axis.

Returns:

A list with the coefficient tensor for each scale.

Raises:

ValueError – If the decomposition level is not a positive integer or if the input signal has not the expected shape.

property sparse_fwt_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.

The operation

torch.sparse.mm(sparse_fwt_operator, data.T)

computes a batched FWT.

This property exists to make the operator matrix transparent. Calling the object will handle odd-length inputs properly.

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 decomposition using MatrixWavedec2#

class ptwt.MatrixWavedec2(wavelet: Wavelet | str, level: int | None = None, *, axes: tuple[int, int] = (-2, -1), orthogonalization: ptwt.constants.OrthogonalizeMethod = 'qr', separable: bool = True, odd_coeff_padding_mode: ptwt.constants.BoundaryMode = 'zero')[source]#

Bases: BaseMatrixWaveDec

Compute the 2d fast wavelet transform using sparse matrices.

This transform is the sparse matrix correspondant to ptwt.wavedec2(). The convolution operations are implemented as a matrix-vector product between a sparse transformation matrix and the input signal. This transform uses boundary wavelets instead of padding to handle the signal boundaries, see the boundary wavelet docs.

Note

Constructing the sparse FWT matrix is expensive. For longer wavelets, high-level transforms, and large input images this may take a while. The matrix is therefore constructed only once. In the non-separable case, it can be accessed via the sparse_fwt_operator property.

Note

On each level of the transform both axis of the convolved signal are required to be of even length. This transform uses zero padding to transform coefficients with an odd length. To avoid padding consider transforming signals with dimensions divisable by \(2^L\) for a \(L\)-level transform.

Example

>>> import ptwt, torch
>>> 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("haar", level=2)
>>> mat_coeff = matrixfwt(pt_face)

Create a new matrix fwt object.

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.

  • level (int, optional) – The maximum decomposition level. If None, the level is computed based on the signal shape. Defaults to None.

  • axes (tuple[int, int]) – Compute the transform over these axes of the data tensor. 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. Matrix construction is significantly faster for separable transformations since only a small constant-size part of the matrices must be orthogonalized. Defaults to True.

  • odd_coeff_padding_mode – The constructed FWT matrices require inputs with even lengths. Thus, any odd-length approximation coefficients are padded to an even length using this mode, see ptwt.constants.BoundaryMode. Defaults to zero.

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__(input_signal: Tensor) → ptwt.constants.WaveletCoeff2d[source]#

Compute the FWT for the given input signal.

The FWT matrix is set up during the first call and stored for future use.

Parameters:

input_signal (torch.Tensor) – The input data tensor with at least two dimensions. By default the last two axes are transformed. The axes class attribute allows other choices.

Returns:

The resulting coefficients per level are stored in a pywt style tuple, see ptwt.constants.WaveletCoeff2d.

Raises:

ValueError – If the decomposition level is not a positive integer or if the input signal has not the expected shape.

property sparse_fwt_operator: Tensor#

Compute the operator matrix for padding-free cases.

This property exists to make the transformation matrix available. To benefit from code handling odd-length levels call the object.

Returns:

The sparse 2d FWT 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 decomposition using MatrixWavedec3#

class ptwt.MatrixWavedec3(wavelet: Wavelet | str, level: int | None = None, *, axes: tuple[int, int, int] = (-3, -2, -1), orthogonalization: ptwt.constants.OrthogonalizeMethod = 'qr', odd_coeff_padding_mode: ptwt.constants.BoundaryMode = 'zero')[source]#

Bases: BaseMatrixWaveDec

Compute 3d separable transforms.

Note

On each level of the transform both axis of the convolved signal are required to be of even length. This transform uses zero padding to transform coefficients with an odd length. To avoid padding consider transforming signals with dimensions divisable by \(2^L\) for a \(L\)-level transform.

Create a separable three-dimensional fast boundary wavelet transform.

Input signals should have the shape [batch_size, depth, height, width], this object transforms the last three dimensions.

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.

  • level (int, optional) – The desired decomposition level. Defaults to None.

  • 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.

  • odd_coeff_padding_mode – The constructed FWT matrices require inputs with even lengths. Thus, any odd-length approximation coefficients are padded to an even length using this mode, see ptwt.constants.BoundaryMode. Defaults to zero.

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

Raises:

  • NotImplementedError – If the chosen orthogonalization method is not implemented.

  • ValueError – If the analysis and synthesis filters do not have the same length.

__call__(input_signal: Tensor) → ptwt.constants.WaveletCoeffNd[source]#

Compute a separable 3d FWT using boundary wavelets.

Parameters:

input_signal (torch.Tensor) – The input data tensor with at least three dimensions. By default the last three axes are transformed. The axes class attribute allows other choices.

Returns:

A tuple containing the wavelet coefficients, see ptwt.constants.WaveletCoeffNd.

Raises:

ValueError – If the input dimensions don’t work.

Sparse-matrix FWT base class#

All sparse-matrix decomposition classes extend ptwt.matmul_transform.BaseMatrixWaveDec.

class ptwt.matmul_transform.BaseMatrixWaveDec[source]#

A base class for matrix wavedec.

Contents