Tutorial: How to display an image in a window

1. 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.

2. Create and display an image

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/core/vpConfig.h>
#include <visp3/gui/vpDisplayFactory.h>
 
#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif
 
int main()
{
#if defined(VISP_HAVE_DISPLAY)
  vpImage<unsigned char> I(2160, 3840, 128);
 
#if (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_11)
  std::shared_ptr<vpDisplay> d = vpDisplayFactory::createDisplay(I);
#else
  vpDisplay *d = vpDisplayFactory::allocateDisplay(I);
#endif
 
  vpDisplay::display(I);
  vpDisplay::displayCircle(I, I.getHeight() / 2, I.getWidth() / 2, 200, vpColor::red, true);
  vpDisplay::flush(I);
  std::cout << "A click to quit..." << std::endl;
  vpDisplay::getClick(I);
 
#if (VISP_CXX_STANDARD < VISP_CXX_STANDARD_11)
  delete d;
#endif
 
#else
  std::cout << "No gui available to display an image..." << std::endl;
#endif
 
  return EXIT_SUCCESS;
}

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, a vpDisplayGDI, a vpDisplayOpenCV, a vpDisplayGTK or a vpDisplayD3D.

3. Display an image larger than screen resolution

3.1. 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 (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_11)
  std::shared_ptr<vpDisplay> d = vpDisplayFactory::createDisplay(I, -1, -1, "Manual scaling display", vpDisplay::SCALE_5);
#else
  vpDisplay *d = vpDisplayFactory::allocateDisplay(I, -1, -1, "Manual scaling display", vpDisplay::SCALE_5);
#endif

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

#if defined(VISP_HAVE_X11)
  vpDisplayX d;
#elif defined(VISP_HAVE_GDI)
  vpDisplayGDI d;
#endif
  d.setDownScalingFactor(vpDisplay::SCALE_5);
  d.init(I);
}

3.2. 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.

  // Initialize the display with the image I. Display and image are now linked together
#if (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_11)
  std::shared_ptr<vpDisplay> d = vpDisplayFactory::createDisplay(I, -1, -1, "Auto scaling display", vpDisplay::SCALE_AUTO);
#else
  vpDisplay *d = vpDisplayFactory::allocateDisplay(I, -1, -1, "Auto scaling display", vpDisplay::SCALE_AUTO);
#endif

It is also possible to do the same using the dedicated constructors:

#if defined(VISP_HAVE_X11)
  vpDisplayX d;
#elif defined(VISP_HAVE_GDI)
  vpDisplayGDI d;
#endif
  d.setDownScalingFactor(vpDisplay::SCALE_AUTO);
  d.init(I);
}

Next image shows the content of the display window:

4. Next tutorial

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