Download thelatest release and placecvui.h along with the files of your project. Includecvui.h in one of your C++ files as follows:

#define CVUI_IMPLEMENTATION#include "cvui.h"

// File: main.cpp#define CVUI_IMPLEMENTATION      <-- CVUI_IMPLEMENTATION defined in one (and only one) C++ source file.#include "cvui.h"// (...)/////////////////////////////////////////////// File: another.cpp#include "cvui.h"// (...)/////////////////////////////////////////////// File: MyClass.hpp#include "cvui.h"// (...)/////////////////////////////////////////////

2. Initialize cvui

Before using cvui, you need to callcvui::init() to initialize it. The easiest way is to initialize cvui and tell it to create any OpenCV window that will be used. Below is an example where cvui is initialized and a window is created:

#include <opencv2/opencv.hpp>#define CVUI_IMPLEMENTATION#include "cvui.h"#define WINDOW_NAME "CVUI Test"intmain(){// Tell cvui to init and create a windowcvui::init(WINDOW_NAME);while(true){// your app logic hereif(cv::waitKey(20)==27){break;}}return0;}

3. Render cvui components

All cvui components are rendered to acv::Mat. Below is an example showing how to render a"Hello world" message on acv::Mat namedframe:

#include <opencv2/opencv.hpp>#define CVUI_IMPLEMENTATION#include "cvui.h"#define WINDOW_NAME "CVUI Test"intmain(){cvui::init(WINDOW_NAME);// Create a framecv::Matframe=cv::Mat(cv::Size(400,200),CV_8UC3);while(true){// clear the frameframe=cv::Scalar(49,52,49);// render a message in the frame at position (10, 15)cvui::text(frame,10,15,"Hello world!");if(cv::waitKey(20)==27){break;}}return0;}

4. Show (window) content

After rendering your components, show the final result usingcvui::imshow(), which is cvui’s improved version of OpenCV’scv::imshow():

#include <opencv2/opencv.hpp>#define CVUI_IMPLEMENTATION#include "cvui.h"#define WINDOW_NAME "CVUI Test"intmain(){cvui::init(WINDOW_NAME);cv::Matframe=cv::Mat(cv::Size(400,200),CV_8UC3);while(true){frame=cv::Scalar(49,52,49);cvui::text(frame,x,y,"Hello world!");// Show window contentcvui::imshow(WINDOW1_NAME,frame);if(cv::waitKey(20)==27){break;}}return0;}

When you usecvui::imshow() instead ofcv::imshow(), cvui will not only show the content, but update its internal structures to ensure all UI interactions work.

If you want to usecv::imshow(), you must callcvui::update() beforecv::imshow() and after you are finished invoking cvui components, so cvui can perform its internal processing to handle mouse interactions. E.g.

#include <opencv2/opencv.hpp>#define CVUI_IMPLEMENTATION#include "cvui.h"#define WINDOW_NAME "CVUI Test"intmain(){cvui::init(WINDOW_NAME);cv::Matframe=cv::Mat(cv::Size(400,200),CV_8UC3);while(true){frame=cv::Scalar(49,52,49);cvui::text(frame,x,y,"Hello world!");// Update cvui internal stuffcvui::update();// Show window contentcv::imshow(WINDOW1_NAME,frame);if(cv::waitKey(20)==27){break;}}return0;}

(Optional) 5. Disable cvui compilation messages

The compilation process of cvui will produce a few console messages to help developers debug possible problems, e.g. inclusion ofcvui.h using#define CVUI_IMPLEMENTATION. The two possible messages are:

• cvui.h: compiling implementation because of CVUI_IMPLEMENTATION. See: https://dovyski.github.io/cvui/usage/
• cvui.h: implementation skipped. Ensure one of your C++ files included cvui.h after a #define CVUI_IMPLEMENTATION. See: https://dovyski.github.io/cvui/usage/

You can disable such compilation messages by definingCVUI_DISABLE_COMPILATION_NOTICES before includingcvui.h. E.g.:

