resnet_model_cn.md

# Model Zoo - ImageNet #

[ImageNet](http://www.image-net.org/) 是通用物体分类领域一个众所周知的数据库。本教程提供了一个用于ImageNet上的卷积分类网络模型。

## ResNet 介绍

论文 [Deep Residual Learning for Image Recognition](http://arxiv.org/abs/1512.03385) 中提出的ResNet网络结构在2015年ImageNet大规模视觉识别竞赛(ILSVRC 2015)的分类任务中赢得了第一名。他们提出残差学习的框架来简化网络的训练，所构建网络结构的的深度比之前使用的网络有大幅度的提高。下图展示的是基于残差的连接方式。左图构造网络模块的方式被用于34层的网络中，而右图的瓶颈连接模块用于50层，101层和152层的网络结构中。

<center>![resnet_block](./resnet_block.jpg)</center>
<center>Figure 1. ResNet Block</center>

本教程中我们给出了三个ResNet模型，这些模型都是由原作者提供的模型<https://github.com/KaimingHe/deep-residual-networks>转换过来的。我们使用PaddlePaddle在ILSVRC的验证集共5000幅图像上测试了模型的分类错误率，其中输入图像的颜色通道顺序为**BGR**，保持宽高比缩放到短边为256，只截取中心方形的图像区域。分类误差和模型大小由下表给出。
<center>
<table border="2" cellspacing="0" cellpadding="6" rules="all" frame="border">
<colgroup>
<col  class="left" />
<col  class="left" />
<col  class="left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="left">ResNet</th>
<th scope="col" class="left">Top-1</th>
<th scope="col" class="left">Model Size</th>
</tr>
</thead>

<tbody>
<tr>
<td class="left">ResNet-50</td>
<td class="left">24.9%</td>
<td class="left">99M</td>
</tr>
<tr>
<td class="left">ResNet-101</td>
<td class="left">23.7%</td>
<td class="left">173M</td>
</tr>
<tr>
<td class="left">ResNet-152</td>
<td class="left">23.2%</td>
<td class="left">234M</td>
</tr>
</tbody>

</table></center>
<br>

## ResNet 模型

50层，101层和152层的网络配置文件可参照```demo/model_zoo/resnet/resnet.py```。你也可以通过在命令行参数中增加一个参数如```--config_args=layer_num=50```来指定网络层的数目。

### 网络可视化

你可以通过执行下面的命令来得到ResNet网络的结构图解。该脚本会生成一个dot文件，然后利用我们服务器上已安装好的draw_dot工具将dot文件转成PNG图像。如果你不是在该服务器上运行，请自行安装graphviz来转换dot文件。

```
cd demo/model_zoo/resnet
./net_diagram.sh
```

### 模型下载

```
cd demo/model_zoo/resnet
./get_model.sh
```
你可以执行上述命令来下载所有的模型和均值文件，如果下载成功，这些文件将会被保存在```demo/model_zoo/resnet/model```路径下。

```
mean_meta_224  resnet_101  resnet_152  resnet_50
```
   * resnet_50: 50层网络模型。
   * resnet_101: 101层网络模型。
   * resnet_152: 152层网络模型。
   * mean\_meta\_224: 均值图像文件，图像大小为3 x 224 x 224，颜色通道顺序为**BGR**。你也可以使用这三个值: 103.939, 116.779, 123.68。

### 参数信息

* **卷积层权重**

  由于每个卷积层后面连接的是batch normalization层，因此该层中没有偏置(bias)参数，并且只有一个权重。
  形状: `(Co, ky, kx, Ci)`
   * Co: 输出特征图的通道数目
   * ky: 滤波器核在垂直方向上的尺寸
   * kx: 滤波器核在水平方向上的尺寸
   * Ci: 输入特征图的通道数目

  二维矩阵: (Co * ky * kx, Ci), 行优先次序存储。

* **全连接层权重**

  二维矩阵: (输入层尺寸, 本层尺寸), 行优先次序存储。

* **[Batch Normalization](<http://arxiv.org/abs/1502.03167>) 层权重**

本层有四个参数，实际上只有.w0和.wbias是需要学习的参数，另外两个分别是均值和方差。在测试阶段它们将会被加载到模型中。下表展示了batch normalization层的参数。
<center>
<table border="2" cellspacing="0" cellpadding="6" rules="all" frame="border">
<colgroup>
<col  class="left" />
<col  class="left" />
<col  class="left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="left">参数名</th>
<th scope="col" class="left">尺寸</th>
<th scope="col" class="left">含义</th>
</tr>
</thead>

<tbody>
<tr>
<td class="left">_res2_1_branch1_bn.w0</td>
<td class="left">256</td>
<td class="left">gamma, 缩放参数</td>
</tr>
<tr>
<td class="left">_res2_1_branch1_bn.w1</td>
<td class="left">256</td>
<td class="left">特征图均值</td>
</tr>
<tr>
<td class="left">_res2_1_branch1_bn.w2</td>
<td class="left">256</td>
<td class="left">特征图方差</td>
</tr>
<tr>
<td class="left">_res2_1_branch1_bn.wbias</td>
<td class="left">256</td>
<td class="left">beta, 偏置参数</td>
</tr>
</tbody>

</table></center>
<br>

### 参数观察

使用者可以使用下面的python脚本来读取参数值:

```
import sys
import numpy as np

def load(file_name):
    with open(file_name, 'rb') as f:
        f.read(16) # skip header for float type.
        return np.fromfile(f, dtype=np.float32)

if __name__=='__main__':
    weight = load(sys.argv[1])
```

或者直接使用下面的shell命令:

```
od -j 16 -f _res2_1_branch1_bn.w0
```

## 特征提取

我们提供了C++和Python接口来提取特征。下面的例子使用了`demo/model_zoo/resnet/example`中的数据，详细地展示了整个特征提取的过程。

### C++接口

首先，在配置文件中的`define_py_data_sources`里指定图像数据列表，具体请参照示例`demo/model_zoo/resnet/resnet.py`。

```
    train_list = 'train.list' if not is_test else None
    # mean.meta is mean file of ImageNet dataset.
    # mean.meta size : 3 x 224 x 224.
    # If you use three mean value, set like:
    # "mean_value:103.939,116.779,123.68;"
    args={
        'mean_meta': "model/mean_meta_224/mean.meta",
        'image_size': 224, 'crop_size': 224,
        'color': True,'swap_channel:': [2, 1, 0]}
    define_py_data_sources2(train_list,
                           'example/test.list',
                           module="example.image_list_provider",
                           obj="processData",
                           args=args)
```

第二步，在`resnet.py`文件中指定要提取特征的网络层的名字。例如，

```
Outputs("res5_3_branch2c_conv", "res5_3_branch2c_bn")
```

第三步，在`extract_fea_c++.sh`文件中指定模型路径和输出的目录，然后执行下面的命令。

```
cd demo/model_zoo/resnet
./extract_fea_c++.sh
```

如果执行成功，特征将会存到`fea_output/rank-00000`文件中，如下所示。同时你可以使用`load_feature.py`文件中的`load_feature_c`接口来加载该文件。

```
-0.115318 -0.108358 ... -0.087884;-1.27664 ... -1.11516 -2.59123;
-0.126383 -0.116248 ... -0.00534909;-1.42593 ... -1.04501 -1.40769;
```

* 每行存储的是一个样本的特征。其中，第一行存的是图像`example/dog.jpg`的特征，第二行存的是图像`example/cat.jpg`的特征。
* 不同层的特征由分号`;`隔开，并且它们的顺序与`Outputs()`中指定的层顺序一致。这里，左边是`res5_3_branch2c_conv`层的特征，右边是`res5_3_branch2c_bn`层特征。

### Python接口

示例`demo/model_zoo/resnet/classify.py`中展示了如何使用python来提取特征。下面的例子同样使用了`./example/test.list`中的数据。执行的命令如下：

```
cd demo/model_zoo/resnet
./extract_fea_py.sh
```

extract_fea_py.sh:

```
python classify.py \
     --job=extract \
     --conf=resnet.py\
     --use_gpu=1 \
     --mean=model/mean_meta_224/mean.meta \
     --model=model/resnet_50 \
     --data=./example/test.list \
     --output_layer="res5_3_branch2c_conv,res5_3_branch2c_bn" \
     --output_dir=features

```
* \--job=extract:              指定工作模式来提取特征。
* \--conf=resnet.py:           网络配置文件。
* \--use_gpu=1:                指定是否使用GPU。
* \--model=model/resnet_5:     模型路径。
* \--data=./example/test.list: 数据列表。
* \--output_layer="xxx,xxx":   指定提取特征的层。
* \--output_dir=features:      输出目录。

需要注意的是，这些ResNet模型中的卷积层适配于cudnn的实现，因此只支持GPU上操作。由于兼容性问题，它暂不支持CPU，我们以后将会修复该问题。

如果运行成功，你将会看到特征存储在`features/batch_0`文件中，该文件是由cPickle产生的。你可以使用`load_feature.py`中的`load_feature_py`接口来打开该文件，它将返回如下的字典：

```
{
'cat.jpg': {'res5_3_branch2c_conv': array([[-0.12638293, -0.116248  , -0.11883899, ..., -0.00895038, 0.01994277, -0.00534909]], dtype=float32), 'res5_3_branch2c_bn': array([[-1.42593431, -1.28918779, -1.32414699, ..., -1.45933616, -1.04501402, -1.40769434]], dtype=float32)},
'dog.jpg': {'res5_3_branch2c_conv': array([[-0.11531784, -0.10835785, -0.08809858, ...,0.0055237, 0.01505112, -0.08788397]], dtype=float32), 'res5_3_branch2c_bn': array([[-1.27663755, -1.18272924, -0.90937918, ..., -1.25178063, -1.11515927, -2.59122872]], dtype=float32)}
}
```

仔细观察，这些特征值与上述使用C++接口提取的结果是一致的。

## 预测

`classify.py`文件也可以用于对新样本进行预测。我们提供了一个示例脚本`predict.sh`，它可以使用50层的ResNet模型来对`example/test.list`中的数据进行预测。

```
cd demo/model_zoo/resnet
./predict.sh
```

predict.sh调用了`classify.py`:

```
python classify.py \
     --job=predict \
     --conf=resnet.py\
     --multi_crop \
     --model=model/resnet_50 \
     --use_gpu=1 \
     --data=./example/test.list
```
* \--job=extract:              指定工作模型进行预测。
* \--conf=resnet.py:           网络配置文件。network configure.
* \--multi_crop:               使用10个裁剪图像块，预测概率取平均。
* \--use_gpu=1:                指定是否使用GPU。
* \--model=model/resnet_50:    模型路径。
* \--data=./example/test.list: 数据列表。

如果运行成功，你将会看到如下结果，其中156和285是这些图像的分类标签。

```
Label of example/dog.jpg is: 156
Label of example/cat.jpg is: 282
```