YoloDotNet v1.7

YoloDotNet is a C# .NET 8 implementation of Yolov8 for real-time detection of objects in images and videos using ML.NET and ONNX runtime, with GPU acceleration using CUDA.

YoloDotNet supports the following:

  ✓   Classification   Categorize an image
  ✓   Object Detection   Detect multiple objects in a single image
  ✓   OBB Detection   OBB (Oriented Bounding Box), like Object Detection but with rotated bounding boxes
  ✓   Segmentation   Separate detected objects using pixel masks
  ✓   Pose Estimation   Identifying location of specific keypoints in an image

Batteries not included ;)

Classification	Object Detection	OBB Detection	Segmentation	Pose Estimation
image from pexels.com	image from pexels.com	image from pexels.com	image from pexels.com	image from pexels.com

What's new?

• Minor improvements and optimizations
• Updated dependencies to the latest version

Nuget

> dotnet add package YoloDotNet

Install CUDA (optional)

YoloDotNet with GPU-acceleration requires CUDA and cuDNN.

:information_source: Before installing CUDA and cuDNN, make sure to verify the ONNX runtime's current compatibility with specific versions.

• Download and install CUDA v11.8
• Download cuDNN v8.9.7 ZIP for CUDA v11.x, unzip and copy the dll's in bin folder to your CUDA bin folder
• Add CUDA bin folder-path to your Path environment variables
• Youtube Installation guide
• Optional: Allocate memory to the GPU for faster initial inference

Export Yolov8 model to ONNX

All models must be Yolov8-models. How to export to ONNX format.

Verify your model

using YoloDotNet;

// Instantiate a new Yolo object with your ONNX-model
using var yolo = new Yolo(@"path\to\model.onnx");

Console.WriteLine(yolo.OnnxModel.ModelType); // Output modeltype...

Example - Image inference

using YoloDotNet;
using YoloDotNet.Extensions;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

// Instantiate a new Yolo object with your ONNX-model and CUDA (default)
using var yolo = new Yolo(@"path\to\your_model.onnx");
//using var yolo = new Yolo(@"path\to\your_model.onnx", primeGpu: true); // Allocate GPU-memory for blazing fast inference

// Load image
using var image = Image.Load<Rgba32>(@"path\to\image.jpg");

// Run
var results = yolo.RunClassification(image, 5); // Top 5 classes
//var results = yolo.RunObjectDetection(image) // Example with default confidence (0.25) and IoU (0.45) threshold;
//var results = yolo.RunObbDetection(options, 0.35, 0.5);
//var results = yolo.RunSegmentation(image, 0.25, 0.5);
//var results = yolo.RunPoseEstimation(image, 0.25, 0.5);

image.Draw(results);
image.Save(@"path\to\save\image.jpg");

Example - Video inference

[!IMPORTANT] Processing video requires FFmpeg and FFProbe

• Download FFMPEG
• Add FFmpeg and ffprobe to the Path-variable in your Environment Variables

using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;
using YoloDotNet;
using YoloDotNet.Extensions;

// Instantiate a new Yolo object with your ONNX-model and CUDA
using var yolo = new Yolo(@"path\to\your_model.onnx");

// Video options
var options = new VideoOptions
{
    VideoFile = @"path\to\video.mp4",
    OutputDir = @"path\to\output\folder",
    //GenerateVideo = true,
    //DrawLabels = true,
    //FPS = 30,
    //Width = 640, // Resize video...
    //Height = -2, // -2 automatically calculate dimensions to keep proportions
    //Quality = 28,
    //DrawConfidence = true,
    //KeepAudio = true,
    //KeepFrames = false,
    //DrawSegment = DrawSegment.Default,
    //PoseOptions = MyPoseMarkerConfiguration // Your own pose marker configuration...
};

// Run
var results = yolo.RunClassification(options, 5); // Top 5 classes
//var results = yolo.RunObjectDetection(options, 0.25);
//var results = yolo.RunObbDetection(options, 0.25);
//var results = yolo.RunSegmentation(options, 0.25);
//var results = yolo.RunPoseEstimation(options, 0.25);

// Do further processing with 'results'...

GPU

Object detection with GPU and GPU-Id = 0 is enabled by default

// Default setup. GPU with GPU-Id 0
using var yolo = new Yolo(@"path\to\model.onnx");

Allocate GPU memory for faster initial inference (disabled by default)

// With CUDA and Allocated GPU memory
using var yolo = new Yolo(@"path\to\model.onnx", primeGpu: true);

With a specific GPU-Id

// GPU with a user defined GPU-Id
using var yolo = new Yolo(@"path\to\model.onnx", gpuId: 1);

CPU

YoloDotNet detection with CPU

// With CPU
using var yolo = new Yolo(@"path\to\model.onnx", false);

Custom Pose-marker configuration

Example on how to configure PoseOptions for a Pose Estimation model

// Pass in a PoseOptions parameter to the Draw() extension method. Ex:
image.Draw(poseEstimationResults, poseOptions);

Access ONNX metadata and labels

The internal ONNX metadata such as input & output parameters, version, author, description, date along with the labels can be accessed via the yolo.OnnxModel property.

Example:

using var yolo = new Yolo(@"path\to\model.onnx");

// ONNX metadata and labels resides inside yolo.OnnxModel
Console.WriteLine(yolo.OnnxModel);

Example:

// Instantiate a new object
using var yolo = new Yolo(@"path\to\model.onnx");

// Display metadata
foreach (var property in yolo.OnnxModel.GetType().GetProperties())
{
    var value = property.GetValue(yolo.OnnxModel);
    Console.WriteLine($"{property.Name,-20}{value!}");

    if (property.Name == nameof(yolo.OnnxModel.CustomMetaData))
        foreach (var data in (Dictionary<string, string>)value!)
            Console.WriteLine($"{"",-20}{data.Key,-20}{data.Value}");
}

// Get ONNX labels
var labels = yolo.OnnxModel.Labels;

Console.WriteLine();
Console.WriteLine($"Labels ({labels.Length}):");
Console.WriteLine(new string('-', 58));

// Display
for (var i = 0; i < labels.Length; i++)
    Console.WriteLine($"index: {i,-8} label: {labels[i].Name,20} color: {labels[i].Color}");

// Output:

// ModelType           ObjectDetection
// InputName           images
// OutputName          output0
// CustomMetaData      System.Collections.Generic.Dictionary`2[System.String,System.String]
//                     date                2023-11-07T13:33:33.565196
//                     description         Ultralytics YOLOv8n model trained on coco.yaml
//                     author              Ultralytics
//                     task                detect
//                     license             AGPL-3.0 https://ultralytics.com/license
//                     version             8.0.202
//                     stride              32
//                     batch               1
//                     imgsz               [640, 640]
//                     names               {0: 'person', 1: 'bicycle', 2: 'car' ... }
// ImageSize           Size [ Width=640, Height=640 ]
// Input               Input { BatchSize = 1, Channels = 3, Width = 640, Height = 640 }
// Output              ObjectDetectionShape { BatchSize = 1, Elements = 84, Channels = 8400 }
// Labels              YoloDotNet.Models.LabelModel[]
//
// Labels (80):
// ---------------------------------------------------------
// index: 0        label: person              color: #5d8aa8
// index: 1        label: bicycle             color: #f0f8ff
// index: 2        label: car                 color: #e32636
// index: 3        label: motorcycle          color: #efdecd
// ...

Donate

https://paypal.me/nickswardh

References & Acknowledgements

https://github.com/ultralytics/ultralytics

https://github.com/sstainba/Yolov8.Net

https://github.com/mentalstack/yolov5-net