PyTorch 中的 2D 小波变换

|build-status| |docs| |doi|

.. |build-status| image:: https://travis-ci.org/fbcotter/pytorch_wavelets.png?branch=master :alt: 构建状态 :scale: 100% :target: https://travis-ci.org/fbcotter/pytorch_wavelets

.. |docs| image:: https://readthedocs.org/projects/pytorch-wavelets/badge/?version=latest :target: https://pytorch-wavelets.readthedocs.io/en/latest/?badge=latest :alt: 文档状态

.. |doi| image:: https://zenodo.org/badge/146817005.svg :target: https://zenodo.org/badge/latestdoi/146817005

完整的文档也可以在 这里__ 查看。

__ http://pytorch-wavelets.readthedocs.io/

这个包提供了计算二维离散小波变换和二维双树复小波变换及其逆变换的支持，并且可以在 PyTorch 中对这两种变换进行梯度传递。

该实现设计用于处理多通道图像的批量数据。我们使用 PyTorch 标准的 'NCHW' 数据格式。

此外，我们还添加了基于 2D DTCWT 的散射网络层。这与 KymatIO__ 中基于 Morlet 的散射网络类似，但速度大约快 10 倍。

如果您使用此仓库，请引用我的博士论文第 3 章：https://doi.org/10.17863/CAM.53748。

__ https://github.com/kymatio/kymatio

版本 1.3.0 新增内容

- 添加了 1D DWT 支持

.. code:: python

    import torch
    from pytorch_wavelets import DWT1DForward, DWT1DInverse  # 或者直接使用 DWT1D, IDWT1D
    dwt = DWT1DForward(wave='db6', J=3)
    X = torch.randn(10, 5, 100)
    yl, yh = dwt(X)
    print(yl.shape)
    >>> torch.Size([10, 5, 22])
    print(yh[0].shape)
    >>> torch.Size([10, 5, 55])
    print(yh[1].shape)
    >>> torch.Size([10, 5, 33])
    print(yh[2].shape)
    >>> torch.Size([10, 5, 22])
    idwt = DWT1DInverse(wave='db6')
    x = idwt((yl, yh))

版本 1.2.0 新增内容

• 添加了一个基于 DTCWT 的散射网络

.. code:: python

import torch
from pytorch_wavelets import ScatLayer
scat = ScatLayer()
X = torch.randn(10,5,64,64)
# 一阶散射网络有 6 种方向和一个低通通道
# 输出通道数是输入通道数的 7 倍
Z = scat(X)
print(Z.shape)
>>> torch.Size([10, 35, 32, 32])
# 二阶散射网络同样有 6 种方向和一个低通通道
# 输出通道数是输入通道数的 7^2 倍
scat2 = torch.nn.Sequential(ScatLayer(), ScatLayer())
Z = scat2(X)
print(Z.shape)
>>> torch.Size([10, 245, 16, 16])
# 我们还有一个稍微更专业但速度较慢的二阶散射网络
from pytorch_wavelets import ScatLayerj2
scat2a = ScatLayerj2()
Z = scat2a(X)
print(Z.shape)
>>> torch.Size([10, 245, 16, 16])
# 当然，这些都可以在 CUDA 上运行
scat2a.cuda()
Z = scat2a(X.cuda())

版本 1.1.0 新增内容

- 修复了 DWT 的内存问题
- 修复了 DTCWT 计算的后端代码——现在更加简洁，但性能相似
- DTCWT 和 DWT 现在都更加节省内存或对内存更敏感。
- 移除了指定 DTCWTInverse 的尺度数量的需求。

版本 1.0.0 新增内容

版本 1.0.0 现在增加了对可分离 DWT 计算的支持，以及更多的填充方式，如对称、零填充和周期化。

此外，在创建小波变换类时不再需要指定通道数。

速度测试

我们将使用 Python 包进行 DTCWT 计算和使用 PyWavelets 进行 DWT 计算的速度，与在 pytorch_wavelets 中同时进行这两项计算的速度进行了比较，使用的硬件是 GTX1080。NumPy 方法是在一台拥有 14 核 Xeon Phi 处理器的机器上，通过 Intel 的并行 Python 库运行的。对于 DTCWT，我们在第一尺度使用 `near_sym_a` 滤波器，在后续尺度使用 `qshift_a` 滤波器。对于 DWT，我们使用 `db4` 滤波器。

对于固定输入大小，但改变尺度数量（从 1 到 4），我们得到了以下速度（平均 5 次运行的结果）：

.. raw:: html

    <img src="https://oss.gittoolsai.com/images/fbcotter_pytorch_wavelets_readme_dec026c47f2b.png" width="700px">

