# YOLOv3_TensorFlow-master

**Repository Path**: abcc009/YOLOv3_TensorFlow-master

## Basic Information

- **Project Name**: YOLOv3_TensorFlow-master
- **Description**: 本文将介绍 YOLO3 的完整 TensorFlow 实现。可在自己的数据集上进行完整的训练和验证操作
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2019-01-30
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#  YOLOv3_TensorFlow

### 1. Introduction

This is my implementation of [YOLOv3](https://pjreddie.com/media/files/papers/YOLOv3.pdf) in pure TensorFlow. It contains the full pipeline of training and evaluation on your own dataset. The key features of this repo are:
 **本文将介绍 YOLO3 的完整 TensorFlow 实现。可在自己的数据集上进行完整的训练和验证操作，pipeline 完整。其特点包括：** 

- Efficient tf.data pipeline
- Weights converter (converting pretrained darknet weights on COCO dataset to TensorFlow checkpoint.)
- Extremely fast GPU non maximum supression.
- Full training pipeline.
- Kmeans algorithm to select prior anchor boxes.
- [ ] Multi-GPU training with sync batch norm. (on working)
高效的 tf.data 管道
权重转换
GPU 提速，无限制
完整的训练管道
使用 kMeans 算法来选择 anchor boxes
多 GPU 同步训练


### 2. Requirements

- tensorflow >= 1.8.0 (lower versions may work too)
- opencv-python
  tensorflow >= 1.8.0（不排除低版本也能工作）
  opencv-python




### 3. Weights convertion


预训练的 darknet 权重文件可从下方链接下载：


The pretrained darknet weights file can be downloaded [here](https://pjreddie.com/media/files/yolov3.weights). Place this weights file under directory `./data/darknet_weights/` and then run:

```shell
python convert_weight.py
```
把下载好后的文件放在 ./data/darknet_weights/ 目录下，运行下面的命令：
Then the converted TensorFlow checkpoint file will be saved to `./data/darknet_weights/` directory.

You can also download the converted TensorFlow checkpoint file by me via [[Google Drive link](https://drive.google.com/drive/folders/1mXbNgNxyXPi7JNsnBaxEv1-nWr7SVoQt?usp=sharing)] or [[Github Release](https://github.com/wizyoung/YOLOv3_TensorFlow/releases/)]and then place it to the same directory.
然后，转换后的 TensorFlow checkpoint 文件将被保存在 ./data/darknet_weights/ 目录下。

### 4. Running demos

There are some demo images and videos under the `./data/demo_data/`. You can run the demo by:

Single image test demo:
单个图像测试 demo：
在 ./data/demo_data/ 目录里有一些图像和视频的 demos 可以运行。




```shell
python test_single_image.py ./data/demo_data/messi.jpg
```

Video test demo:

```shell
python video_test.py ./data/demo_data/video.mp4
```

Some results:

![](https://images.gitee.com/uploads/images/2019/0130/112923_d217c7b0_1265313.jpeg)

![](https://images.gitee.com/uploads/images/2019/0130/112923_c1217e30_1265313.jpeg)

![](https://images.gitee.com/uploads/images/2019/0130/112923_c5f01c7f_1265313.jpeg)

Compare the kite detection results with TensorFlow's offical API result [here](https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/img/kites_detections_output.jpg).

(The kite detection result is under input image resolution 1344x896)

### 5. Inference speed

How fast is the inference speed? With images scaled to 416*416:

图片尺寸为 416x416，论文实现与我的模型运行速度比较如下：


| Backbone              |   GPU    | Time(ms) |
| :-------------------- | :------: | :------: |
| Darknet-53 (paper)    | Titan X  |    29    |
| Darknet-53 (my impl.) | Titan XP |   ~23    |

why is it so fast? Check the ImageNet classification result comparision from the paper:
图片尺寸为 416x416，论文实现与我的模型运行速度比较如下：
![](https://images.gitee.com/uploads/images/2019/0130/112923_c442bc57_1265313.png)

### 6. Model architecture

为了更好地理解模型体系结构，可以参考下图：
For better understanding of the model architecture, you can refer to the following picture. With great thanks to [Levio](https://blog.csdn.net/leviopku/article/details/82660381) for your excellent work!

![](https://images.gitee.com/uploads/images/2019/0130/112923_2e037318_1265313.png)

### 7. Training

#### 7.1 Data preparation 
首先是数据准备，分为三步。

(1) annotation file

Generate `train.txt/val.txt/test.txt` files under `./data/my_data/` directory. One line for one image, in the format like `image_absolute_path box_1 box_2 ... box_n`. Box_format: `label_index x_min y_min x_max y_max`.(The origin of coordinates is at the left top corner.)
在 ./data/my_data/ 目录下生成 train.txt/val.txt/test.txt 文件。txt 文件中一行表示一张图片，形式为：图片绝对路径 + box_1 + box_2 + ... + box_n。Box 的形式为：label_index + x_min + y_min + x_max + y_max，原始坐标为图片左上角。

For example:

```
xxx/xxx/1.jpg 0 453 369 473 391 1 588 245 608 268
xxx/xxx/2.jpg 1 466 403 485 422 2 793 300 809 320
...
```
注意：每个 txt 文件最后一行为空白行。
**NOTE**: **You should leave a blank line at the end of each txt file.**

(2)  class_names file:

Generate the `data.names` file under `./data/my_data/` directory. Each line represents a class name.

For example:在 ./data/my_data/ 目录下生成 data.names 文件，每一行代表一个类别名称。例如：

```
bird
person
bike
...
```

The COCO dataset class names file is placed at `./data/coco.names`.

(3) prior anchor file:

Using the kmeans algorithm to get the prior anchors:
使用 kMeans 算法来选择 anchor boxes：
```
python get_kmeans.py
```
然后，你将得到 9 个 anchors 和评价 IOU，把 anchors 保存在 txt 文件中。


准备完数据之后就可以开始训练了。


使用 train.py 文件，函数参数如下：

Then you will get 9 anchors and the average IOU. Save the anchors to a txt file.

The COCO dataset anchors offered by YOLO v3 author is placed at `./data/yolo_anchors.txt`, you can use that one too.

**NOTE: The yolo anchors should be scaled to the rescaled new image size. Suppose your image size is [W, H], and the image will be rescale to 416*416 as input, for each generated anchor [anchor_w, anchor_h], you should apply the transformation anchor_w = anchor_w / W * 416, anchor_h = anchor_g / H * 416.**

#### 7.2 Training

Using `train.py`. The parameters are as following:

```shell
$ python train.py -h
usage: train.py [-h] [--train_file TRAIN_FILE] [--val_file VAL_FILE]
                [--restore_path RESTORE_PATH] 
                [--save_dir SAVE_DIR]
                [--log_dir LOG_DIR] 
                [--progress_log_path PROGRESS_LOG_PATH]
                [--anchor_path ANCHOR_PATH]
                [--class_name_path CLASS_NAME_PATH] [--batch_size BATCH_SIZE]
                [--img_size [IMG_SIZE [IMG_SIZE ...]]]
                [--total_epoches TOTAL_EPOCHES]
                [--train_evaluation_freq TRAIN_EVALUATION_FREQ]
                [--val_evaluation_freq VAL_EVALUATION_FREQ]
                [--save_freq SAVE_FREQ] [--num_threads NUM_THREADS]
                [--prefetech_buffer PREFETECH_BUFFER]
                [--optimizer_name OPTIMIZER_NAME]
                [--save_optimizer SAVE_OPTIMIZER]
                [--learning_rate_init LEARNING_RATE_INIT] [--lr_type LR_TYPE]
                [--lr_decay_freq LR_DECAY_FREQ]
                [--lr_decay_factor LR_DECAY_FACTOR]
                [--lr_lower_bound LR_LOWER_BOUND]
                [--restore_part [RESTORE_PART [RESTORE_PART ...]]]
                [--update_part [UPDATE_PART [UPDATE_PART ...]]]
                [--update_part [UPDATE_PART [UPDATE_PART ...]]]
                [--use_warm_up USE_WARM_UP] [--warm_up_lr WARM_UP_LR]
                [--warm_up_epoch WARM_UP_EPOCH]
```

Check the `train.py` for more details. You should set the parameters yourself. 

Some training tricks in my experiment:

(1) Apply the two-stage training strategy:

First stage: Restore `darknet53_body` part weights from COCO checkpoints, train the `yolov3_head` with big learning rate like 1e-3 until the loss reaches to a low level, like less than 1.

Second stage: Restore the weights from the first stage, then train the whole model with small learning rate like 1e-4 or smaller. At this stage remember to restore the optimizer parameters if you use optimizers like adam.

(2) Quick train:

If you want to obtain good results in a short time like in 10 minutes. You can use the coco names but substitute several with real class names in your dataset. In this way you restore the whole pretrained COCO model and get a 80 class classification model, but you only care the class names from your dataset.

### 8. Evaluation

Using `eval.py` to evaluate the validation or test dataset. The parameters are as following:


使用 eval.py 来评估验证集和测试集，函数参数如下：

```shell
$ python eval.py -h
usage: eval.py [-h] [--eval_file EVAL_FILE] [--restore_path RESTORE_PATH]
               [--anchor_path ANCHOR_PATH] 
               [--class_name_path CLASS_NAME_PATH]
               [--batch_size BATCH_SIZE]
               [--img_size [IMG_SIZE [IMG_SIZE ...]]]
               [--num_threads NUM_THREADS]
               [--prefetech_buffer PREFETECH_BUFFER]
```

Check the `eval.py` for more details. You should set the parameters yourself. 
函数返回 loss、召回率 recall、精准率 precision，如下所示：
You will get the loss, recall and precision metrics results, like:

```shell
recall: 0.927, precision: 0.945
total_loss: 0.210, loss_xy: 0.010, loss_wh: 0.025, loss_conf: 0.125, loss_class: 0.050
```

### 9. Other tricks

There are many skills you can try during training:

(1) Data augmentation: You can implement your data augmentation like color jittering under `data_augmentation` method in `./utils/data_utils.py`.

(2) Mixed up and label smoothing like what [Gluon-CV](https://github.com/dmlc/gluon-cv/tree/master/scripts/detection/yolo) does.

(3) Normalizations like L2 norm.

(4) Mutil-scale training: You can change the input image scales (i.e. different input resolutions) periodically like the author does in the original paper.
训练的时候可以尝试使用下面这些技巧：


Data augmentation：使用 ./utils/data_utils.py 中的 data_augmentation 方法来增加数据。
像 Gluon CV 一样混合和 label 平滑。
正则化技巧，例如 L2 正则化。
多尺度训练：你可以像原稿中的作者那样定期改变输入图像的尺度（即不同的输入分辨率）。


-------

### Credits:

I refer to many fantastic repos during the implementation:

https://github.com/YunYang1994/tensorflow-yolov3

https://github.com/qqwweee/keras-yolo3

https://github.com/eriklindernoren/PyTorch-YOLOv3

https://github.com/pjreddie/darknet