Visual Servoing Platform
version 3.6.1 under development (2024-10-09)
|
This tutorial gives some guide lines to explain how to introduce a new class that depends on an external 3rd-party that has its own SDK.
We suppose here that you followed one of the Installation from source code tutorials.
Let us consider the case where we want to implement a new class with name vpDummyWrapper
that belongs to visp_robot
module and that is a wrapper over a 3rd-party SDK called DummySDK
. This SDK contains headers and libraries that are organized like:
To illustrate this tutorial, let us consider that <dummy sdk root path>
is equal to /home/user/visp-ws/3rdparty/dummy-sdk
folder.
In order that ViSP remains cross-platform, here we should consider that this dummy SDK is used only if VISP_HAVE_DUMMY_SDK
macro is defined. We suppose here that this macro is automatically defined (or not) in visp3/core/vpConfig.h
file that is located in ViSP build tree, more precisely in $VISP_WS/visp-build/include
folder.
The class declaration is implemented in vpDummyWrapper.h
. Since we want that the class belongs to visp_robot
module, you have to put this file in $VISP_WS/visp/modules/robot/include/visp3/robot/
folder. The content of this file looks like:
The corresponding class definition is implemented in vpDummyWrapper.cpp
located for example in a new folder dummy_sdk
that belongs to visp_robot
module like $VISP_WS/visp/modules/robot/src/real-robot/dummy_sdk/vpDummyWrapper.cpp
:
DummySDK
package. To this end you should introduce FindDummySDK.cmake
file in ViSP cmake
folder. The content of $VISP_WS/visp/cmake/FindDummySDK.cmake
looks like: $VISP_WS/visp/CMakeLists.txt
CMake root file to call FindDummySDK.cmake
. This is done adding a line like: $VISP_WS/visp/CMakeLists.txt
add also a line like: DUMMYSDK_HOME
environment variable and run cmake over ViSP source code. On unix-like OS, this could be achieved running: DummySDK
package is found by CMake: [t]
key, you should be also able to see the following lines that indicate the full path to DummySDK
headers folder and library: Now you should modify ViSP source code to define VISP_HAVE_DUMMY_SDK
macro when DummySDK
package is found. We recall that this macro is used to protect the class that should be build only if this macro is defined.
$VISP_WS/visp/CMakeLists.txt
CMake root file to add a line like: $VISP_WS/visp/cmake/templates/VISPConfig.cmake.in
to set VISP_HAVE_DUMMY_SDK
as a CMake var that could be used later in all CMakeFiles.txt
files that are using ViSP as 3rd-party: $VISP_WS/visp/cmake/templates/vpConfig.h.in
to set VISP_HAVE_DUMMY_SDK
as a C++ compiler macro that could be used later in all *.h
header and *.cpp
source files: $VISP_WS/visp/doc/config-doxygen.in
to set VISP_HAVE_DUMMY_SDK
as a predefined macro for Doxygen. It allows to see vpDummySDK
class in generated Doxygen documentation: VISP_HAVE_DUMMY_SDK
macro is correctly set after CMake configuration in $VISP_WS/visp-build/include/visp3/core/vpConfig.h
. To this end, under linux-like OS run simply: DummySDK
is well detected: VISP_HAVE_DUMMY_SDK
macro in $VISP_WS/visp-build/include/visp3/core/vpConfig.h
generated file: $VISP_WS/visp/modules/robot/include/visp3/robot/vpDummyWrapper.h
that contains vpDummyWrapper
class declaration.#ifndef vpDummyWrapper_h #define vpDummyWrapper_h #include <visp3/core/vpConfig.h> #ifdef VISP_HAVE_DUMMY_SDK #include <dummy_sdk_header.h> /*! \class vpDummyWrapper Dummy wrapper example. */ class VISP_EXPORT vpDummyWrapper { public: vpDummyWrapper(); virtual ~vpDummyWrapper(); ... }; #endif #endifwhere
VISP_HAVE_DUMMY_SDK
macro is used to ensure that the build doesn't fail when DummySDK
package is not detected or not used. There is also the "\class" Doxygen directive that allows to expose vpDummyWrapper
class in Doxygen documentation that is generated using make visp_doc
.$VISP_WS/visp/modules/robot/src/real-robot/dummy_sdk/vpDummyWrapper.cpp
that contains vpDummyWrapper
class definition.#include <visp3/robot/vpDummyWrapper.h> #ifdef VISP_HAVE_DUMMY_SDK /*! Default constructor. */ vpDummyWrapper::vpDummyWrapper() {} /*! Default destructor. */ vpDummyWrapper::~vpDummyWrapper() {} #endif
vpDummyWrapper
appearing in the class list and class index: $VISP_WS/visp-build/doc/html/classes.html
to see the new class in the class index.vpDummyWrapper.h
and vpDummyWrapper.cpp
files that belong to visp_robot
module tree by making a link to DummySDK
headers and library. This is simply achieved in visp_robot
root CMakeLists.txt
file adding the following lines in $VISP_WS/visp/modules/robot/CMakeLists.txt: visp_robot
module modules/robot/dummy
folder and add the following file in $VISP_WS/visp/modules/robot/test/dummy/testDummySDK.cpp
which contains for example: //! \example testForceTorqueIitSensor.cpp #include <iostream> #include <visp3/robot/vpDummyWrapper.h> int main() { #ifdef VISP_HAVE_DUMMY_SDK vpDummyWrapper wrapper; ... #else std::cout << "ViSP is not build with DummySDK support" << std::endl; #endif return EXIT_SUCCESS; }
$VISP_WS/visp/modules/robot/CMakeLists.txt
file adding a CTEST_EXCLUDE_FILE
parameter to vp_add_tests()
cmake function: Here we explain how to introduce a new example in ViSP example folder.
$VISP_WS/visp/example/servo-dummy
folder that contains exampleDummy.cpp
file: //! \example exampleDummy.cpp #include <iostream> #include <visp3/robot/vpDummyWrapper.h> int main() { #ifdef VISP_HAVE_DUMMY_SDK vpDummyWrapper wrapper; ... #else std::cout << "ViSP is not build with DummySDK support" << std::endl; #endif return EXIT_SUCCESS; }
CMakeLists.txt
file that allows to build this new example: visp_core
and visp_robot
are the required modules that need to be linked with to build this example. The list of required module could be extended by simply adding the visp_<module>
name after the REQUIRED
keyword.$VISP_WS/visp/example/CMakeLists.txt
to indicate that CMake has to parse the new folder called dummy
that contains the new example: dummy
folder only if all the required modules are enabled during CMake configuration step.This sections explains how to add a new Doxygen tutorial like this one, that may appear in ViSP main page documentation
$VISP_WS/visp/doc/tutorial/robot/dummy/tutorial-dummy-robot.doc
that may contain something like: /**\page tutorial-dummy-robot Tutorial: How to start with dummy robot \tableofcontents \section dummy_intro Introduction Bla Bla... */
tutorial-dummy-robot
in ViSP main page documentation modifying $VISP_WS/visp/doc/mainpage.dox.in
, either adding as bellow a new section (here called "Playing with robots"), either introducing the reference to this new page in an existing section: \subsection tuto_robot Playing with robots \ref tutorial-dummy-robot <br>This tutorial explains how to start with dummy robot.
$VISP_WS/visp/doc/tutorial/tutorial.doc
: /*! \page tutorial_mainpage Tutorials This page references all the tutorials. ... \subpage tutorial_robot */ /*! \page tutorial_robot Playing with robots This page introduces the way toplay with robots. \subpage tutorial-dummy-robot <br>This tutorial explains how to start with dummy robot. */
$VISP_WS/visp-build/doc/html/tutorial-dummy-robot.html
in Firefox or any other browser to see the corresponding tutorial.We suppose here that you Modify ViSP source code and that you want to create your own external project that uses the new dummyWrapper
class. This as simple as adding a new example inside ViSP as described in Add a new example.
$VISP_WS/my-project
that may contain your main example and a CMakeLists.txt
file. They could be simply the same as the one described in Add a new example section: //! \example exampleDummy.cpp #include <iostream> #include <visp3/robot/vpDummyWrapper.h> int main() { #ifdef VISP_HAVE_DUMMY_SDK vpDummyWrapper wrapper; ... #else std::cout << "ViSP is not build with DummySDK support" << std::endl; #endif return EXIT_SUCCESS; }
VISP_DIR
var: Bellow we give a list of some Pull Request to illustrate this tutorial with real use cases: