Visual Servoing Platform  version 3.2.0 under development (2018-08-20)
Tutorial: How to extend ViSP creating a new contrib module

Introduction

ViSP implements a modular architecture where each module:

  • corresponds to a library (.so, .a, .lib, .dll) prefixed with visp_
  • has headers that are grouped in a single folder
  • has dependencies with other modules and at least with the core module
  • may have dependencies with 3rd parties (OpenCV…)

The following image illustrates this modular architecture, where for example the tt_mi (template tracker with mutual information) module depends on the tt (template tracker) module which depends on the vision (computer vision) module that depends at the end on the core module. Note that the gui (graphical user interface) module and the io (input/output) modules are optional.

img-contrib-visp-module.jpg
ViSP modular architecture

In this tutorial you will learn how to extend ViSP architecture introducing new contrib modules.

Note
We assume here that you are familiar with an Installation from source and that you succeed in creating a first project that uses ViSP by following Tutorial: How to create and build a CMake project that uses ViSP on Unix or Windows.

Contribution model

User may contribute to ViSP creating new modules. The following image shows the introduction of two new modules called contrib_1 and contrib_2. They depend on ViSP existing modules.

img-contrib-module.jpg
ViSP architecture extended with new contrib_1 and contrib_2 modules

What about the source tree

Even if it is possible to introduce these new contrib modules in ViSP source code tree, we suggest to separate them in different folders. It will ease ViSP upgrade to future releases avoiding mixing all the source code. In that case, contributions are nothing more than new modules apart from ViSP.

img-contrib-module-tree.jpg
Source tree organization; on the left a folder (visp) that contains ViSP source code, on the right one (visp_contrib) or more other separate folders for the contrib modules

A typical source tree is the following:

$ cd workspace
$ ls
visp visp_contrib

In our previous example, in visp_contrib folder we may have the following tree:

└── visp_contrib
└── modules
├── contrib_1
│   └── ...
└── contrib_2
└── ...

What about the build tree

Even if the source code is located in separate folders, ViSP build mechanism allows to build ViSP and the contrib modules together in a single build tree. Once build contrib modules will be part of ViSP; two libraries named visp_contrib_1 and visp_contrib_2 will be created near ViSP libraries (visp_core, …)

If we come back to our small example, building ViSP with our contrib modules is done with the following command:

$ cd workspace
$ mkdir visp_contrib-build; cd visp_contrib-build
$ cmake -DVISP_CONTRIB_MODULES_PATH=../visp_contrib/modules ../visp

Creating a new contrib module

In ViSP source code you will find a python script in script/create_module.py that allows to create a new module from scratch. The structure of the module created by the script is the following:

<root directory>
|-- <parent name>
|-- modules
|-- <module name>
|-- CMakeLists.txt
|-- include
| |-- visp3
| |-- <module name>
| |-- <class name>.h
|-- src
|-- <class name>.cpp

To know how to use this script, enter in ViSP source tree and run:

$ python script/create_module.py --help

The following instructions allow to create a new module named contrib from scratch in a parent folder named visp_contrib. In this module we will introduce vpContrib.h and vpContrib.cpp files that correspond to vpContrib class implementation and the file test-vpContrib.cpp corresponding to a test that calls vpContrib constructor. There is also a CMakeLists.txt file that allows to build the module and the test.

  • first we have to get ViSP source code
    $ cd workspace
    $ git clone https://github.com/lagadic/visp
    $ ls
    visp
  • then we can create the new module using the script
    $ python visp/script/create_module.py --parent-name=visp_contrib --module-name=contrib --class-name=vpContrib
    $ ls
    visp visp_contrib

The content of the visp_contrib folder is the following:

visp_contrib
└── modules
└── contrib
├── CMakeLists.txt
├── include
│   └── visp3
│   └── contrib
│   └── vpContrib.h
├── src
│   └── vpContrib.cpp
└── test
└── test-vpContrib.cpp

Building a new contrib module

Now we are ready to build this new module.

On a unix-like platform

  • create a new folder to host the build and enter in it
    $ cd workspace
    $ mkdir visp_contrib-build
    $ ls
    visp visp_contrib visp_contrib-build
    $ cd visp_contrib-build
  • now configure the build
    $ cmake -DVISP_CONTRIB_MODULES_PATH=../visp_contrib/modules ../visp
  • finally build the module using
    $ make -j4 visp_contrib
  • you can also build all the modules, tests and examples as usual by
    $ make -j4
  • Run the test:
    $ ./modules/contrib/test-vpContrib
    I’m in my first contrib module

On a windows-like platform

We consider here that the workspace folder is C:/ViSP and that in this folder we have:

$ dir C:\ViSP
visp visp_contrib
  • create a new folder to host the build and enter in it
    $ cd C:\ViSP
    $ mkdir visp_contrib-build
    $ dir
    visp visp_contrib visp_contrib-build
    $ cd visp_contrib-build
  • start cmake-gui
    $ cmake-gui ../visp
    img-contrib-module-1.png
  • press "Configure" button and specify the generator for this project. Here we are using Visual Studio 14 2015 Win64
    img-contrib-module-2.png
  • press "Finish" button
    img-contrib-module-3.png
  • scroll CMake variables list until appearing VISP_CONTRIB_MODULES_PATH var
    img-contrib-module-4.png
  • set this var to C:/ViSP/visp_contrib
    img-contrib-module-5.png
  • press "Configure" button. A new module named visp_contrib is appearing
    img-contrib-module-6.png
  • press "Generate" button.
    img-contrib-module-7.png
  • This ends the CMake configuration stage. Start now Visual Studio and open the C:/ViSP/visp_contrib-build/VISP.sln solution file. As described in Tutorial: Installation from source for Windows with Visual C++ 2015 (vc14) you have now to build ViSP from source.

Advanced contrib module

We provide here after the link to existing contrib modules that use advanced functionalities:

  • https://github.com/lagadic/visp_contrib : contains a module name imgproc that implements various image processing algorithms. In this module you will also find the way to introduce tests
  • https://github.com/lagadic/ustk : a ViSP extension for ultrasound images called UsTK for Ultrasound Toolkit. This extension contains multiple modules. The modules/CMakeLists.txt file allows here to detect optional 3rd parties. It allows also to generate a separate doxygen documentation that contains only the classes part or UsTK. Tutorials and tests are also considered in UsTK.

Next tutorial

You are now ready to see the Tutorial: How to display an image.