From 97165e3ebd2d50f09da970375b5992be13d94d0d Mon Sep 17 00:00:00 2001 From: Emanuele Plebani Date: Sat, 26 Nov 2016 09:55:06 +0100 Subject: [PATCH] update README and move it to RST format, add LICENSE file --- LICENSE | 12 ++++++ README.md | 72 ------------------------------- README.rst | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+), 72 deletions(-) create mode 100644 LICENSE delete mode 100644 README.md create mode 100644 README.rst diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a50f7d7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,12 @@ + YOLO LICENSE + Version 2, July 29 2016 + +THIS SOFTWARE LICENSE IS PROVIDED "ALL CAPS" SO THAT YOU KNOW IT IS SUPER +SERIOUS AND YOU DON'T MESS AROUND WITH COPYRIGHT LAW BECAUSE YOU WILL GET IN +TROUBLE HERE ARE SOME OTHER BUZZWORDS COMMONLY IN THESE THINGS WARRANTIES +LIABILITY CONTRACT TORT LIABLE CLAIMS RESTRICTION MERCHANTABILITY. NOW HERE'S +THE REAL LICENSE: + +0. Darknet is public domain. +1. Do whatever you want with it. +2. Stop emailing me about it! diff --git a/README.md b/README.md deleted file mode 100644 index 11453db..0000000 --- a/README.md +++ /dev/null @@ -1,72 +0,0 @@ -# YOLO in caffe - -## Introduction - -This is a caffe implementation of the paper _YOLO: Real-Time Object Detection_. - -Note, the caffe models are not trained in caffe, but converted from darknet's (`.weight`) files (http://pjreddie.com/darknet/yolo/). - -The converter is consisted of three steps: - -* initialize the caffe network and weights from `.prototxt` file, which is generated from darknet's (`.cfg`) file -* read the weights from pre-trained darknet's (`.weight`) file -* replace the initialized weights with the weights in pre-trained darkenet's (`.weight`) file - -## Model files - -These caffemodel files have been converted for you. - -* YOLO: https://drive.google.com/file/d/0Bzy9LxvTYIgKMXdqS29HWGNLdGM/view?usp=sharing - -* YOLO_small: https://drive.google.com/file/d/0Bzy9LxvTYIgKa3ZHbnZPLUo0eWs/view?usp=sharing - -* YOLO_tiny: https://drive.google.com/file/d/0Bzy9LxvTYIgKNFEzOEdaZ3U0Nms/view?usp=sharing - - - -## Convert yolo's (.weight) files to caffemodel - -If you want to create the caffemodel files from yolo's (`.weights`) files on your own, - -* first, you need to download the pretrained yolo weight files in the darknet official website (http://pjreddie.com/darknet/yolo/) - -* after that, run `create_yolo_caffemodel.py` to create the caffemodel from yolo's (`.weight`) files: - - ``` - python create_yolo_caffemodel.py -m train_val_prototxt.filename -w yoloweights_filename -o caffemodel_filename - ``` - - replace *train_val_prototxt.filename* with `/your/path/to/yolo_train_val.prototxt` (*yolo_small*, *yolo_tiny*), - *yoloweights_filename* with `/your/path/to/yolo.weights` (*yolo-small*, *yolo-tiny*), and *caffemodel_filename* with your output caffemodel name, e.g. - - ``` - python create_yolo_caffemodel.py -m yolo_train_val.prototxt -w yolo.weights -o yolo.caffemodel - ``` - - -## Main file usage - -Run `yolo_detect.py` to perform YOLO object detection on an input image: - - python yolo_main.py -m model_filename -w weight_filename -i image_filename - -replace *model_filename* with `/your/path/to/yolo_small_deploy.prototxt` or `yolo_tiny_deploy.prototxt`, -*weight_filename* with `/your/path/to/yolo_tiny.caffemodel` or `yolo_small.caffemodel` and *image_filename* with the target image file. - -## Requirements - - * Caffe, pycaffe - - * OpenCV 2 - -## Copyrights - -According to the LICENSE file of the original code, - - * Me and original author hold no liability for any damages - - * Do not use this on commercial! - -## ToDoList - -Generate caffe prototxt files from darknet cfg files diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..2618baa --- /dev/null +++ b/README.rst @@ -0,0 +1,121 @@ +|Python27| + +.. |Python27| image:: https://img.shields.io/badge/python-2.7-blue.svg + :target: https://www.python.org/ + +========== +Caffe-YOLO +========== + +Introduction +============ + +This is a set of tools to convert models from +`Darknet `_ to +`Caffe `_, and in +particular to convert the YOLO networks for object detection. For more details, +see the paper: + + *"You Only Look Once: Unified, Real-Time Object Detection"* + [`Redmon2015 `_] + + +Usage +===== + +The repository includes a tool to convert the Darknet configuration file ``.cfg`` +to the ``.prototxt`` definition in Caffe, a tool to convert the weight +file ``.weights`` to ``.caffemodel`` in Caffe and a detection demo to test the +converted networks. + +Convert the configuration file with: + +.. code:: bash + + python create_yolo_prototxt.py tiny-yolo.cfg yolo_tiny + +By default, only the *deploy* prototxt is generate. If the ``--train`` option is +passed, the *train_val* version of the prototxt file is generated; however, the +file lacks the information about input annotations, training loss and it's meant +as a form of partial automation of a manually defined training. + +The YOLO weights are available on the `Darknet v1 `_ +website. See the instructions there on how to download them. To convert the +weights to Caffe, use: + +.. code:: bash + + python create_yolo_caffemodel.py yolo_tiny_deploy.prototxt tiny-yolo.weights \ + yolo_tiny.caffemodel + +If the number of weights is not compatible with the given prototxt, an error is +returned. + +Test the results on one of the images in the repository with: + +.. code:: bash + + python yolo_detect.py yolo_tiny_deploy.prototxt yolo_tiny.caffemodel images/dog.jpg + +To test the *CoCo* networks pass the ``--coco`` option in order to use the correct +set of class labels. + + +Limitations +^^^^^^^^^^^ + +The process only supports a limited number of layers and options. The *detection* +layer in YOLO is not implemented and parsing of the network output is left to +the caller application. + +The most recent ``yolo`` and ``yolo-coco`` models in Darknet v1 use the *Local +Convolution* layer (convolutions without weight sharing) which is not supported +by the official Caffe repository. There is partial support to the version in +`caffe-mt `_ by passing ``--loclayer`` to +``create_yolo_prototxt.py`` but the implementation is still buggy. + +The *softmax* layer (for ``Darknet`` v2) and shortcut connections introduced in +the Darknet v2 YOLO models are also not supported. + + +Model files +=========== + +Three converted models are available in the `prototxt` directory: + +* **YOLO tiny**: converted from `tiny-yolo.cfg`, + `caffemodel `__. + +* **YOLO small**: converted from `yolo-small.cfg`, + `caffemodel `__. + +* **YOLO CoCo tiny**: converted from `tiny-coco.cfg`, + `caffemodel `__. + + +Legacy models +^^^^^^^^^^^^^ + +The models originally converted by *xingwangsfu* (https://github.com/xingwangsfu/caffe-yolo) +are available in the directory ``prototxt/legacy``. The converted weights can +be downloaded here: + +* **YOLO**: https://drive.google.com/file/d/0Bzy9LxvTYIgKMXdqS29HWGNLdGM/view?usp=sharing + +* **YOLO small**: https://drive.google.com/file/d/0Bzy9LxvTYIgKa3ZHbnZPLUo0eWs/view?usp=sharing + +* **YOLO tiny**: https://drive.google.com/file/d/0Bzy9LxvTYIgKNFEzOEdaZ3U0Nms/view?usp=sharing + + +Requirements +============ + + * `Caffe `_ with ``pycaffe`` support + + * OpenCV 2 with python interfaces (``python-opencv`` in Ubuntu) + + +License +======= + +The code is released under the YOLO license.