cvui 組件使用指南

cvui 是一個基於 OpenCV 繪圖原語的輕量級 UI 庫。

基本使用流程

#define CVUI_IMPLEMENTATION
#include "cvui.h"

#define WINDOW_NAME "Demo"

int main() {
    cv::Mat frame = cv::Mat(600, 800, CV_8UC3);
    cvui::init(WINDOW_NAME);

    while (true) {
        frame = cv::Scalar(49, 52, 49);  // 清空畫布

        // 添加 UI 組件...

        cvui::update();   // 更新交互
        cv::imshow(WINDOW_NAME, frame);

        if (cv::waitKey(20) == 27) break;
    }

    return 0;
}

組件列表

1. text - 文本顯示

cvui::text(frame, x, y, "Hello", 0.4, 0xCECECE);

參數

説明

frame

目標畫布

x, y

位置座標

text

文字內容

fontScale

字體大小（默認 0.4）

color

顏色（0xBBGGRR 格式）

2. button - 按鈕

// 簡單按鈕
if (cvui::button(frame, 50, 50, "Click me")) {
    // 按鈕被點擊時執行
}

// 自定義大小
if (cvui::button(frame, 50, 50, 120, 30, "Button")) {
    // 寬度120, 高度30
}

// 圖片按鈕（三態）
cvui::button(frame, x, y, imgIdle, imgOver, imgDown);

3. checkbox - 複選框

bool checked = false;
cvui::checkbox(frame, x, y, "Check me", &checked);

if (checked) {
    // 被選中
}

4. counter - 計數器

// 整數版本
int value = 10;
cvui::counter(frame, x, y, &value, 1);  // 步長為1

// 雙精度版本
double dvalue = 5.5;
cvui::counter(frame, x, y, &dvalue, 0.5, "%.2f");

5. trackbar - 滑塊

int value = 50;
cvui::trackbar(frame, x, y, 200, &value, 0, 100);

參數

説明

width

滑塊寬度

value

變量指針

min

最小值

max

最大值

6. window - 窗口組件

cvui::window(frame, x, y, width, height, "Title");

繪製一個帶標題的矩形區域（裝飾性組件）。

7. rect - 矩形

cvui::rect(frame, x, y, 200, 100, 0xFF0000, 0x00FF00);

參數

説明

width, height

寬高

borderColor

邊框顏色

fillingColor

填充顏色

8. image - 顯示圖片

cvui::image(frame, x, y, myImage);

將 myImage 繪製到 frame 的指定位置。

9. sparkline - 迷你圖

std::vector<double> values = {1, 5, 3, 8, 4};
cvui::sparkline(frame, values, x, y, 200, 50, 0x00FF00);

顯示數據變化趨勢圖。

10. printf - 格式化文本

// 完整版
cvui::printf(frame, x, y, 0.5, 0xFF0000, "Value: %d", 123);

// 簡化版
cvui::printf(frame, x, y, "FPS: %.1f", fps);

顏色格式

cvui 使用 0xAABBGGRR 格式（BGR 順序，非 RGB）：

值

顏色

0xFF0000

紅色

0x00FF00

綠色

0x0000FF

藍色

0xFFFF00

青色

0xFF00FF

品紅

0x00FFFF

黃色

0xFFFFFF

白色

0x000000

黑色

0xff000000

完全透明

完整示例

#define CVUI_IMPLEMENTATION
#include "cvui.h"

#define WINDOW_NAME "Demo"

int main() {
    cv::Mat frame = cv::Mat(600, 800, CV_8UC3);
    cvui::init(WINDOW_NAME);

    bool checked = false;
    int count = 0;
    double value = 50.0;
    std::vector<double> data = {1, 3, 2, 5, 4};

    while (true) {
        frame = cv::Scalar(49, 52, 49);  // 清空畫布

        // 文本
        cvui::text(frame, 50, 30, "CVUI Demo", 0.6, 0xffffff);

        // 按鈕
        if (cvui::button(frame, 50, 60, "Click me")) {
            count++;
        }

        // 複選框
        cvui::checkbox(frame, 50, 100, "Enable", &checked);

        // 計數器
        cvui::counter(frame, 50, 140, &count);

        // 滑塊
        cvui::trackbar(frame, 50, 180, 200, &value, 0, 100);

        // 格式化輸出
        cvui::printf(frame, 50, 240, "Count: %d, Value: %.1f", count, value);

        // 矩形
        cvui::rect(frame, 300, 60, 150, 100, 0xFF0000, 0x333333);

        // 窗口組件
        cvui::window(frame, 300, 180, 200, 100, "Settings");

        // 迷你圖
        cvui::sparkline(frame, data, 50, 280, 200, 50, 0x00FF00);

        // 更新並顯示
        cvui::update();
        cv::imshow(WINDOW_NAME, frame);

        if (cv::waitKey(20) == 27) break;
    }

    return 0;
}

多窗口使用

cvui::init("window1");
cvui::init("window2");

while (true) {
    // 窗口1
    cv::Mat frame1(200, 300, CV_8UC3);
    frame1 = cv::Scalar(49, 52, 49);
    cvui::context("window1");
    cvui::text(frame1, 10, 10, "Window 1");
    cvui::button(frame1, 10, 40, "Button");
    cvui::imshow("window1", frame1);

    // 窗口2
    cv::Mat frame2(200, 300, CV_8UC3);
    frame2 = cv::Scalar(49, 52, 49);
    cvui::context("window2");
    cvui::text(frame2, 10, 10, "Window 2");
    cvui::printf(frame2, 10, 40, "Value: %d", 123);
    cvui::update("window2");
    cv::imshow("window2", frame2);

    if (cv::waitKey(20) == 27) break;
}

重要提示

  1. 必須定義 CVUI_IMPLEMENTATION
  2. 調用 cvui::update() - 在所有組件定義之後、imshow() 之前
  3. 顏色格式 - 使用 0xAABBGGRR (BGR順序)
  4. 鍵盤快捷鍵 - 如需使用，init() 時傳入正的延遲值（如 20）