ViSP  2.8.0
Tutorial: Getting started
Note
We assume in this tutorial that you have successfully installed ViSP. Information on ViSP installation is provided in:

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 available in ViSP source code, in tutorial/image folder.

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 <visp/vpDisplayD3D.h>
#include <visp/vpDisplayGDI.h>
#include <visp/vpDisplayGTK.h>
#include <visp/vpDisplayX.h>
#include <visp/vpDisplayOpenCV.h>
#include <visp/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;
}
try {
vpImageIo::read(I, argv[1]);
}
catch(...) {
std::cout << "Cannot read image \"" << argv[1] << "\"" << std::endl;
return -1;
}
#if defined(VISP_HAVE_X11)
vpDisplayX d(I);
#elif defined(VISP_HAVE_OPENCV)
#elif defined(VISP_HAVE_GTK)
#elif defined(VISP_HAVE_GDI)
#elif defined(VISP_HAVE_D3D9)
vpDisplayD3d d(I);
#else
std::cout << "No image viewer is available..." << std::endl;
#endif
vpDisplay::setTitle(I, "My image");
std::cout << "A click to quit..." << std::endl;
}

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

#include <visp/vpDisplayD3D.h>
#include <visp/vpDisplayGDI.h>
#include <visp/vpDisplayGTk.h>
#include <visp/vpDisplayX.h>
#include <visp/vpDisplayOpenCV.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 <visp/vpImageIo.h>

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

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)
#elif defined(VISP_HAVE_OPENCV)
#elif defined(VISP_HAVE_GTK)
#elif defined(VISP_HAVE_GDI)
#elif defined(VISP_HAVE_D3D9)
vpDisplayD3d d(I);
#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".

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

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.6)
find_package(VISP REQUIRED)
if(VISP_FOUND)
include(${VISP_USE_FILE})
endif(VISP_FOUND)
add_executable(tutorial-viewer tutorial-viewer.cpp)

On Unix-like systems

Configure your project

Proceed as with any other project using CMake:

cmake .

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 lena.ppm

Here is a screen shot of the resulting output window :

img-lena.png

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 lena.ppm. These files are also provider 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.
img-started-win-cmake-1.jpg
  • 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.
img-started-win-cmake-2.jpg
  • 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.
img-started-win-cmake-3.jpg
  • 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.
img-started-win-msvc-1.jpg
  • Now to build the solution, enter "BUILD/Build Solution" menu.
img-started-win-msvc-2.jpg
  • 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:
img-started-win-run.jpg
  • Here is a screen shot of the resulting output window :

    img-lena-win.jpg

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