
# DynamicRCNN（图像目标检测/Pytorch）
## 1. 概述
此模型基于[Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training](https://arxiv.org/pdf/2004.06002.pdf "Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training")中突出的模型结构实现，该算法可以载入预训练好的，达到论文精度的模型作为特征提取网络，可以在用户的数据集上进行训练，用于其他场景的预测。训练后生成的模型可以直接在modelArts平台部署成在线服务。
图像目标检测的评估手段一般使用mAp，详细说明请参考：[coco数据集评价指标](https://cocodataset.org/#detection-eval "coco数据集评价指标")
本算法的其他信息如下表所示：

|项目|说明|
| ------------ | ------------ |
|参考论文  |Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training  |
|使用框架   |Pytorch-1.0.0-python3.6   |
|训练集   |COCO 2017 train   |
|训练总iteration数   |270k   |
|训练batch_size   |使用8卡训练，每张卡IMS_PER_GPU = 2，相当于总batch_size为16   |
|训练硬件及耗时   |8*v100,54.9小时   |
|测试集   |COCO 2017test-dev   |
|推理硬件及速度   |GPU，2.3s/pic(GPU型号v100NV32)   |
|输入图像尺寸   |multi-scale训练，有400\*400，600\*600，800\*800，1000\*1000，1200\*1200五种，可以支持多尺度   |
|原论文准确率   |mAP=49.2   |
|本算法准确率   |map=49.2   |
## 2. 训练
### 2.1 算法基本信息
- 任务类型：目标检测
- 支持的框架引擎：Pytorch-1.0.0-python3.6
- 算法输入：
   - 存储在OBS上的数据集，必须按照coco数据集的格式进行存储。训练时标记文件以train.json命名，图片文件放在train文件夹下，测试时标记文件以test.json命名，图片文件放在test文件夹下。详情及目录结构查看下文和第4节案例指导
   - 训练好的iteration_270000_mAP_49.2.pth参数文件。
- 算法输出
   - 用于Pytorch推理的pth模型，GPU推理速度:2.3s/pic
- 代码结构
```
DynamicRCNN-sub
|-pre-trained_weights
	|R101.pkl
	|R50.pkl
|-trained_model
	|-model
		|-build
			|...
		|-dynamic_rcnn
			|...
		|-DynamicRCNN.egg-info
			|...
		|config.json
		|config.py
		|customize_service.py
		|network.py
		|iteration_270000_mAP_49.2.pth
|train.py #模型启动文件
|evaluation.py #模型预测文件
|pip-requirements #环境配置文件
|... #其他配置文件
|-build #以下为模型运行必须的文件
	|...
|-dynamic_rcnn
	|...
|-DynamicRCNN.egg-info
	|...
```
### 2.2 训练参数说明

|名称|默认值|类型|是否必填|是否可修改|描述|
| ------------ | ------------ | ------------ | ------------ | ------------ | ------------ |
|eval|False|string|是|是|（1）False，本算法执行模型训练过程；（2）True，本算法加载load_weight参数指定的模型，然后执行模型评估过程。创建训练作业时指定的数据存储位置data_url目录下，需要有test文件夹（存放测试图片）和test.json文件，输出有test_log.txt包含计算得到的mAP等各项预测指标，预测的结果图片文件夹imgs和包含预测结果bbox.json的文件夹inference。针对test.json中是否包含groundtruth，输出的test_log.txt会有所不同。2a) 如果test.json中包含groundtruth则模型输出的test_log.txt包含计算得到的mAP等各项预测指标。2b) 如果test.json中包含groundtruth则模型输出的test_log.txt中的mAP等各项预测指标为-1。除此之外，创建训练作业时指定的数据存储位置data_url目录下，如果没有图片，则模型评估过程报错；|
|num_gpus|1|int|是|是|训练使用到的gpu个数，与用户选择的训练规格有关，如果用户选择单个gpu训练那么该参数为1，如果用户选择8gpu训练，为了避免资源浪费，请将该参数改为8。注意在test模式下该参数不起作用，无论使用什么样的训练规格，都只使用单gpu进行测试|   
|training_iter|1000|int|是|是|train模式下训练的轮数，论文中是在8gpu的条件下训练了270k个iteration。test模式下该参数不起作用。|
|check_period|5000|string|是|是|经过多少个iteration保留一次训练的中间结果参数文件，默认5000。由于训练时有内存的限制，该值不易设置的太小，建议一次训练最多保留15次中间结果。|
|load_weight|std|string|是|是|（1）std会加载固定的默认路径，默认加载本算法源码目录中的trained_model/model/best_model.pth继续训练，加载成功会打印日志；（2）可变的OBS路径，如obs://blb-paper/DynamicRCNN-MINE/output/model/dynamic_rcnn_r101_dcnv2_fpn_mstrain_2x_test_model_0270000.pth。用户可指定OBS上的一个模型文件路径，然后本算法会加载该模型继续训练，加载成功会打印日志。eval是false的时候，load_weights如果加载obs路径的模型则用于继续训练，eval为true的时候load_weights如果加载obs路径的模型则用于测试|
注1：训练模式下输入的数据文件夹格式
```
|train.json#相当于coco数据集里的annotations，里面有图片信息和标记信息
|-train#放入训练图片数据
	|0000000001.jpg
	|0000000002.jpg
	|	...
```
注2：测试模式下输入的数据文件夹格式
```
|test.json#相当于coco数据集里的annotations，里面有图片信息和标记信息
|-test#放入测试图片数据
	|0000000001.jpg
	|0000000002.jpg
	|	...

```
### 2.3 训练输出文件
train模式下的训练输出文件如下：
```
|-model
	|-build
		...
	|-dynamic_rcnn
		...
	|-DynamicRCNN.egg-info
		...
	|config.json
	|config.py
	|customize_service.py
	|network.py
	|iteration_270000_mAP_49.2.pth
|-checkpoints
	|xxx.pth
	|xxx.pth
	|...#训练过程中保存的中间过程参数
|train_log.txt#训练日志
```
test模式下的训练输出文件如下：
```
|-log
	|test_log.txt#测试日志
|-inference
	|xxx.bbox#预测结果的所有bbox输出
	|xxx #其他输出文件
|-imgs#预测结果图片
	|1.jpg
	|2.jpg
	|xxx.jpg
```
# 3. GPU推理
本模型只支持GPU训练与测试
# 4. 案例指导
本算法的详细使用方法，请查看[ModelArts AI Gallery算法Dynamic R-CNN使用指导](https://marketplace.huaweicloud.com/markets/aihub/article/detail/?content_id=503f96ec-2e2d-4a0f-8759-9f08dd0949b9)。

DynamicRCNN（图像目标检测/Pytorch）

1. 概述

此模型基于Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training中突出的模型结构实现，该算法可以载入预训练好的，达到论文精度的模型作为特征提取网络，可以在用户的数据集上进行训练，用于其他场景的预测。训练后生成的模型可以直接在modelArts平台部署成在线服务。
图像目标检测的评估手段一般使用mAp，详细说明请参考：coco数据集评价指标
本算法的其他信息如下表所示：

项目	说明
参考论文	Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training
使用框架	Pytorch-1.0.0-python3.6
训练集	COCO 2017 train
训练总iteration数	270k
训练batch_size	使用8卡训练，每张卡IMS_PER_GPU = 2，相当于总batch_size为16
训练硬件及耗时	8*v100,54.9小时
测试集	COCO 2017test-dev
推理硬件及速度	GPU，2.3s/pic(GPU型号v100NV32)
输入图像尺寸	multi-scale训练，有400400，600600，800800，10001000，1200*1200五种，可以支持多尺度
原论文准确率	mAP=49.2
本算法准确率	map=49.2

2. 训练

2.1 算法基本信息

任务类型：目标检测
支持的框架引擎：Pytorch-1.0.0-python3.6
算法输入：
- 存储在OBS上的数据集，必须按照coco数据集的格式进行存储。训练时标记文件以train.json命名，图片文件放在train文件夹下，测试时标记文件以test.json命名，图片文件放在test文件夹下。详情及目录结构查看下文和第4节案例指导
- 训练好的iteration_270000_mAP_49.2.pth参数文件。
算法输出
- 用于Pytorch推理的pth模型，GPU推理速度:2.3s/pic
代码结构

DynamicRCNN-sub
|-pre-trained_weights
	|R101.pkl
	|R50.pkl
|-trained_model
	|-model
		|-build
			|...
		|-dynamic_rcnn
			|...
		|-DynamicRCNN.egg-info
			|...
		|config.json
		|config.py
		|customize_service.py
		|network.py
		|iteration_270000_mAP_49.2.pth
|train.py #模型启动文件
|evaluation.py #模型预测文件
|pip-requirements #环境配置文件
|... #其他配置文件
|-build #以下为模型运行必须的文件
	|...
|-dynamic_rcnn
	|...
|-DynamicRCNN.egg-info
	|...

2.2 训练参数说明

名称	默认值	类型	是否必填	是否可修改	描述
eval	False	string	是	是	（1）False，本算法执行模型训练过程；（2）True，本算法加载load_weight参数指定的模型，然后执行模型评估过程。创建训练作业时指定的数据存储位置data_url目录下，需要有test文件夹（存放测试图片）和test.json文件，输出有test_log.txt包含计算得到的mAP等各项预测指标，预测的结果图片文件夹imgs和包含预测结果bbox.json的文件夹inference。针对test.json中是否包含groundtruth，输出的test_log.txt会有所不同。2a) 如果test.json中包含groundtruth则模型输出的test_log.txt包含计算得到的mAP等各项预测指标。2b) 如果test.json中包含groundtruth则模型输出的test_log.txt中的mAP等各项预测指标为-1。除此之外，创建训练作业时指定的数据存储位置data_url目录下，如果没有图片，则模型评估过程报错；
num_gpus	1	int	是	是	训练使用到的gpu个数，与用户选择的训练规格有关，如果用户选择单个gpu训练那么该参数为1，如果用户选择8gpu训练，为了避免资源浪费，请将该参数改为8。注意在test模式下该参数不起作用，无论使用什么样的训练规格，都只使用单gpu进行测试
training_iter	1000	int	是	是	train模式下训练的轮数，论文中是在8gpu的条件下训练了270k个iteration。test模式下该参数不起作用。
check_period	5000	string	是	是	经过多少个iteration保留一次训练的中间结果参数文件，默认5000。由于训练时有内存的限制，该值不易设置的太小，建议一次训练最多保留15次中间结果。
load_weight	std	string	是	是	（1）std会加载固定的默认路径，默认加载本算法源码目录中的trained_model/model/best_model.pth继续训练，加载成功会打印日志；（2）可变的OBS路径，如obs://blb-paper/DynamicRCNN-MINE/output/model/dynamic_rcnn_r101_dcnv2_fpn_mstrain_2x_test_model_0270000.pth。用户可指定OBS上的一个模型文件路径，然后本算法会加载该模型继续训练，加载成功会打印日志。eval是false的时候，load_weights如果加载obs路径的模型则用于继续训练，eval为true的时候load_weights如果加载obs路径的模型则用于测试

