乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > YOLO_HaiKang 项目使用说明

YOLO_HaiKang 项目使用说明

当前时间： 2026-04-11 13:51:10 更新时间： 2026-04-11 分类：软件教程 评论(0)

YOLO_HaiKang 项目使用说明

YOLO_HaiKang 项目使用说明

本文档说明本 WinForms 项目的主要功能、界面操作、开发与运行环境安装步骤，以及 YOLO 检测在 CPU 与 GPU（CUDA）之间切换时的注意点。

一、项目主要功能

功能模块
说明
海康工业相机
基于海康 MVS SDK（MvCamCtrl.Net）枚举 GigE / USB（含 U3V）设备，打开相机、连续/触发采集、取流并在界面显示。
本地 USB 摄像头
使用 OpenCvSharp VideoCapture 打开默认摄像头（索引 0），在界面显示预览。
海康与本地互斥
同一时刻只使用一种视频源：本地摄像头开启时不可启动海康采集；海康已连接或采集中时不可开本地摄像头。
YOLO 目标检测
集成 YoloDotNet，加载 ONNX 模型，对当前画面做 目标检测（ObjectDetection），在 实时画面 区域叠加检测框。
执行后端选择
支持 CPU 与 CUDA（GPU） 两种 ONNX Runtime 执行提供程序（通过独立 NuGet 包引入）。
相机参数与 ROI
读取/设置曝光、增益、帧率、伽马、像素格式及宽高与偏移等（依赖相机与固件支持的参数）。
图像保存
将当前帧保存为 BMP / JPG；支持“连续采集每一帧”到指定目录（配合录制对话框）。

说明：界面中的「模型类型」「任务类型」下拉框用于后续扩展；当前代码中 仅实现了 ObjectDetection，选择其他任务类型会提示未实现。

二、环境安装需求

2.1 操作系统与运行时

  • Windows 10 / 11（64 位推荐）。
  • .NET 8 SDK（开发与 dotnet build / dotnet run 需要；安装 SDK 即包含运行时）。

2.2 开发工具（任选其一）

  • Visual Studio 2022，工作负载勾选 “.NET 桌面开发”；或
  • Visual Studio Code + C# 扩展 + 已安装的 .NET 8 SDK。

2.3 海康 MVS SDK（必须，用于海康相机）

  • 从海康机器人官网安装 MVS（Machine Vision Software） 或随设备提供的 .NET 开发包。

  • 本工程通过 程序集引用 使用 MvCamCtrl.Net.dll，YOLO_HaiKang.csproj 中默认路径为：

    hkCameraApp/DotNet/AnyCpu/MvCamCtrl.Net.dll

    （相对项目文件为 ..\..\DotNet\AnyCpu\MvCamCtrl.Net.dll。）

  • 若你本机 SDK 安装路径不同：请将 MvCamCtrl.Net.dll（及官方要求的依赖）复制到上述目录，或修改 .csproj 中 <HintPath> 指向实际路径，再重新生成解决方案。

2.4 NuGet 依赖（自动还原）

主要包（版本以 YOLO_HaiKang.csproj 为准）：

  • SunnyUI / SunnyUI.Common：界面控件与主题。
  • OpenCvSharp4 及 OpenCvSharp4.runtime.win：本地摄像头与图像矩阵处理。
  • SkiaSharp：YoloDotNet 绘图与图像管线。
  • YoloDotNet：YOLO 推理封装。
  • YoloDotNet.ExecutionProvider.Cpu / YoloDotNet.ExecutionProvider.Cuda：CPU 与 CUDA 执行提供程序（会拉取对应 Microsoft.ML.OnnxRuntime 等原生依赖）。

无需手动逐个安装；在解决方案目录执行 dotnet restore 即可。

三、安装与编译运行教程

3.1 获取代码并还原包

在仓库根目录或 hkCameraApp 目录下打开终端：

cd hkCameraApp
dotnet restore YOLO_HaiKang.sln

3.2 配置海康 DLL

确认 MvCamCtrl.Net.dll 已按 §2.3 放置或已修改 HintPath。

3.3 编译

dotnet build YOLO_HaiKang.sln -c Release

输出一般在：hkCameraApp/YOLO_HaiKang/bin/Release/net8.0-windows/（具体以生成配置为准）。

3.4 运行

dotnet run --project YOLO_HaiKang/YOLO_HaiKang.csproj -c Release

或在 Visual Studio 中将 YOLO_HaiKang 设为启动项目后按 F5。

3.5 首次运行前检查清单

  1. 海康相机已上电、网线/USB 已连接（若用海康源）。
  2. 已安装相机驱动 / MVS，且设备可在 MVS 客户端中被识别。
  3. 准备 与任务匹配的 YOLO ONNX 模型（见下文 YOLO 小节）。
  4. 若使用 CUDA：已安装匹配的 NVIDIA 驱动（及官方要求的 CUDA/cuDNN，见 §五）。

