Tutorial: How to extend ViSP creating a new contrib module

Table of Contents

• Introduction
• Contribution model
  • What about the source tree
  • What about the build tree
• Creating a new contrib module
• Building a new contrib module
  • On a unix-like platform
  • On a windows-like platform
• Advanced contrib module
• Next tutorial

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.

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.

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.

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

  
• press "Configure" button and specify the generator for this project. Here we are using Visual Studio 14 2015 Win64
  
• press "Finish" button
  
• scroll CMake variables list until appearing VISP_CONTRIB_MODULES_PATH var
  
• set this var to C:/ViSP/visp_contrib
  
• press "Configure" button. A new module named visp_contrib is appearing
  
• press "Generate" button.
  
• 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.