tutorial-install-raspberry.doc

/**

\page tutorial-install-raspberry Tutorial: Installation from source for Raspberry Pi
\tableofcontents

In this tutorial you will learn how to install ViSP from source on <a href="http://www.raspberrypi.org/help/what-is-a-raspberry-pi">Raspberry Pi 1 or Pi 2</a> equipped with an optional HD camera module.

\image html img-raspberry-pi.jpg

In a first section we give some useful instructions to start with a Raspberry PI. Then in the second section, we focus on the installation of ViSP from source.

\note Concerning ViSP installation, we provide also other \ref tutorial.
 
\section install_raspberry Raspberry Pi installation

\subsection install_raspberry_setup Setting up Raspberry Pi

- There are a lot of documentation and tutorial that explain different ways to setup a Raspberry Pi. A good reference is the official page <a href="http://www.raspberrypi.org/">http://www.raspberrypi.org</a>

- We suggest to start with NOOBS (New Out Of the Box Software). Bellow we resume the different steps that are fully described in <a href="http://www.raspberrypi.org/help/noobs-setup/">http://www.raspberrypi.org/help/noobs-setup</a>:
  - Format you SD card (at least 4Go are requested) on your computer. To this end you can use "GParted partition editor"  under Ubuntu.
  - Download Noobs "Offline and network install" zip file from <a href="http://www.raspberrypi.org/downloads/">http://www.raspberrypi.org/downloads</a>.
  - Unzip all the files on the SD card.
  - Insert your SD Card into your Raspberry Pi.
  - Plug in your keyboard, mouse, monitor and Ethernet cables.
  - Now plug in the USB power cable to your Pi.
  - Your Raspberry Pi will boot, and a window will appear with a list of different operating systems that you can install. Select the "recommended Raspbian" checkbox and click on "Install" button.
  - When the install process has completed, the Raspberry Pi configuration menu (raspi-config) will load. Here you are able to set the time and date for your region and enable a Raspberry Pi camera board, or even create users. You can exit this menu by using Tab on your keyboard to move to Finish.

\subsection install_raspberry_login Logging in 

- The default login for Raspbian is username `pi` with the password `raspberry`.

\subsection update Update your Raspbian distribution

- If your Raspberry Pi is connected to Ethernet you can update your Raspbian distribution:
\code
$ sudo apt-get update
$ sudo apt-get upgrade
\endcode

\subsection install_raspberry_camera Setting up a Raspberry Pi camera

- If you have a Raspberry Pi camera module see <a href="http://www.raspberrypi.org/help/camera-module-setup/">http://www.raspberrypi.org/help/camera-module-setup</a>. To resume, enable the camera using:
\code
$ sudo raspi-config
\endcode
- Enter in menu "5/ Interfacing Options" to enable the camera.
- Do a reboot 
\code
$ sudo reboot
\endcode

- Connect again and load the camera module:
\code
$ sudo modprobe bcm2835-v4l2
\endcode

- This will add the following modules:
\code
$ lsmod
Module Size Used by
bcm2835_v4l2 37611 0
videobuf2_core 30853 1 bcm2835_v4l2
v4l2_common 7792 1 bcm2835_v4l2
videodev 121362 3 bcm2835_v4l2,v4l2_common,videobuf2_core
\endcode

- To check if the camera is recognized and connected, run:
\code
$ v4l2-ctl --list-formats
\endcode

- After each Raspberry Pi reboot you need to relaunch the previous modprobe command. To load bcm2835-v4l2 module during reboot, you can edit `/etc/modules` file 
\code
$ sudo nano /etc/modules
\endcode
and add a line with the name of the module:
\code
bcm2835-v4l2
\endcode

- To check if the camera is working you may run in a terminal:
\code
$ v4l2-ctl --overlay=1 # enable viewfinder
\endcode
Here you should see the live camera stream. To disable camera view run
\code
v4l2-ctl --overlay=0 # disable viewfinder
\endcode

\subsection install_raspberry_startx Start graphical user interface

- To load the graphical user interface, type `startx` and press Enter on your keyboard. This will later allow to use ViSP vpDisplayX or vpDisplayOpenCV classes useful to display images in a X11 window.

\section install_raspberry_visp_prerequisities Install prerequisites

- First you need to install the following packages (g++, CMake, Git) that are requested to get and build ViSP:
\code
$ sudo apt-get install build-essential cmake-curses-gui git subversion wget
\endcode

\section install_raspberry_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_raspberry_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_raspberry_advanced.

- Install a small number of recommended 3rd parties
\code
$ sudo apt-get install libopencv-dev libx11-dev liblapack-dev libeigen3-dev libv4l-dev libzbar-dev libpthread-stubs0-dev libjpeg-dev libpng12-dev
\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_raspberry_dataset before running some binaries that you just build or jump to \ref install_raspberry_next. You can later come back to the \ref install_raspberry_advanced. 

\section install_raspberry_advanced Advanced ViSP installation

\subsection install_raspberry_3rdparty Install 3rd parties

ViSP is interfaced with several optional 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_raspberry_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_raspberry_tips_new_3rdparty.

\subsubsection install_raspberry_visp_3rd_party Install recommended 3rd parties

ViSP is interfaced with several optional 3rd party libraries. The <a href="http://visp.inria.fr/software-architecture">complete list is provided here</a>. 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
- libv4l to grab images from usb or analogic cameras
- libzbar to be able to detect QR codes
- pthread library

Installation of recommended 3rd parties could be performed running:
\code
$ sudo apt-get install libopencv-dev libx11-dev liblapack-dev libeigen3-dev libv4l-dev libzbar-dev libpthread-stubs0-dev
\endcode

\subsubsection install_raspberry_visp_3rd_party_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 apt-get install libjpeg-dev libpng12-dev
\endcode

\subsection install_raspberry_visp_get_source Get ViSP source code

There are different ways to get ViSP source code on Raspberry Pi:

- 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_raspberry_visp_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-raspberry-all.png Snapshot of the `"ccmake ../visp"` command used to configure ViSP.

\subsection install_raspberry_visp_build Build ViSP libraries

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

\subsection install_raspberry_visp_doc Build ViSP documentation

To build ViSP documentation, you have first to install Doxygen package:
\code
$ sudo apt-get install doxygen graphviz texlive-latex-base
\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_raspberry_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_raspberry_dataset Install ViSP data set

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_raspberry_tips Tips and tricks

\subsection install_raspberry_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_raspberry_tips_3rd_party).

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

\subsection install_raspberry_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_raspberry_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_raspberry_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_raspberry_tips_modules How to build only ViSP libraries

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

\subsection install_raspberry_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
$ cd $VISP_WS/visp-build
$ make -j4 visp_mbt
\endcode

\subsection install_raspberry_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_demos
... visp_examples
... visp_modules
... visp_tests
... visp_tutorials
... 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_raspberry_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 that contains also build info.
\code
$ cat $VISP_WS/visp-build/ViSP-third-party.txt
==========================================================
General configuration information for ViSP 3.3.0

  Version control:               3.2.0-799-ge98496a

  Platform:
    Timestamp:                   2020-02-11T15:49:13Z
    Host:                        Linux 4.1.19-v7+ armv7l
    CMake:                       3.0.2
    CMake generator:             Unix Makefiles
    CMake build tool:            /usr/bin/make
    Configuration:               Release

  C/C++:
    Built as dynamic libs?:      yes
    C++ Compiler:                /usr/bin/c++  (ver 4.9.2)
    C++ flags (Release):         -Wall -Wextra -fopenmp -fvisibility=hidden -fPIC -O3 -DNDEBUG
    C++ flags (Debug):           -Wall -Wextra -fopenmp -fvisibility=hidden -fPIC -g
    C Compiler:                  /usr/bin/cc
    C flags (Release):           -Wall -Wextra -fopenmp -fvisibility=hidden -fPIC -O3 -DNDEBUG
    C flags (Debug):             -Wall -Wextra -fopenmp -fvisibility=hidden -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/python2.7

  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:           yes (ver 3.7.0)
    Use Lapack (built-in):       no
    Use Eigen3:                  yes (ver 3.2.2)
    Use OpenCV:                  yes (ver 2.4.9.1)
    Use GSL:                     yes (ver 1.16)

  Simulator: 
    Ogre simulator: 
    \- Use Ogre3D:               yes (ver 1.9.0)
    \- 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.2.50)
    \- Use ZLIB:                 yes (ver 1.2.8)
    Use OpenCV:                  yes (ver 2.4.9.1)
    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):     no

  GUI: 
    Use X11:                     yes
    Use GTK:                     no
    Use OpenCV:                  yes (ver 2.4.9.1)
    Use GDI:                     no
    Use Direct3D:                no

  Cameras: 
    Use DC1394-2.x:              yes (ver 2.2.3)
    Use CMU 1394:                no
    Use V4L2:                    yes (ver 1.6.0)
    Use directshow:              no
    Use OpenCV:                  yes (ver 2.4.9.1)
    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:                    yes (ver 0.10)
    Use dmtx:                    yes (ver 0.7.4)
    Use AprilTag (built-in):     yes (ver 3.1.1)
    \- Use AprilTag big family:  no

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

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

  Documentation: 
    Use doxygen:                 no

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

  Install path:                  /usr/local

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

\section install_raspberry_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 on Raspberry Pi or on any other system. Then if you have a Raspberry Pi camera module, you can also follow the \ref tutorial-tracking-blob especially subsection Tracking form v4l2 live cameras.

You may also be interested in \ref tutorial-install-crosscompiling-raspberry if you want to speed up the build process or deploy ViSP on other Raspberry boards.

There is also \ref tutorial-mbot-vs that uses a Raspberry Pi in order to control a mBot Ranger educational robot kit by visual-servoing.

*/