ViSP 2.6.

1: Visual Servoing Platform

Getting Started for Windows

September 6, 2011

Francois Chaumette Eric Marchand Nicolas Melchior Fabien Spindler

CONTENTS

Contents
1 2 3 4 Introduction Where and how downloading ViSP How to build ViSP under Windows How to use ViSP as a third party library under Windows 4.1 How to create a HelloWorld project using ViSP with CMake . . . . . . . . . . . . . . . . . 4.2 How to create a HelloWorld project using ViSP without CMake . . . . . . . . . . . . . . . 4 4 5 7 7 9

Additional information 12 5.1 How to use third party libraries while building ViSP . . . . . . . . . . . . . . . . . . . . . 12 5.2 How to execute ViSP examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

WHERE AND HOW DOWNLOADING VISP

This getting started for Windows is for those who want to use ViSP under Windows and who do not intend to participate in the development of the library. Its goal is to help them to start writing a program using ViSP as a third party library without going into details. It does not replace the ViSP source code documentation which can be consulted on the website: http://www.irisa.fr/lagadic/visp Thereafter, the different steps between the download and the use of the library will be described.

Introduction

Before to download ViSP and try to build it, it is advised to install all the following required programs. You are supposed to have on your computer an IDE (Visual C++, Borland, Eclipse, . . . ) and the last version of CMake which can be found at the address : http://www.cmake.org. As described in section 5.1, some ViSP capabilities require third party libraries to be installed. But they are not required to build ViSP. Dont worry, if you use a function which requires another library you do not have installed yet, you will be warned during the execution of your own program.

Where and how downloading ViSP

First you have to know that there are two ways to download ViSP source code. The simplest one consists in downloading the zip le which can be found at the address: http://www.irisa.fr/lagadic/visp/download.html It contains a release version of the source code. Unzip the package in the folder of your choice and go directly to Section 3. The other way to recover ViSP is to download it from Subversion repository hosted on InriaGForge http://gforge.inria.fr/projects/visp/. Subversion is a tool for a team of developers which enable to manage the source code during the development process. The advantage is that you can have the current development version of the code. The drawback is that it is not necessary stable and the last functions could be not documented yet. Prior to download something from Subversion repository you have to install a Subversion client like TortoiseSVN, either Slik Subversion or Subversion package from Cygwin. Then you can use the following address to recover ViSP by checking out the source code les: svn://scm.gforge.inria.fr/svn/visp/trunk/ViSP Regardless the method you used to download ViSP, you have now a version of the source code which must be build to be used.

How to build ViSP under Windows

Now, the step consists in preparing the build by creating a project or a makele depending on your IDE. It will be done thanks to CMake. 1. Execute CMake to get the GUI presented Figure 1. 2. In the rst box "Where is the source code" (see Fig. 1) you have to set the path to the folder which contains the ViSP source code. 3. In the second box "Where to build the binaries" (see Fig. 1) set the path to the folder you choose to contain ViSP binaries obtained after the build stage described at step 6. If it doesnt exist yet, it will be created automatically. Let us denote this path as VISP_BUILD_DIR. An advice is to choose two different folders, one for the source code and another one for the build version. There are two advantages to do this. Firstly, the folder which contains the source code will not be contaminated by les created by CMake. So, if you want to modify ViSP it will be easier. Secondly, it allows to have more than one build version of ViSP. Indeed, it exists numerous possibilities to build it depending on the third party libraries you are using. So you could use the version which matches the best to your own project. 4. Click on the "Congure" button (see Fig. 1). The IDE you want to use will be asked. You have to indicate it in order to enable CMake to create the right project conguration les. Continue to click on "Congure" until the "Generate" button becomes active. During this step you are allowed to modify any options. Figure 2 shows for example how to print advanced options that can be modied like the CMAKE_INSTALL_PREFIX variable used to specify where ViSP will be installed. 5. After clicking on "Congure", you will be allowed to click on "Generate" (see Fig. 2). CMake will create the useful conguration les in the folder you indicate in the box "Where to build the binaries". Now you are allowed to build ViSP binaries corresponding to the library and the examples.

