90 lines
2.8 KiB
Markdown
90 lines
2.8 KiB
Markdown
# 博诺思 YOLO SDK v2.0.0
|
||
|
||
## 简介
|
||
|
||
本SDK提供了一个使用ONNX Runtime和OpenCV进行YOLO实时目标检测的C++动态链接库。
|
||
|
||
v2.0.0版本引入了有状态的API，通过创建持久化的 `detector` 句柄，极大提升了批量处理性能并解决了线程安全问题。
|
||
|
||
## API 接口 (v2.0 - 高性能API - 推荐)
|
||
|
||
推荐用于批量处理、多线程和Web服务。模型只在创建时加载一次。
|
||
|
||
```cpp
|
||
/**
|
||
@brief 用来接受检测后结果的结构体
|
||
*/
|
||
struct Detection {
|
||
int class_id;
|
||
float score;
|
||
int x;
|
||
int y;
|
||
int width;
|
||
int height;
|
||
};
|
||
|
||
/**
|
||
* @brief [v2.0 新增] 创建一个检测器实例 (有状态)
|
||
* @details 此函数加载ONNX模型并初始化Session，返回一个句柄。
|
||
* @param model_path ONNX模型的绝对路径
|
||
* @param input_width 模型输入宽度 (例如 640)
|
||
* @param input_height 模型输入高度 (例如 640)
|
||
* @return void* 指向检测器实例的句柄。如果失败则返回 nullptr。
|
||
*/
|
||
void* create_detector(
|
||
const wchar_t* model_path,
|
||
int input_width,
|
||
int input_height
|
||
);
|
||
|
||
/**
|
||
* @brief [v2.0 新增] 释放由 create_detector 创建的检测器实例
|
||
* @param detector_handle 要释放的句柄
|
||
*/
|
||
void free_detector(void* detector_handle);
|
||
|
||
/**
|
||
* @brief [v2.0 新增] 使用已加载的检测器执行检测 (线程安全)
|
||
* @details
|
||
* @param detector_handle 由 create_detector 返回的句柄
|
||
* @param image_bytes 指向图像数据(BGR格式)的指针
|
||
* @param image_width 图像宽度
|
||
* @param image_height 图像高度
|
||
* @param out_detections [输出] Detection结构体数组指针，函数会为其分配内存
|
||
* @param out_detections_count [输出] 检测到的物体数量
|
||
* @param conf_threshold 置信度阈值
|
||
* @param iou_threshold NMS的IOU阈值
|
||
* @return int 0表示成功
|
||
*/
|
||
int perform_detection_on_session(
|
||
void* detector_handle,
|
||
unsigned char* image_bytes,
|
||
int image_width,
|
||
int image_height,
|
||
Detection** out_detections,
|
||
int* out_detections_count,
|
||
float conf_threshold,
|
||
float iou_threshold
|
||
);
|
||
|
||
⚠️ 关键参数 (重要!)
|
||
模型输入尺寸 (input_width, input_height):
|
||
|
||
这是调用 create_detector 时最关键的参数。
|
||
|
||
您必须提供ONNX模型训练和导出时所用的尺寸（例如 640x640 或 1280x1280）。
|
||
|
||
如果此参数错误，将导致检测结果完全错误。
|
||
|
||
图像数据格式 (image_bytes):
|
||
|
||
SDK的所有函数（..._on_session 和 draw_and_encode_image）均需要 BGR 格式的图像字节（cv::imread 默认格式）。
|
||
|
||
SDK内部在推理时会自动处理BGR到RGB的转换。
|
||
|
||
类别名称 (class_names):
|
||
|
||
SDK本身是类别无关的，它只返回 class_id (整数)。
|
||
|
||
调用者在调用 draw_and_encode_image 时，必须提供一个与模型元数据（如 {"qd", "fl", "zw"}）顺序完全一致的 class_names 数组。
|