# 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

# Complex-Domain Signal Compression Research Project

[![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/)

> A deep-learning-based learned compression framework for radio frequency (RF) complex-valued baseband I/Q signals
>
> **Inspired by** [QmapCompression](https://github.com/micmic123/QmapCompression) --- *Variable-Rate Deep Image Compression through Spatially-Adaptive Feature Transform* (ICCV 2021)

## Overview

This project focuses on **learned compression for radio frequency (RF) complex-valued baseband I/Q signals**, aiming to achieve efficient representation of long-sequence complex-valued signals under bandwidth-, storage-, and edge-computing-constrained scenarios. Beyond minimizing reconstruction error, the framework further constrains "communication-semantics-related" structural information (correlation, phase consistency, etc.).

The core methodology is inspired by **QmapCompression** proposed by Song et al. (ICCV 2021), which leverages **Spatial Feature Transform (SFT)** and **quality maps** for variable-rate image compression. This project migrates the approach from the image pixel domain to the RF complex-valued signal domain, introducing complex-valued network operators and communication-semantics-oriented multi-objective loss design.

**Project Established:** February 2025

**Dataset:** RadioML 2018.01 (DeepSig)

---

## Key Features

### Technical Innovations

- **Complex-Valued Network Modeling**: Complex convolution, complex GDN, and complex activation operators that preserve the complex-domain structure of I/Q signals
- **Quality-Map-Guided Compression**: Energy/amplitude-variation-driven quality maps with SFT-based adaptive encoding
- **Multi-Objective Loss Function**: MSE + complex correlation + phase consistency, ensuring communication-semantic integrity
- **End-to-End Trainable**: Complete encoder-decoder framework with gradient backpropagation optimization

### Experimental Features

- Complete training/validation/testing pipeline
- Time-domain and frequency-domain mode support
- Multi-dimensional evaluation metrics: MSE / PSNR / SNR / Correlation / Phase Consistency
- TensorBoard visualization support
- Ablation study support (multiple ablation model variants provided)

---

## Quick Start

### 1. Environment Setup

**System Requirements:**
- Python 3.8+
- CUDA 11.8+ (recommended for GPU training)
- GPU Memory: at least 5 GB (batch_size=1024)

**Install Dependencies:**

```bash
# Clone the repository
git clone https://gitee.com/OceanEyeFF/complex-conv-image-compression.git
cd complex-conv-image-compression

# Create a virtual environment (recommended)
conda create -n rfcomp python=3.9
conda activate rfcomp

# Install dependencies
pip install -r requirements.txt
```

### 2. Dataset Preparation

**Option A: Automatic Download (Recommended)**

```bash
# Requires Kaggle API credentials to be configured first
# Reference: https://github.com/Kaggle/kaggle-api#api-credentials
python scripts/download_dataset.py
```

**Option B: Manual Download**

1. Visit [Kaggle - RadioML 2018.01](https://www.kaggle.com/datasets/pinxau1000/radioml2018)
2. Download `GOLD_XYZ_OSC.0001_1024.hdf5`
3. Place it in the `data/2018.01/` directory

**Split the Dataset:**

```bash
# Split raw data into training/validation/test sets
python split_dataset.py
```

This generates:
- `data/processed/train_data.hdf5` (training set)
- `data/processed/val_data.hdf5` (validation set)
- `data/processed/test_data.hdf5` (test set)

### 3. Train the Model

```bash
# Start training with default configuration
python train3.py
```

**Training Configuration:**
- Configuration file: `configs/DefaultConfig.json`
- Adjustable parameters: batch_size, learning_rate, num_epochs, etc.
- Log directory: `experiments/`
- Model checkpoint: `checkpoints/best_model.pth`

**Monitor Training:**

```bash
# Launch TensorBoard
tensorboard --logdir experiments/
```

### 4. Test the Model

```bash
# Test a saved model
python test_saved_model.py
```

---

## Project Structure

```
complex-conv-image-compression/
├── models/                      # Model definitions
│   ├── models.py               # Main network (RFSpatiallyAdaptiveCompression)
│   ├── layers.py               # Complex convolution/normalization/SFT modules
│   ├── ComplexReLUs.py         # Complex-valued activation functions
│   ├── entropy_models.py       # Entropy models
│   ├── hyperpriors.py          # Hyperprior models
│   └── models - *.py           # Ablation study variants
├── losses/                      # Loss functions
│   └── losses.py               # Multi-objective loss (ComplexPixelwiseRateDistortionLoss)
├── ops/                         # Operator library
│   ├── bound_ops.py
│   ├── ops.py
│   └── parametrizers.py
├── scripts/                     # Utility scripts
│   ├── download_dataset.py     # Dataset download script
│   └── prepare_*.sh            # Data preparation scripts
├── configs/                     # Configuration files
│   └── DefaultConfig.json      # Default training configuration
├── data/                        # Data directory
│   ├── 2018.01/                # Raw data
│   └── processed/              # Processed data
├── train3.py                    # Main training script
├── test_saved_model.py         # Model testing script
├── Class_RMLDataset.py         # Dataset class (with quality map generation)
├── ConfigLoader.py             # Configuration loader
├── split_dataset.py            # Dataset splitting script
├── requirements.txt            # Dependency list
└── README.md                   # This file
```

---

## Configuration

### Training Configuration (`configs/DefaultConfig.json`)

```json
{
    "batch_size": 1024,              // Batch size (1024=5GB, 2048=10GB)
    "num_epochs": 1000,              // Number of training epochs
    "warmup_learning_epochs": 150,   // Learning rate warmup epochs
    "learning_rate": 0.01,           // Initial learning rate
    "signal_length": 1024,           // Signal length
    "num_channels": 2,               // I/Q dual channels
    "domain_mode": "freq",           // Domain mode: "time" or "freq"
    "early_stopping_patience": 20,   // Early stopping patience
    "reduce_lr_patience": 5          // Learning rate reduction patience
}
```

### GPU Memory Requirements (Encoder/Decoder Channels = 8)

| Batch Size | GPU Memory |
|-----------|------------|
| 512       | ~2.2 GB    |
| 1024      | ~5 GB      |
| 2048      | ~10 GB     |

---

## Evaluation Metrics

The training and validation processes automatically compute the following metrics:

- **MSE (Mean Squared Error)**: Point-to-point reconstruction error
- **PSNR (Peak Signal-to-Noise Ratio)**: Peak signal-to-noise ratio
- **SNR (Signal-to-Noise Ratio)**: Signal-to-noise ratio
- **Corr (Correlation Coefficient)**: Real-valued correlation coefficient
- **Complex Corr**: Complex-domain correlation coefficient
- **Phase Consistency**: Phase alignment between original and reconstructed signals
- **Compress Diff**: Compression-decompression consistency verification

---

## Core Technical Details

### 1. Complex-Valued Network Architecture

```
Input I/Q Signal (2 x 1024)
    ↓
Quality Map Generation (Energy Map)
    ↓
Encoder (Complex Convolution + Complex GDN)
    ↓
Latent Representation (Compressed)
    ↓
Decoder (Complex Deconvolution + SFT Fusion)
    ↓
Reconstructed I/Q Signal (2 x 1024)
```

### 2. Quality Map Guidance Mechanism

- **Energy Proportion**: Local energy / Global energy
- **Amplitude Variation**: Amplitude differential between adjacent samples
- **SFT Fusion**: Quality map injection at multi-scale feature hierarchies

### 3. Multi-Objective Loss

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

---

## Usage Examples

### Custom Training

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

# Load configuration
config = load_or_create_config("configs/DefaultConfig.json")

# Create model
model = RFSpatiallyAdaptiveCompression(
    input_channels=2,
    N=32,  # Encoder channels
    M=32,  # Latent channels
    sft_ks=3
).cuda()

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

### Compression and Decompression

```python
# Load model
model = RFSpatiallyAdaptiveCompression(...)
model.load_state_dict(torch.load("checkpoints/best_model.pth"))

# Compress
compressed_data = model.compress(signal, quality_map)

# Decompress
reconstructed = model.decompress(compressed_data)
```

---

## Ablation Studies

The project provides multiple ablation variants for comparative experiments:

- `models/models.py` - Full model
- `models/models - qmap引导消融.py` - Quality map guidance removed
- `models/models - 残差网络消融.py` - Residual connections removed
- `models/models - 特征压缩消融.py` - Simplified feature compression
- `models/models - 深度特征压缩消融.py` - Shallow feature compression

---

## License

The RadioML 2018.01 dataset used in this project follows its original license.
See: [data/2018.01/LICENSE.TXT](data/2018.01/LICENSE.TXT)

The project source code is licensed under the MIT License.

---

## Author

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

---

## Acknowledgements

- This project is inspired by **QmapCompression**: Song, M., Choi, J., & Han, B. *"Variable-Rate Deep Image Compression through Spatially-Adaptive Feature Transform."* ICCV 2021. [[Paper]](https://arxiv.org/abs/2108.09551) [[Code]](https://github.com/micmic123/QmapCompression)
- RadioML dataset provided by [DeepSig](https://www.deepsig.ai/)
- Built with the PyTorch deep learning framework

---

## Citation

If this project is helpful to your research, please consider citing:

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

This project is based on the following work:

```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 Reporting

For questions or suggestions, please submit an [Issue](https://gitee.com/OceanEyeFF/complex-conv-image-compression/issues).