專案目標

• 深度學習推論：如何在生產環境中運行預訓練的 AI 模型
• Rust 語言：使用現代系統程式語言進行高效能計算
• ONNX Runtime：業界標準的模型推論引擎
• 物件偵測：YOLO 系列模型的實際應用

支援的 YOLO 任務類型

• 物件偵測 (Object Detection) - 識別並定位圖像中的物體
• 姿勢估計 (Pose Estimation) - 偵測人體關鍵點
• 實例分割 (Instance Segmentation) - 精確的物體輪廓提取
• 圖像分類 (Classification) - 圖像內容分類

效能優化特性

• 多種執行後端：CPU、CUDA GPU、TensorRT 加速
• 批次處理 (Batch Processing) - 同時處理多張圖像
• 動態形狀 (Dynamic Shapes) - 支援不同輸入尺寸
• 半精度支援 (FP16) - 更快的推論速度

架構設計

模組結構

src/
├── lib.rs              # 主要公開 API
├── main.rs             # 示範應用程式
├── model.rs            # YOLOv8 模型核心邏輯
├── ort_backend.rs      # ONNX Runtime 後端整合
├── yolo_result.rs      # 結果資料結構
├── config.rs           # 配置管理
├── nms.rs             # 非極大值抑制演算法
└── color.rs           # 可視化色彩工具

處理流程

graph TD
    A[輸入影像] --> B[前處理]
    B --> C[模型推論]
    C --> D[後處理]
    D --> E[NMS 過濾]
    E --> F[結果輸出]

1. 前處理：調整影像尺寸、色彩空間轉換、標準化
2. 模型推論：使用 ONNX Runtime 執行神經網路
3. 後處理：解析模型輸出、座標轉換
4. NMS 過濾：移除重疊的偵測框

依賴套件說明

使用教學

基本使用範例

use ort_tutorial::YOLOv8;
use ort_tutorial::config;

// 建立配置
let config = config::Config {
    model: "model_weight/onnx/version/yolo11s.onnx".to_string(),
    height: 640,
    width: 640,
    conf: 0.3,
    iou: 0.45,
    ..Default::default()
};

// 初始化模型
let mut model = YOLOv8::new(config)?;

// 載入影像
let img = opencv::imgcodecs::imread("test.jpg", opencv::imgcodecs::IMREAD_COLOR)?;

// 執行推論
let results = model.run_mat(&vec![img])?;

// 處理結果
if let Some(result) = results.get(0) {
    if let Some(bboxes) = &result.bboxes {
        println!("偵測到 {} 個物體", bboxes.len());
        for bbox in bboxes {
            println!("類別: {}, 信心度: {:.2}", bbox.id(), bbox.confidence());
        }
    }
}

📹 視訊處理範例

// 開啟視訊檔案
let mut cap = opencv::videoio::VideoCapture::from_file("input.mp4", opencv::videoio::CAP_ANY)?;

// 設定輸出視訊寫入器
let fourcc = opencv::videoio::VideoWriter::fourcc('m', 'p', '4', 'v')?;
let mut writer = opencv::videoio::VideoWriter::new(
    "output.mp4",
    fourcc,
    30.0,
    opencv::core::Size::new(640, 480),
    true,
)?;

// 處理每一幀
let mut frame = opencv::core::Mat::default();
while cap.read(&mut frame)? {
    if frame.empty() { break; }

    // 執行物件偵測
    let results = model.run_mat(&vec![frame.clone()])?;

    // 在影像上繪製結果
    // ... 繪圖程式碼 ...

    // 寫入輸出視訊
    writer.write(&frame)?;
}

YOLOv8 結構體

pub struct YOLOv8 {
    pub engine: OrtBackend,        // ONNX Runtime 引擎
    pub nc: u32,                   // 類別數量
    pub nk: u32,                   // 關鍵點數量
    pub nm: u32,                   // 遮罩數量
    pub height: u32,               // 輸入高度
    pub width: u32,                // 輸入寬度
    pub task: YOLOTask,            // 任務類型
    // ... 其他欄位
}

主要方法

new(config: Config) -> Result<Self>

建立新的 YOLOv8 模型實例。

run_mat(xs: &Vec<Mat>) -> Result<Vec<YOLOResult>>

處理 OpenCV Mat 影像並返回偵測結果。

YOLOResult 結構體

pub struct YOLOResult {
    pub probs: Option<Embedding>,           // 分類機率
    pub bboxes: Option<Vec<Bbox>>,          // 邊界框
    pub keypoints: Option<Vec<Vec<Point2>>>, // 關鍵點
    pub masks: Option<Vec<Vec<u8>>>,        // 分割遮罩
}

邊界框 (Bbox)

pub struct Bbox {
    xmin: f32, ymin: f32,     // 左上角座標
    width: f32, height: f32,  // 寬度和高度
    id: usize,                // 類別 ID
    confidence: f32,          // 信心度分數
}

⚙️ 配置選項

基本配置

pub struct Config {
    pub model: String,        // ONNX 模型檔案路徑
    pub cuda: bool,           // 是否使用 CUDA
    pub height: u32,          // 輸入影像高度
    pub width: u32,           // 輸入影像寬度
    pub device_id: u32,       // GPU 裝置 ID
    pub batch: u32,           // 批次大小
    pub conf: f32,            // 信心度閾值 (0.0-1.0)
    pub iou: f32,             // IoU 閾值 (0.0-1.0)
    pub kconf: f32,           // 關鍵點信心度閾值
    pub window_view: bool,    // 是否顯示視窗
    pub profile: bool,        // 是否啟用效能分析
    // ... 其他選項
}

執行提供者 (Execution Provider)

效能分析

啟用效能分析

let config = config::Config {
    profile: true,  // 啟用效能分析
    // ... 其他配置
};

分析輸出範例

[Model Preprocess]: 2.34ms
[Model Inference]: 15.67ms
[Model Postprocess]: 1.23ms
Total processing time: 19.24ms

可視化功能

自動色彩分配

專案使用 HSV 色彩空間生成鮮豔的隨機色彩，每個類別都會獲得獨特的顏色，並在整個運行過程中保持一致。

use ort_tutorial::color;

// 獲取類別色彩
let color = color::get_class_color(class_id);

支援的繪圖功能

• 邊界框繪製
• 類別標籤顯示
• 關鍵點可視化
• 分割遮罩渲染

技術細節

影像前處理流程

1. 尺寸調整：保持長寬比，填充至目標尺寸
2. 色彩空間轉換：BGR → RGB
3. 正規化：像素值縮放到 [0, 1] 範圍
4. 張量轉換：轉換為神經網路輸入格式

後處理流程

1. 輸出解析：從模型輸出提取邊界框、類別機率
2. 座標轉換：從模型座標系轉換回原始影像座標
3. 信心度過濾：移除低信心度的偵測結果
4. 非極大值抑制：移除重疊的邊界框

記憶體管理

• 使用 ndarray 進行高效能陣列運算
• 支援批次處理減少記憶體分配開銷
• GPU 記憶體與 CPU 記憶體的高效轉換