Usage

Below are a few steps you need to perform to work with cvui.

Using cvui in C++

1. Include `cvui.h`

Download the latest release and place cvui.h along with the files of your project. Include cvui.h in one of your C++ files as follows:

#define CVUI_IMPLEMENTATION
#include "cvui.h"

IMPORTANT: if you are using cvui.h in multiple files, e.g. different layout classes, you need to use #define CVUI_IMPLEMENTATION in one (and only one) of your C++ files. All other files should include cvui.h without #define CVUI_IMPLEMENTATION. E.g:

// 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"
// (...)
/////////////////////////////////////////////

Tip: check the multiple-files example to learn more about the use of cvui in projects with multiple files that include cvui.h.

2. Initialize cvui

Before using cvui, you need to call cvui::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"

int main() {
  // Tell cvui to init and create a window
  cvui::init(WINDOW_NAME);

  while(true) {
    // your app logic here
    if (cv::waitKey(20) == 27) {
      break;
    }
  }

  return 0;
}

Tip: if you need to use cvui with multiple windows, or you want more control over the process of creating windows, check the Multiple OpenCV windows page and the multiple-windows and multiple-windows-complex examples.

3. Render cvui components

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

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

#define WINDOW_NAME "CVUI Test"

int main() {
  cvui::init(WINDOW_NAME);

  // Create a frame
  cv::Mat frame = cv::Mat(cv::Size(400, 200), CV_8UC3);

  while(true) {
    // clear the frame
    frame = 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;
    }
  }

  return 0;
}

4. Show (window) content

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

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

#define WINDOW_NAME "CVUI Test"

int main() {
  cvui::init(WINDOW_NAME);
  cv::Mat frame = 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 content
    cvui::imshow(WINDOW1_NAME, frame);

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

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

If you want to use cv::imshow(), you must call cvui::update() before cv::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"

int main() {
  cvui::init(WINDOW_NAME);
  cv::Mat frame = 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 stuff
    cvui::update();

    // Show window content
    cv::imshow(WINDOW1_NAME, frame);

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

  return 0;
}

(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 of cvui.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 defining CVUI_DISABLE_COMPILATION_NOTICES before including cvui.h. E.g.:

#include <opencv2/opencv.hpp>

#define CVUI_DISABLE_COMPILATION_NOTICES
#define CVUI_IMPLEMENTATION
#include "cvui.h"

Using cvui in Python

1. Add `cvui.py` and import `cvui`

Download the latest release and place cvui.py along with the files of your project, or install it using pip install cvui. Import cvui in any of your Python files as follows:

import cvui

2. Initialize cvui

Before using cvui, you need to call cvui.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:

import numpy as np
import cv2
import cvui

WINDOW_NAME = 'CVUI Test'

# Tell cvui to init and create a window
cvui.init(WINDOW_NAME)

while True:
    # your app logic here
    if cv2.waitKey(20) == 27:
        break

3. Rendering and using cvui components

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

import numpy as np
import cv2
import cvui

WINDOW_NAME = 'CVUI Test'

cvui.init(WINDOW_NAME)

# Create a frame
frame = np.zeros((200, 400, 3), np.uint8)

while True:
    # clear the frame
    frame[:] = (49, 52, 49)

    # render a message in the frame at position (10, 15)
    cvui.text(frame, 10, 15, 'Hello world!')

    if cv2.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.

Tip: cvui components that change external variables are: counter, trackbar and checkbox.

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 variable checkboxState:

import numpy as np
import cv2
import cvui

WINDOW_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 cvui
checkboxState = [False]

while True:
    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.
    if checkboxState[0] == True:
        print('Checkbox is checked')

    if cv2.waitKey(20) == 27:
        break

3. Show (window) content

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

import numpy as np
import cv2
import cvui

WINDOW_NAME = 'CVUI Test'

cvui.init(WINDOW_NAME)
frame = np.zeros((200, 400, 3), np.uint8)

while True:
    frame[:] = (49, 52, 49)
    cvui.text(frame, 10, 15, 'Hello world!')

    # Show window content
    cvui.imshow(WINDOW1_NAME, frame)

    if cv2.waitKey(20) == 27:
        break

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

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

import numpy as np
import cv2
import cvui

WINDOW_NAME = 'CVUI Test'

cvui.init(WINDOW_NAME)
frame = np.zeros((200, 400, 3), np.uint8)

while True:
    frame[:] = (49, 52, 49)
    cvui.text(frame, 10, 15, 'Hello world!')

    # Update cvui internal stuff
    cvui.update()

    # Show window content
    cv2.imshow(WINDOW1_NAME, frame)

    if cv2.waitKey(20) == 27:
        break

Learn more

Check out the examples page for more usage demonstrations of cvui.

Edit this page on Github

Usage

Using cvui in C++

1. Include cvui.h

2. Initialize cvui

3. Render cvui components

4. Show (window) content

(Optional) 5. Disable cvui compilation messages

Using cvui in Python

1. Add cvui.py and import cvui

2. Initialize cvui

3. Rendering and using cvui components

3. Show (window) content

Learn more

1. Include `cvui.h`

1. Add `cvui.py` and import `cvui`