Visual Servoing Platform  version 3.6.1 under development (2024-03-28)
Tutorial: How to display an image in a window

Introduction

Note
We assume in this tutorial that you have successfully build your first project using ViSP as 3rd party as explained in one of the Getting started tutorials.

In this tutorial you will learn how to display an image in a window with ViSP either on Unix-like systems (including OSX, Fedora, Ubuntu, Debian, ...) or on Windows.

Note that all the material (source code and images) described in this tutorial is part of ViSP source code (in tutorial/image folder) and could be found in https://github.com/lagadic/visp/tree/master/tutorial/image.

Create and display an image in a window

ViSP gui module provides Graphical User Interfaces capabilities that allows to display a vpImage in a window. To this end you may use several optional third-party libraries which are: X11, GDI, OpenCV, GTK, Direct3D. We recommend to use X11 on unix-like systems thanks to vpDisplayX class and GDI on Windows thanks to vpDisplayGDI. If none of these classes are available, you may use vpDisplayOpenCV instead.

The following example also available in tutorial-image-display.cpp shows how to create a gray level 3840x2160 image with all the pixels set to 128, and display a red circle with 200 pixel radius in the middle of the image.

#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayX.h>
int main()
{
vpImage<unsigned char> I(2160, 3840, 128);
try {
#if defined(VISP_HAVE_X11)
vpDisplayX d(I);
#elif defined(VISP_HAVE_GDI)
#endif
vpDisplay::setTitle(I, "My image");
vpDisplay::displayCircle(I, I.getHeight() / 2, I.getWidth() / 2, 200, vpColor::red, true);
std::cout << "A click to quit..." << std::endl;
} catch (const vpException &e) {
std::cout << "Catch an exception: " << e.getMessage() << std::endl;
}
}
static const vpColor red
Definition: vpColor.h:211
Display for windows using GDI (available on any windows 32 platform).
Definition: vpDisplayGDI.h:128
Use the X11 console to display images on unix-like OS. Thus to enable this class X11 should be instal...
Definition: vpDisplayX.h:128
static bool getClick(const vpImage< unsigned char > &I, bool blocking=true)
static void displayCircle(const vpImage< unsigned char > &I, const vpImageCircle &circle, const vpColor &color, bool fill=false, unsigned int thickness=1)
static void display(const vpImage< unsigned char > &I)
static void setTitle(const vpImage< unsigned char > &I, const std::string &windowtitle)
static void flush(const vpImage< unsigned char > &I)
error that can be emitted by ViSP classes.
Definition: vpException.h:59
const char * getMessage() const
Definition: vpException.cpp:64
unsigned int getWidth() const
Definition: vpImage.h:245
unsigned int getHeight() const
Definition: vpImage.h:184

Depending on your screen resolution you may just see a part of the image, and certainly not the full red circle. Next image shows an example of this behavior when screen resolution is less than image size:

Note
A vpImage can only be associated to one display window. In the previous example, image I is associated to display d. Depending on your platform, object d is either a vpDisplayX or a vpDisplayGDI.

Display an image that is larger than the screen resolution

Setting a manual down scaling factor

This other example available in tutorial-image-display-scaled-manu.cpp shows how to modify the previous example in order to introduce a down scaling factor to reduce the size of the display by 5 along the lines and the columns. This feature may be useful to display images that are larger than the screen resolution.

To down scale the display size, just modify the previous example adding the vpDisplay::vpScaleType parameter to the constructor.

#if defined(VISP_HAVE_X11)
#elif defined(VISP_HAVE_GDI)
#endif

It is also possible to do the same using the default constructor:

#if defined(VISP_HAVE_X11)
#elif defined(VISP_HAVE_GDI)
#endif
d.init(I);
}
void init(vpImage< unsigned char > &I, int win_x=-1, int win_y=-1, const std::string &win_title="") vp_override
virtual void setDownScalingFactor(unsigned int scale)
Definition: vpDisplay.cpp:227

Setting an auto down scaling factor

This other example available in tutorial-image-display-scaled-auto.cpp shows now how to modify the previous example in order to introduce an auto down scaling factor that is automatically computed from the screen resolution in order that two images could be displayed given the screen resolution.

To consider an auto down scaling factor, modify the previous example adding the vpDisplay::SCALE_AUTO parameter to the constructor.

#if defined(VISP_HAVE_X11)
#elif defined(VISP_HAVE_GDI)
#endif
@ SCALE_AUTO
Definition: vpDisplay.h:179

It is also possible to do the same using the default constructor:

#if defined(VISP_HAVE_X11)
#elif defined(VISP_HAVE_GDI)
#endif
d.init(I);
}

Next image shows the content of the display window:

Next tutorial

You are now ready to see the Tutorial: Image frame grabbing or Tutorial: Image filtering.