# YOLO11 推理类 API 文档

## 概述

该类封装了 `YOLO11` 模型的完整推理流程，包含：

* 图像预处理
* 模型推理
* 结果后处理
* 检测结果可视化

支持 **目标检测、语义分割、分类、旋转框检测** 四种任务类型。该类依赖于 `K230_KPU` 和 `K230_AI2D` 模块实现，对 `YOLO11` 模型在 `K230/K230D` 上部署做了封装。

## API 介绍

### 构造方法 `Yolo11()`

加载 YOLO11 模型文件、初始化输入输出张量、并配置检测参数。

```cpp
Yolo11(std::string task_type,
       std::string task_mode,
       std::string kmodel_file,
       FrameSize image_wh,
       std::vector<std::string> labels,
       float conf_thres = 0.5f,
       float nms_thres = 0.5f,
       float mask_thres = 0.5f,
       int debug_mode = 0);
```

**参数**

| 参数名           | 类型                         | 说明                                                                |
| ------------- | -------------------------- | ----------------------------------------------------------------- |
| `task_type`   | `std::string`              | 任务类型：`"classify"`（分类）、`"detect"`（检测）、`"segment"`（分割）、`"obb"`（旋转框） |
| `task_mode`   | `std::string`              | 模式类型：`"video"`（视频流）或 `"image"`（单张图像）                              |
| `kmodel_file` | `std::string`              | KModel 模型文件路径                                                     |
| `image_wh`    | `FrameSize`                | 原始输入图像的宽高                                                         |
| `labels`      | `std::vector<std::string>` | 类别标签列表                                                            |
| `conf_thres`  | `float`                    | 置信度阈值（默认 0.5）                                                     |
| `nms_thres`   | `float`                    | 非极大值抑制阈值（默认 0.5）                                                  |
| `mask_thres`  | `float`                    | 分割任务掩码阈值（默认 0.5）                                                  |
| `debug_mode`  | `int`                      | 调试等级：0=关闭，1=打印耗时，2=打印详细日志                                         |

**返回值**

`Yolo`类实例。

### 析构函数 `~Yolo11()`

释放模型加载、预处理、推理等过程中分配的所有资源，确保内存安全。

```cpp
~Yolo11();
```

**参数**

无

**返回值**

无

### 预处理方法 `pre_process`

对输入图像执行预处理操作，包括尺寸变换、通道格式转换、填充等。预处理完成后，结果将被写入模型输入张量中。

```cpp
void pre_process(runtime_tensor &input_tensor);
```

**参数**

| 参数名            | 类型                 | 说明                    |
| -------------- | ------------------ | --------------------- |
| `input_tensor` | `runtime_tensor &` | 输入图像创建的张量，用于后续的预处理过程 |

**返回值**

无

### 模型推理方法 `inference`

执行 `YOLO11` 模型推理，将预处理后的输入数据送入 KPU（神经网络加速单元）进行计算。该接口执行完成后可直接调用后处理接口获取结果。

```cpp
void inference();
```

**参数**

无

**返回值**

无

### 后处理方法 `post_process`

对模型的原始输出进行解码与筛选，根据任务的不同实现不同的处理，包括：

* 分类任务中根据处理分类结果和置信度；
* 检测任务重提取每个检测框的置信度与类别，应用置信度阈值与 NMS（Non-Maximum Suppression）过滤，生成最终检测结果（边界框 + 类别 + 置信度）；
* 分割任务中提取每个检测框位置、类别置信度和mask图像；
* 旋转目标检测任务中提取检测框和旋转角度；

```cpp
void post_process(std::vector<YOLOBbox> &yolo_results);
```

**参数**

| 参数名            | 类型                        | 说明          |
| -------------- | ------------------------- | ----------- |
| `yolo_results` | `std::vector<YOLOBbox> &` | 用于保存检测结果的向量 |

**返回值**

无

### 结果绘制方法 `draw_results`

在输入图像上绘制检测结果，包括：

* 边界框
* 类别标签文字
* 置信度数值
* mask图像

常用于实时视频流显示或结果可视化输出。

```cpp
void draw_results(cv::Mat &draw_frame, std::vector<YOLOBbox> &yolo_results);
```

**参数**

| 参数名            | 类型                        | 说明           |
| -------------- | ------------------------- | ------------ |
| `draw_frame`   | `cv::Mat &`               | 要绘制检测结果的图像帧  |
| `yolo_results` | `std::vector<YOLOBbox> &` | 后处理得到的检测框结果集 |

### 集成方法 `run`

单个方法实现，包含预处理、推理、后处理和结果绘制。

```cpp
void run(runtime_tensor &input_tensor, std::vector<YOLOBbox> &yolo_results);
```

**参数**

| 参数名            | 类型                        | 说明          |
| -------------- | ------------------------- | ----------- |
| `input_tensor` | `runtime_tensor &` | 输入图像创建的张量，用于后续的预处理过程 |
| `yolo_results` | `std::vector<YOLOBbox> &` | 后处理得到的检测框结果集 |

**返回值**

无

## 私有成员变量

该类包含的私有成员变量及其类型说明如下表所示：

| 成员变量                  | 类型                         | 说明                                                      |
| --------------------- | -------------------------- | ------------------------------------------------------- |
| `model_input_tensor_` | `runtime_tensor`           | 模型输入张量（由 AI2D 预处理输出，用于推理输入）                             |
| `task_type_`          | `std::string`              | 当前任务类型（如 `cls` 分类 / `det` 检测 / `seg` 分割 / `obb` 旋转框检测） |
| `task_mode_`          | `std::string`              | 当前任务模式（如 `video` 实时视频 / `image` 静态图像）                   |
| `labels_`             | `std::vector<std::string>` | 类别标签列表                                                  |
| `label_num_`          | `int`                      | 类别数量                                                    |
| `colors`              | `std::vector<cv::Scalar>`  | 绘制检测框或分割掩码时使用的颜色表                                       |
| `image_wh_`           | `FrameSize`                | 原始输入图像的宽高尺寸                                             |
| `input_wh_`           | `FrameSize`                | 模型输入张量对应的标准尺寸（AI2D resize 输出）                           |
| `conf_thres_`         | `float`                    | 置信度阈值（低于此值的检测结果将被过滤）                                    |
| `nms_thres_`          | `float`                    | 非极大值抑制（NMS）阈值，用于去除冗余检测框                                 |
| `mask_thres_`         | `float`                    | 分割任务的掩码二值化阈值                                            |
| `box_num_`            | `int`                      | 当前帧检测到的目标框数量                                            |
| `max_box_num_`        | `int`                      | 允许的最大检测框数量（用于内存预分配）                                     |
| `box_feature_len_`    | `int`                      | 每个检测框对应的特征维度长度               |
| `debug_mode_`         | `int`                      | 调试模式等级（0-关闭 / 1-基础输出 / 2-详细输出）                        |
| `kpu`                 | `KPU*`                     | KPU推理单元实例指针                   |
| `ai2d_yolo`           | `AI2D*`                    | AI2D 图像预处理模块实例指针，用于模型输入 resize / padding                |
