Darknet Object Detection Framework and YOLO
Darknet is an open-source neural network framework crafted using C, C++, and CUDA. It serves as the foundation for YOLO (You Only Look Once), a cutting-edge real-time object detection system renowned for its speed and accuracy.
Read about how Hank.ai is bolstering the Darknet/YOLO community: [link to Hank.ai blog]
Explore the official Darknet/YOLO website: [link to Darknet website]
Dive into the comprehensive Darknet/YOLO FAQ: [link to FAQ]
Engage with the vibrant Darknet/YOLO community on Discord: [link to Discord server]
Papers
1. YOLOv7: [link to paper]
2. Scaled-YOLOv4: [link to paper]
3. YOLOv4: [link to paper]
4. YOLOv3: [link to paper]
General Information
The Darknet/YOLO framework continues to dominate other frameworks and YOLO versions in terms of speed and accuracy. Its open-source nature and complete freedom from licensing fees allow seamless integration into existing projects and commercial products.
Darknet V3 ("Jazz"), released in October 2024, achieves remarkable performance, processing the LEGO dataset videos at an astounding 1000 FPS using an NVIDIA RTX 3090 GPU. This translates to a processing time of less than 1 millisecond per video frame.
Join the active Darknet/YOLO Discord server at [link to Discord server] for support, discussions, and collaborative learning.
Darknet/YOLO caters to a wide range of devices, from Raspberry Pi to high-end training rigs, supporting both CPU and GPU versions. The GPU version requires a CUDA-capable GPU from NVIDIA.
Darknet/YOLO boasts compatibility with Linux, Windows, and Mac operating systems. Find detailed building instructions below.
Darknet Version
The original Darknet tool, developed by Joseph Redmon between 2013 and 2017, lacked a version number. We designate this version as 0.x.
Alexey Bochkovskiy continued maintaining the popular Darknet repository from 2017 to 2021, again without a version number. We refer to this as version 1.x.
The Darknet repository, sponsored by Hank.ai and maintained by Stéphane Charette since 2023, introduced the "version" command. Between 2023 and late 2024, it returned version 2.x "OAK".
The development goals were to minimize disruption to existing functionality while familiarizing ourselves with the codebase. Key improvements include:
Unified build process: Re-written build steps for a consistent CMake-based build process on both Windows and Linux.
C++ codebase: Conversion of the codebase to leverage the C++ compiler.
Enhanced training chart: Improved chart.png visualization during training.
Bug fixes and optimizations: Performance-related enhancements, focusing on reducing training time.
The last branch of this codebase is version 2.1, residing in the "v2" branch.
The next phase of development commenced in mid-2024 and culminated in the October 2024 release of version 3.x "JAZZ".
You can always access the previous "v2" branch to execute commands from those versions. Please inform us if you encounter any missing commands, and we will investigate their re-integration.
Significant changes in Darknet V3 include:
Command removal: Removal of outdated and infrequently used commands.
Performance optimizations: Enhancements for both training and inference performance.
Legacy API modification: Modification of the legacy C API; applications using the original Darknet API might require minor adjustments.
New C/C++ API: Introduction of a new Darknet V3 C and C++ API.
Updated sample code: Inclusion of new applications and sample code in the "src-examples" directory.
For detailed information on the new API: [link to Darknet V3 API documentation]
Explore the updated sample code: [link to Darknet V3 API files]
MSCOCO Pre-trained Weights
Several popular YOLO versions have been pre-trained for convenience on the MSCOCO dataset. This dataset encompasses 80 classes, readily identifiable in the "cfg/coco.names" text file.
Beyond MSCOCO, Darknet/YOLO provides pre-trained weights for simpler datasets like LEGO Gears and Rolodex, allowing you to experiment with various scenarios. Refer to the Darknet/YOLO FAQ for comprehensive details.
The MSCOCO pre-trained weights are accessible from multiple sources, including this repository:
YOLOv2 (November 2016):
YOLOv2-tiny: [link to weights]
YOLOv2-full: [link to weights]
YOLOv3 (May 2018):
YOLOv3-tiny: [link to weights]
YOLOv3-full: [link to weights]
YOLOv4 (May 2020):
YOLOv4-tiny: [link to weights]
YOLOv4-full: [link to weights]
YOLOv7 (August 2022):
YOLOv7-tiny: [link to weights]
YOLOv7-full: [link to weights]
These pre-trained weights are primarily intended for demonstration purposes. The corresponding .cfg and .names files for MSCOCO are located in the "cfg" directory. Example commands:
`
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
`
Remember, training your own networks is encouraged. MSCOCO primarily serves as a benchmark to confirm the correct functioning of your setup.
Building
The various build methods used before 2023 have been consolidated into a single unified solution. Darknet relies on C++17 or later, OpenCV, and utilizes CMake to generate the necessary project files.
Building, installing, and running Darknet/YOLO does not require C++ expertise, similar to driving a car without being a mechanic.
Google Colab
The Google Colab instructions are identical to the Linux instructions. Several Jupyter notebooks demonstrate various tasks, such as training a new network.
Explore the notebooks in the "colab" subdirectory or follow the Linux instructions below.
Linux CMake Method
Darknet build tutorial for Linux
Optional: If you have a modern NVIDIA GPU, you can install either CUDA or CUDA+cuDNN at this point. If installed, Darknet will use your GPU to speed up image (and video) processing.
You must delete the CMakeCache.txt file from your Darknet build directory to force CMake to re-find all of the necessary files.
Remember to re-build Darknet.
Darknet can run without it, but if you want to train a custom network then either CUDA or CUDA+cuDNN is required.
1. Install prerequisites:
`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:
`bash
mkdir buildcd build
`
4. Configure CMake:
`bash
cmake -DCMAKEBUILDTYPE=Release ..
`
5. Build Darknet:
`bash
make -j4
`
6. Package Darknet:
`bash
package
`
7. Install the package:
`bash
sudo dpkg -i darknet-VERSION.deb
`
If you are using an older version of CMake then you'll need to upgrade CMake before you can run the cmake command above. Upgrading CMake on Ubuntu can be done with the following commands:
`bash
sudo apt-get purge cmake
sudo snap install cmake --classic
`
If using bash as your command shell you'll want to re-start your shell at this point. If using fish, it should immediately pick up the new path.
Advanced users:
If you prefer an RPM installation package instead of a DEB file, modify the relevant lines in "CM_package.cmake". Before running "make -j4 package", adjust these lines:
`cmake
SET (CPACKGENERATOR "DEB")# SET (CPACKGENERATOR "RPM")
`
For distributions like Centos and OpenSUSE, modify those lines as follows:
`cmake
SET (CPACK_GENERATOR "DEB")
SET (CPACK_GENERATOR "RPM")
`
Install the built package using your distribution's package manager. For Debian-based systems like Ubuntu:
`bash
sudo dpkg -i darknet-2.0.1-Linux.deb
`
The .deb package installation will copy the following files:
/usr/bin/darknet: The main Darknet executable. Run "darknet version" from the CLI to confirm successful 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: The library to link against for C, C++, and Python developers.
/opt/darknet/cfg/...: Stores all .cfg templates.
Congratulations! Darknet has been built and installed into /usr/bin/. Run "darknet version" to verify the installation.
If you don't have /usr/bin/darknet, this means you only built it, not installed it. Ensure you install the .deb or .rpm file as described above.
Windows CMake Method
These instructions assume a brand new installation of Windows 11 22H2.
1. Install prerequisites using Winget:
`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, then "Yes."
3. Install Microsoft VCPKG:
- Once the installation finishes, click on the "Windows Start" menu and select "Developer Command Prompt for VS 2022." Do not use PowerShell for these steps, it will cause issues!
- Advanced users: Instead of using the Developer Command Prompt, you can run a normal command prompt or ssh into the device and manually execute "Program FilesMicrosoft Visual Studio2022CommunityCommon7ToolsVsDevCmd.bat."
4. Install OpenCV using 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
`
Be patient during this step as it can take a significant amount of time to download and build dependencies.
Advanced users:
- Note that there are many other optional modules you might want to add when building OpenCV. Run .vcpkg.exe search opencv to see the full list.
Optional: If you have a modern NVIDIA GPU, you can install either CUDA or CUDA+cuDNN at this point. If installed, Darknet will use your GPU to speed up image (and video) processing.
You must delete the CMakeCache.txt file from your Darknet build directory to force CMake to re-find all of the necessary files.
Remember to re-build Darknet.
Darknet can run without it, but if you want to train a custom network then either CUDA or CUDA+cuDNN is required.
1. Install CUDA:
Visit https://developer.nvidia.com/cuda-downloads to download and install CUDA.
2. Install cuDNN:
Visit https://developer.nvidia.com/rdp/cudnn-download or https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html#download-windows to download and install cuDNN.
3. Verify CUDA installation:
After installing CUDA, ensure you can run nvcc.exe and nvidia-smi.exe. You might need to adjust your PATH variable.
4. Integrate cuDNN:
Unzip the downloaded cuDNN archive and copy the "bin", "include", and "lib" directories into C:Program FilesNVIDIA GPU Computing ToolkitCUDA[version]. You might need to overwrite existing files.
5. Install CUDA after Visual Studio:
- CUDA must be installed after Visual Studio. If you upgrade Visual Studio, remember to reinstall CUDA.
6. Clone Darknet and build:
`bash
cd c:src
git clone https://github.com/hank-ai/darknet.gitcd darknet
mkdir buildcd 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
`
7. Handle missing CUDA/cuDNN DLLs:
- If you encounter errors about missing CUDA or cuDNN DLLs (e.g., cublas64_12.dll), manually copy the relevant CUDA .dll files into the same directory as darknet.exe. For example:
`bash
copy "C:Program FilesNVIDIA GPU Computing ToolkitCUDAv12.2bin*.dll" src-cliRelease
`
(This is an example. Verify your CUDA version and execute the appropriate command.)
- Re-run the last msbuild.exe command to generate the NSIS installation package.
Advanced users:
The cmake command output is a regular Visual Studio solution file (Darknet.sln). If you prefer using the Visual Studio GUI instead of msbuild.exe for building, you can load the Darknet project in Visual Studio and ignore the command-line steps.
You should now have C:srcDarknetbuildsrc-cliReleasedarknet.exe executable. Run C:srcDarknetbuildsrc-cliReleasedarknet.exe version to test the installation.
To install Darknet correctly, including the libraries, include files, and necessary DLLs, run the NSIS installation wizard built in the last step. Locate the darknet-VERSION.exe file in the build directory, e.g., darknet-2.0.31-win64.exe.
The NSIS installation package will:
Create a directory called "Darknet" (e.g., C:Program FilesDarknet).
Install the CLI application (darknet.exe) and other sample applications.
Install the required 3rd-party .dll files (e.g., from OpenCV).
Install necessary Darknet .dll, .lib, and .h files for using darknet.dll from other applications.
Install template .cfg files.
You are now finished! Once the installation wizard completes, Darknet will be installed in C:Program FilesDarknet. Run C:Program FilesDarknetbindarknet.exe version to verify the installation.
If you don't have C:/Program Files/darknet/bin/darknet.exe, this indicates you only built it, not installed it. Make sure you go through each panel of the NSIS installation wizard as described earlier.
Using Darknet
CLI
This is not an exhaustive list of all commands supported by Darknet.
In addition to the Darknet CLI, note the DarkHelp project CLI, which offers an alternative interface for Darknet/YOLO. It includes several advanced features not directly available in Darknet. You can utilize both the Darknet CLI and DarkHelp CLI concurrently; they are not mutually exclusive.
For most commands below, you'll need the .weights file along with corresponding .names and .cfg files. You can either train your own network (highly recommended!) or download a pre-trained neural network from publicly available resources. Some examples include:
LEGO Gears (object detection in images)
Rolodex (text detection in images)
MSCOCO (standard 80-class object detection)
Here are some example commands and their usage:
Basic commands:
Help:
`bash
darknet help
`
Version:
`bash
darknet version
`
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
`
Outputting 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
`
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
`
Webcam input:
V2:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -c 0
`
V3:
`bash
darknet08display_webcam animals
`
Saving results to 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
`
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
`
Running on a specific GPU:
V2:
`bash
darknet detector demo animals.data animals.cfg animals_best.weights -i 1 test.mp4
`
Checking network accuracy:
mAP:
`bash
darknet detector map driving.data driving.cfg driving_best.weights ...
`
- This command will display the average precision (AP) for each class in the dataset.
mAP@IoU=75:
`bash
darknet detector map animals.data animals.cfg animalsbest.weights -iouthresh 0.75
`
- This command calculates the mAP at an IoU threshold of 0.75.
Calculating anchors:
The best practice for anchor recalculation is to use DarkMark, as it runs 100 consecutive calculations and selects the optimal anchors. However, you can use the older Darknet method:
`bash
darknet detector calcanchors animals.data -numof_clusters 6 -width 320 -height 256
`
Training a new network:
Basic training:
`bash
darknet detector -map -dont_show train animals.data animals.cfg
`
- The best weights will be saved as animals_best.weights, and training progress is visible in chart.png.
Verbose training:
`bash
darknet detector -map -dont_show --verbose train animals.data animals.cfg
`
- This command provides more detailed information during training.
Training
Quick links to relevant sections of the Darknet/YOLO FAQ:
File and directory setup: [link to FAQ section]
Choosing the right configuration file: [link to FAQ section]
Training command: [link to FAQ section]
The most straightforward way to annotate and train is by using DarkMark to create all necessary Darknet files. This is the recommended approach for training a new neural network.
Manual training setup:
1. Create a folder: Create a new folder to store your training files. For example, ~/nn/animals/.
2. Copy the configuration file: Copy a Darknet configuration file as a template (e.g., cfg/yolov4-tiny.cfg) into your folder. You now have ~/nn/animals/animals.cfg.
3. Create the .names file: Create a animals.names text file in the same folder.
- Edit the file to list the classes you want to detect. Each class must be on a separate line with no blank lines or comments. For example:
`
dog
cat
bird
horse
`
4. Create the .data file: Create a animals.data text file in the same folder.
- The .data file defines the training and validation datasets, class names, and backup directory. 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 the image and annotation folder: Create a folder (e.g., ~/nn/animals/dataset) to store your images and annotations.
- Each image requires a corresponding .txt file containing annotations. The annotation format is specific; it cannot be manually created. Use DarkMark or similar software to annotate images.
- The YOLO annotation format is explained in the Darknet/YOLO FAQ.
6. Create the "train" and "valid" files: Create the "train" and "valid" text files mentioned in the .data file.
- These files list the images used for training and validation, respectively. Each image should be on a separate line. You can use relative or absolute paths.
7. Modify the configuration file:
- Open your .cfg file with a text editor and make the following adjustments:
- batch=64: This value is usually fine.
- subdivisions: Start with subdivisions=1. You might need to increase this value depending on your GPU's memory and network dimensions. See the Darknet/YOLO FAQ for guidance.
- maxbatches: Set this to 2000 * number of classes. For example, with 4 classes, maxbatches=8000.
- steps: Set this to 80% and 90% of maxbatches. For example, with maxbatches=8000, steps=6400,7200.
- width and height: These are the network dimensions. Consult the Darknet/YOLO FAQ for dimension calculation advice.
- classes: Change the classes=... line to match the number of classes in your .names file (in this example, classes=4).
- filters: Modify the filters=... line in each [convolutional] section before each [yolo] section. The value is calculated as (numberofclasses + 5) * 3. For example, with 4 classes, filters=27.
8. Start training:
`bash
cd ~/nn/animals/
darknet detector -map -dont_show train animals.data animals.cfg
`
- Training might take a while. The best weights will be saved as animals_best.weights. Training progress is visible in the chart.png file. Refer to the Darknet/YOLO FAQ for additional training parameters.
- If you want more detailed training information, add the --verbose parameter:
`bash
darknet detector -map -dont_show --verbose train animals.data animals.cfg
`
Other Tools and Links
DarkMark: This tool assists with managing your Darknet/YOLO projects, annotating images, verifying annotations, and generating the necessary files for Darknet training.
DarkHelp: A robust alternative CLI for Darknet that provides features such as image tiling, object tracking in videos, and a robust C++ API for commercial applications.
Darknet/YOLO FAQ: A valuable resource for answering your questions about Darknet/YOLO.
Stéphane's YouTube channel: Find numerous tutorials and example videos.
Darknet/YOLO Discord server: Join the server to ask support questions and connect with other Darknet/YOLO users.
Roadmap
Last updated: 2024-10-30
Completed
Swap out qsort(): Replaced qsort() with std::sort() in relevant parts of the codebase. (Some remaining instances still use qsort())
Remove outdated functions: Removed check_mistakes, getchar(), and system().
C++ codebase: Converted Darknet to use the C++ compiler (g++ on Linux, VisualStudio on Windows).
Windows build: Fixed Windows build process.
Python support: Fixed Python integration.
Darknet library: Built the Darknet library.
Prediction labels: Re-enabled labels on predictions (the "alphabet" code).
CUDA/GPU code: Re-enabled CUDA/GPU functionality.
CUDNN: Re-enabled CUDNN support.
CUDNN half: Re-enabled CUDNN half-precision support.
CUDA architecture: Removed hard-coding of CUDA architecture.
CUDA version information: Improved CUDA version information.
AVX: Re-enabled AVX support.
Removed legacy files: Removed old solutions and Makefile.
OpenCV dependency: Made OpenCV a required dependency.
pthread library: Removed dependence on the old pthread library.
STB: Removed STB dependency.
CMakeLists.txt: Re-written CMakeLists.txt to use the new CUDA detection method.
Removed outdated files: Removed old "alphabet" code and deleted the 700+ images in data/labels.
Out-of-source build: Enabled out-of-source builds.
Version number: Improved version number output.
Training performance: Performance optimizations for training (ongoing task).
Inference performance: Performance optimizations for inference (ongoing task).
Pass-by-reference: Used pass-by-reference where possible for improved efficiency.
Code cleanup: Cleaned up .hpp files.
Re-written darknet.h: Updated the Darknet API header file.
cv::Mat usage: Used cv::Mat as a proper C++ object instead of casting it to void*.
Image structure: Fixed inconsistencies and issues related to the internal image structure.
Jetson support: Fixed builds for ARM-based Jetson devices.
- Older Jetson devices are unlikely to be fixed due to NVIDIA discontinuing support (no C++17 compiler).
- New Jetson Orin devices are working.
Python API in V3: Fixed the Python API in Darknet V3.
Short-term goals
Swap out printf(): Replace printf() with std::cout (in progress).
Zed camera support: Revisit and improve support for the Zed camera.
Command line parsing: Implement more robust and consistent command line parsing (in progress).
Mid-term goals
Remove char code: Eliminate all char code and replace it with std::string.
Compiler warnings: Don't hide warnings and address compiler warnings (in progress).
cv::Mat usage: Enhance the use of cv::Mat instead of the custom image structure in C (in progress).
List functionality: Replace old list functionality with std::vector or std::list.
Greyscale image support: Fix support for 1-channel greyscale images.
N-channel image support: Add support for images with more than 3 channels (e.g., depth or thermal channels).
Ongoing code cleanup: Continue with ongoing code clean-up (in progress).
Long-term goals
CUDA/CUDNN issues: Address CUDA/CUDNN compatibility issues across different GPUs.
Re-write CUDA/CUDNN code: Re-write the CUDA/CUDNN code for improved performance and compatibility.
Non-NVIDIA GPU support: Investigate support for non-NVIDIA GPUs.
Rotated bounding boxes: Implement support for rotated bounding boxes or angle information.
Keypoints/Skeletons: Add support for keypoints and skeletons.
Heatmaps: Implement heatmap support (in progress).
Segmentation: Add support for segmentation.
