Darknet Object Detection Framework and YOLO
!Darknet and Hank.ai logos
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 that runs within the Darknet framework.
Discover how Hank.ai is supporting the Darknet/YOLO community
Explore the official Darknet/YOLO website
Consult the comprehensive Darknet/YOLO FAQ
Join the lively Darknet/YOLO Discord server
Papers
1. YOLOv7 Paper
2. Scaled-YOLOv4 Paper
3. YOLOv4 Paper
4. YOLOv3 Paper
General Information
The Darknet/YOLO framework continues to push the boundaries of performance, consistently delivering both speed and accuracy exceeding other frameworks and YOLO versions. This framework is completely free and open source, allowing you to seamlessly integrate Darknet/YOLO into existing projects and products, including commercial applications, without the need for licensing or fees.
Darknet V3 ("Jazz"), released in October 2024, achieves remarkable performance, capable of accurately processing LEGO dataset videos at up to 1000 FPS using an NVIDIA RTX 3090 GPU. This translates to Darknet/YOLO handling each video frame, including resizing and processing, within just 1 millisecond or less.
Join the vibrant Darknet/YOLO Discord server at https://discord.gg/zSq8rtW for assistance, discussions, and to connect with fellow users.
The CPU version of Darknet/YOLO can run on diverse devices, including Raspberry Pi, cloud & colab servers, desktops, laptops, and high-end training rigs. The GPU version of Darknet/YOLO necessitates a CUDA-capable GPU from NVIDIA.
Darknet/YOLO is known to function seamlessly on Linux, Windows, and Mac. For detailed instructions, refer to the building sections below.
Darknet Version
1. Version 0.x: This refers to the original Darknet tool developed by Joseph Redmon from 2013-2017, which lacked a version number.
2. Version 1.x: This encompasses the popular Darknet repository maintained by Alexey Bochkovskiy between 2017-2021, also without an official version number.
3. Version 2.x "OAK": This version was introduced in 2023, sponsored by Hank.ai and maintained by Stéphane Charette. It marked the first time the Darknet repository incorporated a version command.
- The goal was to minimize disruptions to existing functionality while familiarizing with the codebase.
- Key changes included:
- Unified CMake build system for Windows and Linux
- Codebase conversion to C++ compiler
- Enhanced chart.png during training
- Bug fixes and performance optimizations, particularly for training time reduction
- The final branch of this codebase was version 2.1 in the v2 branch.
4. Version 3.x "JAZZ": This phase of development began in mid-2024 and launched in October 2024. The version command now returns 3.x.
- Changes in this version include:
- Removal of several outdated and unsupported commands.
- Comprehensive performance optimizations for both training and inference.
- Modifications to the legacy C API, requiring minor adjustments for applications utilizing the original Darknet API. The updated documentation for the Darknet V3 C and C++ API can be found at https://darknetcv.ai/api/api.html.
- Introduction of new applications and sample code in the src-examples directory, accessible at https://darknetcv.ai/api/files.html.
Note: For compatibility, you can always access the previous v2 branch if you need to execute any of those specific commands. Please reach out to us if you encounter any missing commands, and we'll investigate their reintegration.
MSCOCO Pre-trained Weights
For convenience, several popular YOLO versions have been pre-trained on the MSCOCO dataset. This dataset contains 80 classes, which can be viewed in the cfg/coco.names text file.
Beyond MSCOCO, you can find other pre-trained weights and simpler datasets for testing Darknet/YOLO, such as LEGO Gears and Rolodex. Detailed information can be found in the Darknet/YOLO FAQ.
The MSCOCO pre-trained weights are accessible from various locations, including within this repository:
1. YOLOv2 (November 2016)
- yolov2-tiny.weights
- yolov2-full.weights
2. YOLOv3 (May 2018)
- yolov3-tiny.weights
- yolov3-full.weights
3. YOLOv4 (May 2020)
- yolov4-tiny.weights
- yolov4-full.weights
4. YOLOv7 (August 2022)
- yolov7-tiny.weights
- yolov7-full.weights
The MSCOCO pre-trained weights are provided primarily for demonstration purposes. The corresponding .cfg and .names files for MSCOCO are located 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
`
It is essential to understand that training your own networks is the recommended practice. MSCOCO is primarily used for verifying the correct operation of Darknet/YOLO.
Building
The various build methods employed in the past (before 2023) have been streamlined into a unified solution. Darknet requires C++17 or newer, OpenCV, and utilizes CMake for project file generation.
Remember, building, installing, and running Darknet/YOLO does not require C++ knowledge. It's akin to driving a car without being a mechanic.
Please note: If you're referring to older tutorials with more complex build steps or those that don't align with this readme, proceed with caution. The new build instructions outlined below were introduced in August 2023.
For insights into the inner workings of the Darknet/YOLO object detection framework, software developers are encouraged to visit https://darknetcv.ai/.
Google Colab
The Google Colab instructions are identical to the Linux instructions. Several Jupyter notebooks are available, demonstrating how to perform specific tasks like training a new network.
Explore the notebooks within the colab subdirectory, or follow the Linux instructions provided below.
Linux CMake Method
Darknet Build Tutorial for Linux
1. Install Dependencies:
`bash
sudo apt-get install build-essential git libopencv-dev cmake
`
2. Clone Darknet Repository:
`bash
mkdir ~/srccd ~/src
git clone https://github.com/hank-ai/darknet
cd darknet
`
3. Create Build Directory:
`bash
mkdir buildcd build
`
4. Configure Using CMake:
`bash
cmake -DCMAKEBUILDTYPE=Release ..
`
5. Build Darknet:
`bash
make -j4
`
6. Package and Install:
`bash
package
sudo dpkg -i darknet-VERSION.deb
`
Optional: CUDA and cuDNN Installation
For accelerated image and video processing, you can optionally install either CUDA or CUDA+cuDNN. Darknet will leverage your GPU if available.
1. Install CUDA:
- Download and install CUDA from https://developer.nvidia.com/cuda-downloads.
- Ensure you can execute nvcc and nvidia-smi. You may need to modify your PATH variable.
2. Install cuDNN:
- Download and install cuDNN from https://developer.nvidia.com/rdp/cudnn-download or https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html#cudnn-package-manager-installation-overview.
If you install CUDA or CUDA+cuDNN after initial setup or upgrade the NVIDIA software:
1. Delete CMakeCache.txt:
- Remove the CMakeCache.txt file from your Darknet build directory to force CMake to re-discover all dependencies.
2. Re-build Darknet:
- Repeat the cmake and make steps above.
Note: These instructions assume Ubuntu 22.04, but can be adapted for other distributions.
Advanced Users:
To create an RPM installation file instead of a DEB file, modify the relevant lines in CM_package.cmake. Prior to running make -j4 package, update these two lines:
`cmake
SET (CPACK_GENERATOR "DEB")
SET (CPACK_GENERATOR "RPM")
`
For distributions like Centos and OpenSUSE, adjust the lines to:
`cmake
SET (CPACK_GENERATOR "DEB")
SET (CPACK_GENERATOR "RPM")
`
After building, install the package using your distribution's package manager. For example, on Debian-based systems:
`bash
sudo dpkg -i darknet-2.0.1-Linux.deb
`
Installation Outcome:
/usr/bin/darknet: The standard Darknet executable. Run darknet version to verify correct installation.
/usr/include/darknet.h: The Darknet API for C, C++, and Python developers.
/usr/include/darknet_version.h: Contains version information for developers.
/usr/lib/libdarknet.so: Library for linking C, C++, and Python projects.
/opt/darknet/cfg/...: Location for all .cfg templates.
Confirmation: Run darknet version in your terminal to confirm successful Darknet installation.
Windows CMake Method
Windows Build Instructions (Assumes Windows 11 22H2)
1. Install Dependencies:
`bash
winget install Git.Git
winget install Kitware.CMake
winget install nsis.nsis
winget install Microsoft.VisualStudio.2022.Community
`
2. Modify Visual Studio Installation:
- Open 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 "Yes".
3. Open Developer Command Prompt:
- Open 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/vcpkg
cd 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. Optional: CUDA and cuDNN Installation:
- Install either CUDA or CUDA+cuDNN for GPU acceleration.
- Follow the same steps as in the Linux instructions.
6. Clone Darknet and Build:
`bash
cd c:src
git clone https://github.com/hank-ai/darknet.git
cd darknet
mkdir build
cd build
cmake -DCMAKEBUILDTYPE=Release -DCMAKETOOLCHAINFILE=C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake ..
msbuild.exe /property:Platform=x64;Configuration=Release /target:Build -maxCpuCount -verbosity:normal -detailedSummary darknet.sln
msbuild.exe /property:Platform=x64;Configuration=Release PACKAGE.vcxproj
`
If you encounter errors about missing CUDA or cuDNN DLLs (e.g., cublas64_12.dll):
1. Copy CUDA DLLs:
- Manually copy the CUDA .dll files to the same output directory as Darknet.exe. For example:
`bash
copy "C:Program FilesNVIDIA GPU Computing ToolkitCUDAv12.2bin*.dll" src-cliRelease
`
2. Re-run msbuild.exe:
- Execute the last msbuild.exe command again to generate the NSIS installation package.
Advanced Users:
Instead of the Developer Command Prompt, you can use a normal command prompt or SSH and run "Program FilesMicrosoft Visual Studio2022CommunityCommon7ToolsVsDevCmd.bat".
The cmake command generates a Visual Studio solution file (Darknet.sln). If you prefer using the Visual Studio GUI, load the project instead of relying on command-line tools.
Confirmation: Run C:srcDarknetbuildsrc-cliReleasedarknet.exe version to verify installation.
Install using NSIS Wizard:
Execute the NSIS installation wizard found in the build directory (e.g., darknet-VERSION.exe). This will:
- Create a Darknet directory (e.g., C:Program FilesDarknet).
- Install the CLI application, darknet.exe, and other sample apps.
- Install necessary 3rd-party .dll files (e.g., from OpenCV).
- Install Darknet .dll, .lib, and .h files for usage in other applications.
- Install template .cfg files.
Confirmation: After installation, run C:Program FilesDarknetbindarknet.exe version to confirm Darknet is ready.
Using Darknet
CLI
The following is a partial list of commands supported by Darknet.
In addition to the Darknet CLI, consider the DarkHelp project CLI, offering an alternative CLI with advanced features not directly available in Darknet. You can use both CLIs together.
For most commands, you'll need the .weights file along with its corresponding .names and .cfg files. You can either train your own network (highly recommended) or download pre-trained networks freely available online. Examples include:
LEGO Gears (object detection in images)
Rolodex (text detection in images)
MSCOCO (standard 80-class object detection)
Common Darknet CLI Commands:
1. Get Help:
`bash
darknet help
`
2. Check Version:
`bash
darknet version
`
3. Image Prediction:
- 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. Video Processing:
- 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. Webcam Input:
- V2:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -c 0
`
- V3:
`bash
darknet08display_webcam animals
`
7. Save Video Results:
- 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 Output:
- 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. GPU Selection:
- V2:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -i 1 test.mp4
`
10. Network Accuracy Evaluation:
- Calculate mAP:
`bash
darknet detector map driving.data driving.cfg driving_best.weights ...
`
- Detailed Accuracy Information:
`bash
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
`
- Calculate mAP@IoU=75:
`bash
darknet detector map animals.data animals.cfg animalsbest.weights -iouthresh 0.75
`
- Calculate Anchors:
`bash
darknet detector calcanchors animals.data -numof_clusters 6 -width 320 -height 256
`
11. Train a New Network:
`bash
darknet detector -map -dont_show train animals.data animals.cfg
`
Training
Essential Links to the Darknet/YOLO FAQ:
Setting up Files and Directories
Choosing the Right Configuration File
Training a Custom Network Command
For seamless annotation and training, DarkMark simplifies the process by automatically creating all the necessary Darknet files. Using DarkMark is highly recommended for training a new neural network.
Manual Training Setup:
1. Create a Project Directory:
- For example, create a directory named ~/nn/animals/ for detecting animals.
2. Copy Configuration File:
- Copy a suitable Darknet configuration file as a template (e.g., cfg/yolov4-tiny.cfg) into your project directory. This creates ~/nn/animals/animals.cfg.
3. Create animals.names File:
- Create a text file named animals.names in the same directory.
- List your desired classes, one per line, without blank lines or comments. For example:
`
dog
cat
bird
horse
`
4. Create animals.data File:
- Create a text file named animals.data. The content should be:
`
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 Dataset Directory:
- Create a directory (e.g., ~/nn/animals/dataset) to store images and annotations. Each image requires a corresponding .txt file defining its annotations. The format is specific and cannot be created manually. Use DarkMark or similar software to annotate images. The YOLO annotation format is explained in the Darknet/YOLO FAQ.
6. Create Training and Validation Files:
- Create the files animalstrain.txt and animalsvalid.txt mentioned in the .data file. These files list all images for training and validation, respectively, one image per line. Paths can be relative or absolute.
7. Configure .cfg File:
- Open your .cfg file with a text editor.
- Ensure batch=64.
- Adjust subdivisions based on network dimensions and GPU memory. Start with subdivisions=1. Refer to the Darknet/YOLO FAQ for alternative values.
- Set max_batches to 2000 * number of classes (e.g., 8000 for 4 classes).
- Set steps to 80% and 90% of maxbatches (e.g., 6400,7200 for maxbatches=8000).
- Configure width and height (network dimensions) using guidelines from the Darknet/YOLO FAQ.
- Replace classes=... with the number of classes from your .names file (e.g., classes=4).
- Modify filters=... in the [convolutional] section before each [yolo] section. Use the formula (numberofclasses + 5) * 3 (e.g., filters=27 for 4 classes).
8. Start Training:
- Navigate to your project directory:
`bash
cd ~/nn/animals/
`
- Run the training command:
`bash
darknet detector -map -dont_show train animals.data animals.cfg
`
9. Monitor Progress:
- The best weights will be saved as animals_best.weights.
- Track training progress by viewing the chart.png file.
- See the Darknet/YOLO FAQ for additional training parameters.
10. Verbose Training:
- For more detailed output during training, include the --verbose parameter:
`bash
darknet detector -map -dont_show --verbose train animals.data animals.cfg
`
Other Tools and Links
DarkMark: For managing Darknet/YOLO projects, annotating images, verifying annotations, and generating training files.
DarkHelp: Provides a robust alternative CLI for Darknet, image tiling, object tracking in videos, and a comprehensive C++ API for commercial applications.
Darknet/YOLO FAQ: A valuable resource for answering your questions.
Stéphane's YouTube Channel: Numerous tutorials and example videos.
Darknet/YOLO Discord Server: Join the community for support and discussions.
Roadmap
Last Updated: 2024-10-30
Completed:
Replaced qsort() with std::sort() during training (except for a few remaining cases).
Removed check_mistakes, getchar(), and system().
Converted Darknet to use the C++ compiler (g++ on Linux, VisualStudio on Windows).
Fixed Windows build.
Enabled Python support.
Built the Darknet library.
Re-enabled prediction labels (using "alphabet" code).
Re-enabled CUDA/GPU code.
Re-enabled CUDNN and CUDNN half.
Removed hard-coded CUDA architecture.
Improved CUDA version information.
Re-enabled AVX.
Removed old solutions and Makefile.
Made OpenCV non-optional.
Removed dependency on the old pthread library.
Removed STB.
Rewritten CMakeLists.txt for new CUDA detection.
Removed old "alphabet" code and deleted 700+ images in data/labels.
Enabled out-of-source building.
Improved version number output.
Implemented performance optimizations during training (ongoing).
Implemented performance optimizations during inference (ongoing).
Employed pass-by-reference where feasible.
Cleaned up .hpp files.
Rewritten darknet.h.
Avoided casting cv::Mat to void* and used it as a proper C++ object.
Fixed inconsistent use of the internal image structure.
Fixed build issues for ARM-based Jetson devices (except for unsupported original Jetson models).
Jetson Orin devices are functional.
Fixed the Python API in V3.
Enhanced Python support (seeking Python developers to contribute).
Short-Term Goals:
Replace printf() with std::cout (in progress).
Revisit support for old Zed cameras.
Improve and ensure consistency in command-line parsing (in progress).
Mid-Term Goals:
Eliminate all char* code and replace with std::string.
Unhide warnings and address compiler warnings (in progress).
Optimize usage of cv::Mat instead of the custom C image structure (in progress).
Replace old list functionality with std::vector or std::list.
Fix support for 1-channel grayscale images.
Add support for N-channel images (N > 3).
Continue ongoing code cleanup (in progress).
Long-Term Goals:
Resolve CUDA/CUDNN issues across all GPUs.
Rewrite CUDA+cuDNN code.
Explore support for non-NVIDIA GPUs.
Implement rotated bounding boxes or "angle" support.
Add keypoints/skeletons.
Implement heatmaps (in progress).
Introduce segmentation functionality.
