PyTorch Wavelet Toolbox

For transforms that do not add extra pixels at the edges (unlike padding/convolution approaches), use the MatrixWavedec and MatrixWaverec classes. These utilize torch.sparse.mm for efficiency.

1D Sparse Transforms

Use MatrixWavedec for forward and MatrixWaverec for backward transforms.

2D Sparse Transforms

Use MatrixWavedec2 and MatrixWaverec2.

• Separable (Default): Uses a 1D transformation along both axes. This is generally faster.
• Non-separable: Pass separable=False to the constructor to use a non-separable transformation.

import torch
import ptwt

# 1D sparse matrix forward transform
data = torch.arange(16, dtype=torch.float32)
matrix_wavedec = ptwt.MatrixWavedec("haar", level=2)
coeff = matrix_wavedec(data)

# 1D sparse matrix backward transform
matrix_waverec = ptwt.MatrixWaverec("haar")
rec = matrix_waverec(coeff)

When working with finite signals and higher-order wavelets, simple truncation of convolution matrices leads to a loss of information and prevents perfect reconstruction (i.e., $\mathbf{S}\mathbf{A} \neq \mathbf{I}$). Common methods like zero-padding or periodic extension can create artificial discontinuities at the boundaries.

ptwt addresses this by using Gram-Schmidt boundary filters. These are specially constructed, shorter filters at the boundaries that preserve both the signal length and the perfect reconstruction property. When using ptwt.MatrixWavedec or ptwt.MatrixWaverec, the resulting matrices are orthogonalized/corrected so that their product results in an identity matrix, ensuring the transform is mathematically sound for finite-length inputs.

Wavelet packets can be used to identify GAN-generated (fake) images by analyzing frequency energy distributions.

Key Observation:

• GAN-generated images (e.g., from StyleGAN) tend to exhibit higher energy in high-frequency bands compared to real images (e.g., from FFHQ).
• This difference in high-frequency packet energy can be visualized using log-scaled mean absolute packet plots to distinguish between real and synthetic content.

The toolbox provides experimental support for training adaptive wavelet layers in PyTorch. This includes:

• Adaptive product-filters
• Optimizable orthogonal-wavelets

Implementation examples can be found in the examples/network_compression/ directory of the repository.

2D wavelet transforms in ptwt return one of two types depending on the transform implementation:

1. WaveletCoeff2d: The standard coefficient container for 2D transforms.
2. WaveletDetailTuple2d: Used for specific 2D transform implementations where coefficients are returned as a tuple of detail components.
3. WaveletCoeff2dSeparable: Specifically used for fully separable 2D transforms.

For transforms in N dimensions, the library uses the following structures to return coefficients:

• WaveletCoeffNd: The general container for N-dimensional wavelet coefficients.
• WaveletDetailDict: A dictionary-based container used to organize detail coefficients in N-dimensional space.

The pytorch-wavelet-toolbox (ptwt) provides two primary strategies for handling signal boundaries when applying wavelet transforms to finite-size tensors:

1. Signal extension via padding: Extends the signal using torch.nn.functional.pad. This is controlled via the BoundaryMode class.
2. Boundary wavelets: Uses specialized boundary filters for coefficients located at the signal edges. This approach is managed via ExtendedBoundaryMode and PaddingMode.

Choose padding when you want to extend the signal before the transform, and boundary wavelets when you want to use specific filter coefficients designed for edge cases.

To run the performance benchmarks provided in the examples, you must install ptwt along with its dependencies: pywt (PyWavelets) and pytorch-wavelets. You can re-run all available speed tests on your local machine using the run_all.sh script.

# Ensure dependencies are installed
pip install pywt pytorch-wavelets ptwt

# Run all speed tests
./run_all.sh