# Complex-Conv-Image-Compression

**Repository Path**: OceanEyeFF/complex-conv-image-compression

## Basic Information

- **Project Name**: Complex-Conv-Image-Compression
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: 202502
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-17
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 复频域图像压缩研究项目

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.1.0-orange.svg)](https://pytorch.org/)

> 基于深度学习的无线电(RF)复值基带 I/Q 信号学习式压缩框架
>
> **Inspired by** [QmapCompression](https://github.com/micmic123/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 可视化支持
- ✅ 支持消融研究（提供多个消融版本模型）

---

## 🚀 快速开始

### 1️⃣ 环境配置

**系统要求：**
- Python 3.8+
- CUDA 11.8+ (推荐用于 GPU 训练)
- 显存：至少 5GB (batch_size=1024)

**安装依赖：**

```bash
# 克隆仓库
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
```

### 2️⃣ 数据集准备

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

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

**方法二：手动下载**

1. 访问 [Kaggle - RadioML 2018.01](https://www.kaggle.com/datasets/pinxau1000/radioml2018)
2. 下载 `GOLD_XYZ_OSC.0001_1024.hdf5`
3. 放置到 `data/2018.01/` 目录

**分割数据集：**

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

这会生成：
- `data/processed/train_data.hdf5` (训练集)
- `data/processed/val_data.hdf5` (验证集)
- `data/processed/test_data.hdf5` (测试集)

### 3️⃣ 训练模型

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

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

**监控训练：**

```bash
# 启动 TensorBoard
tensorboard --logdir experiments/
```

### 4️⃣ 测试模型

```bash
# 测试保存的模型
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                   # 本文件
```

---

## ⚙️ 配置说明

### 训练配置 (`configs/DefaultConfig.json`)

```json
{
    "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          // 学习率衰减耐心值
}
```

### 显存需求（编解码器通道数=8）

| Batch Size | 显存需求 |
|-----------|---------|
| 512       | ~2.2 GB |
| 1024      | ~5 GB   |
| 2048      | ~10 GB  |

---

## 📈 评估指标

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

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

---

## 🔬 核心技术

### 1. 复值网络架构

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

### 2. 质量图引导机制

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

### 3. 多目标损失

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

---

## 📚 使用示例

### 自定义训练

```python
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)
```

### 压缩与解压

```python
# 加载模型
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) - 详细的代码说明
- [学术价值介绍.md](学术价值介绍.md) - 学术价值与研究方向
- [测试结果.txt](测试结果.txt) - 实验结果记录

---

## 📄 许可证

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

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

---

## 👤 作者

**OceanEyeFF**
- Email: fdch00@163.com
- Gitee: [@OceanEyeFF](https://gitee.com/OceanEyeFF)

---

## 🙏 致谢

- 本项目受 **QmapCompression** 启发：Song, M., Choi, J., & Han, B. *"Variable-Rate Deep Image Compression through Spatially-Adaptive Feature Transform."* ICCV 2021. [[论文]](https://arxiv.org/abs/2108.09551) [[代码]](https://github.com/micmic123/QmapCompression)
- RadioML 数据集由 [DeepSig](https://www.deepsig.ai/) 提供
- 项目基于 PyTorch 深度学习框架

---

## 📊 引用

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

```bibtex
@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}
}
```

本项目基于以下工作：

```bibtex
@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](https://gitee.com/OceanEyeFF/complex-conv-image-compression/issues)。

---

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