# YOLO Application Guide

```{attention}
YOLO deployment code uses the same single-camera dual-channel development pattern. Refer to [single_model_example.md](./single_model_example.md) for the core application logic.
```

## Overview

K230 provides a unified wrapper for the YOLO family and supports **YOLOv5, YOLOv8, and YOLO11**. It covers four mainstream visual tasks:

- image classification (`classify`)
- object detection (`detect`)
- instance segmentation (`segment`)
- oriented object detection (`obb`, supported by YOLOv8 and YOLO11)

Users can switch model types through parameters and choose the input mode according to the application scenario (`video` or `image`). Custom AI-frame resolutions are also supported so that model performance, speed, and accuracy can be tuned during deployment.

## Model Conversion

For model training and conversion to `kmodel`, refer to the official workflow in **YOLO Battle Guide**:

[YOLO Battle Guide](https://www.kendryte.com/k230_canmv/zh/main/zh/example/ai/YOLO%E5%A4%A7%E4%BD%9C%E6%88%98.html#)

After following that guide, the generated YOLO `kmodel` files can be used directly with the functions and examples described on this page.

## YOLO Support

The YOLO source code is located at:

```bash
src/rtsmart/examples/ai/yolo
```

The code wraps the camera and display parts of AI inference, so the user mainly needs to obtain inference frames and pass them to the YOLO model interfaces.

### Code Structure

```text
YOLO
├── cmake
├── src
│   ├── ai_base.cc
│   ├── ai_base.h
│   ├── main.cc
│   ├── pipeline.cc
│   ├── pipeline.h
│   ├── scoped_timing.hpp
│   ├── utils.cc
│   ├── utils.h
│   ├── yolo11.cc
│   ├── yolo11.h
│   ├── yolov5.cc
│   ├── yolov5.h
│   ├── yolov8.cc
│   ├── yolov8.h
│   └── CMakeLists.txt
├── utils
├── Makefile
├── CMakeLists.txt
└── build_app.sh
```

### Code Notes

| File | Purpose |
| --- | --- |
| `ai_base.h` | interfaces used during model inference |
| `ai_base.cc` | implementation of the common inference wrapper |
| `scoped_timing.hpp` | timing helper for debugging |
| `pipeline.h` | media wrapper for display, video output, camera capture, OSD initialization, frame get/release/insert, and pipeline destruction |
| `pipeline.cc` | implementation of the media wrapper |
| `utils.h` | helper interfaces for binary-file reading, image saving, preprocessing configuration, and shared utilities |
| `utils.cc` | implementation of the helper functions |
| `yolo11.h/.cc` | YOLO11 initialization, preprocess, inference, postprocess, and draw interfaces |
| `yolov5.h/.cc` | YOLOv5 initialization, preprocess, inference, postprocess, and draw interfaces |
| `yolov8.h/.cc` | YOLOv8 initialization, preprocess, inference, postprocess, and draw interfaces |
| `main.cc` | main entry and application flow |

The `utils` directory contains example models and images used for board deployment, and `build_app.sh` is the build script.

## Build

### Select Board and Build Application

From the RTOS root:

```bash
make list-def
make ***_defconfig
make -j
```

### Build Method 1

After the code is ready, enter the directory containing `build_app.sh` and run:

```bash
./build_app.sh
```

The build intermediates are placed in `build`, and the deployment summary files are placed in `k230_bin`.

### Build Method 2

From the RTOS SDK root, run `make menuconfig` and enable:

```text
RT-Smart UserSpace Examples Configuration
-> Enable build ai examples
-> Enable Build YOLO Programs
```

Then run:

```bash
make -j
```

This builds the deployment outputs directly into:

```text
/sdcard/app/examples/ai/yolo
```

You can also enter the example directory and run:

```bash
make -j
```

This also supports incremental build and places outputs in `k230_bin`.

## Runtime Parameters

| Parameter | Default | Description |
| --- | --- | --- |
| `-ai_frame_width` | `640` | AI-frame width |
| `-ai_frame_height` | `360` | AI-frame height |
| `-display_mode` | `0` | display mode: `0=LT9611`, `1=ST7701`, `2=HX8377` |
| `-model_type` | `yolov8` | model type: `yolov5`, `yolov8`, `yolo11` |
| `-task_type` | `detect` | task type: `classify`, `detect`, `segment`, `obb` |
| `-task_mode` | `video` | task mode: `image` or `video` |
| `-image_path` | `test.jpg` | image path for image mode |
| `-kmodel_path` | `yolov8n.kmodel` | model path |
| `-labels_txt_filepath` | `coco_labels.txt` | label file, one label per line |
| `-conf_thres` | `0.35` | confidence threshold |
| `-nms_thres` | `0.65` | NMS threshold |
| `-mask_thres` | `0.5` | mask threshold |
| `-debug_mode` | `0` | debug mode, `0` or `1` |

## Run Examples

Flash the firmware first. See:

[how_to_flash](../../userguide/how_to_flash.md)

Then copy the generated `.elf`, `kmodel`, test images, and related files from `k230_bin` to `CanMV/sdcard`.

Connect to the board through a serial console. You can run `yolo.elf -help` to view the parameter list.

### Video Inference

```bash
# equivalent helper: ./video_run.sh
./yolo.elf -ai_frame_width 640 -ai_frame_height 360 -display_mode 0 -model_type yolov8 -task_type detect -task_mode video -kmodel_path yolov8n.kmodel -labels_txt_filepath coco_labels.txt -conf_thres 0.35 -nms_thres 0.65 -mask_thres 0.5 -debug_mode 0
```

### Image Inference

```bash
# equivalent helper: ./image_run.sh
./yolo.elf -model_type yolov8 -task_type detect -task_mode image -image_path test.jpg -kmodel_path yolov8n.kmodel -labels_txt_filepath coco_labels.txt -conf_thres 0.35 -nms_thres 0.65 -mask_thres 0.5 -debug_mode 0
```

During deployment, you can change the model, AI-frame resolution, task type, task mode, and thresholds as needed.

## Notes

- Supported models: `yolov5`, `yolov8`, `yolo11`
- Supported task types: `classify`, `detect`, `segment`, `obb`
- Supported task modes: `video`, `image`
- Supported display modes: `LT9611`, `ST7701`, `HX8377`
- For tuning, first adjust thresholds, then revisit quantization and input resolution
- If the AI-frame resolution matches the model input resolution, runtime speed is usually better optimized