[Contribs] Add CPS

contrib/CrossPseudoSupervision/README.md

@@ -0,0 +1,135 @@
+English | [简体中文](README_CN.md)
+
+# Semi-Supervised Semantic Segmentation with Cross Pseudo Supervision
+
+Unlike image classification tasks, **data annotation is relatively difficult and costly for semantic segmentation tasks**. It is necessary to label each pixel of an image, including objects with special details, such as electric poles. However, obtaining RGB data is relatively simple. **How to use a large amount of unlabeled data to improve the performance of the model is a research issue in the field of semi supervised semantic segmentation**.
+
+[Cross pseudo supervision, CPS](https://arxiv.org/abs/2106.01226) is a **very concise and high-performance** semi supervised semantic segmentation task algorithm. During training, two networks with the same structure but different initializations are used, and constraints are added to ensure that the outputs of the two networks for the same sample are similar. Specifically, the one hat pseudo label generated by the current network will serve as the target for another path of network prediction. This process can be monitored using cross entropy loss, just like the traditional supervision of fully supervised semantic segmentation tasks. **This algorithm has achieved SOTA results in both benchmarks (PASCAL VOC, Cityscapes)**
+
+Some visualization results are as follows: RGB image on the left, prediction image in the middle, and true value on the right:
+
+![](https://ai-studio-static-online.cdn.bcebos.com/e45cf14fe5a0417791a5455e84b2243abe8d8298cba94c8f9d98b0edd8a431d1)
+
+![](https://ai-studio-static-online.cdn.bcebos.com/a136cff0ce7748dbb7bd3d8fa5b6942b8eeee8cb10ec456694c749a09375fc29)
+
+## Contents
+- [Installation](#Installation)
+- [Models](#Models)
+- [Dataset Preparation](#Dataset-Preparation)
+- [Training, Evaluation and Prediction](#Training-Evaluation-and-Prediction)
+
+## Installation
+
+- [PaddlePaddle Installation](https://www.paddlepaddle.org.cn/install/quick)
+    - Versions：PaddlePaddle develop, Python>=3.7
+
+- PaddleSeg Installation, use the following command:
+
+```shell
+git clone -b develop https://github.com/PaddlePaddle/PaddleSeg
+cd PaddleSeg
+pip install -r requirements.txt
+pip install -v -e .
+```
+
+## Models
+
+The results reproduced in this project are 50% of the labeled Cityscapes dataset, and the mIOU of the reproduced model is **78.39%**. The comparison is shown in the following table:
+
+| CPS.resnet50.deeplabv3+(1/2 Cityscapes) | mIOU |
+| --- | --- |
+| pytorch | 78.77% |
+| paddle | 78.39% |
+
+The model weight download link for Paddle replication is:
+
+## Dataset-Preparation
+
+The Cityscapes dataset provided using the CPS source code has been uploaded to [AI Studio](https://aistudio.baidu.com/aistudio/datasetdetail/177911). We recommended decompressing the data to the `contrib/CrossPseudoService/data` folder. The prepared data is organized as follows:
+
+```
+data/
+|-- city
+    ├── config_new
+    │    ├── coarse_split
+    │    │   ├── train_extra_3000.txt
+    │    │   ├── train_extra_6000.txt
+    │    │   └── train_extra_9000.txt
+    │    ├── subset_train
+    │    │   ├── train_aug_labeled_1-16.txt
+    │    │   ├── train_aug_labeled_1-2.txt
+    │    │   ├── train_aug_labeled_1-4.txt
+    │    │   ├── train_aug_labeled_1-8.txt
+    │    │   ├── train_aug_unlabeled_1-16.txt
+    │    │   ├── train_aug_unlabeled_1-2.txt
+    │    │   ├── train_aug_unlabeled_1-4.txt
+    │    │   └── train_aug_unlabeled_1-8.txt
+    │    ├── test.txt
+    │    ├── train.txt
+    │    ├── train_val.txt
+    │    └── val.txt  
+    ├── generate_colored_gt.py
+    ├── images
+    │   ├── test
+    │   ├── train
+    │   └── val
+    └── segmentation
+        ├── test
+        ├── train
+        └── val
+```
+
+## Training-Evaluation-and-Prediction
+
+Execute the following command to enter the branch where `CPS` is located:
+```shell
+cd ./contrib/CrossPseudoSupervision
+```
+
+### Training
+
+After preparing the environment and data, execute the following command training:
+
+```shell
+python train.py --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml --log_iters 10 --save_dir ./output/ --batch_size 2
+```
+
+We recommend using a single machine with multiple cards for training. Execute the following command to start four card training:
+
+```shell
+python -m paddle.distributed.launch --gpus="0,1,2,3" train.py --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml \
+--log_iters 10 --save_dir $SAVE_PATH$ --batch_size 8
+```
+
+**Note**: The training process in the original repo of the paper is not validated, but rather the accuracy of the remaining saved weights will be tested one by one after the training is completed, so this project will not be validated during the training process either; The configuration file is training for 1/2 labeled data. To change to another ratio, the number of training epochs needs to be adjusted:
+
+| Dataset    | 1/16 | 1/8  | 1/4  | 1/2  |
+| ---------- | ---- | ---- | ---- | ---- |
+| Cityscapes | 128  | 137  | 160  | 240  |
+
+### Evaluation
+
+After training, execute the following command to evaluate the model accuracy:
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python val.py \
+       --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml \
+       --model_path $MODEL_PATH$
+```
+
+### Prediction
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+!python predict.py \
+       --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml \
+       --model_path $MODEL_PATH$ \
+       --image_path $IMG_PATH$ \
+       --save_dir $SAVE_PATH$ \
+       --is_slide \
+       --crop_size 800 800 \
+       --stride 532 532
+```
+
+You can directly download the model provided by us for prediction.

contrib/CrossPseudoSupervision/README_CN.md

@@ -0,0 +1,139 @@
+简体中文 | [English](README.md)
+
+# CPS: 基于交叉伪监督的半监督语义分割
+
+不同于图像分类任务，**数据的标注对于语义分割任务来说是比较困难而且成本高昂的**，需要为图像的每一个像素标注一个标签，包括一些特别细节的物体，如电线杆等。但是对于获取RGB数据是比较简单，如何**利用大量的无标注数据去提高模型的性能**，便是半监督语义分割领域研究的问题。
+
+[Cross pseudo supervision, CPS](https://arxiv.org/abs/2106.01226)是一种**非常简洁而又性能很好**的半监督语义分割任务算法。训练时，使用两个相同结构、但是不同初始化的网络，添加约束**使得两个网络对同一样本的输出是相似的**。具体来说，当前网络产生的one-hot pseudo label，会作为另一路网络预测的目标，这个过程可以用cross entropy loss监督，就像传统的全监督语义分割任务的监督一样。**该算法在在两个benchmark (PASCAL VOC, Cityscapes) 都取得了SOTA的结果**
+
+部分可视化结果如下，左边为RGB图像，中间为预测图，右边为真值
+
+![](https://ai-studio-static-online.cdn.bcebos.com/e45cf14fe5a0417791a5455e84b2243abe8d8298cba94c8f9d98b0edd8a431d1)
+
+![](https://ai-studio-static-online.cdn.bcebos.com/a136cff0ce7748dbb7bd3d8fa5b6942b8eeee8cb10ec456694c749a09375fc29)
+
+
+## 目录
+- [环境配置](#环境配置)
+- [模型](#模型)
+- [数据准备](#数据准备)
+- [训练评估预测](#训练评估预测)
+
+## 环境配置
+
+
+- [PaddlePaddle安装](https://www.paddlepaddle.org.cn/install/quick)
+    - 版本要求：PaddlePaddle develop, Python>=3.7
+
+- PaddleSeg安装，通过以下命令：
+
+```shell
+git clone -b develop https://github.com/PaddlePaddle/PaddleSeg
+cd PaddleSeg
+pip install -r requirements.txt
+pip install -v -e .
+```
+
+## 模型
+
+本项目复现的为在Cityscapes数据集以0.5倍数据量上的结果，复现模型的mIOU为**78.39%**，对比如下表所示：
+
+| CPS.resnet50.deeplabv3+(1/2 Cityscapes) | mIOU |
+| --- | --- |
+| pytorch | 78.77% |
+| paddle | 78.39% |
+
+Paddle复现的模型权重下载链接为：
+
+## 数据准备
+
+使用CPS源代码所提供的Cityscapes数据集，已上传至[AI Studio](https://aistudio.baidu.com/aistudio/datasetdetail/177911)，建议将数据解压至`contrib/CrossPseudoSupervision/data`文件夹下，准备好的数据组织如下：
+
+```
+data/
+|-- city
+    ├── config_new
+    │    ├── coarse_split
+    │    │   ├── train_extra_3000.txt
+    │    │   ├── train_extra_6000.txt
+    │    │   └── train_extra_9000.txt
+    │    ├── subset_train
+    │    │   ├── train_aug_labeled_1-16.txt
+    │    │   ├── train_aug_labeled_1-2.txt
+    │    │   ├── train_aug_labeled_1-4.txt
+    │    │   ├── train_aug_labeled_1-8.txt
+    │    │   ├── train_aug_unlabeled_1-16.txt
+    │    │   ├── train_aug_unlabeled_1-2.txt
+    │    │   ├── train_aug_unlabeled_1-4.txt
+    │    │   └── train_aug_unlabeled_1-8.txt
+    │    ├── test.txt
+    │    ├── train.txt
+    │    ├── train_val.txt
+    │    └── val.txt  
+    ├── generate_colored_gt.py
+    ├── images
+    │   ├── test
+    │   ├── train
+    │   └── val
+    └── segmentation
+        ├── test
+        ├── train
+        └── val
+```
+
+## 训练评估预测
+
+执行以下命令，进入到`CPS`所在分支：
+
+```shell
+cd ./contrib/CrossPseudoSupervision
+```
+
+### 训练
+
+准备好环境与数据之后，执行以下命令训练：
+
+```shell
+python train.py --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml --log_iters 10 --save_dir ./output/ --batch_size 2
+```
+
+建议使用单机多卡进行训练，执行以下命令启动四卡训练：
+
+```shell
+python -m paddle.distributed.launch --gpus="0,1,2,3" train.py --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml \
+--log_iters 10 --save_dir $SAVE_PATH$ --batch_size 8
+```
+
+**注**： 论文原repo中训练过程并不验证，而是训练结束后再对后几个保存的权重逐个测试精度，因此本项目也不在训练过程中验证；配置文件是训练1/2有标签的数据，若要改为其他比例，训练epoch数需要进行调整
+
+| Dataset    | 1/16 | 1/8  | 1/4  | 1/2  |
+| ---------- | ---- | ---- | ---- | ---- |
+| Cityscapes | 128  | 137  | 160  | 240  |
+
+
+### 评估
+
+训练结束后，执行以下命令评估模型精度：
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python val.py \
+       --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml \
+       --model_path $MODEL_PATH$
+```
+
+### 预测
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+!python predict.py \
+       --config ./configs/deeplabv3p/deeplabv3p_resnet50_0.5cityscapes_800x800_240e.yml \
+       --model_path $MODEL_PATH$ \
+       --image_path $IMG_PATH$ \
+       --save_dir $SAVE_PATH$ \
+       --is_slide \
+       --crop_size 800 800 \
+       --stride 532 532
+```
+
+你可以直接下载我们提供的模型进行预测。

contrib/CrossPseudoSupervision/batch_transforms/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2023 PaddlePaddle Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .mask_gen import BoxMaskGenerator, AddMaskParamsToBatch
+from .custom_collate import SegCollate

contrib/CrossPseudoSupervision/batch_transforms/custom_collate.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2023 PaddlePaddle Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from paddle.fluid.dataloader.collate import default_collate_fn
+
+
+class SegCollate(object):
+    def __init__(self, batch_aug_fn=None):
+        self.batch_aug_fn = batch_aug_fn
+
+    def __call__(self, batch):
+        if self.batch_aug_fn is not None:
+            batch = self.batch_aug_fn(batch)
+        return default_collate_fn(batch)