四、界面分区与各按键 / 控件用法

4.1 相机选择与连接（主界面顶部）

控件
用法
选择相机

（下拉框）
在枚举到的设备列表中选择一台（GigE 显示为 GEV，USB 显示为 U3V）。
查找相机
重新枚举 GigE + USB 设备并刷新下拉列表。
打开相机
打开当前选中的海康设备；成功后方可采集（本地摄像头模式下不可用）。
关闭相机
关闭海康设备；会停止相关采集逻辑并释放资源。

4.2 实时画面

控件
用法
实时画面
显示海康采集或本地摄像头的预览；开启 YOLO 检测 后显示带检测框的结果图（海康模式下由检测线程刷新，避免被原始帧覆盖）。

4.3 采集图像

控件
用法
连续模式 / 触发模式
切换采集模式；触发模式下可配合软触发。
软触发

（复选框）
在触发模式且触发源为软件时启用软触发。
开始采集
启动取流线程并开始抓取图像（需已打开海康相机，且 未 开启本地摄像头）。
停止采集
停止抓取；会停止检测并清空海康侧缓存帧。
软触发一次
在软触发可用时手动触发一帧（具体行为依赖相机触发配置）。

4.4 YOLO 检测

控件
用法
模型类型
预留选项（YOLOv8 / v11 / v12 / v26）；当前推理以 ONNX 模型本身 为准，请保证模型与 YoloDotNet 版本兼容。
任务类型
请选择 ObjectDetection；其他类型当前版本会提示未实现。
执行后端
选择 CPU 或 CUDA（详见 §五）。
模型路径

（旁路按钮）
选择 .onnx 模型文件。
打开本地摄像头
开启默认摄像头；再次点击为关闭。与海康 互斥。
开始检测 / 停止检测
在 已开始海康采集 或 本地摄像头已运行 且有帧时启动循环检测；再次点击停止。

4.5 相机参数与 ROI

控件
用法
获取参数
从相机读取曝光、增益、帧率等及 ROI 相关参数到文本框。
设置参数
将文本框中的值写入相机（受相机能力限制）。
曝光 / 增益 / 帧率 / 伽马 / 像素格式
显示或编辑对应参数。
宽度 / 高度 / 水平偏移 / 垂直偏移
ROI 相关；部分状态下控件为只读，需先停止采集等再调整（以界面启用状态为准）。

4.6 数据保存

控件
用法
路径

（旁路按钮）
选择保存目录。
保存 BMP / 保存 JPG
将当前缓存的一帧保存到上述路径（需处于可保存状态）。
连续采集每一帧
弹出录制对话框，开始连续将帧保存为 BMP（用于连拍类场景）；结束按对话框提示操作。

4.7 录制对话框（RecordForm）

控件
用法
开始
开始计时并开始连续采帧逻辑。
停止
停止计时与采帧。

五、YOLO 检测：CPU 与 GPU（CUDA）切换

5.1 重要原则（请务必遵守）

  1. 不要混用执行提供程序
    本项目中，CPU 使用 CpuExecutionProvider，GPU 使用 CudaExecutionProvider。切换 执行后端 后，内部会按需要 重新创建 Yolo 引擎；建议在 停止检测 后再切换，然后重新开始检测，避免会话与原生 DLL 状态异常。

  2. 先选后端，再开始检测
    在点击 开始检测 前，在 执行后端 下拉框中选定 CPU 或 CUDA。运行中若切换，请 停止检测 → 改后端 → 再开始检测。

  3. 模型与任务
    必须使用与 目标检测 兼容的 ONNX；任务类型请选择 ObjectDetection。

  4. 进程架构与 CUDA
    ONNX Runtime 的 CUDA 原生库在 Windows 上通常为 x64。请使用 64 位进程 运行本程序（本仓库默认 PlatformTarget 为 AnyCPU，在 64 位系统上一般为 64 位进程）。若你强制 x86 仅生成 32 位程序，CUDA 推理很可能不可用。

5.2 CPU 模式

  • 优点：无 NVIDIA 显卡亦可运行；环境简单。
  • 缺点：同分辨率下速度通常慢于 GPU。
  • 环境要求：安装 .NET 8 与 OpenCvSharp 等托管依赖即可，无需 CUDA。

5.3 GPU（CUDA）模式 — 环境要求

GPU 路径依赖 ONNX Runtime 的 CUDA Execution Provider 及本机 NVIDIA 驱动 与 CUDA/cuDNN 等原生库。当前工程通过 NuGet 引入的依赖链中会使用 Microsoft.ML.OnnxRuntime 1.23.x 系列（具体以还原后的 project.assets.json / 实际包版本为准）。

NuGet 包里的 onnxruntime_providers_cuda.dll不会自带完整的 NVIDIA 数学库；cublasLt64_12.dll 等文件来自本机安装的 CUDA Toolkit 12.x（文件名中的 12 表示 CUDA 12 系列）。因此仅安装显卡驱动、或只装旧版 CUDA 11，都会出现加载失败。

