# CrowdDet （目标检测/Pytorch）

## 1. 概述

此模型基于[Detection in Crowded Scenes: One Proposal, Multiple Predictions](https://arxiv.org/abs/2003.09163)中提出的模型结构实现，该算法会载入在[CrowdHuman](http://www.crowdhuman.org/)上的预训练模型，在用户数据集上做迁移学习。我们提供了训练代码和可用于训练的模型，用于实际场景的微调训练。训练后生成的模型可直接在ModelArts平台部署成在线服务。



以识别人体为目标的检测的评估手段一般用AP​， MR-2和JI(Jaccard Index)指标，详细描述可参考原论文或下表。

| 指标 | 描述                                               |
| ---- | -------------------------------------------------- |
| AP​   | Averaged precision of detection.                   |
| MR-2 | Log-average miss rate on false positive per image. |
| JI​   | Jaccard Index.                                     |

本算法其他信息如下表所示：

| 项目           | 说明                                                         |
| -------------- | ------------------------------------------------------------ |
| 参考论文       | Detection in Crowded Scenes: One Proposal, Multiple Predictions |
| 使用框架       | Pytorch-1.4.0 （在ModelArts上使用Pytorch-1.4.0创建训练作业，然后在训练开始之前将Pytorch升级为1.5.0）                  |
| 训练集         | CrowdHuman annotation_train.odgt + images                    |
| 训练总epoch数  | 25 (from scratch)                                                      |
| 训练batch_size | 8卡训练，每张卡batch_size = 2                                |
| 训练硬件及耗时 | 8*v100，约11小时                                             |
| 测试集         | CrowdHuman annotation_val.odgt + images                      |
| 输入图像尺寸   | CrowdHuman: [3236, 4856, 3]                                  |
| 原论文指标     | AP = 90.7%, MR-2 = 41.4%, JI = 82.3%​                         |
| 本算法指标     | AP = 90.6%, MR-2 = 41.3%, JI = 83.4%                         |

## 2. 训练

### 2.1. 算法基本信息

* 任务类型：（人体）目标检测
* 支持的框架引擎：PyTorch-1.4.0-python3.6（在ModelArts上使用Pytorch-1.4.0创建训练作业，然后在训练开始之前将Pytorch升级为1.5.0)
* 算法输入：
  * 存储在OBS上的数据集，必须按照CrowdHuman数据集的格式进行储存，详情请查看下文第4节。
  * CrowdHuman预训练模型，在CrowdHuman验证集上的AP​是90.96%。

- 算法输出：

- 用于Pytorch推理的pth模型，在验证集上的推理结果

- 代码结构

  ```
  src
  |-- download/ # 算法运行时将OBS中储存的数据将加载到此目录
  |     |-- annotation_train.odgt
  |     |-- annotation_val.odgt
  |     |-- images/
  |     |     |-- 1066405,100a000985ef070.jpg
  |-- pre-trained_weights/
  |     |-- resnet50_fbaug.pth # 训练模型所需要的backbone起点
  |-- trained_model/
  |     |-- model/
  |     |     |-- model_config.py # 模型和训练默认参数配置
  |     |     |-- network.py # 模型结构
  |     |     |-- config.json # 模型部署文件
  |     |     |-- customize_service.py # 模型部署文件
  |     |     |-- model_final.pth # 训练得到的模型，用于模型部署
  |     |     |-- model_lib/ # 开源包、模型构建、数据集加载等文件
  |     |     |     |--...
  |-- tools/
  |     |-- run_infer.py # 推理
  |     |-- run_train.py # 训练模型
  |     |-- run_test.py # 在验证集上推理并输出评价指标
  |-- config_env.sh # 运行前环境配置（升级Pytorch-1.5.0）
  |-- train.py # 算法执行文件
  |-- evaluation.py # 输出业界评价标准
  ```

### 2.2. 训练参数说明

