polish PaddleSeg loss docs (#269)

README.md

@@ -31,7 +31,7 @@ PaddleSeg是基于[PaddlePaddle](https://www.paddlepaddle.org.cn)开发的端到
 
 - **模块化设计**
 
-支持U-Net, DeepLabv3+, ICNet, PSPNet, HRNet, Fast-SCNN六种主流分割网络，结合预训练模型和可调节的骨干网络，满足不同性能和精度的要求；选择不同的损失函数如Dice Loss, BCE Loss等方式可以强化小目标和不均衡样本场景下的分割精度。
+支持U-Net, DeepLabv3+, ICNet, PSPNet, HRNet, Fast-SCNN六种主流分割网络，结合预训练模型和可调节的骨干网络，满足不同性能和精度的要求；选择不同的损失函数如Dice Loss, Lovasz Loss等方式可以强化小目标和不均衡样本场景下的分割精度。
 
 - **高性能**
 
@@ -107,8 +107,8 @@ pip install -r requirements.txt
 ### 高级功能
 
 * [PaddleSeg的数据增强](./docs/data_aug.md)
-* [如何解决二分类中类别不均衡问题](./docs/loss_select.md)
-* [特色垂类模型使用](./contrib)
+* [PaddleSeg的loss选择](./docs/loss_select.md)
+* [PaddleSeg产业实践](./contrib)
 * [多进程训练和混合精度训练](./docs/multiple_gpus_train_and_mixed_precision_train.md)
 * 使用PaddleSlim进行分割模型压缩([量化](./slim/quantization/README.md), [蒸馏](./slim/distillation/README.md), [剪枝](./slim/prune/README.md), [搜索](./slim/nas/README.md))
 ## 在线体验

docs/dice_loss.md

+# Dice loss
+对于二类图像分割任务中，经常出现类别分布不均匀的情况，例如：工业产品的瑕疵检测、道路提取及病变区域提取等。我们可使用dice loss(dice coefficient loss)解决这个问题。
+
+注：dice loss和bce loss仅支持二分类。
+
+## 原理介绍
+Dice loss的定义如下：
+
+<p align="center">
+  <img src="./imgs/dice.png" hspace='10' height="46" width="200"/> <br />
+ </p>
+
+
+其中 Y 表示ground truth，P 表示预测结果。| |表示矩阵元素之和。![](./imgs/dice2.png) 表示*Y*和*P*的共有元素数，
+实际通过求两者的逐像素乘积之和进行计算。例如：
+
+<p align="center">
+  <img src="./imgs/dice3.png" hspace='10' /> <br />
+ </p>
+
+其中 1 表示前景，0 表示背景。
+
+**Note：** 在标注图片中，务必保证前景像素值为1，背景像素值为0.
+
+Dice系数请参见[维基百科](https://zh.wikipedia.org/wiki/Dice%E7%B3%BB%E6%95%B0)
+
+**为什么在类别不均衡问题上，dice loss效果比softmax loss更好？**
+
+首先来看softmax loss的定义：
+
+<p align="center">
+  <img src="./imgs/softmax_loss.png"  height="130" /> <br />
+ </p>
+
+其中 y 表示ground truth，p 表示网络输出。
+
+在图像分割中，`softmax loss`评估每一个像素点的类别预测，然后平均所有的像素点。这个本质上就是对图片上的每个像素进行平等的学习。这就造成了一个问题，如果在图像上的多种类别有不平衡的表征，那么训练会由最主流的类别主导。以上面DeepGlobe道路提取的数据为例子，网络将偏向于背景的学习，降低了网络对前景目标的提取能力。
+而`dice loss(dice coefficient loss)`通过预测和标注的交集除以它们的总体像素进行计算，它将一个类别的所有像素作为一个整体作为考量，而且计算交集在总体中的占比，所以不受大量背景像素的影响，能够取得更好的效果。
+
+在实际应用中`dice loss`往往与`bce loss(binary cross entroy loss)`结合使用，提高模型训练的稳定性。
+
+
+## PaddleSeg指定训练loss
+
+PaddleSeg通过`cfg.SOLVER.LOSS`参数可以选择训练时的损失函数，
+如`cfg.SOLVER.LOSS=['dice_loss','bce_loss']`将指定训练loss为`dice loss`与`bce loss`的组合
+
+## Dice loss解决类别不均衡问题的示例
+
+我们以道路提取任务为例应用dice loss.
+在DeepGlobe比赛的Road Extraction中，训练数据道路占比为：4.5%. 如下为其图片样例：
+<p align="center">
+  <img src="./imgs/deepglobe.png" hspace='10'/> <br />
+ </p>
+可以看出道路在整张图片中的比例很小。
+
+### 数据集下载
+我们从DeepGlobe比赛的Road Extraction的训练集中随机抽取了800张图片作为训练集，200张图片作为验证集，
+制作了一个小型的道路提取数据集[MiniDeepGlobeRoadExtraction](https://paddleseg.bj.bcebos.com/dataset/MiniDeepGlobeRoadExtraction.zip)
+
+### 实验比较
+
+在MiniDeepGlobeRoadExtraction数据集进行了实验比较。
+
+* 数据集下载
+```shell
+python dataset/download_mini_deepglobe_road_extraction.py
+```
+
+* 预训练模型下载
+```shell
+python pretrained_model/download_model.py deeplabv3p_mobilenetv2-1-0_bn_coco
+```
+* 配置/数据校验
+```shell
+python pdseg/check.py --cfg ./configs/deepglobe_road_extraction.yaml
+```
+
+* 训练
+```shell
+python pdseg/train.py --cfg ./configs/deepglobe_road_extraction.yaml --use_gpu SOLVER.LOSS "['dice_loss','bce_loss']"
+
+```
+
+* 评估
+```
+python pdseg/eval.py --cfg ./configs/deepglobe_road_extraction.yaml --use_gpu SOLVER.LOSS "['dice_loss','bce_loss']"
+
+```
+
+* 结果比较
+
+softmax loss和dice loss + bce loss实验结果如下图所示。
+图中橙色曲线为dice loss + bce loss，最高mIoU为76.02%，蓝色曲线为softmax loss， 最高mIoU为73.62%。
+<p align="center">
+  <img src="./imgs/loss_comparison.png" hspace='10' height="208" width="516"/> <br />
+ </p>

docs/loss_select.md

-# 如何解决二分类中类别不均衡问题
-对于二类图像分割任务中，经常出现类别分布不均匀的情况，例如：工业产品的瑕疵检测、道路提取及病变区域提取等。
-
-目前PaddleSeg提供了三种loss函数，分别为softmax loss(sotfmax with cross entroy loss)、dice loss(dice coefficient loss)和bce loss(binary cross entroy loss). 我们可使用dice loss解决这个问题。
-
-注：dice loss和bce loss仅支持二分类。
-
-## Dice loss
-Dice loss的定义如下：
-
-<p align="center">
-  <img src="./imgs/dice.png" hspace='10' height="46" width="200"/> <br />
- </p>
-
-
-其中 Y 表示ground truth，P 表示预测结果。| |表示矩阵元素之和。![](./imgs/dice2.png) 表示*Y*和*P*的共有元素数，
-实际通过求两者的逐像素乘积之和进行计算。例如：
-
-<p align="center">
-  <img src="./imgs/dice3.png" hspace='10' /> <br />
- </p>
-
-其中 1 表示前景，0 表示背景。
-
-**Note：** 在标注图片中，务必保证前景像素值为1，背景像素值为0.
-
-Dice系数请参见[维基百科](https://zh.wikipedia.org/wiki/Dice%E7%B3%BB%E6%95%B0)
-
-**为什么在类别不均衡问题上，dice loss效果比softmax loss更好？**
-
-首先来看softmax loss的定义：
-
-<p align="center">
-  <img src="./imgs/softmax_loss.png"  height="130" /> <br />
- </p>
- 
-其中 y 表示ground truth，p 表示网络输出。
-
-在图像分割中，`softmax loss`评估每一个像素点的类别预测，然后平均所有的像素点。这个本质上就是对图片上的每个像素进行平等的学习。这就造成了一个问题，如果在图像上的多种类别有不平衡的表征，那么训练会由最主流的类别主导。以上面DeepGlobe道路提取的数据为例子，网络将偏向于背景的学习，降低了网络对前景目标的提取能力。
-而`dice loss(dice coefficient loss)`通过预测和标注的交集除以它们的总体像素进行计算，它将一个类别的所有像素作为一个整体作为考量，而且计算交集在总体中的占比，所以不受大量背景像素的影响，能够取得更好的效果。
-
-在实际应用中`dice loss`往往与`bce loss(binary cross entroy loss)`结合使用，提高模型训练的稳定性。
-
-
-## PaddleSeg指定训练loss
-
-PaddleSeg通过`cfg.SOLVER.LOSS`参数可以选择训练时的损失函数，
-如`cfg.SOLVER.LOSS=['dice_loss','bce_loss']`将指定训练loss为`dice loss`与`bce loss`的组合
-
-## Dice loss解决类别不均衡问题的示例
-
-我们以道路提取任务为例应用dice loss. 
-在DeepGlobe比赛的Road Extraction中，训练数据道路占比为：4.5%. 如下为其图片样例：
-<p align="center">
-  <img src="./imgs/deepglobe.png" hspace='10'/> <br />
- </p>
-可以看出道路在整张图片中的比例很小。
- 
-### 数据集下载
-我们从DeepGlobe比赛的Road Extraction的训练集中随机抽取了800张图片作为训练集，200张图片作为验证集，
-制作了一个小型的道路提取数据集[MiniDeepGlobeRoadExtraction](https://paddleseg.bj.bcebos.com/dataset/MiniDeepGlobeRoadExtraction.zip)
-
-### 实验比较
-
-在MiniDeepGlobeRoadExtraction数据集进行了实验比较。
-
-* 数据集下载
-```shell
-python dataset/download_mini_deepglobe_road_extraction.py
-```
-
-* 预训练模型下载
-```shell
-python pretrained_model/download_model.py deeplabv3p_mobilenetv2-1-0_bn_coco
-```
-* 配置/数据校验
-```shell
-python pdseg/check.py --cfg ./configs/deepglobe_road_extraction.yaml
+# Loss选择
+
+目前PaddleSeg提供了6种损失函数，分别为
+- Softmax loss (softmax with cross entropy loss)
+- Weighted softmax loss (weighted softmax with cross entropy loss)
+- Dice loss (dice coefficient loss)
+- Bce loss (binary cross entropy loss)
+- Lovasz hinge loss
+- Lovasz softmax loss
+
+## 类别不均衡问题
+在图像分割任务中，经常出现类别分布不均匀的情况，例如：工业产品的瑕疵检测、道路提取及病变区域提取等。
+
+针对这个问题，您可使用Weighted softmax loss、Dice loss、Lovasz hinge loss和Lovasz softmax loss进行解决。
+
+### Weighted softmax loss
+Weighted softmax loss是按类别设置不同权重的softmax loss。
+
+通过设置`cfg.SOLVER.CROSS_ENTROPY_WEIGHT`参数进行使用。  
+默认为None. 如果设置为'dynamic'，会根据每个batch中各个类别的数目，动态调整类别权重。
+也可以设置一个静态权重(list的方式)，比如有3类，每个类别权重可以设置为[0.1, 2.0, 0.9]. 示例如下
+```yaml
+SOLVER:
+    CROSS_ENTROPY_WEIGHT: 'dynamic'
 ```
 
-* 训练
-```shell
-python pdseg/train.py --cfg ./configs/deepglobe_road_extraction.yaml --use_gpu SOLVER.LOSS "['dice_loss','bce_loss']"
-
-```
-
-* 评估
-```
-python pdseg/eval.py --cfg ./configs/deepglobe_road_extraction.yaml --use_gpu SOLVER.LOSS "['dice_loss','bce_loss']"
-
-```
-
-* 结果比较
-
-softmax loss和dice loss + bce loss实验结果如下图所示。
-图中橙色曲线为dice loss + bce loss，最高mIoU为76.02%，蓝色曲线为softmax loss， 最高mIoU为73.62%。
-<p align="center">
-  <img src="./imgs/loss_comparison.png" hspace='10' height="208" width="516"/> <br />
- </p>
-
+### Dice loss
+参见[Dice loss教程](./dice_loss.md)
 
+### Lovasz hinge loss和Lovasz softmax loss
+参见[Lovasz loss教程](./lovasz_loss.md)

docs/lovasz_loss.md

 # Lovasz loss
-对于图像分割任务中，经常出现类别分布不均匀的情况，例如：工业产品的瑕疵检测、道路提取及病变区域提取等。
+对于图像分割任务中，经常出现类别分布不均匀的情况，例如：工业产品的瑕疵检测、道路提取及病变区域提取等。我们可使用lovasz loss解决这个问题。
 
-我们可使用lovasz loss解决这个问题。Lovasz loss根据分割目标的类别数量可分为两种：lovasz hinge loss适用于二分类问题，lovasz softmax loss适用于多分类问题。
+Lovasz loss基于子模损失(submodular losses)的凸Lovasz扩展，对神经网络的mean IoU损失进行优化。Lovasz loss根据分割目标的类别数量可分为两种：lovasz hinge loss和lovasz softmax loss. 其中lovasz hinge loss适用于二分类问题，lovasz softmax loss适用于多分类问题。该工作发表在CVPR 2018上，可点击[参考文献](#参考文献)查看具体原理。
 
 
 ## Lovasz hinge loss
-### 使用方式
+### 使用指南
 
 PaddleSeg通过`cfg.SOLVER.LOSS`参数可以选择训练时的损失函数，
-如`cfg.SOLVER.LOSS=['lovasz_hinge_loss','bce_loss']`将指定训练loss为`lovasz hinge loss`与`bce loss`的组合。
+如`cfg.SOLVER.LOSS=['lovasz_hinge_loss','bce_loss']`将指定训练loss为`lovasz hinge loss`与`bce loss`(binary cross-entropy loss)的组合。
 
 Lovasz hinge loss有3种使用方式：（1）直接训练使用。（2）bce loss结合使用。（3）先使用bec loss进行训练，再使用lovasz hinge loss进行finetuning. 第1种方式不一定达到理想效果，推荐使用后两种方式。本文以第2种方式为例。
 
-### 使用示例
+同时，也可以通过`cfg.SOLVER.LOSS_WEIGHT`参数对不同loss进行权重配比，灵活运用于训练调参。如下所示
+```yaml
+SOLVER:
+    LOSS: ["lovasz_hinge_loss","bce_loss"]
+    LOSS_WEIGHT:
+        LOVASZ_HINGE_LOSS: 0.5
+        BCE_LOSS: 0.5
+```
+
+### 实验对比
 
 我们以道路提取任务为例应用lovasz hinge loss.
-在DeepGlobe比赛的Road Extraction中，训练数据道路占比为：4.5%. 如下为其图片样例：
+基于MiniDeepGlobeRoadExtraction数据集与bce loss进行了实验对比。
+该数据集来源于DeepGlobe比赛的Road Extraction单项，训练数据道路占比为：4.5%. 如下为其图片样例：
 <p align="center">
   <img src="./imgs/deepglobe.png" hspace='10'/> <br />
  </p>
 可以看出道路在整张图片中的比例很小。
 
-#### 实验对比
-
-在MiniDeepGlobeRoadExtraction数据集进行了实验对比。
+为进行快速体验，这里使用DeepLabv3+模型，backbone为MobileNetV2.
 
 * 数据集下载
 我们从DeepGlobe比赛的Road Extraction的训练集中随机抽取了800张图片作为训练集，200张图片作为验证集，
@@ -64,23 +72,32 @@ lovasz hinge loss + bce loss和softmax loss的对比结果如下图所示。
 
 
 ## Lovasz softmax loss
-### 使用方式
+### 使用指南
 
 PaddleSeg通过`cfg.SOLVER.LOSS`参数可以选择训练时的损失函数，
 如`cfg.SOLVER.LOSS=['lovasz_softmax_loss','softmax_loss']`将指定训练loss为`lovasz softmax loss`与`softmax loss`的组合。
 
 Lovasz softmax loss有3种使用方式：（1）直接训练使用。（2）softmax loss结合使用。（3）先使用softmax loss进行训练，再使用lovasz softmax loss进行finetuning. 第1种方式不一定达到理想效果，推荐使用后两种方式。本文以第2种方式为例。
 
-### 使用示例
-
-我们以Pascal voc为例应用lovasz softmax loss.
+同时，也可以通过`cfg.SOLVER.LOSS_WEIGHT`参数对不同loss进行权重配比，灵活运用于训练调参。如下所示
+```yaml
+SOLVER:
+    LOSS: ["lovasz_softmax_loss","softmax_loss"]
+    LOSS_WEIGHT:
+        LOVASZ_SOFTMAX_LOSS: 0.2
+        SOFTMAX_LOSS: 0.8
+```
 
+### 实验对比
 
-#### 实验对比
+接下来以PASCAL VOC 2012数据集为例应用lovasz softmax loss. 我们将lovasz softmax loss与softmax loss进行了实验对比。为进行快速体验，这里使用DeepLabv3+模型，backbone为MobileNetV2.
 
-在Pascal voc数据集上与softmax loss进行了实验对比。
 
 * 数据集下载
+<p align="center">
+  <img src="./imgs/VOC2012.png" width="50%" height="50%" hspace='10'/> <br />
+ </p>
+
 ```shell
 python dataset/download_and_convert_voc2012.py
 ```
@@ -114,3 +131,7 @@ lovasz softmax loss + softmax loss和softmax loss的对比结果如下图所示
  </p>
 
 图中橙色曲线代表lovasz softmax loss + softmax loss，最高mIoU为64.63%，蓝色曲线代表softmax loss， 最高mIoU为63.55%，相比提升1.08个百分点。
+
+
+## 参考文献
+[Berman M, Rannen Triki A, Blaschko M B. The lovász-softmax loss: a tractable surrogate for the optimization of the intersection-over-union measure in neural networks[C]//Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition. 2018: 4413-4421.](http://openaccess.thecvf.com/content_cvpr_2018/html/Berman_The_LovaSz-Softmax_Loss_CVPR_2018_paper.html)