improve data_aug doc and code (#121)

* fix color jitter bug

* modify usage.md

* modify data_aug.md

* improve data_aug doc and code

* data_aug.md

* usage.md

* data_aug.py

* Update data_aug.md

* Update data_aug.md

* Update data_aug.md

* Update data_aug.md

* Update check.md

* Update README.md

README.md

@@ -52,7 +52,7 @@ $ pip install -r requirements.txt
 ### 快速入门
 
 * [安装说明](./docs/installation.md)
-* [训练/评估/可视化](./docs/usage.md)
+* [如何训练/评估/可视化](./docs/usage.md)
 
 ### 基础功能
 

docs/check.md

@@ -55,7 +55,7 @@ Doing label pixel statistics:
 
 - 当`AUG.AUG_METHOD`为stepscaling时，`EVAL_CROP_SIZE`的宽高应不小于原图中最大的宽高。
 
-- 当`AUG.AUG_METHOD`为rangscaling时，`EVAL_CROP_SIZE`的宽高应不小于缩放后图像中最大的宽高。
+- 当`AUG.AUG_METHOD`为rangescaling时，`EVAL_CROP_SIZE`的宽高应不小于缩放后图像中最大的宽高。
 
 ### 11 数据增强参数`AUG.INF_RESIZE_VALUE`校验
 验证`AUG.INF_RESIZE_VALUE`是否在[`AUG.MIN_RESIZE_VALUE`~`AUG.MAX_RESIZE_VALUE`]范围内。若在范围内，则通过校验。

docs/data_aug.md

@@ -7,67 +7,108 @@
 
 ## Resize  
 
-resize步骤是指将输入图像按照某种规则讲图片重新缩放到某一个尺寸，PaddleSeg支持以下3种resize方式:
+Resize步骤是指将输入图像按照某种规则讲图片重新缩放到某一个尺寸，PaddleSeg支持以下3种resize方式:
 
 ![](imgs/aug_method.png)
 
-- Un-padding
-将输入图像直接resize到某一个固定大小下，送入到网络中间训练，对应参数为AUG.FIX_RESIZE_SIZE。预测时同样操作。
+- Unpadding
+将输入图像直接resize到某一个固定大小下，送入到网络中间训练。预测时同样操作。
 
 - Step-Scaling
-将输入图像按照某一个比例resize，这个比例以某一个步长在一定范围内随机变动。设定最小比例参数为`AUG.MIN_SCALE_FACTOR`, 最大比例参数`AUG.MAX_SCALE_FACTOR`，步长参数为`AUG.SCALE_STEP_SIZE`。预测时不对输入图像做处理。
+将输入图像按照某一个比例resize，这个比例以某一个步长在一定范围内随机变动。预测时不对输入图像做处理。
 
 - Range-Scaling
-固定长宽比resize，即图像长边对齐到某一个固定大小，短边随同样的比例变化。设定最小大小参数为`AUG.MIN_RESIZE_VALUE`，设定最大大小参数为`AUG.MAX_RESIZE_VALUE`。预测时需要将长边对齐到`AUG.INF_RESIZE_VALUE`所指定的大小，其中`AUG.INF_RESIZE_VALUE`在`AUG.MIN_RESIZE_VALUE`和`AUG.MAX_RESIZE_VALUE`范围内。
+将输入图像按照长边变化进行resize，即图像长边对齐到某一长度，该长度在一定范围内随机变动，短边随同样的比例变化。
+预测时需要将长边对齐到另外指定的固定长度。
 
 Range-Scaling示意图如下：
 
 ![](imgs/rangescale.png)
 
+|Resize方式|配置参数|含义|备注|
+|-|-|-|-|
+|Unpadding|AUG.FIX_RESIZE_SIZE|Resize的固定尺寸|
+|Step-Scaling|AUG.MIN_SCALE_FACTOR|Resize最小比例|
+||AUG.MAX_SCALE_FACTOR|Resize最大比例|
+||AUG.SCALE_STEP_SIZE|Resize比例选取的步长|
+|Range-Scaling|AUG.MIN_RESIZE_VALUE|图像长边变动范围的最小值|
+||AUG.MAX_RESIZE_VALUE|图像长边变动范围的最大值|
+|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|AUG.INF_RESIZE_VALUE|预测时长边对齐时所指定的固定长度|取值必须在<br>[AUG.MIN_RESIZE_VALUE,<br> AUG.MAX_RESIZE_VALUE]<br>范围内。|
+
+**注：本文所有配置参数可在configs目录下您的yaml文件中进行设置。**
+
 ## 图像翻转
 
 PaddleSeg支持以下2种翻转方式：
 
 - 左右翻转（Mirror）
-使用开关`AUG.MIRROR`，为True时该项功能开启，为False时该项功能关闭。
+以50%概率对图像进行左右翻转。
 
 - 上下翻转（Flip）
-使用开关`AUG.FLIP`，为True时该项功能开启，`AUG.FLIP_RATIO`控制是否上下翻转的概率。为False时该项功能关闭。
+以一定概率对图像进行上下翻转。
 
 以上2种开关独立运作，可组合使用。故图像翻转一共有如下4种可能的情况：
 
 <img src="imgs/data_aug_flip_mirror.png" width="60%" height="60%" />
 
+|图像翻转方式|配置参数|含义|备注|
+|-|-|-|-|
+|Mirror|AUG.MIRROR|左右翻转开关|为True时开启，为False时关闭|
+|Flip|AUG.FLIP|上下翻转开关|为True时开启，为False时关闭|
+||AUG.FLIP_RATIO|控制是否上下翻转的概率|当AUG.FLIP为False时无效|
+
+
 ## Rich Crop  
 
 Rich Crop是PaddleSeg结合实际业务经验开放的一套数据增强策略，面向标注数据少，测试数据情况繁杂的分割业务场景使用的数据增强策略。流程如下图所示:
 
 ![RichCrop示意图](imgs/data_aug_example.png)
 
-rich crop是指对图像进行多种变换，保证在训练过程中数据的丰富多样性，PaddleSeg支持以下几种变换。`AUG.RICH_CROP.ENABLE`为False时会直接跳过该步骤。
+Rich Crop是指对图像进行多种变换，保证在训练过程中数据的丰富多样性，包含以下4种变换:
+
+- Blur
+使用高斯模糊对图像进行平滑。
+
+- Rotation
+图像旋转，旋转角度在一定范围内随机选取，旋转产生的多余的区域使用`DATASET.PADDING_VALUE`值进行填充。
 
-- blur
-图像加模糊，使用开关`AUG.RICH_CROP.BLUR`，为False时该项功能关闭。`AUG.RICH_CROP.BLUR_RATIO`控制加入模糊的概率。
+- Aspect
+图像长宽比调整，从图像中按一定大小和宽高比裁取一定区域出来之后进行resize。
 
-- rotation
-图像旋转，`AUG.RICH_CROP.MAX_ROTATION`控制最大旋转角度。旋转产生的多余的区域的填充值为均值。
+- Color jitter
+图像颜色抖动，共进行亮度、饱和度和对比度三种颜色属性的调节。
 
-- aspect
-图像长宽比调整，从图像中crop一定区域出来之后在某一长宽比内进行resize。控制参数`AUG.RICH_CROP.MIN_AREA_RATIO`和`AUG.RICH_CROP.ASPECT_RATIO`。
+|Rich crop方式|配置参数|含义|备注|
+|-|-|-|-|
+|Rich crop|AUG.RICH_CROP.ENABLE|Rich crop总开关|为True时开启，为False时关闭所有变换|
+|Blur|AUG.RICH_CROP.BLUR|图像模糊开关|为True时开启，为False时关闭|
+||AUG.RICH_CROP.BLUR_RATIO|控制进行模糊的概率|当AUG.RICH_CROP.BLUR为False时无效|
+|Rotation|AUG.RICH_CROP.MAX_ROTATION|图像正向旋转的最大角度|取值0~90°，实际旋转角度在\[-AUG.RICH_CROP.MAX_ROTATION, AUG.RICH_CROP.MAX_ROTATION]范围内随机选取|
+|Aspect|AUG.RICH_CROP.MIN_AREA_RATIO|裁取图像与原始图像面积比最小值|取值0~1，取值越小则变化范围越大，若为0则不进行调节|
+||AUG.RICH_CROP.ASPECT_RATIO|裁取图像宽高比范围|取值非负，越小则变化范围越大，若为0则不进行调节|
+|Color jitter|AUG.RICH_CROP.BRIGHTNESS_JITTER_RATIO|亮度调节因子|取值0~1，取值越大则变化范围越大，若为0则不进行调节|
+||AUG.RICH_CROP.SATURATION_JITTER_RATIO|饱和度调节因子|取值0~1，取值越大则变化范围越大，若为0则不进行调节|
+|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|AUG.RICH_CROP.CONTRAST_JITTER_RATIO|对比度调节因子&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|取值0~1，取值越大则变化范围越大，若为0则不进行调节|
 
-- color jitter
-图像颜色调整，控制参数`AUG.RICH_CROP.BRIGHTNESS_JITTER_RATIO`、`AUG.RICH_CROP.SATURATION_JITTER_RATIO`、`AUG.RICH_CROP.CONTRAST_JITTER_RATIO`。
 
 ## Random Crop  
 
-该步骤主要是通过crop的方式使得输入到网络中的图像在某一个固定大小，控制该大小的参数为TRAIN_CROP_SIZE，类型为tuple，格式为(width, height). 当输入图像大小小于CROP_SIZE的时候会对输入图像进行padding，padding值为均值。
-
-- 输入图片格式
-    - 原图
-        - 图片格式：RGB三通道图片和RGBA四通道图片两种类型的图片进行训练，但是在一次训练过程只能存在一种格式。
-        - 图片转换：灰度图片经过预处理后之后会转变成三通道图片
-        - 图片参数设置：当图片为三通道图片时IMAGE_TYPE设置为rgb， 对应MEAN和STD也必须是一个长度为3的list，当图片为四通道图片时IMAGE_TYPE设置为rgba，对应的MEAN和STD必须是一个长度为4的list。
-    - 标注图
-        - 图片格式：标注图片必须为png格式的单通道多值图，元素值代表的是这个元素所属于的类别。
-        - 图片转换：在datalayer层对label图片进行的任何resize，以及旋转的操作，都必须采用最近邻的插值方式。
-        - 图片ignore：设置TRAIN.IGNORE_INDEX 参数可以选择性忽略掉属于某一个类别的所有像素点。这个参数一般设置为255
+随机裁剪图片和标签图，该步骤主要是通过裁剪的方式使得输入到网络中的图像在某一个固定大小。
+
+Random crop过程分为3种情形：
+- 当输入图像尺寸等于CROP_SIZE时，返回原图。
+- 当输入图像尺寸大于CROP_SIZE时，直接裁剪。
+- 当输入图像尺寸小于CROP_SIZE时，分别使用`DATASET.PADDING_VALUE`值和`DATASET.IGNORE_INDEX`值对图像和标签图进行填充，再进行裁剪。
+
+|Random crop方式|配置参数|含义|备注|
+|-|-|-|-|
+|Train crop|TRAIN_CROP_SIZE|训练过程进行random crop后的图像尺寸|类型为tuple，格式为(width, height)
+|Eval crop &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|EVAL_CROP_SIZE|除训练外的过程进行random crop后的图像尺寸|类型为tuple，格式为(width, height)
+
+`TRAIN_CROP_SIZE`可以设置任意大小，具体如何设置根据数据集而定。
+
+`EVAL_CROP_SIZE`的设置需要满足以下条件，共有3种情形：
+- 当`AUG.AUG_METHOD`为unpadding时，`EVAL_CROP_SIZE`的宽高应不小于`AUG.FIX_RESIZE_SIZE`的宽高。
+- 当`AUG.AUG_METHOD`为stepscaling时，`EVAL_CROP_SIZE`的宽高应不小于原图中最大的宽高。
+- 当`AUG.AUG_METHOD`为rangescaling时，`EVAL_CROP_SIZE`的宽高应不小于缩放后图像中最大的宽高。
+

pdseg/data_aug.py

@@ -368,7 +368,7 @@ def hsv_color_jitter(crop_img,
 
 def rand_crop(crop_img, crop_seg, mode=ModelPhase.TRAIN):
     """
-    随机裁剪图片和标签图, 若crop尺寸大于原始尺寸，分别使用均值和ignore值填充再进行crop，
+    随机裁剪图片和标签图, 若crop尺寸大于原始尺寸，分别使用DATASET.PADDING_VALUE值和DATASET.IGNORE_INDEX值填充再进行crop，
     crop尺寸与原始尺寸一致，返回原图，crop尺寸小于原始尺寸直接crop
 
     Args: