Fernando Bevilacqua

Senior software engineer and open-source contributor

cvui 2.5.0 is out!

2018-04-04 Fernando Bevilacqua opencv,ui,gui

I am pleased to inform that version 2.5.0 of cvui is out! cvui is a simple UI lib built on top of OpenCV drawing primitives.

As usual this release contains contributions from several awesome people, so I would like to thank all contributors that have helped improve cvui. Thank you, you rock! New features for this release include support for multiple windows, a mouse API and the addition of cvui::imshow().

This post will give an overview of those cool new features. All GIFs in this post are from applications whose source code is available as examples in the cvui repository.

Support for multiple windows

In previous versions of cvui it was possible to render UI components to multiple windows. However components that respond to user interaction, e.g. buttons, would only work in one of those windows.

That was a significant limitation since multiple windows in graphical applications are quite common. cvui 2.5.0 no longer has such limitation:

cvui

Using the newly added function cvui::context(), developers can easily inform cvui of which window is being rendered/worked at any given time. cvui will internally track the state of each window and ensure that all UI interactions are handled properly, no matter the window.

Some existing functions were also updated and a few new ones were added to facilitate the work with multiple windows. For instance, you don’t need to create your own windows using cv::namedWindow() anymore (only if you wish so, of course). cvui can do that for you now:

const cv::String windows[] = {
    WINDOW1_NAME,
    WINDOW2_NAME,
    WINDOW3_NAME,
    WINDOW4_NAME
};
cvui::init(windows, 4);

All changes regarding windows are backward compatible, so existing projects should not face any problems. To learn more about this new feature, check out the multiple windows entry in the docs.

New mouse API

Mouse interaction is an important part of a graphical application. Particularly in computer vision applications, tasks quite often require quick iterations and selection of regions, for instance.

cvui has the philosophy of “one line of code produces one element on the screen”. This should remain true for a mouse API. The newly added mouse API provides lots of functionality without sacrificing simplicity. Everything related to the mouse is available via cvui::mouse(), which provide an easy way to query mouse information.

The function bool cvui::mouse(int query) allows you to query the mouse for events, e.g. cvui::mouse(cvui::DOWN). Available queries are:

The function cvui::mouse() returns a cv::Point which can be used to track the position of the mouse cursor. The combination of those two functions allow the creation of complex GUI with few (and clean) lines of code.

Below is a simple application demonstrating the new mouse API, whose complete source code has 57 lines in total (excluding comments).

cvui

The new mouse API seamlessly works with multiple windows:

cvui

All mouse functions also accept the name of a given window as a parameter, so you can get mouse info of any window in your application. Additionally it is possible to query information of any given button, e.g.

// check if left button of the mouse is down
// in the current window.
if (cvui::mouse(cvui::LEFT_BUTTON, cvui::IS_DOWN)) {
    // do something
}

// check if the middle button of the mouse is down
// in the window named WINDOW_NAME.
if (cvui::mouse(WINDOW_NAME, cvui::MIDDLE_BUTTON, cvui::IS_DOWN)) {
    // do something
}

Below is one application (source code available as an example) that uses the mouse API to dynamically create ROIs based on clicks of different mouse buttons.

cvui

To learn more about this new feature, check out the mouse API entry in the docs.

Better documentation

cvui documentation was completely overhauled, including the addition of several new code examples. Documentation pages have been significantly improved with code samples, figures and better explanations. All pages also have an Edit this page on Github button, so feel invited to improve the documentation as you see fit.

A tool is as good as its docs, so I hope this will make cvui even better.

Important changes

Finally I want to mention some changes that landed in this release. I tried my best to ensure backward compatibility, but unfortunately a small change is required to make cvui 2.5.0 work with existing projects. I am honestly sorry for any inconveniences this might cause.

From now on, one (and only one) of your C++ files must include cvui.h after a #define CVUI_IMPLEMENTATION, e.g.

#define CVUI_IMPLEMENTATION
#include "cvui.h"

int main() {

}

All other files should include cvui as usual:

#include "cvui.h"

int main() {

}

This change was required to keep cvui as flexible, simple and “sane” as possible. The function cvui::init() was also modified, but it should not affect existing addition of cvui::imshow() (equivalent of calling cvui::update() then cv::imshow(), as explained here).

Below is a list of changes according to the CHANGELOG.

Added

Changed

Fixed

Conclusion

cvui 2.5.0 is full of new features to help you improve your workflow and create awesome GUI applications. I hope this new release will make cvui even more useful.

As a final remark, the source code of all applications mentioned in this post is available in the examples folder of cvui repository. Inspect and use them as you please since everything is MIT licensed (as cvui itself).

Related Posts