# Object_Detection_Cloud

**Repository Path**: study-cooperation/Object_Detection_Cloud

## Basic Information

- **Project Name**: Object_Detection_Cloud
- **Description**: 工具及平台
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2019-02-25
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据预处理

**`data_preprocessor.py`**提供以下接口：

* `cleaning_dataset(dataset_dir, label_filtering_rule)`，清洗数据集，返回所有符合规则的label的list，参数解释如下：

  * `dataset_dir`：数据集路径；

  * `label_filtering_rule`：label的过滤规则;

  * 返回值：所有符合规则的label的list，标注数以及图片总数：

    ```
    {
        "label_list": [ncco1, nccr2, ... ],  # 符合规则的label的list
        "annotation_nums": 4234, # 数据集已标注数量
        "image_nums": 4334,  # 数据集中图片总数
        "dataset_items": [{"image": path_to_image/image_1.jpg, "xml": path_to_xml/image_1.xml}, ... ]  # 数据集中所有已标注和未标注的路径
    }
    ```
* `cleaning_xml(xml_path, label_filtering_rule, old_label_list)`，对一个图片的标注项进行清洗，参数解释如下：

  * `xml_path`：新增的标注数据的路径
  * `label_filtering_rule`：label的过滤规则;
  * `old_label_list`：现有的label_list
  * 返回值，返回一个布尔值和一个新的`label_list`的元组，布尔值指示此次标注是否有效。如果xml中有符合`label_filtering_rule`的但是没在`old_label_list`中出现过的类别，则将其添加到`old_label_list`中生成一个新的`label_list`，否则返回`old_label_list`。形如：`(true, [ncco1, nccr2, ... ])`。

- `create_label_map(label_list, output_file_path)`，从给定的`label_list`生成label_map，参数解释如下：
  - `label_list`：要生成label_map的所有类别；
  - `output_file_path`：label_map文件保存路径。
- `create_tfrecords(dataset_dir, label_map_path, output_file_path)`：从训练数据生成tfrecords便于接下来的训练，参数解释如下：
  - `dataset_dir`：数据集所在目录；
  - `label_map_path`：由`create_label_map()`所产生的label_map文件的路径。

# 数据拆分

**`data_preprocessor.py`**：

- `data_split(dataset_dir, class_list, split_ratio_dict， random_str)`，按照一定比例拆分数据集

  - `dataset_dir`:需拆分数据集路径

  - `class_list`:需要拆分的类别列表

  - `split_ratio_dict`:拆分比例（dict）

    ```
    {
        'train':num,
        'evaluate':num,
        'test':num
     }
    ```

  - `random_str`:生成随机种子（配合split_ratio_dict来生成）

  - 返回值：

    ```
    {
        'train':[{'image':img_path, 'xml':xml_path},...],
        'evaluate':[{'image':img_path, 'xml':xml_path},...], 
        'test':[{'image':img_path, 'xml':xml_path},...]
    }
    ```

- `save(save_path_dict, data_split_dict)`保存拆分好的数据集

  - `save_path_dict`：拆分数据集保存路径
  - `data_split_dict`:从data_split中获得的返回结果

# 数据分析

**`data_preprocessor.py`**：

- `analyze_sample_distribution(dataset_dir, class_list)`,数据分析获得样本分布情况

  - `dataset_dir`:需分析样本分布情况数据集所在路径

  - `class_list`:类别列表

  - 返回值：形如

    ```
    {
        'class_1':{
            'num':int,
            'ratio':float
        },
        ...
    }
    ```

- `analyze_data(dataset_dict, class_list)`分析三个数据集（train, val, test）的样本分布，以及

  train和val，以及train和test的样本一致性分析

  - `dataset_dict`：包含三个数据集的路径的字典:

    ```
    {
        'train':train_path,
        'evaluate':evaluate_path,
        'test':test_path
    }
    ```

  - `class_list`:类别列表

  - 返回值：形如

    ```
    {
        'distribution':{
            'train':{
                'class_1':{
                    'num':int,
            		'ratio':float
                }
                ...
            },
            'evaluate':{
                'class_1':{
                    'num':int,
            		'ratio':float
                }
                ...
            },
            'test':{
                'class_1':{
                    'num':int,
            		'ratio':float
                }
                ...
            }
        },
        'consistency':{
            'train-evaluate':float,
            'train-test':float
        }
    }
    ```

# 训练

* **启动训练无需提供接口函数，提供可执行脚本（python脚本）即可**：

  `python train.py --train_dir=path/to/trian_dir \ `

  `                               --pipeline_config_path=pipeline_config.config`

**`train_and_eval_utils.py`**另还提供一个工具函数获取训练过程中的信息：

- `get_train_info(train_log)`，负责获取从指定次数起的所有训练过程中的信息，包含TrainSteps和Loss，参数解释如下：

  - `train_log`：训练过程中的日志信息（可通过docker获得）；

  - 返回值：从训练开始时到目前为止的所有Loss，如下形式字典数据：

    ```
    {
        1: 1.2342,  # train_step: loss
        2: 1.3322,
        ...
    }
    ```

# 评估

**`train_and_eval_utils.py`**提供以下接口：

* `eval_from_checkpoint(model_dir, config_path, label_map_path, score_threshold)`，此函数主要负责训练过程中模型的评估，参数详细解释如下：

  * `model_dir`：训练过程中模型的保存目录；

  * `config_path`：训练配置文件所在路径；

  * `label_map_path`：由`create_label_map()`所产生的label_map文件的路径；

  * `score_threshold`：评估时的boundingbox置信度阈值；

  * 返回如下形式的评估结果：

    ```
    {
    	"step": 10000,  # 训练步数
        "precison": 0.5，# 准确率
        "recall": 0.6,  # 召回率
        "mAP": 0.60    # mAP
    }
    ```
* `eval_from_pb(pb_file_path, test_images_dir, label_map_path, score_threshold)`，参数主要负责训练结束后导出模型的评估，参数详细解释如下：

  * `pb_file_path`：由ckpt导出的pb模型的路径；
  * `test_images_dir`：测试数据集目录；
  * 其余所有参数与返回值同上面的`eval`。

# 其它工具

**`train_and_eval_utils.py`**：

* `export_pb_file(checkpoint_prefix, config_path, output_dir)`：负责结束训练后从最后的ckpt导出pb模型，参数解释如下：
  * `checkpoint_prefix`：要导出的`ckpt`模型的路径；
  * `config_path`：配置文件路径；
  * `output_dir`：导出结果保存路径。

# Requirements

建议先安装`Anaconda`，然后再按顺序安装以下 *package*（ *TensorFlow* CPU 版本和 GPU 版本二选一）：

- *tensorflow==1.8.0*（CPU版本）：`pip install tensorflow==1.8.0`

- *tensorflow-gpu==1.8.0*（GPU版本）：`pip install tensorflow-gpu==1.8.0`

  GPU 版的 *TensorFlow* 需要额外安装 *CUDA* 和 *CUDNN*，*CUDA* 和 *CUDNN* 的版本选择和 GPU 型号、*TensorFlow* 版本都有关系，需要特别注意。在我们的测试机器上使用的是 *GTX 1050 TI，CUDA 9.0，CUDNN 9.0*，仅供参考。

- *seaborn==0.9.0*

- *opencv-python==3.4.2.16*：`pip install opencv-python==3.4.2.16`

- *opencv-contrib-python==3.4.2.16*：`pip install opencv-contrib-python==3.4.2.16`

- 安装 *Google Object Detection API*，具体安装过程见[此处](https://gitee.com/study-cooperation/models/tree/hnu%2Fmaster/)的安装教程。