SDK UI Utils

class Metavision::BaseWindow

Base class for displaying images in a window. It uses GLFW and OpenGL under the hood.

This class cannot directly be used as is, instead, one needs to instantiate one of its derived class (i.e. Window or MTWindow).

Note

Each window has its own events queue that needs to be regularly processed, either explicitly by calling BaseWindow::poll_events or implicitly by calling Window::show or MTWindow::show_async with auto_poll = true (default behavior). Events are polled from the system and push to the windows’ internal queue by calling EventLoop::poll_and_dispatch.

Warning

The constructor and destructor of this class must only be called from the main thread

Subclassed by Metavision::MTWindow, Metavision::Window

Public Types

enum RenderMode

Color Rendering mode.

Values:

enumerator GRAY
enumerator BGR

Public Functions

~BaseWindow()

Destructor.

Warning

Must only be called from the main thread

void get_size(int &width, int &height) const

Gets the window’s current size.

Parameters
  • width: The window’s width

  • height: The window’s height

RenderMode get_rendering_mode() const

Gets the window’s color rendering mode.

Return

The window’s color rendering mode (Either RenderMode::GRAY or RenderMode::BGR)

bool should_close() const

Indicates whether the window has been asked to close.

Return

True if the window should close, False otherwise

Note

This returns the window’s close flag

void set_close_flag()

Asks the window to close.

Note

This only sets the window’s close flag to True but doesn’t actually close the window. The window will effectively be closed when the destructor is called.

void set_keyboard_callback(const KeyCallback &cb)

Sets a callback that will be called when a key is pressed.

Warning

Due to a GLFW’s limitation, this callback returns key codes corresponding to the standard US keyboard layout. However, keys corresponding to unicode characters are mapped internally to match the current keyboard layout.

Note

See GLFW’s documentation (GLFWkeyfun) for more information

Parameters
  • cb: The callback to call on a key event

void set_mouse_callback(const MouseCallback &cb)

Sets a callback that will be called when a mouse’s button is pressed.

Note

See GLFW’s documentation (GLFWmousebuttonfun) for more information

Parameters
  • cb: The callback to call on a mouse event

void set_cursor_pos_callback(const CursorPosCallback &cb)

Sets a callback that will be called when the mouse’s cursor moves on the current window.

Note

See GLFW’s documentation (GLFWcursorposfun) for more information

Parameters
  • cb: The callback to call on a mouse cursor event

void poll_events()

Dequeues events in this window’s queue and calls corresponding callbacks.

Note

Calling this method is not mandatory when Window::show and MTWindow::show_async are called with auto_poll = true (i.e. default behavior). However, when the image to display is somehow generated from input events (e.g. drawing ROIs from mouse inputs), then it might be useful to call this method before both generating the image and calling Window::show or MTWindow::show_async (with auto_poll = false) to reduce the latency between the moment when the events are generated and the moment when the image is actually displayed.

Warning

The callbacks are called in the same thread as this method’s calling one. This means that if this method is called from a different thread than the one calling Window::show or MTWindow::show_async, a special care must be taken, in the callbacks, to avoid concurrency problems.

class Metavision::EventLoop

A static class used to dispatch system events to the windows they belong to.

Public Static Functions

void poll_and_dispatch(std::int64_t sleep_time_ms = 0)

Polls events from the system and pushes them into the corresponding windows’ internal queue.

Warning

Must only be called from the main thread

Parameters
  • sleep_time_ms: Amount of time in ms this call will wait after polling and dispatching the events

class Metavision::MTWindow : public Metavision::BaseWindow

Window using its own rendering thread to render images.

Images are displayed at a fixed frequency (i.e. the screen’s refresh one) by the internal rendering thread.

Warning

The constructor and destructor of this class must only be called from the main thread

Public Functions

MTWindow(const std::string &title, int width, int height, RenderMode mode)

Constructor.

Warning

Must only be called from the main thread

Parameters
  • title: The window’s title

  • width: Width of the window at starting time (can be resized later on) and width of the images that will be displayed

  • height: Height of the window at starting time (can be resized later on) and height of the images that will be displayed

  • mode: The color rendering mode (i.e. either GRAY or BGR). Cannot be modified.

~MTWindow()

Destructor.

Warning

Must only be called from the main thread

void show_async(cv::Mat &image, bool auto_poll = true)

Asynchronously displays an image.

Here asynchronously means that the image is not immediately displayed, but will be done later on by the internal rendering thread. This window uses a front/back buffers mechanism to avoid copying images.

Warning

If auto_poll is True, the events are processed in this method’s calling thread, not in the internal rendering one.

Parameters
  • image: The image to display. The image is passed as a non constant reference in order to be swapped with the front buffer and thus avoid useless copies.

  • auto_poll: If True, events in this window’s queue are dequeued and processed. If false, BaseWindow::poll_events must explicitly be called.

class Metavision::Window : public Metavision::BaseWindow

A window that can be used to display images from any thread.

This window has no internal rendering thread, meaning that the images are displayed at the same frequency as the one of the Window::show method.

Warning

The constructor and destructor of this class must only be called from the main thread

Public Functions

Window(const std::string &title, int width, int height, RenderMode mode)

Constructs a new Window.

Warning

Must only be called from the main thread

Parameters
  • title: The window’s title

  • width: Width of the window at starting time (can be resized later on) and width of the images that will be displayed

  • height: Height of the window at starting time (can be resized later on) and height of the images that will be displayed

  • mode: The color rendering mode (i.e. either GRAY or BGR). Cannot be modified.

~Window()

Destructor.

Warning

Must only be called from the main thread

void show(const cv::Mat &image, bool auto_poll = true)

Displays an image.

Parameters
  • image: The image to display

  • auto_poll: If True, events in this window’s queue are dequeued and processed. If false, BaseWindow::poll_events must explicitly be called.

enum Metavision::UIAction

Values:

enumerator RELEASE = GLFW_RELEASE
enumerator PRESS = GLFW_PRESS
enumerator REPEAT = GLFW_REPEAT
enum Metavision::UIMouseButton

Ids of the mouse buttons that can be triggered through the User Interface.

Values:

enumerator MOUSE_BUTTON_1 = GLFW_MOUSE_BUTTON_1
enumerator MOUSE_BUTTON_2 = GLFW_MOUSE_BUTTON_2
enumerator MOUSE_BUTTON_3 = GLFW_MOUSE_BUTTON_3
enumerator MOUSE_BUTTON_4 = GLFW_MOUSE_BUTTON_4
enumerator MOUSE_BUTTON_5 = GLFW_MOUSE_BUTTON_5
enumerator MOUSE_BUTTON_6 = GLFW_MOUSE_BUTTON_6
enumerator MOUSE_BUTTON_7 = GLFW_MOUSE_BUTTON_7
enumerator MOUSE_BUTTON_8 = GLFW_MOUSE_BUTTON_8
enumerator MOUSE_BUTTON_LAST = GLFW_MOUSE_BUTTON_LAST
enumerator MOUSE_BUTTON_LEFT = GLFW_MOUSE_BUTTON_LEFT
enumerator MOUSE_BUTTON_RIGHT = GLFW_MOUSE_BUTTON_RIGHT
enumerator MOUSE_BUTTON_MIDDLE = GLFW_MOUSE_BUTTON_MIDDLE
enum Metavision::UIKeyEvent

Ids of the keyboard events that can be triggered through the User Interface.

Values:

enumerator KEY_UNKNOWN = GLFW_KEY_UNKNOWN
enumerator KEY_SPACE = GLFW_KEY_SPACE
enumerator KEY_APOSTROPHE = GLFW_KEY_APOSTROPHE
enumerator KEY_COMMA = GLFW_KEY_COMMA
enumerator KEY_MINUS = GLFW_KEY_MINUS
enumerator KEY_PERIOD = GLFW_KEY_PERIOD
enumerator KEY_SLASH = GLFW_KEY_SLASH
enumerator KEY_0 = GLFW_KEY_0
enumerator KEY_1 = GLFW_KEY_1
enumerator KEY_2 = GLFW_KEY_2
enumerator KEY_3 = GLFW_KEY_3
enumerator KEY_4 = GLFW_KEY_4
enumerator KEY_5 = GLFW_KEY_5
enumerator KEY_6 = GLFW_KEY_6
enumerator KEY_7 = GLFW_KEY_7
enumerator KEY_8 = GLFW_KEY_8
enumerator KEY_9 = GLFW_KEY_9
enumerator KEY_SEMICOLON = GLFW_KEY_SEMICOLON
enumerator KEY_EQUAL = GLFW_KEY_EQUAL
enumerator KEY_A = GLFW_KEY_A
enumerator KEY_B = GLFW_KEY_B
enumerator KEY_C = GLFW_KEY_C
enumerator KEY_D = GLFW_KEY_D
enumerator KEY_E = GLFW_KEY_E
enumerator KEY_F = GLFW_KEY_F
enumerator KEY_G = GLFW_KEY_G
enumerator KEY_H = GLFW_KEY_H
enumerator KEY_I = GLFW_KEY_I
enumerator KEY_J = GLFW_KEY_J
enumerator KEY_K = GLFW_KEY_K
enumerator KEY_L = GLFW_KEY_L
enumerator KEY_M = GLFW_KEY_M
enumerator KEY_N = GLFW_KEY_N
enumerator KEY_O = GLFW_KEY_O
enumerator KEY_P = GLFW_KEY_P
enumerator KEY_Q = GLFW_KEY_Q
enumerator KEY_R = GLFW_KEY_R
enumerator KEY_S = GLFW_KEY_S
enumerator KEY_T = GLFW_KEY_T
enumerator KEY_U = GLFW_KEY_U
enumerator KEY_V = GLFW_KEY_V
enumerator KEY_W = GLFW_KEY_W
enumerator KEY_X = GLFW_KEY_X
enumerator KEY_Y = GLFW_KEY_Y
enumerator KEY_Z = GLFW_KEY_Z
enumerator KEY_LEFT_BRACKET = GLFW_KEY_LEFT_BRACKET
enumerator KEY_BACKSLASH = GLFW_KEY_BACKSLASH
enumerator KEY_RIGHT_BRACKET = GLFW_KEY_RIGHT_BRACKET
enumerator KEY_GRAVE_ACCENT = GLFW_KEY_GRAVE_ACCENT
enumerator KEY_WORLD_1 = GLFW_KEY_WORLD_1
enumerator KEY_WORLD_2 = GLFW_KEY_WORLD_2
enumerator KEY_ESCAPE = GLFW_KEY_ESCAPE
enumerator KEY_ENTER = GLFW_KEY_ENTER
enumerator KEY_TAB = GLFW_KEY_TAB
enumerator KEY_BACKSPACE = GLFW_KEY_BACKSPACE
enumerator KEY_INSERT = GLFW_KEY_INSERT
enumerator KEY_DELETE = GLFW_KEY_DELETE
enumerator KEY_RIGHT = GLFW_KEY_RIGHT
enumerator KEY_LEFT = GLFW_KEY_LEFT
enumerator KEY_DOWN = GLFW_KEY_DOWN
enumerator KEY_UP = GLFW_KEY_UP
enumerator KEY_PAGE_UP = GLFW_KEY_PAGE_UP
enumerator KEY_PAGE_DOWN = GLFW_KEY_PAGE_DOWN
enumerator KEY_HOME = GLFW_KEY_HOME
enumerator KEY_END = GLFW_KEY_END
enumerator KEY_CAPS_LOCK = GLFW_KEY_CAPS_LOCK
enumerator KEY_SCROLL_LOCK = GLFW_KEY_SCROLL_LOCK
enumerator KEY_NUM_LOCK = GLFW_KEY_NUM_LOCK
enumerator KEY_PRINT_SCREEN = GLFW_KEY_PRINT_SCREEN
enumerator KEY_PAUSE = GLFW_KEY_PAUSE
enumerator KEY_F1 = GLFW_KEY_F1
enumerator KEY_F2 = GLFW_KEY_F2
enumerator KEY_F3 = GLFW_KEY_F3
enumerator KEY_F4 = GLFW_KEY_F4
enumerator KEY_F5 = GLFW_KEY_F5
enumerator KEY_F6 = GLFW_KEY_F6
enumerator KEY_F7 = GLFW_KEY_F7
enumerator KEY_F8 = GLFW_KEY_F8
enumerator KEY_F9 = GLFW_KEY_F9
enumerator KEY_F10 = GLFW_KEY_F10
enumerator KEY_F11 = GLFW_KEY_F11
enumerator KEY_F12 = GLFW_KEY_F12
enumerator KEY_F13 = GLFW_KEY_F13
enumerator KEY_F14 = GLFW_KEY_F14
enumerator KEY_F15 = GLFW_KEY_F15
enumerator KEY_F16 = GLFW_KEY_F16
enumerator KEY_F17 = GLFW_KEY_F17
enumerator KEY_F18 = GLFW_KEY_F18
enumerator KEY_F19 = GLFW_KEY_F19
enumerator KEY_F20 = GLFW_KEY_F20
enumerator KEY_F21 = GLFW_KEY_F21
enumerator KEY_F22 = GLFW_KEY_F22
enumerator KEY_F23 = GLFW_KEY_F23
enumerator KEY_F24 = GLFW_KEY_F24
enumerator KEY_F25 = GLFW_KEY_F25
enumerator KEY_KP_0 = GLFW_KEY_KP_0
enumerator KEY_KP_1 = GLFW_KEY_KP_1
enumerator KEY_KP_2 = GLFW_KEY_KP_2
enumerator KEY_KP_3 = GLFW_KEY_KP_3
enumerator KEY_KP_4 = GLFW_KEY_KP_4
enumerator KEY_KP_5 = GLFW_KEY_KP_5
enumerator KEY_KP_6 = GLFW_KEY_KP_6
enumerator KEY_KP_7 = GLFW_KEY_KP_7
enumerator KEY_KP_8 = GLFW_KEY_KP_8
enumerator KEY_KP_9 = GLFW_KEY_KP_9
enumerator KEY_KP_DECIMAL = GLFW_KEY_KP_DECIMAL
enumerator KEY_KP_DIVIDE = GLFW_KEY_KP_DIVIDE
enumerator KEY_KP_MULTIPLY = GLFW_KEY_KP_MULTIPLY
enumerator KEY_KP_SUBTRACT = GLFW_KEY_KP_SUBTRACT
enumerator KEY_KP_ADD = GLFW_KEY_KP_ADD
enumerator KEY_KP_ENTER = GLFW_KEY_KP_ENTER
enumerator KEY_KP_EQUAL = GLFW_KEY_KP_EQUAL
enumerator KEY_LEFT_SHIFT = GLFW_KEY_LEFT_SHIFT
enumerator KEY_LEFT_CONTROL = GLFW_KEY_LEFT_CONTROL
enumerator KEY_LEFT_ALT = GLFW_KEY_LEFT_ALT
enumerator KEY_LEFT_SUPER = GLFW_KEY_LEFT_SUPER
enumerator KEY_RIGHT_SHIFT = GLFW_KEY_RIGHT_SHIFT
enumerator KEY_RIGHT_CONTROL = GLFW_KEY_RIGHT_CONTROL
enumerator KEY_RIGHT_ALT = GLFW_KEY_RIGHT_ALT
enumerator KEY_RIGHT_SUPER = GLFW_KEY_RIGHT_SUPER
enumerator KEY_MENU = GLFW_KEY_MENU
enumerator KEY_LAST = GLFW_KEY_LAST