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

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
```

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

Create a build folder

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

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
```
Build tutorial-viewer example
```
$ make tutorial-viewer
```
Run tutorial-viewer example
```
$ ./tutorial-viewer monkey.pgm
```

On windows operating system

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
```
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 code 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
```

Create a build folder

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

Run CMake in build folder and indicate where to find ViSP thanks to VISP_DIR var.

If your are using Visual Studio 17 2022 and 64 bits hardware, run:

C:\> cmake -G "Visual Studio 17 2022" -A "x64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc17

Or if your are using Visual Studio 16 2019 and 64 bits hardware, run:

C:\> cmake -G "Visual Studio 16 2019" -A "x64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc16

Or if your are using Visual Studio 15 2017 and 64 bits hardware, run:

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

Or if your are using Visual Studio 14 2015 and 64 bits hardware, run:

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

Or if your are rather using MinGW-w64, run:

C:\> cmake -G "MinGW Makefiles" .. -DVISP_DIR=%VISP_WS%\visp-build-mingw

Build tutorial-viewer example

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

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 EXIT_FAILURE;
  }
 
  vpImage<vpRGBa> I;
 
  try {
    vpImageIo::read(I, argv[1]);
  } catch (...) {
    std::cout << "Cannot read image \"" << argv[1] << "\"" << std::endl;
    return EXIT_FAILURE;
  }
 
  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(HAVE_OPENCV_HIGHGUI)
    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 EXIT_FAILURE;
  }

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(HAVE_OPENCV_HIGHGUI)
    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.

cmake_minimum_required(VERSION 3.5)
 
project(tutorial-image)
 
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:

cmake_minimum_required(VERSION 3.5)
 
project(tutorial-image)
 
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 packages 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.

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