tutorial-install-centos.doc

/**

\page tutorial-install-centos Tutorial: Installation from source for Linux CentOS
\tableofcontents

In this tutorial you will learn how to install ViSP from source on CentOS. These steps have been tested with CentOS 8.1 (x86_64), but should work with any other distribution as well. 

\note Concerning ViSP installation, we provide also other \ref tutorial.

\section install_centos_required Install prerequisites

Prior to build and install ViSP from source, you may install GNU g++ compiler, CMake, git and subversion. This can be achieved running:
\code
$ sudo yum install gcc-c++ make cmake git subversion wget
\endcode

\section install_centos_ws Create a workspace

First create a workspace that will contain all ViSP source, build, data set and optional 3rd parties. This workspace is here set to `$HOME/visp-ws` folder, but it could be set to any other location.

In a terminal, run:
\code
$ echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc
$ source ~/.bashrc
$ mkdir -p $VISP_WS
\endcode

\section install_centos_quick Quick ViSP installation

In this section, we give minimal instructions to build ViSP from source just to try ViSP without entering in \ref install_centos_advanced.

- Install a small number of recommended 3rd parties
\code
$ sudo yum install opencv-devel libX11-devel lapack-devel libv4l-devel libjpeg-devel libpng-devel
\endcode

- Get ViSP source code
\code
$ cd $VISP_WS
$ git clone https://github.com/lagadic/visp.git
\endcode

- Create a build folder and build ViSP
\code
$ mkdir -p $VISP_WS/visp-build
$ cd $VISP_WS/visp-build
$ cmake ../visp
$ make -j4
\endcode

- Set `VISP_DIR` environment variable
\code
$ echo "export VISP_DIR=$VISP_WS/visp-build" >> ~/.bashrc
$ source ~/.bashrc
\endcode

To have a trial, just jump to \ref install_centos_dataset before running some binaries that you just build or jump to \ref install_centos_next. You can later come back to the \ref install_centos_advanced.

\section install_centos_advanced Advanced ViSP installation

\subsection install_centos_3rdparty Install 3rd parties

ViSP is interfaced with several 3rd party libraries. The <a href="http://visp.inria.fr/software-architecture">complete list is provided here</a>.

\note ViSP can be used without any third-party since all of them are optional. But obviously in this case, as we do not want to reinvent the wheel, some features implemented in third-party libraries will not be exploitable through ViSP. It is therefore possible to skip in a first time this section and start directly to \ref install_centos_quick. Later, if you realize that a third-party library is missing, you can still install it, go back to the build folder, configure ViSP with CMake to detect the newly installed third-party library and build ViSP again as explained in \ref install_centos_tips_new_3rdparty.

\subsubsection install_centos_3rdparty_recommended Recommended 3rd parties

We recommend to install the following:

- OpenCV
- libX11 to be able to open a window to display images
- lapack and eigen to benefit from optimized mathematical capabilities
- libdc1394 to grab images from firewire cameras
- libv4l to grab images from usb or analogic cameras

Installation of recommended 3rd parties could be performed running:
\code
$ sudo yum install opencv-devel libX11-devel lapack-devel libv4l-devel
\endcode

\subsubsection install_centos_3rdparty_other Other optional 3rd parties

We give also the way to install other 3rd party libraries to enable specific capabilities.

- libjpeg and libpng to support jpeg and png images respectively (only useful if OpenCV is not installed)
\code
$ sudo yum install libjpeg-devel libpng-devel
\endcode

\subsection install_centos_get_source Get ViSP source code

There are different ways to get ViSP source code:

- You can download the <a href="http://visp.inria.fr/download">latest release</a> as a zip or a tarball. Once downloaded, uncompress the file using either
\code
$ tar xvzf visp-x.y.z.tar.gz -C $VISP_WS
\endcode
or
\code
$ unzip visp-x.y.z.zip -d $VISP_WS
\endcode

- You can also download a <a href="http://visp.inria.fr/download#snapshot">daily snapshot</a>. Once downloaded, uncompress the file using
\code
$ tar xvzf visp-snapshot-yyyy-mm-dd.tar.gz -C $VISP_WS
\endcode

- Or you get the cutting-edge ViSP from <a href="https://github.com/lagadic/visp">GitHub repository</a> using the following command
\code
$ cd $VISP_WS
$ git clone https://github.com/lagadic/visp.git
\endcode

We suppose now that ViSP source is in the directory `$VISP_WS/visp`. The following should be adapted if you downloaded ViSP from a zip or tarball. In that case, the source is rather in something like `$VISP_WS/visp-x.y.z`.

\subsection install_centos_config Configure ViSP from source

These are the steps to configure ViSP from source with CMake:

- In the workspace, create first a directory named `visp-build` that will contain all the build material; generated Makefiles, object files, output libraries and binaries.
\code
$ mkdir $VISP_WS/visp-build
\endcode

- Enter the `visp-build` folder and configure the build:
\code
$ cd $VISP_WS/visp-build
$ cmake ../visp
\endcode
A more versatile way to configure the build is to use `ccmake`, the CMake GUI:
\code
$ ccmake ../visp
\endcode
The following image shows that this command allows to configure (just by pressing [c] key) the build in a more advanced way where some options could be easily turned ON/OFF. It allows also to see which are the 3rd parties that will be used. To generate the makefiles, just press [g] key in the ccmake gui.
\image html img-ccmake-centos-all.jpg Snapshot of the `ccmake ../visp command used to configure ViSP.

\subsection install_centos_build Build ViSP libraries

To build ViSP libraries proceed with:
\code
$ cd $VISP_WS/visp-build
$ make -j4
\endcode

\subsection install_centos_doc Build ViSP documentation

To build ViSP documentation, you have first to install Doxygen package:
\code
$ sudo yum install doxygen graphviz
\endcode
Then you can proceed with:
\code
$ cd $VISP_WS/visp-build
$ cmake ../visp
$ make -j4 visp_doc
\endcode
The generated documentation is then available in `$VISP_WS/visp-build/doc/html/index.html`

\note It is also possible to generate a more complete documentation that includes also all the internal classes. This could be achieved setting CMake var `ENABLE_FULL_DOC` to `ON` like:
\code
$ cmake ../visp -DENABLE_FULL_DOC=ON
$ make -j4 visp_doc
\endcode

\subsection install_centos_visp_dir Set VISP_DIR environment var

In order to ease ViSP detection by CMake when ViSP is used as a 3rd party in an external project, like the one described in the \ref tutorial-getting-started, you may set `VISP_DIR` environment variable with the path to the `VISPConfig.cmake` file:
\code
$ echo "export VISP_DIR=$VISP_WS/visp-build" >> ~/.bashrc
$ source ~/.bashrc
\endcode

\section install_centos_dataset Install ViSP dataset

Some ViSP examples and tests require a data set that contains images, video, models that is not part of ViSP source code. This data set is available in Github (https://github.com/lagadic/visp-images) or as a release in a separate archive named `visp-images-x.y.z.zip`. This archive could be downloaded from http://visp.inria.fr/download page. Note that ViSP tutorials are not using ViSP data set.

We give hereafter the two ways to get this data set:

<b>1. Get data set release</b>

- Download `visp-images-3.3.0.zip` from https://visp.inria.fr/download and uncompress it in your workspace `%%VISP_WS%`:
\code
$ unzip ~/Downloads/visp-images-3.2.0.zip -d $VISP_WS
\endcode
- We suppose now that the data are located in `$VISP_WS/visp-images-3.3.0`.
\code
$ ls $VISP_WS/visp-images-3.3.0
3dmodel	   LICENSE.txt    circle     ellipse-1    iv      mbt-depth     video
AprilTag   README.md      cube       endianness   line    mire          warp
Klimt      calibration    ellipse    faces        mbt     mire-2        xml
\endcode
- Once downloaded, you need to set `VISP_INPUT_IMAGE_PATH` environment variable to help ViSP examples and tests to detect automatically the location of the requested data. In our case, this variable should be set to `$VISP_WS/visp-images-3.3.0`. It is more convenient if this environment variables is automatically added to your bash session every time a new shell is launched: 
\code
$ echo "export VISP_INPUT_IMAGE_PATH=$VISP_WS/visp-images-3.3.0" >> ~/.bashrc
$ source ~/.bashrc
\endcode

<b>2. Get data set from github</b>

- Use git to get the data set latest version:
\code
C:\> cd $VISP_WS
C:\> git clone https://github.com/lagadic/visp-images.git
\endcode
- Once cloned, you need to set `VISP_INPUT_IMAGE_PATH` environment variable to help ViSP examples and tests to detect automatically the location of the requested data. In our case, this variable should be set to `$VISP_WS%/visp-images`. In a shell run:
\code
$ echo "export VISP_INPUT_IMAGE_PATH=$VISP_WS/visp-images" >> ~/.bashrc
$ source ~/.bashrc
\endcode

<b>Test data set usage</b>

- From now, you can try to run ViSP examples and tests. For example you can run `displayX` example that should open a windows with Klimt painting image and some overlay drawings:
\code
$ cd $VISP_WS/visp-build
$ ./example/device/display/displayX

A click to close the windows...

A click to display a cross...
Cross position: 201, 441

A click to exit the program...
Bye
\endcode

\section install_centos_tips Tips and tricks

\subsection install_centos_tips_new_3rdparty How to take into account a newly installed 3rd party

Since all 3rd parties are optional you may have started to install only some of them. Imagine that you just installed a new third-party, or that you upgraded the version of this 3rd party. The next step is to go back to the build folder, configure ViSP with CMake to detect the newly installed third-party library and build again ViSP. This could be achieved with:
\code
$ cd $VISP_WS/visp-build
$ cmake ../visp
\endcode

Here you can check the content of the `ViSP-third-party.txt` file and see if the newly installed 3rd party is well detected (see \ref install_centos_tips_3rd_party).

Finally, you need to rebuild ViSP with:
\code
$ make -j4
\endcode

\subsection install_centos_tips_install How to install ViSP

Installing ViSP is optional and not recommended, since ViSP could be used as a 3rd party without installation. If you still want to proceed with the installation run:
\code
$ cd $VISP_WS/visp-build
$ sudo make install
\endcode
\note The default install location is set to `/usr/local`. This location could be changed modifying `CMAKE_INSTALL_PREFIX` var:
\code
$ cd $VISP_WS/visp-build
$ cmake ../visp -DCMAKE_INSTALL_PREFIX=/usr
$ make -j4
$ sudo make install
\endcode

\note If you proceed to ViSP installation in a system folder like `/usr` or `/usr/local` there is no need to \ref install_centos_visp_dir that helps CMake to find ViSP libraries in an external project that uses ViSP as a 3rd party. If you rather install ViSP in a non "standard" folder, let say `/my/install/folder`, you have to set `VISP_DIR` to `/my/install/folder/lib/cmake/visp` that contains the `VISPConfig.cmake` file:
\code
$ cd $VISP_WS/visp-build
$ cmake ../visp -DCMAKE_INSTALL_PREFIX=/my/install/folder
$ make -j4
$ sudo make install
$ echo "export VISP_DIR=/my/install/folder/lib/cmake/visp" >> ~/.bashrc
$ source ~/.bashrc
\endcode

\subsection install_centos_tips_uninstall How to uninstall ViSP
After ViSP installation, you can remove installed material using:
\code
$ cd $VISP_WS/visp-build
$ sudo make uninstall
\endcode

\subsection install_centos_tips_modules How to build only ViSP libraries

If you want to build only ViSP modules libraries, nor the examples, tutorials and tests:
\code
$ make -j4 visp_modules
\endcode

\subsection install_centos_tips_module_once How to build a ViSP specific module

If you want to build a given module and all the dependencies:
\code
$ cd $VISP_WS/visp-build
$ make -j4 visp_<module_name>
\endcode

For example to build the model-based tracker module named mbt, run:
\code
$ make -j4 visp_mbt
\endcode

\subsection install_centos_tips_target Which are the targets that could be run with make ?

To know which are the target available with `make`:
\code
$ make help | grep visp
... visp_tutorials
... visp_tests
... visp_modules
... visp_doc
... visp_examples
... visp_demos
... visp_clipper
... visp_apriltag
... visp_core
... visp_gui
... visp_imgproc
... visp_io
... gen_visp_java_source
... visp_klt
... visp_me
... visp_sensor
... visp_ar
... visp_blob
... visp_robot
... visp_visual_features
... visp_vs
... visp_vision
... visp_detection
... visp_mbt
... visp_tt
... visp_tt_mi
\endcode

\subsection install_centos_tips_3rd_party Which are the 3rd party libraries that are used in ViSP ?

To see which are the optional 3rd parties that are found during the configuration stage and that will be used by ViSP during the build you can have a look to the text file named `ViSP-third-party.txt` and located in `$VISP_WS/visp-build`. We provide hereafter an example of a possible content of this file:
\code
==========================================================
General configuration information for ViSP 3.3.0

  Version control:               3.2.0-822-gf511da75d

  Platform:
    Timestamp:                   2020-02-12T16:47:33Z
    Host:                        Linux 4.18.0-147.el8.x86_64 x86_64
    CMake:                       3.11.4
    CMake generator:             Unix Makefiles
    CMake build tool:            /usr/bin/gmake
    Configuration:               Release

  C/C++:
    Built as dynamic libs?:      yes
    C++ Compiler:                /usr/bin/c++  (ver 8.3.1)
    C++ flags (Release):         -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O2 -DNDEBUG
    C++ flags (Debug):           -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
    C Compiler:                  /usr/bin/cc
    C flags (Release):           -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O2 -DNDEBUG
    C flags (Debug):             -Wall -Wextra -fopenmp -std=c++11 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
    Linker flags (Release):
    Linker flags (Debug):

  ViSP modules:
    To be built:                 core gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi
    Disabled:                    -
    Disabled by dependency:      -
    Unavailable:                 java

  Python (for build):            /usr/bin/python3

  Java:                          
    ant:                         NO
    JNI:                         NO

  Build options: 
    Build deprecated:            yes
    Build with moment combine:   no

  Mathematics: 
    Use MKL:                     no
    Use OpenBLAS:                no
    Use Atlas:                   no
    Use Netlib Lapack:           no
    Use Lapack (built-in):       yes (ver 3.2.1)
    Use Eigen3:                  no
    Use OpenCV:                  no
    Use GSL:                     no

  Simulator: 
    Ogre simulator: 
    \- Use Ogre3D:               no
    \- Use OIS:                  no
    Coin simulator: 
    \- Use Coin3D:               no
    \- Use SoWin:                no
    \- Use SoXt:                 no
    \- Use SoQt:                 no
    \- Use Qt5:                  no
    \- Use Qt4:                  no
    \- Use Qt3:                  no

  Media I/O: 
    Use JPEG:                    yes (ver 62)
    Use PNG:                     yes (ver 1.6.34)
    \- Use ZLIB:                 yes (ver 1.2.11)
    Use OpenCV:                  no
    Use stb_image (built-in):    no

  Real robots: 
    Use Afma4:                   no
    Use Afma6:                   no
    Use Franka:                  no
    Use Viper650:                no
    Use Viper850:                no
    Use aria (Pioneer):          no
    Use PTU46:                   no
    Use Biclops PTU:             no
    Use Flir PTU SDK:            no
    Use Parrot ARSDK:            no
    \-Use ffmpeg:                no
    Use Virtuose:                no
    Use qbdevice (built-in):     yes (ver 2.6.0)

  GUI: 
    Use X11:                     yes
    Use GTK:                     no
    Use OpenCV:                  no
    Use GDI:                     no
    Use Direct3D:                no

  Cameras: 
    Use DC1394-2.x:              no
    Use CMU 1394:                no
    Use V4L2:                    no
    Use directshow:              no
    Use OpenCV:                  no
    Use Flycapture:              no
    Use Pylon:                   no

  RGB-D sensors: 
    Use Realsense:               no
    Use Realsense2:              no
    Use Kinect:                  no
    \- Use libfreenect:          no
    \- Use libusb-1:             no
    \- Use pthread:              yes
    Use PCL:                     no
    \- Use VTK:                  no

  F/T sensors: 
    Use atidaq (built-in):       no
    Use comedi:                  no
    Use IIT SDK:                 no

  Detection: 
    Use zbar:                    no
    Use dmtx:                    no
    Use AprilTag (built-in):     yes (ver 3.1.1)
    \- Use AprilTag big family:  no

  Misc: 
    Use Clipper (built-in):      no
    Use pugixml (built-in):      yes (ver 1.9.0)
    Use libxml2:                 no

  Optimization: 
    Use OpenMP:                  yes
    Use pthread:                 yes
    Use pthread (built-in):      no
    Use cxx standard:            11

  Documentation: 
    Use doxygen:                 no

  Tests and samples:
    Use catch2 (built-in):       yes (ver 2.9.2)
    Tests:                       yes
    Demos:                       yes
    Examples:                    yes
    Tutorials:                   yes

  Install path:                  /usr/local

==========================================================
\endcode

\section install_centos_issues Known issues
\subsection install_centos_issues_pthread libpthread may be hidden by files in //lib64

- On CentOS 7.0 with cmake 2.8.11, during cmake configuration you may encounter the following issue:
\code
CMake Warning at src/CMakeLists.txt:80 (add_library):
   Cannot generate a safe runtime search path for target visp because files in
   some directories may conflict with libraries in implicit directories:

     runtime library [libpthread.so] in /usr/lib64 may be hidden by files in:
       //lib64

   Some of these libraries may not be found correctly.
\endcode
- The problem was that libpthread.so exists in /usr/lib64 and in //lib64. In //lib64 it should be a symbolic link to /usr/lib64.
\code
$ ls -als //lib64
  0 lrwxrwxrwx. 1 root root 9 Feb  4 12:16 //lib64 -> usr/lib64
$ ls -als //lib64/libpthread*
140 -rwxr-xr-x. 1 root root 141616 Jan 27 15:13 //lib64/libpthread-2.17.so
  4 -rw-r--r--. 1 root root    222 Jan 27 14:42 //lib64/libpthread.so
  0 lrwxrwxrwx. 1 root root     18 Feb  4 12:34 //lib64/libpthread.so.0 -> libpthread-2.17.so
\endcode  
- The fix consists in removing //lib64/libpthread.so and creating a new symbolic link
\code
$ cd //lib64
$ sudo rm libpthread.so
$ sudo ln -s libpthread-2.17.so libpthread.so
$ ls -als libpthread*
140 -rwxr-xr-x. 1 root root 141616 Jan 27 15:13 libpthread-2.17.so
  0 lrwxrwxrwx. 1 root root     18 Feb  4 16:09 libpthread.so -> libpthread-2.17.so
  0 lrwxrwxrwx. 1 root root     18 Feb  4 12:34 libpthread.so.0 -> libpthread-2.17.so
\endcode

\subsection install_centos_issues_videoreader vpVideoReader is not able to read mpeg videos

- On CentOS 7.0, vpVideoReader uses OpenCV to read and decode videos. Some examples or tutorials provided in ViSP hang during cv::Capture::open() call. The reason is that OpenCV 2.4.5 cv::Capture seams buggy. This is for example the case if you run:
\code
$ ./example/video/videoReader
\endcode
- A work arround consists in installing a more recent OpenCV version from source. 

\section install_centos_next Next tutorial

You are now ready to see the next \ref tutorial-getting-started that will show you how to use ViSP as a 3rd party to build your own project.

*/