transition to visp 3.0.0

Overview

This document is intended to software developers who want to migrate their code from ViSP 2.x to ViSP 3.0.0.

ViSP 3.0.0 introduced a new modular software architecture where ViSP capabilities are grouped in several modules (core, io, gui, vision…). As a result, the user will find several shared or static libraries, one for each module (libvisp_core, libvisp_io, libvisp_gui, libvisp_vision…) compared to ViSP 2.x where all algorithms were grouped in the same library (libvisp).

ViSP 3.0.0 was designed to be compatible with previous work done with ViSP 2.x. This means that a project build with ViSP 2.x should build against ViSP 3.0.0 without trouble. This is the theory! Since 3.0.0 released we indentify some issues with compat against ViSP 2.10.0. We provide some work arround hints in this document.

Next we describe most notable changes and provide details and examples of transition actions.

ViSP repository migrates to GitHub

Source code migrates from InriaForge http://gforge.inria.fr/projects/visp/ to GitHub https://github.com/lagadic/visp.

ViSP contrib repository

We initiate visp_contrib a GitHub repository https://github.com/lagadic/visp_contrib intended for development of “extra” modules that are contribution from the community, or that do not have stable API, that are not well-tested or that cannot be added to ViSP due to licensing. The scheme adopted in visp_contrib could be replicated by users who want to develop additional modules based on ViSP.

You can build ViSP, so it will include the modules from visp_contrib repository. Here is the CMake command:

$ cd <parent_dir>
$ git clone https://github.com/lagadic/visp.git
$ git clone https://github.com/lagadic/visp_contrib.git
$ mkdir visp-build
$ cd visp-build
$ cmake -DVISP_CONTRIB_MODULES_PATH=../visp_contrib/modules ../visp
$ make -j4

Headers layout

In 2.x all headers were located in visp subfolder (visp/vpMatrix.h).

In 3.0.0 all the headers corresponding to a given module are located in visp3 folder (visp3/core/vpMatrix.h). For compatibility reasons, these headers are also available in visp folder (visp/vpMatrix.h) as for the previous release.

The following sample code builds with ViSP 2.x as well with 3.0.0 without any changes:

#include <visp/vpColVector.h>
#include <visp/vpHomogeneousMatrix.h>
#include <visp/vpDot2.h>
#include <visp/vpMbEdgeTracker.h>

int main()
{
  vpColVector v(6);
  vpHomogeneousMatrix cMo;
  vpDot2 blob;
  vpMbEdgeTracker mbt;
}

Now it is possible to modify the headers to better identify ViSP 3.0.0 modules they belong:

#include <visp3/core/vpColVector.h>
#include <visp3/core/vpHomogeneousMatrix.h>
#include <visp3/blob/vpDot2.h>
#include <visp3/mbt/vpMbEdgeTracker.h>

int main()
{
  vpColVector v(6);
  vpHomogeneousMatrix cMo;
  vpDot2 blob;
  vpMbEdgeTracker mbt;
}

It becomes clear that to build this example we need ViSP 3.0.0 core, blob and mbt modules.

CMake layout

The classical way to build a project that uses ViSP is to write a CMakeLists.txt file. Here after we give an example that works with ViSP 2.x as well as with 3.0.0 to build a file named test.cpp.

project(transition)
cmake_minimum_required(VERSION 2.8)
find_package(VISP REQUIRED)
include_directories(${VISP_INCLUDE_DIRS})
add_executable(test test.cpp)
target_link_libraries(test ${VISP_LIBRARIES})

With ViSP 3.0.0, you can specify which are the modules that are required:

find_package(VISP REQUIRED <module1> <module2> ...)

For example, if you know that your project needs only some specific modules (let say core, blob and mbt) you can modify the CMakeLists.txt file:

find_package(VISP REQUIRED core blob mbt)

With ViSP 3.0.0 we provide also a CMake macro named visp_add_target() that allows to synthetise include_directories(), add_executable() and target_link_libraries directives:

visp_add_target(<source.cpp>)

Thus the previous CMakeLists.txt file could be rewritten to a minimalist version like:

project(transition)
cmake_minimum_required(VERSION 2.8)
find_package(VISP REQUIRED core blob mbt)
visp_add_target(test.cpp)

Known hints to migrate form ViSP 2.10.0 to ViSP 3.0.0

Even if our goal was to keep compat between 2.x and 3.0.0, we discover some functionalities that wer possible with ViSP 2.10.0 that are now brocken with ViSP 3.0.0.

Cannot add a vpTranslationVector to a column vector

The following was possible with ViSP 2.10.0

    vpTranslationVector center;
    vpColVector axis(3);
    vpColVector point;
    point = center + axis;