Tutorial: How to create and build a CMake project that uses ViSP on Unix or Windows

Table of Contents

• Create a program using ViSP
• Create a CMake file
• On Unix-like systems
  • Configure your project
  • Generate the executable
  • Run the executable
• On Windows
  • Configure your project
  • Generate the executable
  • Run the executable
• Next tutorial

Note

We assume in this tutorial that you have successfully installed ViSP either with an Installation from prebuild SDK or with an Installation from source.

In this tutorial you will learn how to use ViSP either on Unix-like systems (including OSX, Fedora, Ubuntu, Debian, ...) or on Windows.

The easiest way of using ViSP in your project is to use CMake. If you are not familiar with CMake, you can check the tutorial.

Note also that all the material (source code and images) described in this tutorial is part of ViSP source code and could be downloaded using the following command:

$ svn export https://github.com/lagadic/visp.git/trunk/tutorial/image

Create a program using ViSP

Let's start to write our first program to see how to read an image and open a window to display the image. This simple program is provided in tutorial-viewer.cpp example and given below:

#include <visp3/gui/vpDisplayD3D.h>
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayGTK.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>
#include <visp3/io/vpImageIo.h>

int main(int argc, char **argv)
{
  if (argc != 2) {
    printf("Usage: %s <image name.[pgm,ppm,jpeg,png,tiff,bmp,ras,jp2]>\n", argv[0]);
    return -1;
  }

  vpImage<vpRGBa> I;

  try {
    vpImageIo::read(I, argv[1]);
  } catch (...) {
    std::cout << "Cannot read image \"" << argv[1] << "\"" << std::endl;
    return -1;
  }

  try {
#if defined(VISP_HAVE_X11)
    vpDisplayX d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_GDI)
    vpDisplayGDI d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_OPENCV)
    vpDisplayOpenCV d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_GTK)
    vpDisplayGTK d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_D3D9)
    vpDisplayD3d d(I, vpDisplay::SCALE_AUTO);
#else
    std::cout << "No image viewer is available..." << std::endl;
#endif

    vpDisplay::setTitle(I, "My image");
    vpDisplay::display(I);
    vpDisplay::flush(I);
    std::cout << "A click to quit..." << std::endl;
    vpDisplay::getClick(I);
  } catch (vpException &e) {
    std::cout << "Catch an exception: " << e << std::endl;
  }
}

Here is the detailed explanation of the source, line by line :

#include <visp3/gui/vpDisplayD3D.h>
#include <visp3/gui/vpDisplayGDI.h>
#include <visp3/gui/vpDisplayGTK.h>
#include <visp3/gui/vpDisplayOpenCV.h>
#include <visp3/gui/vpDisplayX.h>

Include all the headers for image viewers. The two first one are for Windows systems. They require that Direct 3D or the Graphical Device Interface (GDI) coming with the installation of Visual Studio are available. The third one needs GTK that is cross-platform. The fourth is for unix-like systems and requires that libX11 is available. The last one is also cross-platform and requires that OpenCV is available.

#include <visp3/io/vpImageIo.h>

Include the header that allows to read/write PGM, PPM, PNG and JPEG images from the disk using vpImageIo class.

  vpImage<vpRGBa> I;

Create an instance of a color image where each pixel is coded in RGBa.

  try {
    vpImageIo::read(I, argv[1]);
  } catch (...) {
    std::cout << "Cannot read image \"" << argv[1] << "\"" << std::endl;
    return -1;
  }

The image I is initialized by reading an image file from the disk. If the image format is not supported we throw an exception.

#if defined(VISP_HAVE_X11)
    vpDisplayX d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_GDI)
    vpDisplayGDI d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_OPENCV)
    vpDisplayOpenCV d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_GTK)
    vpDisplayGTK d(I, vpDisplay::SCALE_AUTO);
#elif defined(VISP_HAVE_D3D9)
    vpDisplayD3d d(I, vpDisplay::SCALE_AUTO);
#else
    std::cout << "No image viewer is available..." << std::endl;
#endif

Create an instance of an image display window for image I. The first viewer that is available is used. Here we create the link between the image I and the display d. Note that an image can only have one display.

    vpDisplay::setTitle(I, "My image");

The title of the display is then set to "My image".

    vpDisplay::display(I);
    vpDisplay::flush(I);

First we display the content of the image I, then we flush the display to render the image.

    vpDisplay::getClick(I);

Here we handle mouse events. We are waiting for a blocking mouse click to end the program.

Create a CMake file

