# EMCAD项目文档

## 项目概述

EMCAD（Efficient Multi-scale Convolutional Attention Decoding）是一个用于医学图像分割的高效多尺度卷积注意力解码网络。本项目是CVPR 2024论文《EMCAD: Efficient Multi-scale Convolutional Attention Decoding for Medical Image Segmentation》的官方PyTorch实现。

## 项目结构

```
EMCAD/
├── 📁 src/                        # 源代码目录
│   └── emcad/                     # 主包
│       ├── __init__.py             # 包初始化文件
│       ├── core/                   # 核心模块
│       │   ├── __init__.py
│       │   ├── models.py           # 数据模型定义
│       │   └── processors.py       # 核心处理器
│       └── utils/                  # 工具模块
│           ├── __init__.py
│           ├── data_utils.py       # 数据处理工具
│           └── visualization.py    # 可视化工具
├── 📁 tests/                       # 测试代码
│   ├── __init__.py
│   ├── test_core/                  # 核心模块测试
│   └── test_utils/                # 工具模块测试
├── 📁 docs/                        # 项目文档
│   ├── README.md                   # 项目主文档
│   ├── API.md                     # API文档
│   └── QUICKSTART.md              # 快速入门指南
├── 📁 configs/                     # 配置文件
│   ├── default.yaml               # 默认配置
│   ├── development.yaml           # 开发环境配置
│   └── production.yaml           # 生产环境配置
├── 📁 data/                        # 数据目录
│   ├── raw/                       # 原始数据
│   ├── processed/                 # 处理后的数据
│   └── external/                  # 外部数据
├── 📁 notebooks/                   # Jupyter笔记本
├── 📁 scripts/                     # 脚本文件
├── 📄 requirements.txt             # 依赖列表
├── 📄 setup.py                    # 安装配置
├── 📄 pyproject.toml              # 现代项目配置
├── 📄 README.md                   # 项目说明
├── 📄 .gitignore                  # Git忽略规则
├── 📄 .pre-commit-config.yaml     # 预提交钩子配置
└── 📄 Makefile                    # 常用命令封装
```

## 安装指南

### 环境要求

- Python 3.8+
- PyTorch 1.11.0
- CUDA 11.3 (可选，用于GPU加速)

### 安装步骤

1. 创建并激活虚拟环境：
```bash
conda create -n emcadenv python=3.8
conda activate emcadenv
```

2. 安装PyTorch：
```bash
pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cu113
```

3. 安装MMCV：
```bash
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html
```

4. 安装项目依赖：
```bash
pip install -r requirements.txt
```

## 使用指南

### 数据准备

#### Synapse多器官数据集
1. 从[Synapse官网](https://www.synapse.org/#!Synapse:syn3193805/wiki/89480)注册并下载数据集
2. 按照[TransUNet](https://github.com/Beckschen/TransUNet/blob/main/datasets/README.md)的列表将'RawData'文件夹分割为'TrainSet'（18个扫描）和'TestSet'（12个扫描）
3. 将数据放入'./data/synapse/Abdomen/RawData/'文件夹
4. 运行预处理脚本：
```bash
python ./utils/preprocess_synapse_data.py
```
或下载[预处理数据](https://drive.google.com/file/d/1tGqMx-E4QZpSg2HQbVq5W3KSTHSG0hjK/view?usp=share_link)并保存到'./data/synapse/'文件夹

#### ACDC数据集
从[MT-UNet的Google Drive](https://drive.google.com/file/d/13qYHNIWTIBzwyFgScORL2RFd002vrPF2/view)下载预处理的ACDC数据集，并移动到'./data/ACDC/'文件夹

### 预训练模型
从[Google Drive](https://drive.google.com/drive/folders/1Eu8v9vMRvt-dyfCH0XSV2i77lAd62nPXV?usp=sharing)/[PVT GitHub](https://github.com/whai362/PVT/releases/tag/v2)下载预训练的PVTv2模型，并放入'./pretrained_pth/pvt/'文件夹

### 训练模型

使用以下命令训练模型：
```bash
cd EMCAD
python train_synapse.py --root_path ./data/Synapse/train_npz --volume_path ./data/Synapse/test_vol_h5 --encoder pvt_v2_b2 --batch_size 2 --max_epochs 50 --max_iterations 2000
```

### 测试模型

使用以下命令测试模型：
```bash
cd EMCAD
python test_synapse.py --volume_path ./data/synapse/test_vol_h5 --encoder pvt_v2_b2
```

## 模型架构

EMCAD网络架构包含以下核心组件：

1. **编码器**：使用PVTv2作为骨干网络
2. **多尺度卷积块（MSCB）**：通过不同大小的卷积核捕获多尺度特征
3. **轻量级门控注意力（LGAG）**：高效地融合多尺度特征
4. **解码器**：逐步上采样并融合特征，生成分割结果

## 性能指标

在Synapse多器官数据集上，EMCAD取得了以下性能：

- 平均Dice系数：85.63%
- 参数量：仅24.6M
- 计算量（FLOPs）：仅15.8G

## 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

1. Fork本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

## 代码规范

本项目遵循以下代码规范：

1. **代码风格**：遵循PEP 8风格指南
2. **命名规范**：
   - 变量和函数：使用小写字母，单词之间用下划线连接
   - 常量：使用全大写字母，单词之间用下划线连接
   - 类：使用驼峰命名法
3. **注释和文档**：
   - 使用三重双引号编写文档字符串
   - 函数和方法的文档字符串应说明其功能、参数、返回值和异常
4. **类型注解**：在Python 3.5+中使用类型提示

## 许可证

本项目采用MIT许可证。详情请参阅[LICENSE](LICENSE)文件。

## 引用

如果本项目对您的研究有帮助，请考虑引用我们的论文：

```bibtex
@inproceedings{rahman2024emcad,
  title={Emcad: Efficient multi-scale convolutional attention decoding for medical image segmentation},
  author={Rahman, Md Mostafijur and Munir, Mustafa and Marculescu, Radu},
  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
  pages={11769--11779},
  year={2024}
}
```

## 致谢

我们感谢以下优秀工作为本项目提供了基础：
- [timm](https://github.com/huggingface/pytorch-image-models)
- [CASCADE](https://github.com/SLDGroup/CASCADE)
- [MERIT](https://github.com/SLDGroup/MERIT)
- [G-CASCADE](https://github.com/SLDGroup/G-CASCADE)
- [PP-SAM](https://github.com/SLDGroup/PP-SAM)
- [PraNet](https://github.com/DengPingFan/PraNet)
- [Polyp-PVT](https://github.com/DengPingFan/Polyp-PVT)
- [TransUNet](https://github.com/Beckschen/TransUNet)