| 名称              | 默认值                                 | 类型   | 是否必填 | 是否可修改 | 描述                                                     |
| ----------------- | -------------------------------------- | ------ | -------- | ---------- | -------------------------------------------------------- |
| load_weight       | ../trained_model/model/model_final.pth | string | 否       | 是         | 训练起始模型，eval模式下则为测试模型，可以为obs路径      |
| total_epoch       | 1                                     | int    | 否       | 是         | 训练总轮数                                               |
| nr_images_epoch   | 40000                                  | int    | 否       | 是         | 每一轮训练用的图片数                                     |
| mini_batch_size   | 2                                      | int    | 否       | 是         | 每张卡的batch_size                                       |
| wamr_iter         | 1000                                   | int    | 否       | 是         | warmup循环数                                             |
| momentum          | 0.9                                    | float  | 否       | 是         | SGD优化参数                                              |
| base_lr           | 1.25e-3                                | float  | 否       | 是         | 具体learning rate根据实际GPU数计算                       |
| log_dump_interval | 1                                      | int    | 否       | 是         | log打印频率                                              |
| weight_decay      | 1e-4                                   | float  | 否       | 是         | SGD优化参数                                              |
| random_seed       | 7                                      | int    | 否       | 是         | 随机数种子                                               |
| eval              | false                                      | string    | 否       | 是         | 若设为1，则只从确定的模型pth在验证集上推理并计算评价指标 |

### 2.3. 训练输出文件

eval参数决定是否进行训练或跳过训练直接用现有模型在CrowdHuman验证集上推理评价。

- **eval = 0**

  1. 训练模型，打印日志

  2. 将模型储存在本地和train_url指定的路径（创建训练作业时指定的训练出入路径）

  3. 所有输出在工作目录如下所示

     ```
     src
     |-- trained_model/
     |     |-- model/
     |-- ...
     ```

  4. 所有输出在obs上的目录如下所示

     ```
     |-- train_url/
     |     |-- model/
     ```

- **eval = 1**

  1. 用指定的模型进行推理验证，若用户指定模型，必须保证load_weight是obs中模型.pth文件的绝对路径。

  2. 用户指定的data_url（创建训练作业时指定的训练输入路径）中可以只包含.jpg格式的图片，也可以包含annotation_val.odgt文件，若为后者，则输出的文件中包含eval_results.txt为业界评价标准，否则只输出pred_results.json和pred_results目录。支持用户自定义OBS上的数据集路径，若需要输出评价指标，则需要包含符合格式要求的annotation_val.odgt文件，若不需要输出评价指标，可以直接将data_url指向只包含图片的OBS文件夹。

  3. 所有输出在OBS的目录如下所示

     ```
     |-- train_url/ # 创建训练作业时指定的训练出入路径
     |     |-- eval_dump/
     |     |     |-- pred_results.json # 模型推理结果
     |     |     |-- eval_results.txt # 相应的评价指标结果
     |     |     |-- pred_results/ # 对每个图片的推理结果
     |     |     |     |-- 1066405,100a000985ef070.json
     |     |     |     |-- ...
     ```

## 3. GPU/CPU

本算法仅支持GPU运行。

## 4. 数据准备

从[CrowdHuman](http://www.crowdhuman.org/download.html)下载CrowdHuman_train01.zip, CrowdHuman_train02.zip CrowdHuman_train03.zip, CrowdHuman_val.zip, annotation_train.odgt, annotation_val.odgt文件，将所有图片解压到同一个文件夹，最终保证在data_url（创建训练作业时指定的训练输入路径）中的目录如下所示

```
|-- data_url/ # 创建训练作业时指定的训练出入路径
|     |-- images/ # 所有解压得到的图片
|     |     |-- 1066405,100a000985ef070.jpg
|     |     |-- ...
|     |-- annotation_train.odgt # 训练集标注文件
|     |-- annotation_val.odgt # 验证集标注文件
```

## 5. 案例指导

本算法的详细使用方法，请查看[ModelArts AI Gallery CrowdDet算法指导](https://marketplace.huaweicloud.com/markets/aihub/article/detail/?content_id=da91e43a-7660-4c92-8ca8-837cf00e3c66)。