Darknet Object Detection Framework and YOLO
Darknet is an open-source neural network framework written in C, C++, and CUDA.
YOLO (You Only Look Once) is a state-of-the-art, real-time, object detection system, which runs in the Darknet framework.
Read how Hank.ai is helping the Darknet/YOLO community
Announcing Darknet V3 "Jazz"
See the Darknet/YOLO web site
Please read through the Darknet/YOLO FAQ
Join the Darknet/YOLO discord server
Papers
1. Paper YOLOv7
2. Paper Scaled-YOLOv4
3. Paper YOLOv4
4. Paper YOLOv3
General Information
The Darknet/YOLO framework continues to be both faster and more accurate than other frameworks and versions of YOLO.
This framework is both completely free and open source. You can incorporate Darknet/YOLO into existing projects and products - including commercial ones - without a license or paying a fee.
Darknet V3 ("Jazz") released in October 2024 can accurately run the LEGO dataset videos at up to 1000 FPS when using a NVIDIA RTX 3090 GPU, meaning each video frame is read, resized, and processed by Darknet/YOLO in 1 millisecond or less.
Please join the Darknet/YOLO Discord server if you need help or you want to discuss Darknet/YOLO: https://discord.gg/zSq8rtW
The CPU version of Darknet/YOLO can run on simple devices such as Raspberry Pi, cloud & colab servers, desktops, laptops, and high-end training rigs. The GPU version of Darknet/YOLO requires a CUDA-capable GPU from NVIDIA.
Darknet/YOLO is known to work on Linux, Windows, and Mac. See the building instructions below.
Darknet Version
The original Darknet tool written by Joseph Redmon in 2013-2017 did not have a version number. We consider this version 0.x.
The next popular Darknet repo maintained by Alexey Bochkovskiy between 2017-2021 also did not have a version number. We consider this version 1.x.
The Darknet repo sponsored by Hank.ai and maintained by Stéphane Charette starting in 2023 was the first one with a version command. From 2023 until late 2024, it returned version 2.x "OAK".
The goal was to try and break as little of the existing functionality while getting familiar with the codebase.
Key changes in this version include:
1. Re-wrote the build steps to have 1 unified way to build using CMake on both Windows and Linux.
2. Converted the codebase to use the C++ compiler.
3. Enhanced chart.png while training.
4. Bug fixes and performance-related optimizations, mostly related to cutting down the time it takes to train a network.
The last branch of this codebase is version 2.1 in the v2 branch.
The next phase of development started in mid-2024 and was released in October 2024. The version command now returns 3.x "JAZZ".
You can always do a checkout of the previous v2 branch if you need to run one of these commands. Let us know so we can investigate adding back any missing commands.
Key changes in this version include:
1. Removed many old and unmaintained commands.
2. Many performance optimizations, both when training and during inference.
3. Legacy C API was modified; applications that use the original Darknet API will need minor modifications: https://darknetcv.ai/api/api.html
4. New Darknet V3 C and C++ API: https://darknetcv.ai/api/api.html
5. New apps and sample code in src-examples: https://darknetcv.ai/api/files.html
MSCOCO Pre-trained Weights
Several popular versions of YOLO were pre-trained for convenience on the MSCOCO dataset. This dataset has 80 classes, which can be seen in the text file cfg/coco.names.
There are several other simpler datasets and pre-trained weights available for testing Darknet/YOLO, such as LEGO Gears and Rolodex. See the Darknet/YOLO FAQ for details.
The MSCOCO pre-trained weights can be downloaded from several different locations, and are also available for download from this repo:
1. YOLOv2, November 2016
- YOLOv2-tiny
- YOLOv2-full
2. YOLOv3, May 2018
- YOLOv3-tiny
- YOLOv3-full
3. YOLOv4, May 2020
- YOLOv4-tiny
- YOLOv4-full
4. YOLOv7, August 2022
- YOLOv7-tiny
- YOLOv7-full
The MSCOCO pre-trained weights are provided for demo-purpose only. The corresponding .cfg and .names files for MSCOCO are in the cfg directory. Example commands:
`bash
wget --no-clobber https://github.com/hank-ai/darknet/releases/download/v2.0/yolov4-tiny.weights
darknet02displayannotatedimages coco.names yolov4-tiny.cfg yolov4-tiny.weights image1.jpg
darknet03display_videos coco.names yolov4-tiny.cfg yolov4-tiny.weights video1.avi
DarkHelp coco.names yolov4-tiny.cfg yolov4-tiny.weights image1.jpg
DarkHelp coco.names yolov4-tiny.cfg yolov4-tiny.weights video1.avi
`
Note that people are expected to train their own networks. MSCOCO is normally used to confirm that everything is working correctly.
Building
The various build methods available in the past (pre-2023) have been merged together into a single unified solution. Darknet requires C++17 or newer, OpenCV, and uses CMake to generate the necessary project files.
You do not need to know C++ to build, install, nor run Darknet/YOLO, the same way you don't need to be a mechanic to drive a car.
Beware if you are following old tutorials with more complicated build steps, or build steps that don't match what is in this readme. The new build steps as described below started in August 2023.
Software developers are encouraged to visit https://darknetcv.ai/ to get information on the internals of the Darknet/YOLO object detection framework.
Google Colab
The Google Colab instructions are the same as the Linux instructions. Several Jupyter notebooks are available showing how to do certain tasks, such as training a new network.
See the notebooks in the colab subdirectory, and/or follow the Linux instructions below.
Linux CMake Method
1. Install necessary packages:
`bash
sudo apt-get install build-essential git libopencv-dev cmake
`
2. Clone the Darknet repository:
`bash
mkdir ~/srccd ~/src
git clone https://github.com/hank-ai/darknetcd darknet
`
3. Create a build directory and run CMake:
`bash
mkdir buildcd build
cmake -DCMAKEBUILDTYPE=Release ..
`
4. Build Darknet:
`bash
make -j4
`
5. Package and install Darknet:
`bash
package
sudo dpkg -i darknet-VERSION.deb
`
6. Verify installation:
`bash
darknet version
`
Windows CMake Method
1. Install necessary packages:
`bash
winget install Git.Git winget install Kitware.CMake winget install nsis.nsis winget install Microsoft.VisualStudio.2022.Community
`
2. Modify Visual Studio installation:
- Click on the "Windows Start" menu and run "Visual Studio Installer".
- Click on Modify.
- Select Desktop Development With C++.
- Click on Modify in the bottom-right corner, and then click on Yes.
3. Open Developer Command Prompt for VS 2022:
- Click on the "Windows Start" menu and select Developer Command Prompt for VS 2022. Do not use PowerShell for these steps.
4. Install Microsoft VCPKG:
`bash
cd c:mkdir c:srccd c:src git clone https://github.com/microsoft/vcpkgcd vcpkg
bootstrap-vcpkg.bat
.vcpkg.exe integrate
install .vcpkg.exe integrate powershell.vcpkg.exe install opencv[contrib,dnn,freetype,jpeg,openmp,png,webp,world]:x64-windows
`
5. Clone Darknet repository:
`bash
cd c:src
git clone https://github.com/hank-ai/darknet.gitcd darknet
`
6. Create a build directory and run CMake:
`bash
mkdir buildcd build
cmake -DCMAKEBUILDTYPE=Release -DCMAKETOOLCHAINFILE=C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake ..
`
7. Build Darknet:
`bash
msbuild.exe /property:Platform=x64;Configuration=Release /target:Build -maxCpuCount -verbosity:normal -detailedSummary darknet.sln
`
8. Generate the NSIS installation package:
`bash
msbuild.exe /property:Platform=x64;Configuration=Release PACKAGE.vcxproj
`
9. Run the NSIS installation wizard:
- Open the file darknet-VERSION.exe in the build directory. For example: darknet-2.0.31-win64.exe.
10. Verify installation:
`bash
C:Program FilesDarknetbindarknet.exe version
`
Using Darknet
CLI
The following is not the full list of all commands supported by Darknet.
In addition to the Darknet CLI, also note the DarkHelp project CLI which provides an alternative CLI to Darknet/YOLO. The DarkHelp CLI also has several advanced features that are not available directly in Darknet. You can use both the Darknet CLI and the DarkHelp CLI together, they are not mutually exclusive.
For most of the commands shown below, you'll need the .weights file with the corresponding .names and .cfg files. You can either train your own network (highly recommended!) or download a neural network that someone has already trained and made available for free on the internet. Examples of pre-trained datasets include:
1. LEGO Gears (finding objects in an image)
2. Rolodex (finding text in an image)
3. MSCOCO (standard 80-class object detection)
Commands to run include:
1. List some possible commands and options to run:
`bash
darknet help
`
2. Check the version:
`bash
darknet version
`
3. Predict using an image:
- V2:
`bash
darknet detector test cars.data cars.cfg cars_best.weights image1.jpg
`
- V3:
`bash
darknet02displayannotatedimages cars.cfg image1.jpg
`
- DarkHelp:
`bash
DarkHelp cars.cfg cars.cfg cars_best.weights image1.jpg
`
4. Output coordinates:
- V2:
`bash
darknet detector test animals.data animals.cfg animalsbest.weights -extoutput dog.jpg
`
- V3:
`bash
darknet01inference_images animals dog.jpg
`
- DarkHelp:
`bash
DarkHelp --json animals.cfg animals.names animals_best.weights dog.jpg
`
5. Working with videos:
- V2:
`bash
darknet detector demo animals.data animals.cfg animalsbest.weights -extoutput test.mp4
`
- V3:
`bash
darknet03display_videos animals.cfg test.mp4
`
- DarkHelp:
`bash
DarkHelp animals.cfg animals.names animals_best.weights test.mp4
`
6. Reading from a webcam:
- V2:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -c 0
`
- V3:
`bash
darknet08display_webcam animals
`
7. Save results to a video:
- V2:
`bash
darknet detector demo animals.data animals.cfg animalsbest.weights test.mp4 -outfilename res.avi
`
- V3:
`bash
darknet05processvideosmultithreaded animals.cfg animals.names animals_best.weights test.mp4
`
- DarkHelp:
`bash
DarkHelp animals.cfg animals.names animals_best.weights test.mp4
`
8. JSON:
- V2:
`bash
darknet detector demo animals.data animals.cfg animalsbest.weights test50.mp4 -jsonport 8070 -mjpegport 8090 -extoutput
`
- V3:
`bash
darknet06imagestojson animals image1.jpg
`
- DarkHelp:
`bash
DarkHelp --json animals.names animals.cfg animals_best.weights image1.jpg
`
9. Running on a specific GPU:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -i 1 test.mp4
`
10. To check the accuracy of the neural network:
`bash
darknet detector map driving.data driving.cfg driving_best.weights ...
`
Output:
`
Id Name AvgPrecision TP FN FP TN Accuracy ErrorRate Precision Recall Specificity FalsePosRate
-- ---- ------------ ------ ------ ------ ------ -------- --------- --------- ------ ----------- ------------
0 vehicle 91.2495 32648 3903 5826 65129 0.9095 0.0905 0.8486 0.8932 0.9179 0.0821
1 motorcycle 80.4499 2936 513 569 5393 0.8850 0.1150 0.8377 0.8513 0.9046 0.0954
2 bicycle 89.0912 570 124 104 3548 0.9475 0.0525 0.8457 0.8213 0.9715 0.0285
3 person 76.7937 7072 1727 2574 27523 0.8894 0.1106 0.7332 0.8037 0.9145 0.0855
4 many vehicles 64.3089 1068 509 733 11288 0.9087 0.0913 0.5930 0.6772 0.9390 0.0610
5 green light 86.8118 1969 239 510 4116 0.8904 0.1096 0.7943 0.8918 0.8898 0.1102
6 yellow light 82.0390 126 38 30 1239 0.9525 0.0475 0.8077 0.7683 0.9764 0.0236
7 red light 94.1033 3449 217 451 4643 0.9237 0.0763 0.8844 0.9408 0.9115 0.0885
`
11. To check accuracy mAP@IoU=75:
`bash
darknet detector map animals.data animals.cfg animalsbest.weights -iouthresh 0.75
`
12. Recalculating anchors:
- Best done in DarkMark.
- In Darknet, use:
`bash
darknet detector calcanchors animals.data -numof_clusters 6 -width 320 -height 256
`
13. Train a new network:
`bash
cd ~/nn/animals/
darknet detector -map -dont_show train animals.data animals.cfg
`
Training
Quick links to relevant sections of the Darknet/YOLO FAQ:
1. How should I setup my files and directories?
2. Which configuration file should I use?
3. What command should I use when training my own network?
The simplest way to annotate and train is with the use of DarkMark to create all of the necessary Darknet files. This is definitely the recommended way to train a new neural network.
If you'd rather manually setup the various files to train a custom network:
1. Create a new folder for your project:
- For this example, a neural network will be created to detect animals, so the following directory is created: ~/nn/animals/.
2. Copy a Darknet configuration file as a template:
- For example, copy cfg/yolov4-tiny.cfg to the project folder. You will now have ~/nn/animals/animals.cfg.
3. Create a animals.names text file:
- This file will contain the list of classes you want to detect, one per line. For example:
`
dog
cat
bird
horse
`
4. Create a animals.data text file:
- This file specifies the paths to the training and validation data, as well as the names and backup directories. For example:
`
classes=4
train=/home/username/nn/animals/animals_train.txt
valid=/home/username/nn/animals/animals_valid.txt
names=/home/username/nn/animals/animals.names
backup=/home/username/nn/animals
`
5. Create a folder for your images and annotations:
- For example, this could be ~/nn/animals/dataset. Each image will need a corresponding .txt file which describes the annotations for that image. The format of the .txt annotation files is very specific. You cannot create these files by hand since each annotation needs to contain the exact coordinates for the annotation. See DarkMark or other similar software to annotate your images. The YOLO annotation format is described in the Darknet/YOLO FAQ.
6. Create the "train" and "valid" text files:
- These two text files need to individually list all of the images which Darknet must use to train and for validation when calculating the mAP%. Exactly one image per line. The path and filenames may be relative or absolute.
7. Modify your .cfg file:
- batch: Set to 64.
- subdivisions: Start with 1. See the Darknet/YOLO FAQ if you need to adjust this based on memory availability.
- maxbatches: A good starting value is 2000 numberof_classes. For this example, we have 4 animals, so 4 2000 = 8000.
- steps: Set to 80% and 90% of maxbatches. For this example, we'd use steps=6400,7200 since maxbatches was set to 8000.
- width and height: These are the network dimensions. The Darknet/YOLO FAQ explains how to calculate the best size to use.
- classes: Modify this line with the number of classes in your .names file. For this example, we'd use classes=4.
- filters: In the [convolutional] section prior to each [yolo] section, modify filters=... with the value (numberofclasses + 5) * 3. For this example, we'd use filters=27.
8. Start training:
`bash
cd ~/nn/animals/
darknet detector -map -dont_show train animals.data animals.cfg
`
Be patient. The best weights will be saved as animals_best.weights. The progress of training can be observed by viewing the chart.png file. See the Darknet/YOLO FAQ for additional parameters you may want to use when training a new network.
If you want to see more details during training, add the --verbose parameter. For example:
`bash
darknet detector -map -dont_show --verbose train animals.data animals.cfg
`
Other Tools and Links
1. DarkMark: To manage your Darknet/YOLO projects, annotate images, verify your annotations, and generate the necessary files to train with Darknet.
2. DarkHelp: For a robust alternative CLI to Darknet, to use image tiling, for object tracking in your videos, or for a robust C++ API that can easily be used in commercial applications.
3. Darknet/YOLO FAQ: To help answer your questions.
4. Stéphane's YouTube channel: For tutorial and example videos.
5. Darknet/YOLO discord server: To chat with other Darknet/YOLO users and ask for support.
Roadmap
Last updated 2024-10-30:
Completed
1. Swap out qsort() for std::sort() where used during training.
2. Get rid of check_mistakes, getchar(), and system().
3. Convert Darknet to use the C++ compiler.
4. Fix Windows build.
5. Fix Python support.
6. Build darknet library.
7. Re-enable labels on predictions ("alphabet" code).
8. Re-enable CUDA/GPU code.
9. Re-enable CUDNN.
10. Re-enable CUDNN half.
11. Do not hard-code the CUDA architecture.
12. Better CUDA version information.
13. Re-enable AVX.
14. Remove old solutions and Makefile.
15. Make OpenCV non-optional.
16. Remove dependency on the old pthread library.
17. Remove STB.
18. Re-write CMakeLists.txt to use the new CUDA detection.
19. Remove old "alphabet" code, and delete the 700+ images in data/labels.
20. Build out-of-source.
21. Have better version number output.
22. Performance optimizations related to training (on-going task).
23. Performance optimizations related to inference (on-going task).
24. Pass-by-reference where possible.
25. Clean up .hpp files.
26. Re-write darknet.h.
27. Do not cast cv::Mat to void* but use it as a proper C++ object.
28. Fix or be consistent in how internal image structure gets used.
29. Fix build for ARM-based Jetson devices.
30. New Jetson Orin devices are working.
31. Fix Python API in V3.
Short-term goals
1. Swap out printf() for std::cout.
2. Look into old zed camera support.
3. Better and more consistent command line parsing.
Mid-term goals
1. Remove all char* code and replace with std::string.
2. Don't hide warnings and clean up compiler warnings.
3. Better use of cv::Mat instead of the custom image structure in C.
4. Replace old list functionality with std::vector or std::list.
5. Fix support for 1-channel greyscale images.
6. Add support for N-channel images where N > 3.
7. On-going code cleanup.
Long-term goals
1. Fix CUDA/CUDNN issues with all GPUs.
2. Re-write CUDA+cuDNN code.
3. Look into adding support for non-NVIDIA GPUs.
4. Rotated bounding boxes, or some sort of "angle" support.
5. Keypoints/skeletons.
6. Heatmaps.
7. Segmentation.