Figure 1: CMake GUI obtained with CMake 2.8 that allows to congure ViSP on your computer.

HOW TO BUILD VISP UNDER WINDOWS

Figure 2: This CMake snapshot shows where to set the CMAKE_INSTALL_PREFIX variable specifying the directory where ViSP will be installed after the build. By default, this variable is set to C:/Program Files/VISP. As shown Fig. 10, this snapshot shows also the location of the menu that allows to print more advanced options like the location of third party headers and libraries.

7 6. Open the project le which has been created by CMake. For example if you are using Microsoft Visual Studio 2008, its name is VISP.sln. The screenshot Fig. 3 comes from this IDE but you will nd similar things with others.

Figure 3: VISP.sln Visual Studio solution le created by CMake opened with Microsoft Visual Studio 2008. To build ViSP library and all the examples select the ALL_BUILD project. To install ViSP headers and library in the directory corresponding to the CMAKE_INSTALL_PREFIX variable select and build the INSTALL project. To build the HTML documentation select and build the html-doc project. 7. The last thing you have to do is to build the ALL_BUILD project (see Fig. 3). Thus the library will be created and the examples will be compiled. The binaries will be contained in the folder you indicate in the box "Where to build the binaries". You can also build the INSTALL project which will install the ViSP headers and library in the path corresponding to the CMAKE_INSTALL_PREFIX (by default set to C:/Program Files/VISP). You are allowed to modify this installation path during step 4. In order to produce the HTML documentation with Doxygen, you can build the html-doc project. The documentation entry point is than VISP_BUILD_DIR/doc/html/index.html.

4
4.1

How to use ViSP as a third party library under Windows

In this section you will learn how to create a HelloWorld Visual Studio project using ViSP as a third party library. This step is very simple if you still use CMake to congure your project. 1. First you have to create a folder where you want to put the HelloWorld project. 2. Then create inside this folder the HelloWorld.cpp le you want to build and a text le called CMakeLists.txt that corresponds to the HelloWorld conguration le that will be used by CMake. The following simple example shows you to ll in these les 1 .
HelloWorld.cpp : HelloWorld.cpp and CMakeLists.txt example/manual/hello-world/CMake directory.
1

les

are

available

in

ViSP

source

tree

in

HOW TO USE VISP AS A THIRD PARTY LIBRARY UNDER WINDOWS

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

#include <iostream> #include <visp/vpDebug.h> #include <visp/vpImage.h> #include <visp/vpImageIo.h> int main() { std::cout << "ViSP Hello World example" <<std::endl; vpImage<unsigned char> I(288, 384); I = 128; std::cout << "ViSP creates \"./myimage.pgm\" B&W image " <<std::endl; vpImageIo::write(I, "./myimage.pgm"); return 0; }

CMakeLists.txt :
1 2 3 4 5 6 7 8 9 10

PROJECT(HelloWorld) CMAKE_MINIMUM_REQUIRED(VERSION 2.6) FIND_PACKAGE(VISP REQUIRED) IF(VISP_FOUND) INCLUDE(${VISP_USE_FILE}) ENDIF(VISP_FOUND) ADD_EXECUTABLE(HelloWorld HelloWorld.cpp)

3. Then, start CMake to congure the HelloWorld project (see Fig. 4). 4. In the rst box "Where is the source code" (see Fig. 4), indicate the path to your source code (ie the path to the folder you created in step 1). 5. In the second box "Where to build the binaries" (see Fig. 4), indicate where you want to build the binaries corresponding to your project. 6. You can now click on "Congure" (see Fig. 4). If CMake says that it cant nd the ViSP library (VISP_DIR variable is than set to VISP_DIR-NOTFOUND, see Fig. 4), you may indicate the path to the folder containing a build version of ViSP. More precisely, you have to give the path to the ViSPConfig.cmake le. Typically, you can nd it in VISP_BUILD_DIR (replace VISP_BUILD_DIR with the path to the folder where you build ViSP, see Section 3, step 3). If you install ViSP (see Section 3, step 7), you can also set VISP_DIR to the following path C:/Program Files/VISP. 7. Then click on "Congure" until having the right to click on "Generate" button (see Fig. 4). It is the same as for ViSP. CMake will create a project for your own IDE. You need now to download the project (in our case the HelloWorld.sln Visual Studio solution le) in your IDE to build the binaries. The advantage to use CMake is that all the links are automatically done and especially with the third party libraries on which ViSP is depending.

