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

Table of Contents

• Quick getting started
  • On unix-like operating system
  • On windows operating system
• Advanced getting started
  • Create a workspace
  • Get tutorial-viewer.cpp file
  • Get CMakeLists.txt file
  • Get monkey.ppm file
  • On unix-like operating system
    • Create a build folder
    • Configure your project
    • Generate the executable
    • Run the executable
  • On windows operating system
    • Create a build folder
    • 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 operating system (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

Quick getting started

In this section we show how to build an existing project that uses ViSP as third-party and CMake for the build mechanism. As a use case we will use the image project that is part of ViSP tutorials. The source code comes from https://github.com/lagadic/visp/tutorial/image. It contains a set of source files tutorial-viewer.cpp, tutorial-image-viewer.cpp and a CMakeLists.txt file. We show here how to get these files and build them.

On unix-like operating system

1. If you did Installation from packages you have to create a workspace. If you did Installation from source code jump to point 2. since your workspace should be already created.
   Check if VISP_WS environment var exists:

   $ env | grep VISP_WS

   If it returns an empty string, create a workspace with:

   $ echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc
   $ source ~/.bashrc
   $ mkdir -p $VISP_WS

2. Get the source code using Subversion (svn):

   $ sudo apt-get install subversion
   $ cd $VISP_WS
   $ svn export https://github.com/lagadic/visp.git/trunk/tutorial/image

3. Create a build folder

   $ mkdir -p $VISP_WS/image/build
   $ cd $VISP_WS/image/build

4. Run CMake in build directory
   If you did Installation from packages, run:

   $ cmake .. -DCMAKE_BUILD_TYPE=Release

   Otherwise if you did Installation from source code, indicate where to find ViSP thanks to VISP_DIR var:

   $ cmake .. -DCMAKE_BUILD_TYPE=Release -DVISP_DIR=$VISP_WS/visp-build

5. Build tutorial-viewer example

   $ make tutorial-viewer

6. Run tutorial-viewer example

   $ ./tutorial-viewer monkey.pgm

On windows operating system

1. If you did Installation from source code jump to point 2. since your workspace should be already created.
   Open a cmd Command Prompt and check if VISP_WS environment var exists:

   C:\> set | findstr VISP_WS

   If it returns an empty string, create a workspace with:

   C:\> mkdir C:\visp-ws
   C:\> setx VISP_WS=C:\visp-ws
   C:\> exit

2. Get the source code in your workspace either using Subversion (svn), either copying the source code from %VISP_WS%/tutorial/image folder if you follow one of the Installation from source tutorials, or downloading the source from https://github.com/lagadic/visp/tutorial/image:
   With Subversion:

   C:\> svn export https://github.com/lagadic/visp.git/trunk/tutorial/image

   Or by copy from ViSP source code

   C:\> xcopy /E /I %VISP_WS%\visp\tutorial\image %VISP_WS%\image 

3. Create a build folder

   C:\> mkdir %VISP_WS%\image\build
   C:\> cd %VISP_WS%\image\build

4. Run CMake in build folder and indicate where to find ViSP thanks to VISP_DIR var.
   If your are using Visual Studio 15 2017 and 64 bits hardware, run:

   C:\> cmake -G "Visual Studio 15 2017 Win64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc15

   If your are rather using Visual Studio 14 2015 and 64 bits hardware, run:

   C:\> cmake -G "Visual Studio 14 2015 Win64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc14

5. Build tutorial-viewer example

   C:\> cmake --build . --config Release --target tutorial-viewer

6. Run tutorial-viewer example

   C:\> cd Release
   C:\> tutorial-viewer.exe monkey.pgm

Advanced getting started

Create a workspace

We suppose here that you have already setup a workspace and defined VISP_WS environment var.

We recall here after the instructions to create a workspace:

• On unix-like operating system
  Check if VISP_WS environment var exists:

  $ env | grep VISP_WS

  If it returns an empty string, create a workspace with:

  $ echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc
  $ source ~/.bashrc
  $ mkdir -p $VISP_WS

• On windows operating system
  Open a cmd Command Prompt and check if VISP_WS environment var exists:

  C:\> set | findstr VISP_WS

  If it returns an empty string, create a workspace with:

  C:\> mkdir C:\visp-ws
  C:\> setx VISP_WS=C:\visp-ws
  C:\> exit

Enter VISP_WS folder and create a new folder let say started that will contain your first project that uses ViSP as third-party:

• On unix-like operating system
  

  $ cd $VISP_WS
  $ mkdir started

• On windows operating system
  Open a cmd Command Prompt and run

  C:\> cd %VISP_WS%
  C:\> mkdir started

Get tutorial-viewer.cpp file

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

Open your favorite editor and copy/paste the content of this example in VISP_WS/started/tutorial-viewer.cpp source file.

The code to copy/paste is the following:

#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 (const 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.

Get CMakeLists.txt file

Now you have to create a CMakeLists.txt file that gives the instructions on how to build tutorial-viewer.cpp example. A minimalistic CMakeLists.txt should contain the following lines.

Open your editor and copy/paste the following lines in VISP_WS/started/CMakeLists.txt file.

project(tutorial-image)

cmake_minimum_required(VERSION 3.0)

find_package(VISP REQUIRED)

include_directories(${VISP_INCLUDE_DIRS})

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

Here after we explain the content of the CMakeLists.txt file.

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 3.0)

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})

Get monkey.ppm file

Get monkey.ppm image and copy it to VISP_WS/started either:

• copying it from ViSP source code; the file is in VISP_WS/tutorial/image/monkey.ppm
• using Subversion:

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

• by copy/paste from GitHub using the Raw button

On unix-like operating system

In this section we supppose that you have created a folder $VISP_WS/started that contains CMakeLists.txt, tutorial-viewer.cpp and monkey.ppm files.

Create a build folder

Proceed now as with any other project using CMake by first creating a build folder:

C:\> cd $VISP_WS/started
C:\> mkdir build

Configure your project

Enter the build folder and launch CMake GUI:

$ cd build
$ ccmake .. -DCMAKE_BUILD_TYPE=Release
Press [c] key to configure
Then, press [g] to generate Makefiles
Then, press [q] to quit CMake GUI

Note

By default ccmake searches VISPConfig.cmake file in system folders like /usr/share, /usr/local/share... If ViSP is not installed in /usr or /usr/local as suggested in Installation from source code tutorials, 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

If you get the previous error it means that you forget to set VISP_DIR environment variable that helps cmake to find VISPConfig.cmake file.

• If you install ViSP from source following one of the Installation from source code tutorials, set VISP_DIR environment variable to the ViSP build folder location and call ccmake again:

  $ export VISP_DIR=$VISP_WS/visp-build/lib/cmake/visp
  $ ccmake ..

  or run cmake with the additional VISP_DIR definition

  $ ccmake -DVISP_DIR=$VISP_WS/visp-build/lib/cmake/visp .

• If you rather install ViSP from prebuilt packages following one of the Installation from prebuild SDK tutorials, set VISP_DIR environment variable to the installation folder location and call cmake again:

  $ export VISP_DIR=/usr/lib/<multi-arch-folder>/cmake/visp
  $ cmake ..

  or run cmake with the additional VISP_DIR definition

  $ cmake -DVISP_DIR=/usr/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 if you install ViSP using

  $ sudo apt-get install libvisp-dev.

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 operating system

We suppose from now, that you have created a folder %VISP_WS%\started that contains CMakeLists.txt, tutorial-viewer.cpp and monkey.ppm files.

Create a build folder

Proceed now as with any other project using CMake by first creating a build folder:

C:\> cd %%VISP_WS%\started
C:\> mkdir build

Configure your project

• Launch "CMake (cmake-gui)" from Windows "Start" menu. Set the source code location as %VISP_WS%\started and the build location to %VISP_WS%\started\build folder.

• Press "Configure" button and select your compiler. In our case we will use Visual Studio 15 2017 Win64.

• Press then "Finish" button. The configuration is now under progress and should lead to the following image.

• In the previous image you may notice that CMake has automatically found the location of ViSP install folder; %VISP_WS/visp-build-vc15/install. This was possible because you Set VISP_DIR environment var.

  Note

  If at this step you have an error like the one shown in the next image, it means that you forget to set VISP_DIR env var. If this is the case, quit CMake Gui, Set VISP_DIR environment var, open CMake Gui and try again to configure your project.

  

• 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 %VISP_WS%\started\build folder you should have tutorial-image.sln Visual Studio solution file.

Generate the executable

• Open the project in Visual Studio C++ just by double click on %VISP_WS%\stated\build\tutorial-image.sln solution file.
• Modify the configuration to "Release"

• Now to build the solution, enter "BUILD \> Build Solution" menu or hit Ctrl+Shift+B keys.

• In %VISP_WS%\started\build\Release folder you have now tutorial-viewer.exe executable.

Run the executable

• In your "Start" menu click on "Run" and type in cmd.exe to run a Command Prompt.
• Enter in %VISP_WS%\started\build\Release folder, and run tutorial-viewer.exe with an image location as argument:

  C:\> cd %VISP_WS%\started\build\Release
  C:\> tutorial-viewer ..\..\monkey.ppm

• 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 in a window. 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.