cvui使用指南

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 - 在一个且仅一个 .cpp 文件中定义
2. 调用 cvui::update() - 在所有组件定义之后、imshow() 之前
3. 颜色格式 - 使用 0xAABBGGRR (BGR顺序)
4. 键盘快捷键 - 如需使用，init() 时传入正的延迟值（如 20）