# 博诺思 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 数组。