LTW.YoloDotNet.Core 4.2.1-AotFix.1

<img src="https://github.com/NickSwardh/YoloDotNet/assets/35733515/994287a9-556c-495f-8acf-1acae8d64ac0" height=24> YoloDotNet v4.2 🚀

面向 .NET 的超快、可用于生产环境的 YOLO 推理库

YoloDotNet 是一个模块化、轻量级的 C# 库，用于在 .NET 中进行实时计算机视觉与 YOLO 推理。

它为现代 YOLO 模型家族（YOLOv5u 到 YOLOv26、YOLO-World、YOLO-E、RT-DETR）提供高性能推理，并对执行、内存和预处理提供显式控制。

YoloDotNet 构建于 .NET 8、ONNX Runtime 与 SkiaSharp 之上，有意避免 OpenCV 这类重量级计算机视觉框架。
不依赖 Python 运行时、无隐藏预处理、无隐式行为——仅保留在 Windows / Linux / macOS 上实现快速、可预测推理所需的组件。

没有 Python。没有魔法。只有适用于 .NET 的高性能、确定性 YOLO 推理。

⭐ 为什么选择 YoloDotNet？

YoloDotNet 专为以下需求而设计：

• ✅ 纯 .NET —— 无 Python 运行时、无脚本依赖
• ✅ 真实性能 —— 支持 CPU、CUDA / TensorRT、OpenVINO、CoreML、DirectML
• ✅ 显式配置 —— 准确率与内存使用可预测
• ✅ 生产可用 —— 引擎缓存、长时间运行稳定
• ✅ 多视觉任务 —— 检测、OBB、分割、姿态、分类

非常适合需要确定性行为与完全控制的 桌面应用、后端服务与实时视觉流水线。

🆕 v4.2 新特性

• 新增 ROI（感兴趣区域） 支持，可仅对图像或视频流中的指定区域进行推理
  （适用于监控场景、区域告警与性能优化流水线）
• 新增 分割对象边缘绘制 选项，提升可视化清晰度
• 新增 JSON 导出辅助方法：
  • ToJson() —— 将推理结果转换为 JSON
  • SaveJson() —— 将推理结果直接保存为 JSON 文件
• 新增 YOLO 标注格式辅助方法：
  • ToYoloFormat() —— 将结果转换为 YOLO 标注格式
  • SaveYoloFormat() —— 将结果保存为 YOLO 训练数据格式
• 新增 GetContourPoints()，用于提取分割对象的有序轮廓点
• 更新 YOLOv26 推理执行流程，与其他任务对齐，提升一致性与整体执行效率

📖 完整版本历史见：CHANGELOG.md

🚀 快速开始

💡 ONNX 模型导出要求

• YOLOv26 模型请使用 opset=18 导出
• YOLOv5u–YOLOv12 模型请使用 opset=17 导出

示例导出命令（Ultralytics CLI）：

# YOLOv5u–YOLOv12（opset 17）
yolo export model=yolov8n.pt format=onnx opset=17

# YOLOv26（opset 18）
yolo export model=yolo26n.pt format=onnx opset=18

1️⃣ 安装核心包

dotnet add package YoloDotNet

2️⃣ 安装 且仅安装一个 执行器包

# CPU（推荐起点）
dotnet add package YoloDotNet.ExecutionProvider.Cpu

# 硬件加速执行（任选其一）
dotnet add package YoloDotNet.ExecutionProvider.Cuda
dotnet add package YoloDotNet.ExecutionProvider.OpenVino
dotnet add package YoloDotNet.ExecutionProvider.CoreML
dotnet add package YoloDotNet.ExecutionProvider.DirectML

💡 说明： CUDA 执行器已包含可选 TensorRT 加速能力。
无需额外安装单独的 TensorRT NuGet 包。

3️⃣ 运行目标检测

using SkiaSharp;
using YoloDotNet;
using YoloDotNet.Models;
using YoloDotNet.Extensions;
using YoloDotNet.ExecutionProvider.Cpu;

using var yolo = new Yolo(new YoloOptions
{
    ExecutionProvider = new CpuExecutionProvider("model.onnx")
});

using var image = SKBitmap.Decode("image.jpg");

// 说明：IoU 参数用于基于 NMS 的模型。
// 对于 YOLOv10 和 YOLOv26，由于后处理由模型内部完成，IoU 会被忽略。
var results = yolo.RunObjectDetection(image, confidence: 0.25, iou: 0.7);

image.Draw(results);
image.Save("result.jpg");

你现在已经在 纯 C# 环境中运行 YOLO 推理了。

💡 重要提示：准确率取决于配置

YOLO 推理的准确率不是自动保证的。

图像缩放模式、采样方法、置信度/IoU 阈值等预处理设置，必须与模型训练时配置保持一致。
这些参数直接决定准确率与性能的平衡，应视为模型的一部分。

📖 在调参或对比结果前，请先阅读：
👉 Accuracy & Configuration Guide

支持的任务

✅ 已验证的 YOLO 模型

下列 YOLO 模型已基于 Ultralytics 官方导出与默认 head，在 YoloDotNet 中完成测试与验证。

📁 示例项目

Demo 目录提供可直接动手运行的示例：

👉 浏览 Demo 项目

覆盖图像推理、视频流、GPU 加速、分割以及大图处理等场景。

执行器支持

ℹ️ 只能引用 一个 执行器包。
混用多个执行器会导致本机运行时冲突。

⚡ 性能特征

YoloDotNet 聚焦于稳定、低开销推理，运行成本主要由执行器与模型本身决定。

📊 基准测试：/test/YoloDotNet.Benchmarks

• 预热后延迟稳定
• CPU → GPU → TensorRT 线性扩展清晰
• 内存分配行为可预测
• 适用于实时与长时间运行服务

🚀 模块化执行器架构

• 核心包与执行器解耦
• 执行器以独立 NuGet 包提供
• ONNX Runtime 本机依赖隔离

价值： 减少冲突、部署可预测、生产环境更安全稳定。

支持 YoloDotNet

⭐ 点亮 Star
💬 反馈建议
🤝 赞助项目开发

GitHub Sponsors
PayPal

许可证

MIT License

Copyright (c) Niklas Swärd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

模型许可证与责任说明

• YoloDotNet 采用 MIT License，并提供用于运行由 Ultralytics 工具导出的 YOLO ONNX 模型的推理引擎。

• 本项目不内置、分发、下载或捆绑任何预训练模型。

• 用户需自行提供 ONNX 模型。

• 使用 Ultralytics 工具生成的 YOLO ONNX 模型，通常受 AGPL-3.0 或 Ultralytics 单独商业许可证约束。

• YoloDotNet 不会对用户提供模型的许可条款进行附加、修改或转移。

• 用户需自行负责确保所用模型符合相关许可证条款，包括商业使用、分发或网络部署等要求。