Update README.md

kenuoseclab · Sep 4, 2019 · 7721881 · 7721881
1 parent aa03cba
commit 7721881
Show file tree

Hide file tree

Showing 9 changed files with 519 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -6,58 +6,76 @@
 ## 简介
 
 PaddleSeg是基于[PaddlePaddle](https://www.paddlepaddle.org.cn)开发的语义分割库，覆盖了DeepLabv3+, U-Net, ICNet三类主流的分割模型。通过统一的配置，帮助用户更便捷地完成从训练到部署的全流程图像分割应用。
-具备高性能、丰富的数据增强、工业级部署、全流程应用的特点。
 
+PaddleSeg具备高性能、丰富的数据增强、工业级部署、全流程应用的特点:
 
 
 - **丰富的数据增强**
 
   - 基于百度视觉技术部的实际业务经验，内置10+种数据增强策略，可结合实际业务场景进行定制组合，提升模型泛化能力和鲁棒性。
-  
+
 - **主流模型覆盖**
 
   - 支持U-Net, DeepLabv3+, ICNet三类主流分割网络，结合预训练模型和可调节的骨干网络，满足不同性能和精度的要求。
 
 - **高性能**
 
   - PaddleSeg支持多进程IO、多卡并行、多卡Batch Norm同步等训练加速策略，结合飞桨核心框架的显存优化算法，可以大幅度减少分割模型的显存开销，更快完成分割模型训练。
-  
+
 - **工业级部署**
 
   - 基于[Paddle Serving](https://github.com/PaddlePaddle/Serving)和PaddlePaddle高性能预测引擎，结合百度开放的AI能力，轻松搭建人像分割和车道线分割服务。
 
+</br>
+</br>
 
-更多模型信息与技术细节请查看[模型介绍](./docs/models.md)和[预训练模型](./docs/model_zoo.md)
+## 在线体验
 
-## AI Studio教程
+PaddleSeg提供了多种预训练模型，并且以NoteBook的方式提供了在线体验的教程，欢迎体验：
 
-### 快速开始
+|教程|链接|
+|-|-|
+|U-Net宠物分割|[点击体验](https://aistudio.baidu.com/aistudio/projectDetail/102889)|
+|PaddleSeg人像分割|[点击体验](https://aistudio.baidu.com/aistudio/projectDetail/100798)|
+|DeepLabv3+图像分割|[点击体验](https://aistudio.baidu.com/aistudio/projectDetail/101696)|
 
-通过 [PaddleSeg人像分割](https://aistudio.baidu.com/aistudio/projectDetail/100798) 教程可快速体验PaddleSeg人像分割模型的效果。
+</br>
+</br>
 
-### 入门教程
+## 使用教程
 
-入门教程以经典的U-Net模型为例, 结合Oxford-IIIT宠物数据集，快速熟悉PaddleSeg使用流程, 详情请点击[U-Net宠物分割](https://aistudio.baidu.com/aistudio/projectDetail/102889)。
+我们提供了一系列的使用教程，来说明如何使用PaddleSeg完成一个语义分割模型的训练、评估、部署。
 
-### 高级教程
+这一系列的文档被分为`快速入门`、`基础功能`、`预测部署`、`高级功能`四个部分，四个教程由浅至深地介绍PaddleSeg的设计思路和使用方法。
 
-高级教程以DeepLabv3+模型为例，结合Cityscapes数据集，快速了解ASPP, Backbone网络切换，多卡Batch Norm同步等策略，详情请点击[DeepLabv3+图像分割](https://aistudio.baidu.com/aistudio/projectDetail/101696)。
+### 快速入门
 
-### 垂类模型
+* [安装说明](./docs/installation.md)
+* [训练/评估/可视化](./docs/usage.md)
 
-更多特色垂类分割模型如LIP人体部件分割、人像分割、车道线分割模型可以参考[contrib](./contrib)
+### 基础功能
 
-## 使用文档
+* [模型列表与简介](./docs/models.md)
+* [预训练模型列表](./docs/model_zoo.md)
+* [自定义数据的准备与标注](./docs/data_prepare.md)
+* [数据和配置校验](./docs/check.md)
+* [使用DeepLabv3+预训练模型](./turtorial/finetune_deeplabv3plus.md)
+* [使用UNet预训练模型](./turtorial/finetune_unet.md)
+* [使用ICNet预训练模型](./turtorial/finetune_icnet.md)
 
-* [安装说明](./docs/installation.md)
-* [数据准备](./docs/data_prepare.md)
-* [数据增强](./docs/data_aug.md)
-* [预训练模型](./docs/model_zoo.md)
-* [训练/评估/预测(可视化)](./docs/usage.md)
-* [预测库集成](./inference/README.md)
-* [服务端部署](./serving/README.md)
-* [垂类分割模型](./contrib/README.md)
+### 预测部署
 
+* [模型导出](./docs/model_export.md)
+* [预测库使用](./inference)
+* [模型部署与Serving](./serving)
+
+### 高级功能
+
+* [PaddleSeg的数据增强](./docs/data_aug.md)
+* [特色垂类模型使用](./contrib)
+
+</br>
+</br>
 
 ## FAQ
 
@@ -69,15 +87,20 @@ A: 数据增强的配置可以参考文档[数据增强](./docs/data_aug.md)
 
 A: 降低Batch size，使用Group Norm策略等。
 
+</br>
+</br>
+
 ## 更新日志
 
-### 2019.08.26
+* 2019.08.26
 
-#### v0.1.0
+  **`v0.1.0`**
+  * PaddleSeg分割库初始版本发布，包含DeepLabv3+, U-Net, ICNet三类分割模型, 其中DeepLabv3+支持Xception, MobileNet两种可调节的骨干网络。
+  * CVPR 19' LIP人体部件分割比赛冠军预测模型发布[ACE2P](./contrib/ACE2P)
+  * 预置基于DeepLabv3+网络的[人像分割](./contrib/HumanSeg/)和[车道线分割](./contrib/RoadLine)预测模型发布
 
-* PaddleSeg分割库初始版本发布，包含DeepLabv3+, U-Net, ICNet三类分割模型, 其中DeepLabv3+支持Xception, MobileNet两种可调节的骨干网络。
-* CVPR 19' LIP人体部件分割比赛冠军预测模型发布[ACE2P](./contrib/ACE2P)
-* 预置基于DeepLabv3+网络的人像分割和车道线分割预测模型发布
+</br>
+</br>
 
 ## 如何贡献代码
 

diff --git a/docs/check.md b/docs/check.md
@@ -0,0 +1,57 @@
+# 配置/数据校验
+对用户自定义的数据集和yaml配置进行校验，帮助用户排查基本的数据和配置问题。
+
+数据校验脚本如下，支持通过`YAML_FILE_PATH`来指定配置文件。
+```
+# YAML_FILE_PATH为yaml配置文件路径
+python pdseg/check.py --cfg ${YAML_FILE_PATH}
+```
+运行后，命令行将显示校验结果的概览信息，详细信息可到detail.log文件中查看。
+
+### 1 列表分割符校验
+判断在`TRAIN_FILE_LIST`，`VAL_FILE_LIST`和`TEST_FILE_LIST`列表文件中的分隔符`DATASET.SEPARATOR`设置是否正确。
+### 2 数据集读取校验
+通过是否能成功读取`DATASET.TRAIN_FILE_LIST`，`DATASET.VAL_FILE_LIST`，`DATASET.TEST_FILE_LIST`中所有图片，判断这3项设置是否正确。
+
+若不正确返回错误信息。错误可能有多种情况，如数据集路径设置错误、图片损坏等。
+
+### 3 标注格式校验
+检查标注图像是否为PNG格式。
+
+**NOTE:** 标注图像请使用PNG无损压缩格式的图片，若使用其他格式则可能影响精度。
+
+### 4 标注通道数校验
+检查标注图的通道数。正确的标注图应该为单通道图像。
+
+### 5 标注类别校验
+检查实际标注类别是否和配置参数`DATASET.NUM_CLASSES`，`DATASET.IGNORE_INDEX`匹配。
+
+**NOTE:**
+标注图像类别数值必须在[0~(`DATASET.NUM_CLASSES`-1)]范围内或者为`DATASET.IGNORE_INDEX`。
+标注类别最好从0开始，否则可能影响精度。
+
+### 6 标注像素统计
+统计每种类别像素数量，显示以供参考。
+
+### 7 图像格式校验
+检查图片类型`DATASET.IMAGE_TYPE`是否设置正确。
+
+**NOTE:** 当数据集包含三通道图片时`DATASET.IMAGE_TYPE`设置为rgb；
+当数据集全部为四通道图片时`DATASET.IMAGE_TYPE`设置为rgba；
+
+### 8 图像与标注图尺寸一致性校验
+验证图像尺寸和对应标注图尺寸是否一致。
+
+### 9 模型验证参数`EVAL_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`为rangscaling时，`EVAL_CROP_SIZE`的宽高应不小于缩放后图像中最大的宽高。
+
+我们将计算并给出`EVAL_CROP_SIZE`的建议值。
+
+### 10 数据增强参数`AUG.INF_RESIZE_VALUE`校验
+验证`AUG.INF_RESIZE_VALUE`是否在[`AUG.MIN_RESIZE_VALUE`~`AUG.MAX_RESIZE_VALUE`]范围内。若在范围内，则通过校验。
diff --git a/docs/data_prepare.md b/docs/data_prepare.md
@@ -58,61 +58,3 @@ PaddleSeg采用通用的文件列表方式组织训练集、验证集和测试
 ![cityscapes_filelist](./imgs/file_list.png)
 
 完整的配置信息可以参考[`./dataset/cityscapes_demo`](../dataset/cityscapes_demo/)目录下的yaml和文件列表。
-
-## 数据校验
-对用户自定义的数据集和yaml配置进行校验，帮助用户排查基本的数据和配置问题。
-
-数据校验脚本如下，支持通过`YAML_FILE_PATH`来指定配置文件。
-```
-# YAML_FILE_PATH为yaml配置文件路径
-python pdseg/check.py --cfg ${YAML_FILE_PATH}
-```
-运行后，命令行将显示校验结果的概览信息，详细信息可到detail.log文件中查看。
-
-### 1 列表分割符校验
-判断在`TRAIN_FILE_LIST`，`VAL_FILE_LIST`和`TEST_FILE_LIST`列表文件中的分隔符`DATASET.SEPARATOR`设置是否正确。
-### 2 数据集读取校验
-通过是否能成功读取`DATASET.TRAIN_FILE_LIST`，`DATASET.VAL_FILE_LIST`，`DATASET.TEST_FILE_LIST`中所有图片，判断这3项设置是否正确。
-
-若不正确返回错误信息。错误可能有多种情况，如数据集路径设置错误、图片损坏等。
-
-### 3 标注格式校验
-检查标注图像是否为PNG格式。
-
-**NOTE:** 标注图像请使用PNG无损压缩格式的图片，若使用其他格式则可能影响精度。
-
-### 4 标注通道数校验
-检查标注图的通道数。正确的标注图应该为单通道图像。
-
-### 5 标注类别校验
-检查实际标注类别是否和配置参数`DATASET.NUM_CLASSES`，`DATASET.IGNORE_INDEX`匹配。
-
-**NOTE:**
-标注图像类别数值必须在[0~(`DATASET.NUM_CLASSES`-1)]范围内或者为`DATASET.IGNORE_INDEX`。
-标注类别最好从0开始，否则可能影响精度。
-
-### 6 标注像素统计
-统计每种类别像素数量，显示以供参考。
-
-### 7 图像格式校验
-检查图片类型`DATASET.IMAGE_TYPE`是否设置正确。
-
-**NOTE:** 当数据集包含三通道图片时`DATASET.IMAGE_TYPE`设置为rgb；
-当数据集全部为四通道图片时`DATASET.IMAGE_TYPE`设置为rgba；
-
-### 8 图像与标注图尺寸一致性校验
-验证图像尺寸和对应标注图尺寸是否一致。
-
-### 9 模型验证参数`EVAL_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`为rangscaling时，`EVAL_CROP_SIZE`的宽高应不小于缩放后图像中最大的宽高。
-
-我们将计算并给出`EVAL_CROP_SIZE`的建议值。
-
-### 10 数据增强参数`AUG.INF_RESIZE_VALUE`校验
-验证`AUG.INF_RESIZE_VALUE`是否在[`AUG.MIN_RESIZE_VALUE`~`AUG.MAX_RESIZE_VALUE`]范围内。若在范围内，则通过校验。
diff --git a/docs/model_export.md b/docs/model_export.md
@@ -0,0 +1,21 @@
+# 模型导出
+
+通过训练得到一个满足要求的模型后，如果想要将该模型接入到C++预测库或者Serving服务，我们需要通过`pdseg/export_model.py`来导出该模型。
+
+该脚本的使用方法和`train.py/eval.py/vis.py`完全一样
+
+# FLAGS
+
+|FLAG|用途|默认值|备注|
+|-|-|-|-|
+|--cfg|配置文件路径|None||
+
+# 使用示例
+
+我们使用[训练/评估/可视化](./usage.md)一节中训练得到的模型进行试用，脚本如下
+
+```shell
+python pdseg/export_model.py --cfg configs/unet_pet.yaml TEST.TEST_MODEL test/saved_models/unet_pet/final
+```
+
+模型会导出到freeze_model目录
diff --git a/docs/usage.md b/docs/usage.md
@@ -1,16 +1,14 @@
-# 训练/评估/预测(可视化)
+# 训练/评估/可视化
 
-PaddleSeg提供了 `训练`/`评估`/`预测(可视化)`/`模型导出` 等四个功能的使用脚本。四个脚本都支持通过不同的Flags来开启特定功能，也支持通过Options来修改默认的[训练配置](./config.md)。四者的使用方式非常接近，如下：
+PaddleSeg提供了 `训练`/`评估`/`可视化` 等三个功能的使用脚本。三个脚本都支持通过不同的Flags来开启特定功能，也支持通过Options来修改默认的[训练配置](./config.md)。三者的使用方式非常接近，如下：
 
 ```shell
 # 训练
 python pdseg/train.py ${FLAGS} ${OPTIONS}
 # 评估
 python pdseg/eval.py ${FLAGS} ${OPTIONS}
-# 预测/可视化
+# 可视化
 python pdseg/vis.py ${FLAGS} ${OPTIONS}
-# 模型导出
-python pdseg/export_model.py ${FLAGS} ${OPTIONS}
 ```
 
 `Note`:
@@ -27,7 +25,7 @@ python pdseg/export_model.py ${FLAGS} ${OPTIONS}
 |FLAG|支持脚本|用途|默认值|备注|
 |-|-|-|-|-|
 |--cfg|ALL|配置文件路径|None||
-|--use_gpu|train/eval/vis|是否使用GPU进行训练|False||
+|--use_gpu|ALL|是否使用GPU进行训练|False||
 |--use_mpio|train/eval|是否使用多线程进行IO处理|False|打开该开关会占用一定量的CPU内存，但是可以提高训练速度。</br> NOTE：windows平台下不支持该功能, 建议使用自定义数据初次训练时不打开，打开会导致数据读取异常不可见。 </br> |
 |--use_tb|train|是否使用TensorBoard记录训练数据|False||
 |--log_steps|train|训练日志的打印周期（单位为step）|10||
@@ -54,22 +52,19 @@ python pdseg/export_model.py ${FLAGS} ${OPTIONS}
 
 ### 下载预训练模型
 ```shell
-# 下载预训练模型
-wget https://bj.bcebos.com/v1/paddleseg/models/unet_coco_init.tgz
-# 解压缩到当前路径下
-tar xvzf unet_coco_init.tgz
+# 下载预训练模型并进行解压
+python pretrained_model/download_model unet_bn_coco
 ```
-### 下载Oxford-IIIT数据集
+### 下载mini_pet数据集
+我们使用了Oxford-IIIT中的猫和狗两个类别数据制作了一个小数据集mini_pet，用于快速体验
 ```shell
-# 下载Oxford-IIIT Pet数据集
-wget https://paddleseg.bj.bcebos.com/dataset/mini_pet.zip --no-check-certificate
-# 解压缩到当前路径下
-unzip mini_pet.zip
+# 下载预训练模型并进行解压
+python dataset/download_pet.py
 ```
 
 ### 模型训练
 
-为了方便体验，我们在configs目录下放置了Oxford-IIIT Pet所对应的配置文件`unet_pet.yaml`，可以通过`--cfg`指向该文件来设置训练配置。
+为了方便体验，我们在configs目录下放置了mini_pet所对应的配置文件`unet_pet.yaml`，可以通过`--cfg`指向该文件来设置训练配置。
 
 我们选择GPU 0号卡进行训练，这可以通过环境变量`CUDA_VISIBLE_DEVICES`来指定。
 
@@ -81,19 +76,14 @@ python pdseg/train.py --use_gpu \
                       --tb_log_dir train_log \
                       --cfg configs/unet_pet.yaml \
                       BATCH_SIZE 4 \
-                      TRAIN.PRETRAINED_MODEL unet_coco_init \
-                      DATASET.DATA_DIR mini_pet \
-                      DATASET.TEST_FILE_LIST mini_pet/file_list/test_list.txt \
-                      DATASET.TRAIN_FILE_LIST mini_pet/file_list/train_list.txt \
-                      DATASET.VAL_FILE_LIST mini_pet/file_list/val_list.txt \
-                      DATASET.VIS_FILE_LIST mini_pet/file_list/val_list.txt \
+                      TRAIN.PRETRAINED_MODEL pretrained_model/unet_bn_coco \
                       TRAIN.SYNC_BATCH_NORM True \
                       SOLVER.LR 5e-5
 ```
 
 `NOTE`:
 
-> * 上述示例中，一共存在三套配置方案: PaddleSeg默认配置/unet_pet.yaml/OPTIONS，三者的优先级顺序为 OPTIONS > yaml > 默认配置。这个原则对于train.py/eval.py/vis.py/export_model.py都适用
+> * 上述示例中，一共存在三套配置方案: PaddleSeg默认配置/unet_pet.yaml/OPTIONS，三者的优先级顺序为 OPTIONS > yaml > 默认配置。这个原则对于train.py/eval.py/vis.py都适用
 >
 > * 如果发现因为内存不足而Crash。请适当调低BATCH_SIZE。如果本机GPU内存充足，则可以调高BATCH_SIZE的大小以获得更快的训练速度
 
@@ -121,30 +111,17 @@ NOTE:
 ```shell
 python pdseg/eval.py --use_gpu \
                      --cfg configs/unet_pet.yaml \
-                     DATASET.DATA_DIR mini_pet \
-                     DATASET.VAL_FILE_LIST mini_pet/file_list/val_list.txt \
                      TEST.TEST_MODEL test/saved_models/unet_pet/final
 ```
 
 
-### 模型预测/可视化
+### 模型可视化
 通过vis.py来评估模型效果，我们选择最后保存的模型进行效果的评估：
 ```shell
 python pdseg/vis.py --use_gpu \
                      --cfg configs/unet_pet.yaml \
-                     DATASET.DATA_DIR mini_pet \
-                     DATASET.TEST_FILE_LIST mini_pet/file_list/test_list.txt \
                      TEST.TEST_MODEL test/saved_models/unet_pet/final
 ```
 `NOTE`
 1. 可视化的图片会默认保存在visual/visual_results目录下，可以通过`--vis_dir`来指定输出目录
 2. 训练过程中会使用DATASET.VIS_FILE_LIST中的图片进行可视化显示，而vis.py则会使用DATASET.TEST_FILE_LIST
-
-### 模型导出
-当确定模型效果满足预期后，我们需要通过export_model.py来导出可用于C++预测库部署的模型：
-```shell
-python pdseg/export_model.py --cfg configs/unet_pet.yaml \
-                                   TEST.TEST_MODEL test/saved_models/unet_pet/final
-```
-
-模型会导出到freeze_model目录，接下来就是进行模型的部署，相关步骤请查看[模型部署](../inference/README.md)