复频域图像压缩研究项目

基于深度学习的无线电(RF)复值基带 I/Q 信号学习式压缩框架

Inspired by QmapCompression — Variable-Rate Deep Image Compression through Spatially-Adaptive Feature Transform (ICCV 2021)

本项目围绕无线电(RF)复值基带 I/Q 信号的学习式压缩开展研究，目标是在带宽/存储/边缘算力受限的场景下，实现对长序列复值信号的高效表示，并在重建误差之外进一步约束"通信语义相关"的结构信息（相关性、相位一致性等）。

本项目的核心思路受 Song 等人 (ICCV 2021) 提出的 QmapCompression 启发，将基于空间自适应特征变换（SFT）与质量图（quality map） 的可变速率图像压缩方法，从图像像素域迁移到 RF 复值信号域，并引入复值网络算子与面向通信语义的多目标损失设计。

项目建立时间： 2025年2月

使用数据集： RadioML 2018.01 (DeepSIG)

• 复值网络建模：构建复值卷积、复值GDN、复值激活等算子，保留 I/Q 信号的复数域结构
• 质量图引导压缩：基于能量/幅度变化生成质量图，通过 SFT 机制实现自适应编码
• 多目标损失函数：MSE + 复数相关性 + 相位一致性，保障通信语义完整性
• 端到端可训练：完整的编码-解码框架，支持梯度反向传播优化

• ✅ 完整的训练/验证/测试流程
• ✅ 支持时域/频域两种模式
• ✅ 多维度评估指标：MSE/PSNR/SNR/相关性/相位一致性
• ✅ TensorBoard 可视化支持
• ✅ 支持消融研究（提供多个消融版本模型）

系统要求：

• Python 3.8+
• CUDA 11.8+ (推荐用于 GPU 训练)
• 显存：至少 5GB (batch_size=1024)

安装依赖：

# 克隆仓库
git clone https://gitee.com/OceanEyeFF/complex-conv-image-compression.git
cd complex-conv-image-compression

# 创建虚拟环境（推荐）
conda create -n rfcomp python=3.9
conda activate rfcomp

# 安装依赖
pip install -r requirements.txt

方法一：自动下载（推荐）

# 需要先配置 Kaggle API 凭证
# 参考：https://github.com/Kaggle/kaggle-api#api-credentials
python scripts/download_dataset.py

方法二：手动下载

1. 访问 Kaggle - RadioML 2018.01
2. 下载 GOLD_XYZ_OSC.0001_1024.hdf5
3. 放置到 data/2018.01/ 目录

分割数据集：

# 将原始数据分割为训练/验证/测试集
python split_dataset.py

这会生成：

• data/processed/train_data.hdf5 (训练集)
• data/processed/val_data.hdf5 (验证集)
• data/processed/test_data.hdf5 (测试集)

# 使用默认配置开始训练
python train3.py

训练配置：

• 配置文件：configs/DefaultConfig.json
• 可调参数：batch_size, learning_rate, num_epochs 等
• 日志目录：experiments/
• 模型保存：checkpoints/best_model.pth

监控训练：

# 启动 TensorBoard
tensorboard --logdir experiments/

# 测试保存的模型
python test_saved_model.py

complex-conv-image-compression/
├── models/                      # 模型定义
│   ├── models.py               # 主网络 (RFSpatiallyAdaptiveCompression)
│   ├── layers.py               # 复值卷积/归一化/SFT 模块
│   ├── ComplexReLUs.py         # 复值激活函数
│   ├── entropy_models.py       # 熵模型
│   ├── hyperpriors.py          # 超先验模型
│   └── models - *.py           # 消融研究版本
├── losses/                      # 损失函数
│   └── losses.py               # 多目标损失 (ComplexPixelwiseRateDistortionLoss)
├── ops/                         # 算子库
│   ├── bound_ops.py
│   ├── ops.py
│   └── parametrizers.py
├── scripts/                     # 辅助脚本
│   ├── download_dataset.py     # 数据集下载脚本 ⭐
│   └── prepare_*.sh            # 数据准备脚本
├── configs/                     # 配置文件
│   └── DefaultConfig.json      # 默认训练配置
├── data/                        # 数据目录
│   ├── 2018.01/                # 原始数据
│   └── processed/              # 处理后数据
├── train3.py                    # 主训练脚本 ⭐
├── test_saved_model.py         # 模型测试脚本 ⭐
├── Class_RMLDataset.py         # 数据集类（含质量图生成）
├── ConfigLoader.py             # 配置加载器
├── split_dataset.py            # 数据集分割脚本 ⭐
├── requirements.txt            # 依赖列表
├── 说明文档.md                 # 详细说明文档
├── 学术价值介绍.md             # 学术价值介绍
└── README.md                   # 本文件

