半监督语义分割的对抗学习

本仓库是以下论文的 PyTorch 实现：

Adversarial Learning for Semi-supervised Semantic Segmentation
Wei-Chih Hung、Yi-Hsuan Tsai、Yan-Ting Liou、Yen-Yu Lin 和 Ming-Hsuan Yang
英国机器视觉会议（BMVC）论文集，2018 年。

联系人：Wei-Chih Hung (whung8 at ucmerced dot edu)

代码大量借鉴了 PyTorch 版的 DeepLab 实现 (链接)。基准模型为 DeepLabv2-Resnet101，未使用多尺度训练和 CRF 后处理，在 VOC2012 验证集上的 meanIOU 为 73.6%。

如果您觉得我们的工作对您的研究有帮助，请引用我们的论文。

@inproceedings{Hung_semiseg_2018,
  author = {W.-C. Hung and Y.-H. Tsai and Y.-T. Liou and Y.-Y. Lin and M.-H. Yang},
  booktitle = {Proceedings of the British Machine Vision Conference (BMVC)},
  title = {Adversarial Learning for Semi-supervised Semantic Segmentation},
  year = {2018}
}

前置条件

• CUDA/CUDNN
• pytorch >= 0.2（我们仅支持 0.4 进行评估，代码将很快迁移到 0.4）
• python-opencv >=3.4.0（3.3 在多线程数据加载器中会导致额外的 GPU 内存占用）

安装

• 克隆本仓库

git clone https://github.com/hfslyc/AdvSemiSeg.git

• 将 VOC2012 数据集放置在 AdvSemiSeg/dataset/VOC2012 目录下。训练时需要增强标签（下载）。文件夹结构应如下所示：

AdvSemiSeg/dataset/VOC2012/JPEGImages
                          /SegmentationClassAug

使用预训练模型在 VOC2012 验证集上测试

python evaluate_voc.py --pretrained-model semi0.125 --save-dir results

该命令会下载使用 1/8 训练数据的预训练模型，并在 VOC2012 验证集上进行评估。着色后的图像将保存在 results/ 目录中，详细的类别 IOU 将保存在 results/result.txt 中。平均 IOU 应约为 68.8%。

• 可用的 --pretrained-model 选项：semi0.125、semi0.25、semi0.5、advFull。

示例可视化结果

在 VOC2012 上训练

python train.py --snapshot-dir snapshots \
                --partial-data 0.125 \
                --num-steps 20000 \
                --lambda-adv-pred 0.01 \
                --lambda-semi 0.1 --semi-start 5000 --mask-T 0.2

这些参数对应于论文表 5 中的设置。

要评估训练好的模型，请执行以下命令：

python evaluate_voc.py --restore-from snapshots/VOC_20000.pth \
                       --save-dir results

更改记录

• 2018年7月24日：更新 BMVC 结果

AdvSemiSeg 快速上手指南

AdvSemiSeg 是基于 PyTorch 实现的“半监督语义分割对抗学习”工具，源自 BMVC 2018 论文。该工具利用少量标注数据和大量未标注数据，通过对抗学习提升分割性能。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐)
• GPU 驱动: 已安装 CUDA 和 cuDNN
• Python 版本: 建议 Python 3.6+
• 核心依赖:
  • pytorch >= 0.4 (原文提到评估仅支持 0.4，训练基于 0.2+，建议直接使用 0.4 或更高兼容版本以避免环境问题)
  • python-opencv >= 3.4.0 (注意: 版本低于 3.4.0 可能导致多线程数据加载时显存异常增加)
• 其他库: 标准 PyTorch 生态库 (如 numpy, PIL 等)

安装步骤

1. 克隆代码仓库

git clone https://github.com/hfslyc/AdvSemiSeg.git
cd AdvSemiSeg

2. 准备数据集 (VOC2012)

将 PASCAL VOC 2012 数据集放置在 dataset/VOC2012 目录下。为了进行训练，您需要下载增强版的标签数据。

目录结构应如下所示：

AdvSemiSeg/dataset/VOC2012/
├── JPEGImages
└── SegmentationClassAug  (需单独下载并放入此处)

• 增强标签下载地址: SegmentationClassAug.zip
• 国内开发者提示: 如果上述链接下载缓慢，可尝试使用迅雷或其他下载加速工具，或寻找国内镜像源（如阿里云盘、百度网盘收录的资源）。

3. 安装依赖

确保已安装符合版本要求的 opencv-python 和 pytorch。

pip install opencv-python>=3.4.0
# PyTorch 安装请参考 pytorch.org 根据您的 CUDA 版本选择对应命令

基本使用

场景一：使用预训练模型进行评估 (最快体验)

您可以直接下载作者在 VOC2012 验证集上训练的预训练模型进行测试。以下命令将自动下载使用 1/8 标注数据训练的模型 (semi0.125) 并输出评估结果。

python evaluate_voc.py --pretrained-model semi0.125 --save-dir results

• 输出说明:
  • 可视化结果图片保存在 results/ 文件夹。
  • 详细的各类别 IOU 及平均 IOU (Mean IOU) 保存在 results/result.txt。
  • 预期平均 IOU 约为 68.8%。
• 其他可用模型参数: --pretrained-model 可选值包括 semi0.125, semi0.25, semi0.5, advFull。

场景二：从头训练模型

如果您希望在自己的数据子集上复现训练过程，可以使用以下命令。以下示例对应论文中 Table 5 的参数配置（使用 12.5% 的标注数据）：

python train.py --snapshot-dir snapshots \
                --partial-data 0.125 \
                --num-steps 20000 \
                --lambda-adv-pred 0.01 \
                --lambda-semi 0.1 --semi-start 5000 --mask-T 0.2

训练完成后评估： 假设训练生成的权重文件为 snapshots/VOC_20000.pth，执行以下命令进行评估：

python evaluate_voc.py --restore-from snapshots/VOC_20000.pth \
                       --save-dir results