/**

\page tutorial-imgproc-contour Tutorial: Contours extraction from a binary image
\tableofcontents

\section imgproc_contour_intro Introduction

This tutorial will show you how to extract the contours from a binary image. The contour extraction algorithm is based on \cite articleSuzuki article and most of the implementation has been ported from \cite Hare:2011:OIJ:2072298.2072421 library.

The function to call is vp::findContours(const vpImage<unsigned char> &, vpContour &, std::vector<std::vector<vpImagePoint> > &, const vpContourRetrievalType&):
- the first argument is the image where '0' pixel value means the background and '1' pixel value means the foreground. **Other values are not allowed.**
- the second argument is a vp::vpContour structure that contains the list of contours in a tree
- the third argument is the list of contours
- the last argument is an option to choose the type of contour extraction, see vp::vpContourRetrievalType

The vp::vpContour structure is composed of:
- std::vector< \ref vp::vpContour * > m_children, the list of children contours for the current contour
- vp::vpContourType m_contourType, the type of contour (vp::CONTOUR_OUTER or vp::CONTOUR_HOLE)
- vp::vpContour * m_parent, the parent contour for the current contour
- std::vector< \ref vpImagePoint > m_points, the list of contour points
- the first or top level contour is called the root contour (with vp::CONTOUR_HOLE type by default) and contains in \a m_children the list of contours

The different contour extraction methods are:
- vp::CONTOUR_RETR_TREE, all the contours are extracted and stored in a hierarchical tree. 
- vp::CONTOUR_RETR_LIST, all the contours are extracted and stored in a list. The top level contour contains in \a m_children the list of all the extracted contours.
- vp::CONTOUR_RETR_EXTERNAL, only the external contours are extracted and stored in a list. The top level contour contains in \a m_children the list of the external extracted contours.

The next section will provide a concrete example for better understanding.

\section imgproc_contour_example Example code

The following example also available in tutorial-contour.cpp will demonstrate on a sample image the result of each of these methods:

\include tutorial-contour.cpp

These functions are provided in a \a vp:: namespace and accessible using this include:

\snippet tutorial-contour.cpp Include

The first steps are:
- read an image in grayscale
\snippet tutorial-contour.cpp Read
- threshold / binarize the image, here with the Otsu method.
\snippet tutorial-contour.cpp Otsu
If the object of interest is in white in the image, the formula for the binarization is:
\f[
  I_{bin}\left ( i,j \right ) = 
  \left \{ \begin{matrix}
  0 \text{ if } I_{src}\left ( i,j \right ) < \text{threshold} \\ 
  1 \text{ otherwise}
  \end{matrix} \right.
\f]
If the object of interest is in black in the image, the formula for the binarization is:
\f[
  I_{bin}\left ( i,j \right ) = 
  \left \{ \begin{matrix}
  1 \text{ if } I_{src}\left ( i,j \right ) < \text{threshold} \\ 
  0 \text{ otherwise}
  \end{matrix} \right.
\f]
- extract the contours (by default, it is the vp::CONTOUR_RETR_TREE method)
\snippet tutorial-contour.cpp Find contours
- draw the contours if wanted
\snippet tutorial-contour.cpp Draw contours


The result images for each step are:

\image html img-auto-threshold-grid36-03.png "Input image"

\image html img-tutorial-contour-binarisation.png "Image after binarization using the Otsu method"

\image html img-tutorial-contour-draw-contours.png "Contours extracted and displayed on a new image"

To understand how the hierarchical contours extraction works, let's switch on another example. In a terminal, run:

\code
$ ./tutorial-contour --input Contours_tree.pgm --white_foreground
\endcode

The image after binarisation:

\image html img-tutorial-contour-binarisation2.png "Image after binarization using the Otsu method"

Instead of drawing all the contours with the same color, we can assign a first color for vp::CONTOUR_OUTER contour and a second color for vp::CONTOUR_HOLE contour.

The function to navigate in the contour tree is the following:

\snippet tutorial-contour.cpp Draw contours hierarchical func

The call to draw the hierarchical contours:

\snippet tutorial-contour.cpp Draw contours hierarchical

The result image is:

\image html img-tutorial-contour-draw-contours2.png "Contours extracted and displayed on a new image, in red outer contours, in green hole contours"

To display the hierarchy, we can use this function:

\snippet tutorial-contour.cpp Print contours hierarchy func

For the vp::CONTOUR_RETR_TREE method, the output is:

<blockquote>
Contour:\n
  level: 0\n
  contour type: hole contour\n
  contour size: 0\n
  nb children: 3\n\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 438\n
  nb children: 0\n\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 748\n
  nb children: 0\n\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 2012\n
  nb children: 1\n\n

Contour:\n
  level: 2\n
  contour type: hole contour\n
  contour size: 1906\n
  nb children: 1\n\n

Contour:\n
  level: 3\n
  contour type: outer contour\n
  contour size: 1610\n
  nb children: 1\n\n

Contour:\n
  level: 4\n
  contour type: hole contour\n
  contour size: 1494\n
  nb children: 1\n\n

Contour:\n
  level: 5\n
  contour type: outer contour\n
  contour size: 792\n
  nb children: 2\n\n

Contour:\n
  level: 6\n
  contour type: hole contour\n
  contour size: 372\n
  nb children: 0\n\n

Contour:\n
  level: 6\n
  contour type: hole contour\n
  contour size: 392\n
  nb children: 0\n
</blockquote>

The top level contour is always the root contour with zero contour point and which contains the list of contours.

For the vp::CONTOUR_RETR_EXTERNAL method, the output is:

<blockquote>
Contour:\n
  level: 0\n
  contour type: hole contour\n
  contour size: 0\n
  nb children: 3\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 438\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 748\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 2012\n
  nb children: 0\n
</blockquote>

The result image is:

\image html img-tutorial-contour-draw-contours3.png "External contours extracted and displayed on a new image"

For the vp::CONTOUR_RETR_LIST method, the output is:

<blockquote>
Contour:\n
  level: 0\n
  contour type: hole contour\n
  contour size: 0\n
  nb children: 9\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 438\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 748\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 2012\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: hole contour\n
  contour size: 1906\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 1610\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: hole contour\n
  contour size: 1494\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: outer contour\n
  contour size: 792\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: hole contour\n
  contour size: 372\n
  nb children: 0\n

Contour:\n
  level: 1\n
  contour type: hole contour\n
  contour size: 392\n
  nb children: 0\n
</blockquote>

\section imgproc_contour_next Next tutorial

You can now read the \ref tutorial-imgproc-connected-components, for a similar method to extract the connected-components in a grayscale image.

*/