4.2

How to create a HelloWorld project using ViSP without CMake

Figure 4: CMake based conguration of the HelloWorld project that uses ViSP as a third party library.

4.2

How to create a HelloWorld project using ViSP without CMake

It is also possible to develop your project using ViSP as a third party library without the help of CMake. In such a case, you have to set the properties of your project with additional include directories, preprocessor denitions, library directories and library dependencies. In order to help users, ViSP provides a visp-config.bat batch le that may give the additional properties values. This le is produced during CMake conguration (see Section 3, step 4) and is located in VISP_BUILD_DIR/bin directory. If you install ViSP (see Section 3, step 7), you will also found this le in C:/Program Files/VISP/bin. The usage of this batch le is given by "visp-config.bat --help" executed in a DOS command window. The following steps explain how to set the properties of a HelloWorld project using the visp-config.bat outputs. Once your project is created, with Visual Studio you may edit its properties. 1. Setting additional include directories: The rst thing you have to do is to indicate the folders containing the headers belonging to ViSP and the third party libraries used to build ViSP (see Fig. 5). Note that the include directory for the ViSP library is "VISP_BUILD_DIR/include". If you install ViSP (see Section 3, step 7), the include directory for the ViSP library is rather C:/Program Files/VISP/include. To get all the additional include directories you can copy 2 the result of the "visp-build.bat --include" command executed in a DOS command window and paste it in the box "Conguration PropertiesC/C++General Additional include directories". Note that the result of this command contains already ViSP include directory. 2. Setting additional preprocessor denitions: At least you need to add the WIN32 preprocessor de2 Tip: To copy/past the output of the visp-build.bat command we suggest to redirect the output in a text le by executing for example "visp-build.bat --include > include.txt". The resulting include.txt le can than be opened in the Wordpad from which the copy/past can be done easily.

10

HOW TO USE VISP AS A THIRD PARTY LIBRARY UNDER WINDOWS

Figure 5: This Visual Studio snapshot shows where to set the additional include directories requested to build the HelloWorld project using ViSP as a third party library. The list of additional include directories may be obtained by executing "visp-config.bat --include" in a DOS command window.

nition. To get all the requested additional preprocessor denitions you can copy1 the result of "visp-build.bat --def" command executed in a DOS command window and paste it in the box "Conguration PropertiesC/C++PreprocessorPreprocessor Denitions" as shown Figure 6. Note that the result given by the .bat le contains already the WIN32 preprocessor denition. 3. Setting additional library directories: To set all the additional library directories you can copy1 the result of "visp-build.bat --libpath" command executed in a DOS command window and paste it in the box "Conguration PropertiesLinkerGeneralAdditional Library Directories" as shown Figure 7. Note that ViSP library path is "VISP_BUILD_DIR/lib/${Outdir}" with ${Outdir} equal to Debug or Release depending on your HelloWorld conguration. If you install ViSP (see Section 3, step 7), ViSP library path is rather C:/Program Files/VISP/lib. In all the cases, the result of this command contains already ViSP library directory.

4. Setting additional library dependencies : ViSP library name is visp-2.lib. You may also add winmm.lib library which is used in ViSP for time management. Dependeing on your conguration (debug or release), to set all the additional libraries HelloWorld depends on, you can copy1 the result of "visp-build.bat --libs-debug" or "visp-build.bat --libs-optimized" command executed in a DOS command window and paste it in the box "Conguration PropertiesLinkerInputAdditional Dependencies" as shown Figure 8. Note that the result given by the .bat le contains already the winmm.lib library.

4.2

How to create a HelloWorld project using ViSP without CMake

11

Figure 6: This Visual Studio snapshot shows where to set the additional preprocessor denitions requested to build the HelloWorld project using ViSP as a third party library. The list of additional preprocessor denitions may be obtained by executing "visp-config.bat --def" in a DOS command window.