Now you have to create your CMakeLists.txt file. It should look like this:

project(tutorial-image)

cmake_minimum_required(VERSION 2.8)

find_package(VISP REQUIRED)

include_directories(${VISP_INCLUDE_DIRS})

add_executable(tutorial-viewer tutorial-viewer.cpp)
target_link_libraries(tutorial-viewer ${VISP_LIBRARIES})

The find_package() CMake command searches for a VISPConfig.cmake file that will define the corresponding variables:

• VISP_INCLUDE_DIRS : ViSP and third-party headers location
• VISP_LIBRARIES : ViSP and third-party libraries name and location

Note that the previous CMakeLists.txt file can also be:

project(tutorial-image)

cmake_minimum_required(VERSION 2.8)

find_package(VISP REQUIRED)
if(VISP_FOUND)
  include(${VISP_USE_FILE})
endif(VISP_FOUND)

add_executable(tutorial-viewer tutorial-viewer.cpp)

where VISP_USE_FILE variable is set to the full path to VISPUse.cmake file that contains all the CMake material that allow to build your project with ViSP. In other terms, the line

include(${VISP_USE_FILE})

will include the following lines to your CMakeFile.txt

include_directories(${VISP_INCLUDE_DIRS})
link_libraries(${VISP_LIBRARIES})

On Unix-like systems

Configure your project

Proceed as with any other project using CMake:

$ cmake .

By default cmake searches VISPConfig.cmake file in folders like /usr/share or /usr/local/share. If ViSP was not installed in /usr or /usr/local it is possible that you get the following error:

CMake Error at CMakeLists.txt:5 (find_package):
  Could not find module FindVISP.cmake or a configuration file for package
  VISP.

  Adjust CMAKE_MODULE_PATH to find FindVISP.cmake or set VISP_DIR to the
  directory containing a CMake configuration file for VISP.  The file will
  have one of the following names:

    VISPConfig.cmake
    visp-config.cmake

To help cmake to find VISPConfig.cmake file, just set VISP_DIR environment variable and call cmake again:

$ export VISP_DIR=/home/ViSP-install-folder/lib/<multi-arch-folder>/cmake/visp
$ cmake .

or run cmake with the additional VISP_DIR definition

$ cmake -DVISP_DIR=/home/ViSP-install-folder/lib/<multi-arch-folder>/cmake/visp .

Depending on the platform <multi-arch-folder> can be empty (OSX) or for example equal to x86_64-linux-gnu on Ubuntu.

Note

If you build ViSP from source following one of the tutorials Installation from source code, you can avoid the make install step and set VISP_DIR to the build location instead of the install location.

Generate the executable

Just run:

$ make

Run the executable

By now you should have an executable called tutorial-viewer. You just have to run it giving an image location as an argument:

$ ./tutorial-viewer monkey.ppm

Here is a screen shot of the resulting output window :

On Windows

We suppose from now, that you have created a folder (let say C:/ViSP/ViSP-started) that contains the following files: CMakeLists.txt, tutorial-viewer.cpp and monkey.ppm. These files are also provided in ViSP source code, in tutorial/image folder.

Configure your project

• Launch CMake (cmake-gui) from Windows "Start" menu. Set the source code location as C:/ViSP/ViSP-started. Here we set the build location to the same folder.

• Press "Configure" button, and select your compiler. In our case we will use Visual Studio 11 Win64. Press then "Finish". The configuration is now under progress and should lead to the following image.

• Note here that CMake has automatically found the location of ViSP install folder; C:/ViSP/ViSP-install.
• Press then "Configure" button to remove the red lines, and then "Generate" button. As presented in the following image, all the red lines should disappear.

• From now, in C:/ViSP/ViSP-started you should have tutorial-image.sln Visual Studio solution file.

Generate the executable

• To open the project in Visual Studio C++ just double click on C:/ViSP/ViSP-started/tutorial-image.sln solution file.

• Now to build the solution, enter "BUILD/Build Solution" menu.

• In C:/ViSP/ViSP-started/Debug folder you have now tutorial-image.exe executable.

Run the executable

• In your "Start" menu click on "Run" and type in cmd.exe to run a terminal.
• Enter in C:/ViSP/ViSP-started/Debug folder, and run tutorial-viewer.exe with an image location as argument:

• Here is a screen shot of the resulting output window :

  

Next tutorial

You are now ready to see the Tutorial: How to display an image. There is also the Tutorial: How to extend ViSP creating a new contrib module that could be useful to understand how to introduce new developments in ViSP.