transition to visp 3.0.0
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.
Source code migrates from InriaForge http://gforge.inria.fr/projects/visp/ to GitHub https://github.com/lagadic/visp.
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
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.
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)
Even if our goal was to keep compat between 2.x and 3.0.0, we discover some functionalities that were possible with ViSP 2.x that are now brocken with ViSP 3.0.0.
Let us consider the case where we have two 3-dimension vectors F (force) and T (torque) that we want to stack in a FT (force/torque) 6-dimension vector. The following was possible with ViSP 2.9.0.
#include <visp/vpColVector.h>
int main()
{
vpColVector FT(6);
vpColVector F(3);
vpColVector T(3);
FT.insert(F, 0, 0);
FT.insert(T, 3, 0);
}
With ViSP 3.0.0 (but also with ViSP 2.10.0) if we build the previous example we get the following error:
test-issue1.cpp:9:5: error: too many arguments to function call, expected 2, have 3; did you mean 'vpMatrix::insert'?
FT.insert(F, 0, 0);
To be compatible with more recent ViSP versions, the code should be modified like:
FT.insert(0, F);
FT.insert(3, T);
The following function vpMatrix::column() marked as deprecated in ViSP 2.10.0 was removed in ViSP 3.x. For example, with ViSP 2.x you could make the cross product of the two first columns of a 3-by-3 matrix with the following code:
#include <visp/vpColVector.h>
int main()
{
vpColVector crossprod;
vpMatrix A(3, 3);
crossprod = vpColVector::crossProd(A.column(1), A.column(2));
}
Now with ViSP 3.0.0, you should call vpMatrix::getCol() taking a particular attention to the column indices:
crossprod = vpColVector::crossProd(A.getCol(0), A.getCol(1));
Until ViSP 3.0.0 you could stack lines to a matrix using the following code:
#include <visp/vpColVector.h>
#include <visp/vpMatrix.h>
int main()
{
vpMatrix J;
vpColVector L1(6);
vpColVector L2(6);
J = vpMatrix::stackMatrices(L1.t(), L2.t());
Since ViSP 3.0.0, vpMatrix::stackMatrices() is marked as deprecated. You should rather use vpMatrix::stack():
J = vpMatrix::stack(L1.t(), L2.t());
The following code shows how a vpTranslationVector could be added to a vpColVector:
#include <visp/vpTranslationVector.h>
int main()
{
vpTranslationVector center;
vpColVector axis(3);
vpColVector point;
double distance;
point = (vpColVector)center + distance*axis;
}
In ViSP 3.0.1 (the version under development) we add the missing vpTranslationVector::operator+() that allows to remove the cast
point = center + distance*axis;