Note: We assume in this tutorial that you have successfully installed ViSP either with an Installation from packages or with an Installation from source code.

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

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

1.1. On unix-like OS

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 existing.
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
Copy the source code from tutorial/image ViSP folder
$ cd $VISP_WS

$ cp -p -r visp/tutorial/image .

or donwload it from https://github.com/lagadic/visp/tree/master/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

1.2. On windows OS

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
You can either copy the source code from %VISP_WS%/tutorial/image folder if you follow one of the Installation from source code tutorials
C:> xcopy /E /I %VISP_WS%\visp\tutorial\image %VISP_WS%\image

or downloading it from https://github.com/lagadic/visp/tutorial/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

2. Advanced getting started

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

2.2. 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/core/vpConfig.h>
#include <visp3/core/vpFont.h>
#include <visp3/core/vpIoTools.h>
#include <visp3/core/vpTime.h>
#include <visp3/gui/vpDisplayFactory.h>
#include <visp3/io/vpImageIo.h>
 
#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif
 
int main(int argc, char **argv)
{
#ifdef VISP_HAVE_DISPLAY
  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 (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_11)
    std::shared_ptr<vpDisplay> pdisp = vpDisplayFactory::createDisplay(I, 10, 10, vpIoTools::getName(argv[1]), vpDisplay::SCALE_AUTO);
#else
    vpDisplay *pdisp = vpDisplayFactory::allocateDisplay(I, 10, 10, vpIoTools::getName(argv[1]), vpDisplay::SCALE_AUTO);
#endif
    vpDisplay::setTitle(I, vpIoTools::getName(argv[1]));
    vpDisplay::display(I);
    vpDisplay::flush(I);
    std::cout << "Right click to quit" << std::endl;
    std::cout << "Left click to inspect pixel position (i,j) and RGBa values\n" << std::endl;
    bool quit = false;
    vpImagePoint ip;
    vpMouseButton::vpMouseButtonType button;
    unsigned int scale_factor = vpDisplay::getDownScalingFactor(I);
    vpFont font(14, vpFont::GENERIC_MONOSPACE);
    while (!quit) {
      if (vpDisplay::getClick(I, ip, button, false)) {
        if (button == vpMouseButton::button3) {
          quit = true;
        }
        else {
          std::stringstream ss;
          unsigned int i = static_cast<unsigned int>(ip.get_i());
          unsigned int j = static_cast<unsigned int>(ip.get_j());
          ss << i << " " << j << ": " << I[i][j];
          std::cout << ss.str() << std::endl;
          font.drawText(I, ss.str(), vpImagePoint(I.getHeight() - 20*scale_factor, 10), vpColor::red, vpColor::white);
          vpDisplay::display(I);
          vpDisplay::flush(I);
        }
      }
      vpTime::sleepMs(40);
    }
#if (VISP_CXX_STANDARD < VISP_CXX_STANDARD_11)
    delete pdisp;
#endif
  }
  catch (const vpException &e) {
    std::cout << "Catch an exception: " << e << std::endl;
  }
#else
  (void)argc;
  (void)argv;
  std::cout << "No display available!" << std::endl;
#endif
}

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

#include <visp3/gui/vpDisplayFactory.h>

Includes header for image viewers. Depending on the third party detected by ViSP, we will use one of the following: X11, Direct3D, GTK-2, OpenCV or the Graphical Device Interface (GDI) provided when Visual Studio was installed.

#include <visp3/io/vpImageIo.h>

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

vpImage<vpRGBa> I;

Creates an instance of a color image where each pixel is coded in RGBa (red-channel, green-channel, blue-channel and alpha-channel for transparency).

Note: Transparency is only handled when OpenCV is used to display color images.

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

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

#if (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_11)
    std::shared_ptr<vpDisplay> pdisp = vpDisplayFactory::createDisplay(I, 10, 10, vpIoTools::getName(argv[1]), vpDisplay::SCALE_AUTO);
#else
    vpDisplay *pdisp = vpDisplayFactory::allocateDisplay(I, 10, 10, vpIoTools::getName(argv[1]), vpDisplay::SCALE_AUTO);
#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 pointer to the display pdisp. Note that an image can only have one display.

vpDisplay::setTitle(I, vpIoTools::getName(argv[1]));

The title of the display is then set to the image name.

vpDisplay::display(I);

vpDisplay::flush(I);

Then first we display the content of the image I, and after we flush the display to render the image.

Note: vpDisplay::display() is usually to call at the beginning of an image processing loop, just after a new image is available, while vpDisplay::flush() is usually to call ones at the end of the loop. Between you can call other display functionalities to display lines, points, crosses, circles...

    bool quit = false;
    vpImagePoint ip;
    vpMouseButton::vpMouseButtonType button;
    unsigned int scale_factor = vpDisplay::getDownScalingFactor(I);
    vpFont font(14, vpFont::GENERIC_MONOSPACE);
    while (!quit) {
      if (vpDisplay::getClick(I, ip, button, false)) {
        if (button == vpMouseButton::button3) {
          quit = true;
        }
        else {
          std::stringstream ss;
          unsigned int i = static_cast<unsigned int>(ip.get_i());
          unsigned int j = static_cast<unsigned int>(ip.get_j());
          ss << i << " " << j << ": " << I[i][j];
          std::cout << ss.str() << std::endl;
          font.drawText(I, ss.str(), vpImagePoint(I.getHeight() - 20*scale_factor, 10), vpColor::red, vpColor::white);
          vpDisplay::display(I);
          vpDisplay::flush(I);
        }
      }
      vpTime::sleepMs(40);
    }
 

Here we handle mouse events in a while loop. We are first waiting a mouse right click button3 to quit the loop. If the user is clicking on the left button button1or the middle one button2 we call vpFont::draw() to display the position (i,j) and the R-G-B-A values of the clicked point.

2.3. 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.10)
 
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.10)
 
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})

2.4. Get monkey.jpeg file

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

you may copy it from ViSP source code; the file is in VISP_WS/visp/tutorial/image/monkey.jpeg
or download it from https://github.com/lagadic/visp/blob/master/tutorial/image/ by copy/paste from GitHub using the Raw button

2.5. On unix-like OS

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

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

2.5.2. Configure 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

$ ccmake ..

or run cmake with the additional VISP_DIR definition
$ ccmake -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.

2.5.3. Generate executable

Just run:

$ make

2.5.4. 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.jpeg

Here is a screen shot of the resulting output window:

In the bottom of the image are the coordinates and R-G-B-A values of the centre of the pupil in the monkey's right eye

2.6. On windows OS

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

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

2.6.2. Configure 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 4.7. 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, 4.7. 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.

2.6.3. Generate 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.

2.6.4. 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.jpeg
Here is a screen shot of the resulting output window:

In the bottom of the image are the coordinates and R-G-B-A values of the centre of the pupil in the monkey's right eye

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