注1：训练模式下输入的数据文件夹格式

|train.json#相当于coco数据集里的annotations，里面有图片信息和标记信息
|-train#放入训练图片数据
	|0000000001.jpg
	|0000000002.jpg
	|	...

注2：测试模式下输入的数据文件夹格式

|test.json#相当于coco数据集里的annotations，里面有图片信息和标记信息
|-test#放入测试图片数据
	|0000000001.jpg
	|0000000002.jpg
	|	...

2.3 训练输出文件

train模式下的训练输出文件如下：

|-model
	|-build
		...
	|-dynamic_rcnn
		...
	|-DynamicRCNN.egg-info
		...
	|config.json
	|config.py
	|customize_service.py
	|network.py
	|iteration_270000_mAP_49.2.pth
|-checkpoints
	|xxx.pth
	|xxx.pth
	|...#训练过程中保存的中间过程参数
|train_log.txt#训练日志

test模式下的训练输出文件如下：

|-log
	|test_log.txt#测试日志
|-inference
	|xxx.bbox#预测结果的所有bbox输出
	|xxx #其他输出文件
|-imgs#预测结果图片
	|1.jpg
	|2.jpg
	|xxx.jpg

3. GPU推理

本模型只支持GPU训练与测试

4. 案例指导

本算法的详细使用方法，请查看ModelArts AI Gallery算法Dynamic R-CNN使用指导。

