# 图像分割

## 1 简介

图像分割(Semantic Segmentation)是指将图像分成若干具有相似性质的区域的过程。这里提供了deeplab v3+的实现。图像分割的评价标准是mIOU。![segmentation](/Users/johnson/Documents/Workspace/easy-vision/docs/images/model/segmentation.jpg)



## 2 使用示例

下面我们以使用VOC数据集，训练deeplab v3+模型为例，介绍如何训练一个图像分割模型



### 2.1 数据准备

VOC我们已经提供了转换好的tfrecord， 下载VOC到 `data` 文件夹下

```bash
# 下载文件到pascal_voc_seg
ossutil cp -r  oss://pai-vision-data-hz/data/pascal_voc_seg/ data/pascal_voc_seg
# 下载文件到pascal_voc_seg_aug
ossutil cp -r  oss://pai-vision-data-hz/data/pascal_voc_seg_aug/ data/pascal_voc_seg_aug
```

下载resnet101预训练模型到`pretrained_models`文件夹下

```bash
ossutil cp -r oss://pai-vision-data-hz/pretrained_models/resnet_v1d_101/ pretrained_models/resnet_v1d_101
```



### 2.2 模型训练

#### 2.2.1 文件配置形式

运行如下python代码即可启动文件配置形式的训练评估流程，样例配置文件参见[sample_config](../sample_config.html#id3)，配置文件参数说明参见[proto文档](../proto.html)。如果你使用了自定义的配置文件，把`easy_vision.DEEPLAB_SAMPLE_CONFIG_STEP1` 或`easy_vision.DEEPLAB_SAMPLE_CONFIG_STEP2`替换为你的配置文件路径即可。

```python
import easy_vision
# 训练第一个步骤
easy_vision.train_and_evaluate(easy_vision.DEEPLAB_SAMPLE_CONFIG_STEP1)
# 完成之后，调用第二个步骤
easy_vision.train_and_evaluate(easy_vision.DEEPLAB_SAMPLE_CONFIG_STEP2)
```



#### 2.2.2 参数配置训练

运行如下python代码即可启动参数配置形式的训练评估流程

```python
import easy_vision
param_config = """
  --model_type DeeplabV3
  --backbone  resnet_v1d_101
  --backbone_feature_stride 16
  --bn_trainable true
  --num_classes 21
  --num_epochs 1
  --model_dir experiments/pascal_voc/deeplab_stage1
  --train_data data/pascal_voc_seg_aug/voc_ev_train.tfrecord
  --test_data data/pascal_voc_seg_aug/voc_ev_val.tfrecord
  --num_test_example 2
  --train_batch_size 6
  --test_batch_size 1
  --image_crop_size 513
  --lr_type polynomial_decay
  --initial_learning_rate 0.007
  --power 0.9"""
easy_vision.train_and_evaluate_with_param_config(param_config)
```

param_config 包含若干模型配置参数，格式遵循python argparser格式，各参数具体说明如下，所有字符串均不需要加引号

| 参数名称                | 参数描述                                                 | 参数值格式                                                   | 默认值              |
| ----------------------- | -------------------------------------------------------- | ------------------------------------------------------------ | ------------------- |
| model_type              | 训练模型类型                                             | 字符串， 可选范围<br />DeeplabV3                             | 无，必选参数        |
| backbone                | 分割模型使用的backbone                                   | 字符串格式，可取值范围：<br />resnet_v1_50<br />resnet_v1_101<br />resnet_v1a_18<br />resnet_v1a_34<br />resnet_v1d_50<br />resnet_v1d_101<br />xception_41<br />xception_65<br />xception_71 | 无，必选参数        |
| weight_decay            | l2 regularization的大小                                  | 浮点                                                         | 1e-4                |
| num_classes             | 分割类别数目(包括背景类)                                 | 21                                                           | 无，必选参数        |
| backbone_feature_stride | 主干网络的特征分辨率(下采样步长)                         | 整型，8或16                                                  | 默认为16            |
| bn_trainable            | BN是否可训练， 一般当train_batch_size大于8时，设置为true | 布尔型                                                       | 默认为true          |
| image_crop_size         | 图片裁剪后大小                                           | 整型                                                         | 可选参数，默认为513 |
|                         |                                                          |                                                              |                     |
| optimizer               | 优化方法，其中momentum就是sgd                            | 字符串，可选方法如下：<br />momentum<br />adam               | momentum            |
| lr_type | 学习率调整策略<br />exponential_decay, 指数衰减，详细参考[tf.train.exponential_decay ](https://www.tensorflow.org/api_docs/python/tf/train/exponential_decay)<br />polynomial_decay, 多项式衰减，详细参考[tf.train.polynomial_decay](https://www.tensorflow.org/api_docs/python/tf/train/polynomial_decay)， 其中num_steps自动设置为总的训练迭代次数，end_learning_rate为initial_learning_rate的千分之一<br />manual_step， 人工指定各阶段的学习率，<br />通过decay_epochs 指定需要调整学习率的迭代轮数，<br />通过learning_rates指定对应迭代轮数使用的学习率<br />cosine_decay，通过余弦曲线调制学习率变化，最终会降到0。详细参考[论文](https://arxiv.org/abs/1608.03983)，<br />通过decay_epochs 指定需要调整学习率的迭代轮数 | 字符串，可选方法如下：<br />exponential_decay<br />polynomial_decay<br />manual_step<br />cosine_decay | exponential_decay |
| initial_learning_rate | 初始学习率 | 浮点数 | 0.01 |
| decay_epochs<br /> | 如果使用exponential_decay, 参数对应 [tf.train.exponential_decay]()中的decay_steps，后端会自动根据训练数据总数把decay_epochs转换为decay_steps。例如数值可填：10，一般是总epoch数的1/2。<br /><br />如果使用manual_step， 参数表示需要调整学习率的迭代轮数， "16 18"表示在16epoch 18 epoch对学习率进行调整。一般这两个值取总设置的总epoch的8/10、9/10 | 整数列表<br />20 <br />20 40 60 | 20 |
| decay_factor | [tf.train.exponential_decay ](https://www.tensorflow.org/api_docs/python/tf/train/exponential_decay)中的decay_factor | 浮点数 | 0.95 |
| staircase | [tf.train.exponential_decay ](https://www.tensorflow.org/api_docs/python/tf/train/exponential_decay)中的staircase | 布尔 | true |
| power | [tf.train.polynomial_decay](https://www.tensorflow.org/api_docs/python/tf/train/polynomial_decay) 中的power | float | 0.9 |
| learning_rates | manual_step学习率调整策略中使用的参数，表示在指定epoch 学习率调整为多少. 如果您指定的调整epoch有两个，则需要在此也填写两个对应的学习率。例：decay_epoches为20 40，此处填写0.001 0.0001，则代表在20epoch学习率调整为0.001，40epoch学习率调整为0.0001。建议这几次调整的学习率是初始学习率的1/10、1/100、1/1000...... | manual_step学习率调整策略中使用的参数，表示在指定epoch 学习率调整为多少 | 浮点列表 |
| lr_warmup | 是否对学习率做warmup | 布尔 | false |
| lr_warm_up_epochs | 学习率warmup的轮数 | 浮点型 | 1 |
| train_data | 训练数据文件oss路径 | oss://path/to/train_*.tfrecord | 无，必选参数 |
| test_data | 训练过程中评估数据oss路径 | oss://path/to/test_*.tfrecord | 无，必选参数 |
| train_batch_size | 训练batch_size | 整型， 例如32 | 无，必选参数 |
| test_batch_size | 评估batch_size | 整型， 例如32 | 无，必选参数 |
| train_num_readers | 训练数据并发读取线程数 | 整型 | 4 |
| model_dir | 训练所用oss目录 | oss://path/to/model | 无，必选参数 |
| pretrained_model | 预训练模型oss路径，如果提供，会在此模型基础上finetune | oss://pai-vision-data-hz/pretrained_models/inception_v4.ckpt | "" |
| use_pretrained_model | 是否使用预训练模型 | 布尔型 | true |
| num_epochs | 训练迭代轮数，1表示所有训练数据过了一遍 | 整型  40 | 无，必选参数 |
| num_test_example | 训练过程中评估数据条目数， -1表示使用所有测试数据集数据 | 整型，例如2000 | 可选，默认-1 |
| num_visualizations | 评估过程可视化显示的样本数目 | 整型 | 10 |
| save_checkpoint_epochs | 保存checkpoint的频率，以epoch为单位， 1表示每过一遍训练数据保存一次checkpoint | 整型 | 1 |
| save_summary_epochs | 保存summary的频率，以epoch为单位， 0.01 表示每过1%训练数据保存一次summary | 浮点 | 0.01 |
| num_train_images | 总的训练样本数，如果使用自己生成的tfrecord需要提供该信息 | 整型 | 可选，默认0 |
| label_map_path | 类别映射文件，如果使用自己生成的tfrecord需要提供该信息 | 字符串 | 可选，默认"" |