#include <opencv2/opencv.hpp>#define CVUI_DISABLE_COMPILATION_NOTICES#define CVUI_IMPLEMENTATION#include "cvui.h"

Using cvui in Python

1. Addcvui.py and importcvui

Download thelatest release and placecvui.py along with the files of your project, or install it usingpip install cvui. Import cvui in any of your Python files as follows:

importcvui

2. Initialize cvui

Before using cvui, you need to callcvui.init() to initialize it. The easiest way is to initialize cvui and tell it to create any OpenCV window that will be used. Below is an example where cvui is initialized and a window is created:

importnumpyasnpimportcv2importcvuiWINDOW_NAME='CVUI Test'# Tell cvui to init and create a windowcvui.init(WINDOW_NAME)whileTrue:# your app logic hereifcv2.waitKey(20)==27:break

3. Rendering and using cvui components

All cvui components are rendered to anp.array, i.e. equivalent of C++cv::Mat. Below is an example showing how to render a'Hello world' message on anp.array namedframe:

importnumpyasnpimportcv2importcvuiWINDOW_NAME='CVUI Test'cvui.init(WINDOW_NAME)# Create a frameframe=np.zeros((200,400,3),np.uint8)whileTrue:# clear the frameframe[:]=(49,52,49)# render a message in the frame at position (10, 15)cvui.text(frame,10,15,'Hello world!')ifcv2.waitKey(20)==27:break

Some cvui components use an external variable that they need to modify to control their internal state, e.g.checkbox() uses an external boolean to store if it is checked or not.

Since there are no pointers to built-in types in Python, cvui components that need to change an external variable must receive such variable as an array/list with a single element.

Below is an example of a checkbox whose state is stored in the variablecheckboxState:

importnumpyasnpimportcv2importcvuiWINDOW_NAME='CVUI Test'cvui.init(WINDOW_NAME)frame=np.zeros((200,400,3),np.uint8)# use an array/list because this variable will be changed by cvuicheckboxState=[False]whileTrue:frame[:]=(49,52,49)# Render the checkbox. Notice that checkboxState is used AS IS,# e.g. simply "checkboxState" instead of "checkboxState[0]".# Only internally that cvui will use checkboxState[0].cvui.checkbox(frame,10,15,'My checkbox',checkboxState)# Check the state of the checkbox. Here you need to remember to# use the first position of the array/list because that's the# one being used by all cvui components that perform changes# to external variables.ifcheckboxState[0]==True:print('Checkbox is checked')ifcv2.waitKey(20)==27:break

3. Show (window) content

After rendering your components, show the final result usingcvui.imshow(), which is cvui’s improved version of OpenCV’scv2.imshow():

importnumpyasnpimportcv2importcvuiWINDOW_NAME='CVUI Test'cvui.init(WINDOW_NAME)frame=np.zeros((200,400,3),np.uint8)whileTrue:frame[:]=(49,52,49)cvui.text(frame,10,15,'Hello world!')# Show window contentcvui.imshow(WINDOW1_NAME,frame)ifcv2.waitKey(20)==27:break

When you usecvui.imshow() instead ofcv2.imshow(), cvui will not only show the content, but update its internal structures to ensure all UI interactions work.

If you want to usecv2.imshow(), you must callcvui.update() beforecv2.imshow() and after you are finished invoking cvui components, so cvui can perform its internal processing to handle mouse interactions. E.g.

importnumpyasnpimportcv2importcvuiWINDOW_NAME='CVUI Test'cvui.init(WINDOW_NAME)frame=np.zeros((200,400,3),np.uint8)whileTrue:frame[:]=(49,52,49)cvui.text(frame,10,15,'Hello world!')# Update cvui internal stuffcvui.update()# Show window contentcv2.imshow(WINDOW1_NAME,frame)ifcv2.waitKey(20)==27:break

Learn more

Check out theexamples page for more usage demonstrations of cvui.