<h1><a id="DynamicRCNNPytorch_0"></a>DynamicRCNN（图像目标检测/Pytorch）</h1> <h2><a id="1__1"></a>1. 概述</h2> <p>此模型基于<a href="https://arxiv.org/pdf/2004.06002.pdf" title="Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training" target="_blank">Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training</a>中突出的模型结构实现，该算法可以载入预训练好的，达到论文精度的模型作为特征提取网络，可以在用户的数据集上进行训练，用于其他场景的预测。训练后生成的模型可以直接在modelArts平台部署成在线服务。<br /> 图像目标检测的评估手段一般使用mAp，详细说明请参考：<a href="https://cocodataset.org/#detection-eval" title="coco数据集评价指标" target="_blank">coco数据集评价指标</a><br /> 本算法的其他信息如下表所示：</p> <table> <thead> <tr> <th>项目</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td>参考论文</td> <td>Dynamic R-CNN: Towards High Quality Object Detection via Dynamic Training</td> </tr> <tr> <td>使用框架</td> <td>Pytorch-1.0.0-python3.6</td> </tr> <tr> <td>训练集</td> <td>COCO 2017 train</td> </tr> <tr> <td>训练总iteration数</td> <td>270k</td> </tr> <tr> <td>训练batch_size</td> <td>使用8卡训练，每张卡IMS_PER_GPU = 2，相当于总batch_size为16</td> </tr> <tr> <td>训练硬件及耗时</td> <td>8*v100,54.9小时</td> </tr> <tr> <td>测试集</td> <td>COCO 2017test-dev</td> </tr> <tr> <td>推理硬件及速度</td> <td>GPU，2.3s/pic(GPU型号v100NV32)</td> </tr> <tr> <td>输入图像尺寸</td> <td>multi-scale训练，有400*400，600*600，800*800，1000*1000，1200*1200五种，可以支持多尺度</td> </tr> <tr> <td>原论文准确率</td> <td>mAP=49.2</td> </tr> <tr> <td>本算法准确率</td> <td>map=49.2</td> </tr> </tbody> </table> <h2><a id="2__19"></a>2. 训练</h2> <h3><a id="21__20"></a>2.1 算法基本信息</h3> <ul> <li>任务类型：目标检测</li> <li>支持的框架引擎：Pytorch-1.0.0-python3.6</li> <li>算法输入： <ul> <li>存储在OBS上的数据集，必须按照coco数据集的格式进行存储。训练时标记文件以train.json命名，图片文件放在train文件夹下，测试时标记文件以test.json命名，图片文件放在test文件夹下。详情及目录结构查看下文和第4节案例指导</li> <li>训练好的iteration_270000_mAP_49.2.pth参数文件。</li> </ul> </li> <li>算法输出 <ul> <li>用于Pytorch推理的pth模型，GPU推理速度:2.3s/pic</li> </ul> </li> <li>代码结构</li> </ul> <pre><code class="lang-">DynamicRCNN-sub |-pre-trained_weights |R101.pkl |R50.pkl |-trained_model |-model |-build |... |-dynamic_rcnn |... |-DynamicRCNN.egg-info |... |config.json |config.py |customize_service.py |network.py |iteration_270000_mAP_49.2.pth |train.py #模型启动文件 |evaluation.py #模型预测文件 |pip-requirements #环境配置文件 |... #其他配置文件 |-build #以下为模型运行必须的文件 |... |-dynamic_rcnn |... |-DynamicRCNN.egg-info |... </code></pre> <h3><a id="22__58"></a>2.2 训练参数说明</h3> <table> <thead> <tr> <th>名称</th> <th>默认值</th> <th>类型</th> <th>是否必填</th> <th>是否可修改</th> <th>描述</th> </tr> </thead> <tbody> <tr> <td>eval</td> <td>False</td> <td>string</td> <td>是</td> <td>是</td> <td>（1）False，本算法执行模型训练过程；（2）True，本算法加载load_weight参数指定的模型，然后执行模型评估过程。创建训练作业时指定的数据存储位置data_url目录下，需要有test文件夹（存放测试图片）和test.json文件，输出有test_log.txt包含计算得到的mAP等各项预测指标，预测的结果图片文件夹imgs和包含预测结果bbox.json的文件夹inference。针对test.json中是否包含groundtruth，输出的test_log.txt会有所不同。2a) 如果test.json中包含groundtruth则模型输出的test_log.txt包含计算得到的mAP等各项预测指标。2b) 如果test.json中包含groundtruth则模型输出的test_log.txt中的mAP等各项预测指标为-1。除此之外，创建训练作业时指定的数据存储位置data_url目录下，如果没有图片，则模型评估过程报错；</td> </tr> <tr> <td>num_gpus</td> <td>1</td> <td>int</td> <td>是</td> <td>是</td> <td>训练使用到的gpu个数，与用户选择的训练规格有关，如果用户选择单个gpu训练那么该参数为1，如果用户选择8gpu训练，为了避免资源浪费，请将该参数改为8。注意在test模式下该参数不起作用，无论使用什么样的训练规格，都只使用单gpu进行测试</td> </tr> <tr> <td>training_iter</td> <td>1000</td> <td>int</td> <td>是</td> <td>是</td> <td>train模式下训练的轮数，论文中是在8gpu的条件下训练了270k个iteration。test模式下该参数不起作用。</td> </tr> <tr> <td>check_period</td> <td>5000</td> <td>string</td> <td>是</td> <td>是</td> <td>经过多少个iteration保留一次训练的中间结果参数文件，默认5000。由于训练时有内存的限制，该值不易设置的太小，建议一次训练最多保留15次中间结果。</td> </tr> <tr> <td>load_weight</td> <td>std</td> <td>string</td> <td>是</td> <td>是</td> <td>（1）std会加载固定的默认路径，默认加载本算法源码目录中的trained_model/model/best_model.pth继续训练，加载成功会打印日志；（2）可变的OBS路径，如obs://blb-paper/DynamicRCNN-MINE/output/model/dynamic_rcnn_r101_dcnv2_fpn_mstrain_2x_test_model_0270000.pth。用户可指定OBS上的一个模型文件路径，然后本算法会加载该模型继续训练，加载成功会打印日志。eval是false的时候，load_weights如果加载obs路径的模型则用于继续训练，eval为true的时候load_weights如果加载obs路径的模型则用于测试</td> </tr> </tbody> </table> <p>注1：训练模式下输入的数据文件夹格式</p> <pre><code class="lang-">|train.json#相当于coco数据集里的annotations，里面有图片信息和标记信息 |-train#放入训练图片数据 |0000000001.jpg |0000000002.jpg | ... </code></pre> <p>注2：测试模式下输入的数据文件夹格式</p> <pre><code class="lang-">|test.json#相当于coco数据集里的annotations，里面有图片信息和标记信息 |-test#放入测试图片数据 |0000000001.jpg |0000000002.jpg | ... </code></pre> <h3><a id="23__84"></a>2.3 训练输出文件</h3> <p>train模式下的训练输出文件如下：</p> <pre><code class="lang-">|-model |-build ... |-dynamic_rcnn ... |-DynamicRCNN.egg-info ... |config.json |config.py |customize_service.py |network.py |iteration_270000_mAP_49.2.pth |-checkpoints |xxx.pth |xxx.pth |...#训练过程中保存的中间过程参数 |train_log.txt#训练日志 </code></pre> <p>test模式下的训练输出文件如下：</p> <pre><code class="lang-">|-log |test_log.txt#测试日志 |-inference |xxx.bbox#预测结果的所有bbox输出 |xxx #其他输出文件 |-imgs#预测结果图片 |1.jpg |2.jpg |xxx.jpg </code></pre> <h1><a id="3_GPU_117"></a>3. GPU推理</h1> <p>本模型只支持GPU训练与测试</p> <h1><a id="4__119"></a>4. 案例指导</h1> <p>本算法的详细使用方法，请查看<a href="https://marketplace.huaweicloud.com/markets/aihub/article/detail/?content_id=503f96ec-2e2d-4a0f-8759-9f08dd0949b9" target="_blank">ModelArts AI Gallery算法Dynamic R-CNN使用指导</a>。</p>