Figure 7: This Visual Studio snapshot shows where to set the additional library directories requested to build the HelloWorld project using ViSP as a third party library. The list of additional library directories may be obtained by executing "visp-config.bat --libpath" in a DOS command window.

12

ADDITIONAL INFORMATION

Figure 8: This Visual Studio snapshot shows where to set the additional library dependencies requested to build the HelloWorld project using ViSP as a third party library. The list of additional library dependencies may be obtained by executing "visp-config.bat --libs" in a DOS command window.

5
5.1

Additional information
How to use third party libraries while building ViSP

Many functionalities of ViSP require third party libraries. This is in particular the case for simulation, framegrabbing, and video-devices capabilities that require respectively Coin and SoWin, Directshow and the Graphics Device Interface (GDI). If you want to know the entire list of third party libraries that can be used in ViSP you can get the information on ViSP website. If you are interested to know which are the third party libraries used to build ViSP on your computer, you can rst check the ViSP-third-party.txt text le produced during the CMake conguration stage described in Section 3, step 4. This le is generated in VISP_BUILD_DIR directory. Figure 9 shows and example of such a ViSP-third-party.txt le content. An other way to check which are the third party libraries that will be used while building ViSP, is to choose the "Advanced View" option in CMake GUI to have access to the CMake variables as it is shown in the screenshot Fig. 10. If you are sure you install a third party library which is noted as NOT_FOUND, it seems that you installed it in a not common folder. So you have the choice to set an environment variable to indicate the path to the library. Table 1 gives the list of the environment variables corresponding to the third party libraries. CMake detects automatically the available third party libraries on your computer. But for some reasons, you may not want to build ViSP with all the detected libraries. You can disable these libraries during

5.1

How to use third party libraries while building ViSP

13

Figure 9: Example of the ViSP-third-party.txt le content that indicates which are the third party libraries detected by CMake and used to build ViSP library on your computer.

14

ADDITIONAL INFORMATION

Figure 10: This CMake snapshot shows how to verify if third party libraries are taken into account while building ViSP. If "Advanced View" is chosen in the menu you will get access to all CMake variables that correspond to the location of third party headers and libraries. A variable set to NOT_FOUND indicates that the corresponding third party library is not found. the CMake conguration (see Section 3, step 3). Indeed there are options named USE_THIRD_PARTY (see Figure 11) which appear. In that case, THIRD_PARTY is the name of the third party library which is automatically detected. To disable one of the third party library, uncheck the corresponding option (by default they are all checked).

5.2

How to execute ViSP examples

Some ViSP examples require data like images or videos as input. They can be downloaded on ViSP website. After download and unzip, you have to set the environment variable VISP_INPUT_IMAGE_PATH in the Windows Control Panel. It must be set to the parent directory containing the unzip data. For example, if you download the ViSP-images-2.6.1.zip le and unzip it in the folder C:/images, you will get a new folder named C:/images/ViSP-images containing the data. You need than to set the environment variable VISP_INPUT_IMAGE_PATH to C:/images. Now you should be able to execute the examples that request input data.

5.2

How to execute ViSP examples

15

ViSP capabilities Display

Matrix computation Computer vision Frame grabbing

Simulator

Camera parameters parser HTML documentation Image reading and writing

Third party library Direct3D GDI GTK2 OpenCV Lapack GSL OpenCV Directshow OpenCV Ogre OIS Coin SoQt Qt Coin SoWin XML2 iconv Doxygen Graphviz libjpeg libpng

Corresponding environment variable

none
COIN_DIR or COINDIR COIN_DIR or COINDIR or SOQT_DIR QTDIR COIN_DIR or COINDIR COIN_DIR or COINDIR or SOWIN_DIR XML2_DIR XML2_DIR or ICONV_DIR DOXYGEN_DIR GRAPHVIZ_DIR LIBJPEG_DIR LIBPNG_DIR

Table 1: List of environment variables that can be set throw the Windows Control Panel to help CMake to detect third party libraries that may be used to build ViSP.

16

ADDITIONAL INFORMATION

Figure 11: This CMake snapshot shows were you can nd the options used to enable or disable the detected third party libraries.