{"id":15034439,"url":"https://github.com/wizyoung/yolov3_tensorflow","last_synced_at":"2025-04-08T09:06:55.292Z","repository":{"id":108074366,"uuid":"166516143","full_name":"wizyoung/YOLOv3_TensorFlow","owner":"wizyoung","description":"Complete YOLO v3 TensorFlow implementation. Support training on your own dataset.","archived":false,"fork":false,"pushed_at":"2022-09-16T16:58:43.000Z","size":3240,"stargazers_count":1554,"open_issues_count":118,"forks_count":576,"subscribers_count":59,"default_branch":"master","last_synced_at":"2025-04-08T09:06:51.395Z","etag":null,"topics":["object-detection","real-time","tensorflow","tensorflow-yolo","yolov3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wizyoung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-01-19T06:51:47.000Z","updated_at":"2025-03-28T17:13:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"33827718-0063-443c-8a7d-f5efc540a1b8","html_url":"https://github.com/wizyoung/YOLOv3_TensorFlow","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizyoung%2FYOLOv3_TensorFlow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizyoung%2FYOLOv3_TensorFlow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizyoung%2FYOLOv3_TensorFlow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizyoung%2FYOLOv3_TensorFlow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wizyoung","download_url":"https://codeload.github.com/wizyoung/YOLOv3_TensorFlow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809964,"owners_count":20999816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["object-detection","real-time","tensorflow","tensorflow-yolo","yolov3"],"created_at":"2024-09-24T20:25:02.588Z","updated_at":"2025-04-08T09:06:55.263Z","avatar_url":"https://github.com/wizyoung.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"#  YOLOv3_TensorFlow\n\n**NOTE:** This repo is no longer maintained (actually I dropped the support for a long time) as I have switched to PyTorch for one year. Life is short, I use PyTorch.\n\n\n--------\n\n### 1. Introduction\n\nThis 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:\n\n- Efficient tf.data pipeline\n- Weights converter (converting pretrained darknet weights on COCO dataset to TensorFlow checkpoint.)\n- Extremely fast GPU non maximum supression.\n- Full training and evaluation pipeline.\n- Kmeans algorithm to select prior anchor boxes.\n\n### 2. Requirements\n\nPython version: 2 or 3\n\nPackages:\n\n- tensorflow \u003e= 1.8.0 (theoretically any version that supports tf.data is ok)\n- opencv-python\n- tqdm\n\n### 3. Weights convertion\n\nThe 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:\n\n```shell\npython convert_weight.py\n```\n\nThen the converted TensorFlow checkpoint file will be saved to `./data/darknet_weights/` directory.\n\nYou 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.\n\n### 4. Running demos\n\nThere are some demo images and videos under the `./data/demo_data/`. You can run the demo by:\n\nSingle image test demo:\n\n```shell\npython test_single_image.py ./data/demo_data/messi.jpg\n```\n\nVideo test demo:\n\n```shell\npython video_test.py ./data/demo_data/video.mp4\n```\n\nSome results:\n\n![](https://github.com/wizyoung/YOLOv3_TensorFlow/blob/master/data/demo_data/results/dog.jpg?raw=true)\n\n![](https://github.com/wizyoung/YOLOv3_TensorFlow/blob/master/data/demo_data/results/messi.jpg?raw=true)\n\n![](https://github.com/wizyoung/YOLOv3_TensorFlow/blob/master/data/demo_data/results/kite.jpg?raw=true)\n\nCompare 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).\n\n(The kite detection result is under input image resolution 1344x896)\n\n### 5. Inference speed\n\nHow fast is the inference speed? With images scaled to 416*416:\n\n\n| Backbone              |   GPU    | Time(ms) |\n| :-------------------- | :------: | :------: |\n| Darknet-53 (paper)    | Titan X  |    29    |\n| Darknet-53 (my impl.) | Titan XP |   ~23    |\n\nwhy is it so fast? Check the ImageNet classification result comparision from the paper:\n\n![](https://github.com/wizyoung/YOLOv3_TensorFlow/blob/master/docs/backbone.png?raw=true)\n\n### 6. Model architecture\n\nFor 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!\n\n![](https://github.com/wizyoung/YOLOv3_TensorFlow/blob/master/docs/yolo_v3_architecture.png?raw=true)\n\n### 7. Training\n\n#### 7.1 Data preparation \n\n(1) annotation file\n\nGenerate `train.txt/val.txt/test.txt` files under `./data/my_data/` directory. One line for one image, in the format like `image_index image_absolute_path img_width img_height box_1 box_2 ... box_n`. Box_x format: `label_index x_min y_min x_max y_max`. (The origin of coordinates is at the left top corner, left top =\u003e (xmin, ymin), right bottom =\u003e (xmax, ymax).) `image_index` is the line index which starts from zero. `label_index` is in range [0, class_num - 1].\n\nFor example:\n\n```\n0 xxx/xxx/a.jpg 1920 1080 0 453 369 473 391 1 588 245 608 268\n1 xxx/xxx/b.jpg 1920 1080 1 466 403 485 422 2 793 300 809 320\n...\n```\n\nSince so many users report to use tools like LabelImg to generate xml format annotations, I add one demo script on VOC dataset to do the convertion. Check the `misc/parse_voc_xml.py` file for more details.\n\n(2)  class_names file:\n\nGenerate the `data.names` file under `./data/my_data/` directory. Each line represents a class name.\n\nFor example:\n\n```\nbird\nperson\nbike\n...\n```\n\nThe COCO dataset class names file is placed at `./data/coco.names`.\n\n(3) prior anchor file:\n\nUsing the kmeans algorithm to get the prior anchors:\n\n```\npython get_kmeans.py\n```\n\nThen you will get 9 anchors and the average IoU. Save the anchors to a txt file.\n\nThe COCO dataset anchors offered by YOLO's author is placed at `./data/yolo_anchors.txt`, you can use that one too.\n\nThe yolo anchors computed by the kmeans script is on the resized image scale.  The default resize method is the letterbox resize, i.e., keep the original aspect ratio in the resized image.\n\n#### 7.2 Training\n\nUsing `train.py`. The hyper-parameters and the corresponding annotations can be found in `args.py`:\n\n```shell\nCUDA_VISIBLE_DEVICES=GPU_ID python train.py\n```\n\nCheck the `args.py` for more details. You should set the parameters yourself in your own specific task.\n\n### 8. Evaluation\n\nUsing `eval.py` to evaluate the validation or test dataset. The parameters are as following:\n\n```shell\n$ python eval.py -h\nusage: eval.py [-h] [--eval_file EVAL_FILE] \n               [--restore_path RESTORE_PATH]\n               [--anchor_path ANCHOR_PATH] \n               [--class_name_path CLASS_NAME_PATH]\n               [--batch_size BATCH_SIZE]\n               [--img_size [IMG_SIZE [IMG_SIZE ...]]]\n               [--num_threads NUM_THREADS]\n               [--prefetech_buffer PREFETECH_BUFFER]\n               [--nms_threshold NMS_THRESHOLD]\n               [--score_threshold SCORE_THRESHOLD] \n               [--nms_topk NMS_TOPK]\n```\n\nCheck the `eval.py` for more details. You should set the parameters yourself. \n\nYou will get the loss, recall, precision, average precision and mAP metrics results.\n\nFor higher mAP, you should set score_threshold to a small number.\n\n### 9. Some tricks\n\nHere are some training tricks in my experiment:\n\n(1) Apply the two-stage training strategy or the one-stage training strategy:\n\nTwo-stage training:\n\nFirst 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.\n\nSecond 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.\n\nOne-stage training:\n\nJust restore the whole weight file except the last three convolution layers (Conv_6, Conv_14, Conv_22). In this condition, be careful about the possible nan loss value.\n\n(2) I've included many useful training strategies in `args.py`:\n\n- Cosine decay of lr (SGDR)\n- Multi-scale training\n- Label smoothing\n- Mix up data augmentation\n- Focal loss\n\nThese are all good strategies but it does **not** mean they will definitely improve the performance. You should choose the appropriate strategies for your own task.\n\nThis [paper](https://arxiv.org/abs/1902.04103) from gluon-cv has proved that data augmentation is critical to YOLO v3, which is completely in consistent with my own experiments. Some data augmentation strategies that seems reasonable may lead to poor performance. For example, after introducing random color jittering, the mAP on my own dataset drops heavily. Thus I hope  you pay extra attention to the data augmentation.\n\n(4) Loss nan? Setting a bigger warm_up_epoch number or smaller learning rate and try several more times. If you fine-tune the whole model, using adam may cause nan value sometimes. You can try choosing momentum optimizer.\n\n### 10. Fine-tune on VOC dataset\n\nI did a quick train on the VOC dataset. The params I used in my experiments are included under `misc/experiments_on_voc/` folder for your reference. The train dataset is the VOC 2007 + 2012 trainval set, and the test dataset is the VOC 2007 test set.\n\nFinally with the 416\\*416 input image, I got a 87.54% test mAP (not using the 07 metric). No hard-try fine-tuning. You should get the similar or better results.\n\nMy pretrained weights on VOC dataset can be downloaded [here](https://drive.google.com/drive/folders/1ICKcJPozQOVRQnE1_vMn90nr7dejg0yW?usp=sharing).\n\n### 11. TODO\n\n[ ] Multi-GPUs with sync batch norm. \n\n[ ] Maybe tf 2.0 ?\n\n-------\n\n### Credits:\n\nI referred to many fantastic repos during the implementation:\n\n[YunYang1994/tensorflow-yolov3](https://github.com/YunYang1994/tensorflow-yolov3)\n\n[qqwweee/keras-yolo3](https://github.com/qqwweee/keras-yolo3)\n\n[eriklindernoren/PyTorch-YOLOv3](https://github.com/eriklindernoren/PyTorch-YOLOv3)\n\n[pjreddie/darknet](https://github.com/pjreddie/darknet)\n\n[dmlc/gluon-cv](https://github.com/dmlc/gluon-cv/tree/master/scripts/detection/yolo)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwizyoung%2Fyolov3_tensorflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwizyoung%2Fyolov3_tensorflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwizyoung%2Fyolov3_tensorflow/lists"}