建议准备：

项目
说明
NVIDIA 显卡
支持 CUDA 的 GeForce / RTX / Quadro 等。
显卡驱动
安装 较新 的 Studio 或 Game Ready 驱动，版本需 满足 你所安装的 CUDA 工具包的要求。
CUDA Toolkit 12.x
从 NVIDIA CUDA Toolkit 下载页 安装与 ORT 匹配的 CUDA 12 大版本（例如 12.4、12.6 等，以 ONNX Runtime 发布说明为准）。安装后 cublasLt64_12.dll 通常位于：C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x\bin\。
PATH
将上述 bin 目录 加入 用户或系统环境变量 PATH，保存后 重新打开 Visual Studio / 终端再运行程序；否则进程仍找不到 DLL。
cuDNN
部分场景还需安装与 CUDA 版本匹配的 cuDNN，并把其中 bin 一并加入 PATH（若报错指向 cudnn64_*.dll 再处理）。
对齐官方文档
安装前请打开 ONNX Runtime CUDA 执行提供程序说明 与 兼容性说明，按 与你本机 onnxruntime / Microsoft.ML.OnnxRuntime.* 版本一致 的条目准备环境。

5.3.1 典型错误：cublasLt64_12.dll 缺失（Error 126）

若异常类似：

Error loading "... onnxruntime_providers_cuda.dll" which depends on "cublasLt64_12.dll" which is missing. (Error 126: "找不到指定的模块。")

处理步骤：

  1. 安装 CUDA Toolkit 12.x（完整安装或至少包含 CUDA Runtime / 开发库 中与 cuBLAS 相关的组件）。
  2. 确认文件存在：在资源管理器中打开
    C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x\bin\
    搜索 cublasLt64_12.dll。
  3. 将该 bin 路径 加入系统 PATH，注销或重启 IDE 后再运行。
  4. 若暂时无法安装 CUDA：在界面中将 执行后端 改为 CPU，即可正常推理（速度可能较慢）。

说明： 不要把 CUDA 的 bin 里的 DLL 随意复制到程序 bin 目录代替安装——容易缺其它依赖链（如 cudart64_12.dll 等）。优先使用官方安装 + PATH。

常见问题：

  • 选择 CUDA 后程序报错或回退：多为 未安装 CUDA 12 Toolkit、PATH 未包含 v12.x\bin、驱动/CUDA/cuDNN 版本不匹配、或 以 32 位进程运行。

  • 本机装有多个 CUDA：确保 与 ORT 匹配的v12.x\bin 在 PATH 中优先，或使用官方推荐的部署方式。

  • 常见报错：Microsoft.ML.OnnxRuntime.OnnxRuntimeException:“[ErrorCode:Fail] E:_work\1\s\onnxruntime\core\session\provider_bridge_ort.cc:1844 onnxruntime::ProviderLibrary::Get [ONNXRuntimeError] : 1 : FAIL : Error loading “C:\Users\du\Desktop\hkCameraApp-main\hkCameraApp\YOLO_HaiKang\bin\Debug\net8.0-windows\runtimes\win-x64\native\onnxruntime_providers_cuda.dll” which depends on “cublasLt64_12.dll” which is missing. (Error 126: “找不到指定的模块。”) 

  • 解决办法（推荐） 安装 NVIDIA CUDA Toolkit 12.x（任选 12.4、12.6 等与当前驱动兼容的版本，需为 12.x）。 安装后确认存在类似路径下的文件： C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x\bin\cublasLt64_12.dll 把该目录 …\CUDA\v12.x\bin 加到 系统或用户环境变量 PATH，保存后 关掉并重新打开 Visual Studio / 终端，再运行程序。 若 ONNX Runtime 还要求 cuDNN，需按 ONNX Runtime CUDA EP 文档 安装对应版本，并把 cuDNN 的 bin 也加入 PATH（若后续报错指向 cudnn64_*.dll 再处理）。 临时绕过： 在程序里把 执行后端 选 CPU，不依赖 CUDA，即可先跑通检测。

5.4 验证 GPU 是否可用（建议）

在能正常安装 CUDA EP 依赖的机器上：选择 CUDA、有效 ONNX、开始检测，观察是否持续推理且无原生库加载错误。若失败，请根据异常信息对照 ONNX Runtime 文档检查驱动与 CUDA/cuDNN。

六、其他说明

  • 标题栏：运行检测时可能会显示简易性能信息（采集 / 推理 / 渲染等），停止检测后恢复标题。
  • 性能与分辨率：检测链路会对图像做缩放以平衡速度；界面显示会尽量与原始画幅对齐，具体以当前代码为准。
  • 技术支持与文档：海康相机参数与错误码请参考 MVS 开发文档；YOLO 与 ONNX Runtime 请参考 YoloDotNet 与 ONNX Runtime 官方文档。