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) {// 窗口1cv::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);// 窗口2cv::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;
}
重要提示
- 必须定义
CVUI_IMPLEMENTATION- 在一个且仅一个 .cpp 文件中定义 - 调用
cvui::update()- 在所有组件定义之后、imshow()之前 - 颜色格式 - 使用
0xAABBGGRR(BGR顺序) - 键盘快捷键 - 如需使用，
init()时传入正的延迟值（如20）