/**
  \page tutorial-getting-started Tutorial: How to create and build a project that uses ViSP and CMake on Unix or Windows
  \tableofcontents

\note We assume in this tutorial that you have successfully installed ViSP either with an \ref tutorial_install_pkg or with an \ref tutorial_install_src.

In this tutorial you will learn how to use ViSP either on unix-like operating system (including OSX, Fedora, Ubuntu, Debian, ...) or on Windows.

The easiest way of using ViSP in your project is to use <a href="http://www.cmake.org/">CMake</a>. If you are not familiar with CMake, you can check the <a href="http://www.cmake.org/cmake/help/cmake_tutorial.html">tutorial</a>.

Note also that all the material (source code and images) described in this tutorial is part of ViSP source code and could be downloaded using the following command:

\verbatim
$ svn export https://github.com/lagadic/visp.git/trunk/tutorial/image
\endverbatim

\section started_quick Quick getting started

In this section we show how to build an existing project that uses ViSP as third-party and CMake for the build mechanism. As a use case we will use the `image` project that is part of ViSP tutorials. The source code comes from https://github.com/lagadic/visp/tutorial/image. It contains a set of source files `tutorial-viewer.cpp`, `tutorial-image-viewer.cpp` and a `CMakeLists.txt` file. We show here how to get these files and build them.

\subsection started_quick_unix On unix-like operating system

1. If you did \ref tutorial_install_pkg you have to create a workspace. If you did \ref tutorial_install_src jump to point 2. since your workspace should be already created.<br>
Check if `VISP_WS` environment var exists:
\verbatim
$ env | grep VISP_WS
\endverbatim
If it returns an empty string, create a workspace with:
\verbatim
$ echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc
$ source ~/.bashrc
$ mkdir -p $VISP_WS
\endverbatim

2. Get the source code using Subversion (`svn`):
\verbatim
$ sudo apt-get install subversion
$ cd $VISP_WS
$ svn export https://github.com/lagadic/visp.git/trunk/tutorial/image
\endverbatim

3. Create a build folder
\verbatim
$ mkdir -p $VISP_WS/image/build
$ cd $VISP_WS/image/build
\endverbatim

4. Run CMake in build directory<br>
If you did \ref tutorial_install_pkg, run:
\verbatim
$ cmake .. -DCMAKE_BUILD_TYPE=Release
\endverbatim
Otherwise if you did \ref tutorial_install_src, indicate where to find ViSP thanks to `VISP_DIR` var:
\verbatim
$ cmake .. -DCMAKE_BUILD_TYPE=Release -DVISP_DIR=$VISP_WS/visp-build
\endverbatim

5. Build `tutorial-viewer` example
\verbatim
$ make tutorial-viewer
\endverbatim

6. Run `tutorial-viewer` example
\verbatim
$ ./tutorial-viewer monkey.pgm
\endverbatim

\subsection started_quick_win On windows operating system

1. If you did \ref tutorial_install_src jump to point 2. since your workspace should be already created.<br>
Open a `cmd` Command Prompt and check if `VISP_WS` environment var exists:
\verbatim
C:\> set | findstr VISP_WS
\endverbatim
If it returns an empty string, create a workspace with:
\verbatim
C:\> mkdir C:\visp-ws
C:\> setx VISP_WS=C:\visp-ws
C:\> exit
\endverbatim

2. Get the source code in your workspace either using Subversion (`svn`), either copying the source code from `%%VISP_WS%/tutorial/image` folder if you follow one of the \ref tutorial_install_src tutorials, or downloading the source from https://github.com/lagadic/visp/tutorial/image:<br>
With Subversion:
\verbatim
C:\> svn export https://github.com/lagadic/visp.git/trunk/tutorial/image
\endverbatim
Or by copy from ViSP source code
\verbatim
C:\> xcopy /E /I %VISP_WS%\visp\tutorial\image %VISP_WS%\image
\endverbatim

3. Create a build folder
\verbatim
C:\> mkdir %VISP_WS%\image\build
C:\> cd %VISP_WS%\image\build
\endverbatim

4. Run CMake in build folder and indicate where to find ViSP thanks to `VISP_DIR` var.<br>
  - If your are using Visual Studio 17 2022 and 64 bits hardware, run:
\verbatim
C:\> cmake -G "Visual Studio 17 2022" -A "x64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc17
\endverbatim
  - Or if your are using Visual Studio 16 2019 and 64 bits hardware, run:
\verbatim
C:\> cmake -G "Visual Studio 16 2019" -A "x64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc16
\endverbatim
  - Or if your are using Visual Studio 15 2017 and 64 bits hardware, run:
\verbatim
C:\> cmake -G "Visual Studio 15 2017" -A "x64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc15
\endverbatim
  - Or if your are using Visual Studio 14 2015 and 64 bits hardware, run:
\verbatim
C:\> cmake -G "Visual Studio 14 2015" -A "x64" .. -DVISP_DIR=%VISP_WS%\visp-build-vc14
\endverbatim
  - Or if your are rather using MinGW-w64, run:
\verbatim
C:\> cmake -G "MinGW Makefiles" .. -DVISP_DIR=%VISP_WS%\visp-build-mingw
\endverbatim

5. Build `tutorial-viewer` example
\verbatim
C:\> cmake --build . --config Release --target tutorial-viewer
\endverbatim

6. Run `tutorial-viewer` example
\verbatim
C:\> cd Release
C:\> tutorial-viewer.exe monkey.pgm
\endverbatim

\section started_advanced Advanced getting started

\subsection started_ws Create a workspace

We suppose here that you have already setup a workspace and defined `VISP_WS` environment var.

We recall here after the instructions to create a workspace:

- <b>On unix-like operating system</b><br>
Check if `VISP_WS` environment var exists:
\verbatim
$ env | grep VISP_WS
\endverbatim
If it returns an empty string, create a workspace with:
\verbatim
$ echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc
$ source ~/.bashrc
$ mkdir -p $VISP_WS
\endverbatim

- <b>On windows operating system</b><br>
Open a `cmd` Command Prompt and check if `VISP_WS` environment var exists:
\verbatim
C:\> set | findstr VISP_WS
\endverbatim
If it returns an empty string, create a workspace with:
\verbatim
C:\> mkdir C:\visp-ws
C:\> setx VISP_WS=C:\visp-ws
C:\> exit
\endverbatim

Enter `VISP_WS` folder and create a new folder let say `started` that will contain your first project that uses ViSP as third-party:

- <b>On unix-like operating system</b><br>
\verbatim
$ cd $VISP_WS
$ mkdir started
\endverbatim
- <b>On windows operating system</b><br>
Open a `cmd` Command Prompt and run
\verbatim
C:\> cd %VISP_WS%
C:\> mkdir started
\endverbatim

\subsection image_code Get tutorial-viewer.cpp file

Let's start to write our first C++ example to see how to read an image and open a window to display the image with ViSP. This example is provided in tutorial-viewer.cpp example and given below.

Open your favorite editor and copy/paste the content of this example in `VISP_WS/started/tutorial-viewer.cpp` source file.

The code to copy/paste is the following:

\include tutorial-viewer.cpp

Here is the detailed explanation of the source, line by line:
\snippet tutorial-viewer.cpp Include display

Include all the headers for image viewers. The two first one are for Windows systems. They require that Direct 3D or the \e Graphical \e Device \e Interface (\e GDI) coming with the installation of Visual Studio are available. The third one needs GTK that is cross-platform. The fourth is for unix-like systems and requires that \e libX11 is available. The last one is also cross-platform and requires that OpenCV is available.

\snippet tutorial-viewer.cpp Include io
Include the header that allows to read/write PGM, PPM, PNG and JPEG images from the disk using vpImageIo class.

\snippet tutorial-viewer.cpp vpImage construction
Create an instance of a color image where each pixel is coded in RGBa.

\snippet tutorial-viewer.cpp vpImage reading
The image `I` is initialized by reading an image file from the disk. If the image format is not supported we throw an exception.

\snippet tutorial-viewer.cpp vpDisplay construction
Create an instance of an image display window for image `I`. The first viewer that is available is used. Here we create the link between the image `I` and the display `d`. Note that an image can only have one display.

\snippet tutorial-viewer.cpp vpDisplay set title
The title of the display is then set to "My image".

\snippet tutorial-viewer.cpp vpDisplay display
First we display the content of the image `I`, then we flush the display to render the image.

\snippet tutorial-viewer.cpp vpDisplay get click
Here we handle mouse events. We are waiting for a blocking mouse click to end the program.

\subsection image_cmake Get CMakeLists.txt file

Now you have to create a `CMakeLists.txt` file that gives the instructions on how to build `tutorial-viewer.cpp` example. A minimalistic `CMakeLists.txt` should contain the following lines.

Open your editor and copy/paste the following lines in `VISP_WS/started/CMakeLists.txt` file.
\code
cmake_minimum_required(VERSION 3.5)

project(tutorial-image)

find_package(VISP REQUIRED)

include_directories(${VISP_INCLUDE_DIRS})

add_executable(tutorial-viewer tutorial-viewer.cpp)
target_link_libraries(tutorial-viewer ${VISP_LIBRARIES})
\endcode

Here after we explain the content of the `CMakeLists.txt` file.

The `find_package()` CMake command searches for a `VISPConfig.cmake` file that will define the corresponding variables:
- `VISP_INCLUDE_DIRS`   : ViSP and third-party headers location
- `VISP_LIBRARIES`      : ViSP and third-party libraries name and location

Note that the previous `CMakeLists.txt` file can also be:
\code
cmake_minimum_required(VERSION 3.5)

project(tutorial-image)

find_package(VISP REQUIRED)
if(VISP_FOUND)
  include(${VISP_USE_FILE})
endif(VISP_FOUND)

add_executable(tutorial-viewer tutorial-viewer.cpp)
\endcode

where `VISP_USE_FILE` variable is set to the full path to `VISPUse.cmake` file that contains all the CMake material that allow to build your project with ViSP. In other terms, the line
\code
  include(${VISP_USE_FILE})
\endcode
will include the following lines to your `CMakeFile.txt`
\code
  include_directories(${VISP_INCLUDE_DIRS})
  link_libraries(${VISP_LIBRARIES})
\endcode

\subsection image_monkey Get monkey.ppm file

Get `monkey.ppm` image and copy it to `VISP_WS/started` either:
- copying it from ViSP source code; the file is in `VISP_WS/tutorial/image/monkey.ppm`
- using Subversion:
\verbatim
svn export https://github.com/lagadic/visp.git/trunk/tutorial/image/monkey.ppm
\endverbatim
- by copy/paste from <a href="https://github.com/lagadic/visp/blob/master/tutorial/image/monkey.ppm">GitHub</a> using the Raw button


\subsection image_unix On unix-like operating system

In this section we supppose that you have created a folder `$VISP_WS/started` that contains `CMakeLists.txt`, `tutorial-viewer.cpp` and `monkey.ppm` files.

\subsubsection image_unix_build_folder Create a build folder

Proceed now as with any other project using CMake by first creating a build folder:

\verbatim
C:\> cd $VISP_WS/started
C:\> mkdir build
\endverbatim

\subsubsection image_unix_config Configure your project

Enter the build folder and launch CMake GUI:

\verbatim
$ cd build
$ ccmake .. -DCMAKE_BUILD_TYPE=Release
Press [c] key to configure
Then, press [g] to generate Makefiles
Then, press [q] to quit CMake GUI
\endverbatim

\image html img-ccmake-started.png

\note By default `ccmake` searches `VISPConfig.cmake` file in system folders like `/usr/share`, `/usr/local/share`... If ViSP is not installed in `/usr` or `/usr/local` as suggested in \ref tutorial_install_src tutorials, it is possible that you get the following error:
\verbatim
CMake Error at CMakeLists.txt:5 (find_package):
  Could not find module FindVISP.cmake or a configuration file for package
  VISP.

  Adjust CMAKE_MODULE_PATH to find FindVISP.cmake or set VISP_DIR to the
  directory containing a CMake configuration file for VISP.  The file will
  have one of the following names:

    VISPConfig.cmake
    visp-config.cmake
\endverbatim
If you get the previous error it means that you forget to set `VISP_DIR` environment variable that helps `cmake` to find `VISPConfig.cmake` file.
- If you install ViSP from source following one of the \ref tutorial_install_src tutorials, set `VISP_DIR` environment variable to the ViSP build folder location and call `ccmake` again:
\verbatim
$ export VISP_DIR=$VISP_WS/visp-build/lib/cmake/visp
$ ccmake ..
\endverbatim
or run cmake with the additional `VISP_DIR` definition
\verbatim
$ ccmake -DVISP_DIR=$VISP_WS/visp-build/lib/cmake/visp .
\endverbatim
- If you rather install ViSP from prebuilt packages following one of the \ref tutorial_install_pkg tutorials, set `VISP_DIR` environment variable to the installation folder location and call `cmake` again:
\verbatim
$ export VISP_DIR=/usr/lib/<multi-arch-folder>/cmake/visp
$ cmake ..
\endverbatim
or run cmake with the additional `VISP_DIR` definition
\verbatim
$ cmake -DVISP_DIR=/usr/lib/<multi-arch-folder>/cmake/visp .
\endverbatim
Depending on the platform `<multi-arch-folder>` can be empty (OSX) or for example equal to `x86_64-linux-gnu` on Ubuntu if you install ViSP using
\verbatim
$ sudo apt-get install libvisp-dev.
\endverbatim

\subsubsection image_unix_build Generate the executable

Just run:
\verbatim
$ make
\endverbatim

\subsubsection image_unix_output Run the executable

By now you should have an executable called `tutorial-viewer`. You just have to run it giving an image location as an argument:

\verbatim
$ ./tutorial-viewer ../monkey.ppm
\endverbatim

Here is a screen shot of the resulting output window :

\image html img-monkey.png

\subsection image_win On windows operating system

We suppose from now, that you have created a folder `%%VISP_WS%\started` that contains `CMakeLists.txt`, `tutorial-viewer.cpp` and `monkey.ppm` files.

\subsubsection image_win_build_folder Create a build folder

Proceed now as with any other project using CMake by first creating a build folder:

\verbatim
C:\> cd %%VISP_WS%\started
C:\> mkdir build
\endverbatim

\subsubsection image_win_config Configure your project

- Launch "CMake (cmake-gui)" from Windows "Start" menu. Set the source code location as `%%VISP_WS%\started` and the build location to `%%VISP_WS%\started\build` folder.

\image html img-started-win-cmake-1.jpg

- Press "Configure" button and select your compiler. In our case we will use Visual Studio 15 2017 Win64.

\image html img-started-win-msvc15.jpg

- Press then "Finish" button. The configuration is now under progress and should lead to the following image.

\image html img-started-win-cmake-2.jpg

- In the previous image you may notice that CMake has automatically found the location of ViSP install folder; `%%VISP_WS/visp-build-vc15/install`. This was possible because you \ref install_win10_msvc15_visp_dir.
\note If at this step you have an error like the one shown in the next image, it means that you forget to set `VISP_DIR` env var. If this is the case, quit CMake Gui, \ref install_win10_msvc15_visp_dir, open CMake Gui and try again to configure your project.
\image html img-started-win-cmake-error.jpg

- Press then "Configure" button to remove the red lines, and then "Generate" button. As presented in the following image, all the red lines should disappear.

\image html img-started-win-cmake-3.jpg

- From now, in `%%VISP_WS%\started\build` folder you should have `tutorial-image.sln` Visual Studio solution file.

\subsubsection image_win_build Generate the executable

- Open the project in Visual Studio C++ just by double click on `%%VISP_WS%\stated\build\tutorial-image.sln` solution file.
- Modify the configuration to "Release"

\image html img-started-win-msvc-1.jpg

- Now to build the solution, enter `"BUILD > Build Solution"` menu or hit Ctrl+Shift+B keys.

\image html img-started-win-msvc-2.jpg

- In `%%VISP_WS%\started\build\Release` folder you have now `tutorial-viewer.exe` executable.

\subsubsection image_win_output Run the executable

- In your "Start" menu click on "Run" and type in `cmd.exe` to run a Command Prompt.
- Enter in `%%VISP_WS%\started\build\Release` folder, and run `tutorial-viewer.exe` with an image location as argument:
\verbatim
C:\> cd %VISP_WS%\started\build\Release
C:\> tutorial-viewer ..\..\monkey.ppm
\endverbatim

- Here is a screen shot of the resulting output window :

\image html img-monkey-win.jpg

\section image_next Next tutorial

You are now ready to see the \ref tutorial-image-display.
There is also the \ref tutorial-contrib-module that could be useful to understand how to introduce new developments in ViSP.
*/