对于高度和宽度均为 512 的输入，我们还改变了 3 尺度变换的批次大小。得到的速度如下：

.. raw:: html

    <img src="https://oss.gittoolsai.com/images/fbcotter_pytorch_wavelets_readme_639d00ee6e47.png" width="700px">

安装
````````````
安装 ``pytorch_wavelets`` 最简单的方式是克隆仓库并使用 pip 安装。未来的版本将会发布到 PyPI，但在此之前需要先更新文档::

    $ git clone https://github.com/fbcotter/pytorch_wavelets
    $ cd pytorch_wavelets
    $ pip install .

（不过，如果您打算对该库进行重大修改，使用 `develop` 命令可能会更有用。）我们提供了一个测试套件，以便您验证代码是否能在您的系统上正常工作::

    $ pip install -r tests/requirements.txt
    $ pytest tests/

示例用法
```````````
对于 DWT——请注意，高通输出有一个额外的维度，其中我们堆叠了 (lh, hl, hh) 系数。另外请注意，Yh 输出中，最精细的细节系数排在前面，而最粗糙的排在最后（与 PyWavelets 相反）。

.. code:: python

    import torch
    from pytorch_wavelets import DWTForward, DWTInverse
    xfm = DWTForward(J=3, wave='db3', mode='zero')
    X = torch.randn(10,5,64,64)
    Yl, Yh = xfm(X) 
    print(Yl.shape)
    >>> torch.Size([10, 5, 12, 12])
    print(Yh[0].shape) 
    >>> torch.Size([10, 5, 3, 34, 34])
    print(Yh[1].shape)
    >>> torch.Size([10, 5, 3, 19, 19])
    print(Yh[2].shape)
    >>> torch.Size([10, 5, 3, 12, 12])
    ifm = DWTInverse(wave='db3', mode='zero')
    Y = ifm((Yl, Yh))

对于 DTCWT：

.. code:: python

    import torch
    from pytorch_wavelets import DTCWTForward, DTCWTInverse
    xfm = DTCWTForward(J=3, biort='near_sym_b', qshift='qshift_b')
    X = torch.randn(10,5,64,64)
    Yl, Yh = xfm(X) 
    print(Yl.shape)
    >>> torch.Size([10, 5, 16, 16])
    print(Yh[0].shape) 
    >>> torch.Size([10, 5, 6, 32, 32, 2])
    print(Yh[1].shape)
    >>> torch.Size([10, 5, 6, 16, 16, 2])
    print(Yh[2].shape)
    >>> torch.Size([10, 5, 6, 8, 8, 2])
    ifm = DTCWTInverse(biort='near_sym_b', qshift='qshift_b')
    Y = ifm((Yl, Yh))

一些初步说明：

- 返回的 Yh 是一个元组。有两个额外的维度——第一个位于输入的通道维度和行维度之间，这是 DTCWT 的 6 个方向；第二个是最后一个维度，表示复数的实部和虚部（PyTorch 不原生支持复数）。

在 GPU 上运行

这对 PyTorch 用户来说并不意外。DWT 和 DTCWT 变换都支持 CUDA 调用：

.. code:: python

import torch
from pytorch_wavelets import DTCWTForward, DTCWTInverse
xfm = DTCWTForward(J=3, biort='near_sym_b', qshift='qshift_b').cuda()
X = torch.randn(10,5,64,64).cuda()
Yl, Yh = xfm(X) 
ifm = DTCWTInverse(biort='near_sym_b', qshift='qshift_b').cuda()
Y = ifm((Yl, Yh))

自动化测试无法测试 GPU 功能，但会检查 CPU 的运行情况。 要测试该仓库是否能在你的 GPU 上正常工作，你可以先下载该仓库， 确保已安装支持 CUDA 的 PyTorch（测试会检查 :code:torch.cuda.is_available() 是否返回 True）， 然后执行以下命令：

.. code::

pip install -r tests/requirements.txt
pytest tests/

从仓库的根目录下运行。

反向传播

可以在前向和后向变换中传递梯度。你只需确保每个变换的输入都设置了
:code:`requires_grad` 属性为 True 即可。



出处
~~~~~~~~~~
本项目基于剑桥大学 Nick Kingsbury 开发的 MATLAB 双树复小波变换工具包。
原始的 README 文件位于 ORIGINAL_README.txt 中，其中详细说明了该 MATLAB 工具箱的使用条款。

有关双树复小波变换的更多信息，可从我的网站上下载相关论文（见下方链接）。
其中，1999 年发表于英国皇家学会的论文是最佳教程，尤其解释了如何在“实数”四分量子图像与复数子图像对之间进行转换。
Q 移位滤波器的相关内容则在 2000 年 ICIP 会议论文以及 2001 年 5 月发表于《应用与计算调和分析》期刊的论文中有更详细的阐述。

本代码受版权保护，仅免费提供用于科研目的。作为交换，我唯一的要求是：如果你使用了这些算法，请在撰写论文时适当引用本工作，并在我发现双树复小波变换有良好应用时通知我。如果这些应用确实有价值，我非常愿意开展合作。对于因使用这些算法而产生的任何后果，我概不负责。

Nick Kingsbury,
剑桥大学，2003年6月。

Dr N G Kingsbury,
剑桥大学工程系，
Trumpington St., Cambridge CB2 1PZ, UK，或
剑桥大学三一学院，CB2 1TQ, UK。
电话：(0 或 +44) 1223 338514 / 332647；家庭：1954 211152；
传真：1223 338564 / 332662；电子邮件：ngk@eng.cam.ac.uk
个人主页：http://www.eng.cam.ac.uk/~ngk/

.. vim:sw=4:sts=4:et

pytorch_wavelets 快速上手指南

pytorch_wavelets 是一个基于 PyTorch 的高效工具库，支持二维离散小波变换（DWT）、二维双树复小波变换（DTCWT）及其逆变换。该库专为批量多通道图像处理设计，支持 GPU 加速和自动梯度回传，适用于深度学习中的特征提取与信号处理任务。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.6+
• 核心依赖：
  • PyTorch (需安装与您的 CUDA 版本匹配的 PyTorch)
  • NumPy
• 硬件要求：
  • CPU：通用支持
  • GPU：可选，若需加速请确保已安装支持 CUDA 的 PyTorch 版本 (torch.cuda.is_available() 返回 True)

国内用户提示：建议配置清华或阿里镜像源以加速依赖下载。

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

目前最稳定的安装方式是通过 GitHub 源码安装：

git clone https://github.com/fbcotter/pytorch_wavelets
cd pytorch_wavelets
pip install .

如果您计划修改源码或进行开发，建议使用开发模式安装：

pip install -e .

验证安装（可选）： 安装测试依赖并运行测试套件以确保环境正常：

pip install -r tests/requirements.txt
pytest tests/

基本使用

1. 二维离散小波变换 (2D DWT)

适用于标准图像多尺度分解。注意高频系数输出包含额外维度，按 (lh, hl, hh) 堆叠。

import torch
from pytorch_wavelets import DWTForward, DWTInverse

# 初始化变换：分解层数 J=3, 小波基 'db3', 填充模式 'zero'
xfm = DWTForward(J=3, wave='db3', mode='zero')

# 输入张量格式：[Batch, Channel, Height, Width] (NCHW)
X = torch.randn(10, 5, 64, 64)

# 执行前向变换
Yl, Yh = xfm(X) 

# Yl: 低频近似系数
print(Yl.shape) 
# >>> torch.Size([10, 5, 12, 12])

# Yh: 高频细节系数列表 (从细到粗)
# 维度含义：[N, C, 3(方向), H, W]
print(Yh[0].shape) 
# >>> torch.Size([10, 5, 3, 34, 34])

# 执行逆变换恢复图像
ifm = DWTInverse(wave='db3', mode='zero')
X_reconstructed = ifm((Yl, Yh))

2. 二维双树复小波变换 (2D DTCWT)

提供平移不变性和更好的方向选择性。输出包含实部和虚部。

import torch
from pytorch_wavelets import DTCWTForward, DTCWTInverse

# 初始化变换
xfm = DTCWTForward(J=3, biort='near_sym_b', qshift='qshift_b')

X = torch.randn(10, 5, 64, 64)
Yl, Yh = xfm(X) 

# Yh 维度含义：[N, C, 6(方向), H, W, 2(实部/虚部)]
print(Yh[0].shape) 
# >>> torch.Size([10, 5, 6, 32, 32, 2])

# 逆变换
ifm = DTCWTInverse(biort='near_sym_b', qshift='qshift_b')
X_reconstructed = ifm((Yl, Yh))

3. GPU 加速与梯度回传

该库原生支持 CUDA 和 PyTorch 自动求导机制。

GPU 使用示例： 只需将模型和数据移至 CUDA 设备即可。

xfm = DTCWTForward(J=3, biort='near_sym_b', qshift='qshift_b').cuda()
X = torch.randn(10, 5, 64, 64).cuda()
Yl, Yh = xfm(X)

梯度回传示例： 确保输入张量设置 requires_grad=True 即可在反向传播中计算梯度。

X = torch.randn(10, 5, 64, 64, requires_grad=True)
xfm = DWTForward(J=1, wave='db1')
Yl, Yh = xfm(X)
loss = Yl.sum()
loss.backward() # 可正常计算梯度