{
    "batch_size": 1024,              // 批次大小 (1024=5GB, 2048=10GB)
    "num_epochs": 1000,              // 训练轮数
    "warmup_learning_epochs": 150,   // 学习率预热轮数
    "learning_rate": 0.01,           // 初始学习率
    "signal_length": 1024,           // 信号长度
    "num_channels": 2,               // I/Q 双通道
    "domain_mode": "freq",           // 域模式: "time" 或 "freq"
    "early_stopping_patience": 20,   // 早停耐心值
    "reduce_lr_patience": 5          // 学习率衰减耐心值
}

训练和验证过程会自动计算以下指标：

• MSE (Mean Squared Error): 均方误差
• PSNR (Peak Signal-to-Noise Ratio): 峰值信噪比
• SNR (Signal-to-Noise Ratio): 信噪比
• Corr (Correlation Coefficient): 相关系数
• Complex Corr: 复数域相关系数
• Phase Consistency: 相位一致性
• Compress Diff: 压缩-解压一致性验证

输入 I/Q 信号 (2×1024)
    ↓
质量图生成 (能量图)
    ↓
编码器 (复值卷积 + 复值 GDN)
    ↓
潜变量 (压缩表示)
    ↓
解码器 (复值反卷积 + SFT 融合)
    ↓
重建 I/Q 信号 (2×1024)

• 能量占比：局部能量 / 全局能量
• 幅度变化：相邻采样点幅度差分
• SFT 融合：在多尺度特征层级注入质量图

Loss = w1 * Weighted_MSE
     + w2 * (1 - Complex_Correlation)
     + w3 * Phase_Inconsistency

from train3 import train_one_epoch, validate
from models.models import RFSpatiallyAdaptiveCompression
from ConfigLoader import load_or_create_config

# 加载配置
config = load_or_create_config("configs/DefaultConfig.json")

# 创建模型
model = RFSpatiallyAdaptiveCompression(
    input_channels=2,
    N=32,  # 编码器通道数
    M=32,  # 潜变量通道数
    sft_ks=3
).cuda()

# 训练
for epoch in range(config["num_epochs"]):
    train_loss = train_one_epoch(model, train_loader, optimizer, device)
    val_metrics = validate(model, val_loader, device)

# 加载模型
model = RFSpatiallyAdaptiveCompression(...)
model.load_state_dict(torch.load("checkpoints/best_model.pth"))

# 压缩
compressed_data = model.compress(signal, quality_map)

# 解压
reconstructed = model.decompress(compressed_data)

项目提供多个消融版本用于对比实验：

• models/models.py - 完整版本 ⭐
• models/models - qmap引导消融.py - 移除质量图引导
• models/models - 残差网络消融.py - 移除残差连接
• models/models - 特征压缩消融.py - 简化特征压缩
• models/models - 深度特征压缩消融.py - 浅层特征压缩

• 说明文档.md - 详细的代码说明
• 学术价值介绍.md - 学术价值与研究方向
• 测试结果.txt - 实验结果记录

本项目使用的 RadioML 2018.01 数据集遵循其原始许可证。 详见：data/2018.01/LICENSE.TXT

项目代码部分采用 MIT 许可证。

OceanEyeFF

• Email: fdch00@163.com
• Gitee: @OceanEyeFF

• 本项目受 QmapCompression 启发：Song, M., Choi, J., & Han, B. "Variable-Rate Deep Image Compression through Spatially-Adaptive Feature Transform." ICCV 2021. [论文] [代码]
• RadioML 数据集由 DeepSig 提供
• 项目基于 PyTorch 深度学习框架

如果本项目对您的研究有帮助，欢迎引用：

@misc{complex-conv-image-compression,
  author = {OceanEyeFF},
  title = {Complex-valued Convolution for RF Signal Compression},
  year = {2025},
  publisher = {Gitee},
  url = {https://gitee.com/OceanEyeFF/complex-conv-image-compression}
}

本项目基于以下工作：

@inproceedings{song2021variable,
  title={Variable-Rate Deep Image Compression through Spatially-Adaptive Feature Transform},
  author={Song, Myungseo and Choi, Jinyoung and Han, Bohyung},
  booktitle={Proceedings of the IEEE/CVF International Conference on Computer Vision (ICCV)},
  pages={2380--2389},
  year={2021}
}

如有问题或建议，请提交 Issue。

⭐ 如果觉得项目有帮助，欢迎 Star！