Introduce new doxygen tutorial for hsv segmentation

ChangeLog.txt

@@ -48,6 +48,8 @@ ViSP 3.x.x (Version in development)
       https://visp-doc.inria.fr/doxygen/visp-daily/tutorial-spc.html
     . New tutorial: Installing ViSP Python bindings
       https://visp-doc.inria.fr/doxygen/visp-daily/tutorial-install-python-bindings.html
+    . New tutorial: Color segmentation using HSV color scale
+      https://visp-doc.inria.fr/doxygen/visp-daily/tutorial-hsv-segmentation.html
   - Bug fixed
     . [#1251] Bug in vpDisplay::displayFrame()
     . [#1270] Build issue around std::clamp and optional header which are not found with cxx17

doc/tutorial/segmentation/color/tutorial-hsv-segmentation.dox

@@ -0,0 +1,128 @@
+/**
+  \page tutorial-hsv-segmentation Tutorial: Color segmentation using HSV color scale
+  \tableofcontents
+
+\section hsv_intro Introduction
+
+The HSV scale, which stands for Hue Saturation and Value, provides a numerical readout of your color image that
+corresponds to the color names contained therein. Hue is measured in degrees from 0 to 360, while Saturation and Value
+of a color are both analyzed on a scale of 0 to 100 percent.
+
+Hue, Saturation, and Value are the main color properties that allow us to distinguish between different colors.
+In this tutorial, you will learn how to use HSV color scale to segment a specific color in an image.
+
+Note that all the material (source code and images) described in this tutorial is part of ViSP source code
+(in `tutorial/segmentation/color` folder) and could be found in
+https://github.com/lagadic/visp/tree/master/tutorial/segmentation/color.
+
+\section hsv_converter RGB to HSV color scale conversion
+
+In ViSP, color images can be read and converted to the RGB color scale. The RGB color scale is based on the color
+theory that all visible colors can be obtained from the additive primary colors red, green and blue. In ViSP,
+we introduce an additional Alpha channel to add color transparency. The RGB + Alpha channels are therefore
+implemented in the vpRGBa class. The following snippet shows how to load a color image in ViSP:
+\code
+#include <visp3/io/vpImageIo.h>
+
+int main()
+{
+  vpImage<vpRGBa> I;
+  vpImageIo::read(I, "ballons.jpg");
+}
+\endcode
+
+The color conversion from RGB to HSV or from RGBa to HSV color scale is performed in ViSP using one of the following
+functions:
+- vpImageConvert::RGBToHSV()
+- vpImageConvert::RGBaToHSV()
+
+The following snippet shows how to convert to HSV color scale:
+\code
+#include <visp3/io/vpImageIo.h>
+#include <visp3/core/vpImageConvert.h>
+
+int main()
+{
+  vpImage<vpRGBa> I;
+  vpImageIo::read(I, "ballons.jpg");
+
+  unsigned int width = I.getWidth();
+  unsigned int height = I.getHeight();
+
+  vpImage<unsigned char> H(height, width);
+  vpImage<unsigned char> S(height, width);
+  vpImage<unsigned char> V(height, width);
+
+  vpImageConvert::RGBaToHSV(reinterpret_cast<unsigned char *>(I.bitmap),
+                            reinterpret_cast<unsigned char *>(H.bitmap),
+                            reinterpret_cast<unsigned char *>(S.bitmap),
+                            reinterpret_cast<unsigned char *>(V.bitmap), I.getSize());
+}
+\endcode
+In the previous example, we obtained for each pixel:
+- Hue in `H` image where values are scaled from 0 to 255. here 255 stands for 360 degrees.
+- Saturation in `S` image where values are scaled from 0 to 255. Here 255 stands for 100%.
+- Value in `V` image where values are scaled from 0 to 255. Here 255 stands for 100%.
+
+\section hsv_segmentation HSV color segmentation
+
+It's easy to segment a given color if we select the range of hue, saturation and value we're interested in.
+
+In the image `ballons.jpg`, the pixel at coordinates [93][164] has an RGB value (209, 72, 0) which corresponds to
+an HSV value (14, 255, 209). We can use these HSV values and an additional offset to determine the low and high
+values of the HSV ranges used to create a mask corresponding to the segmented color.
+
+\code
+#include <visp3/io/vpImageIo.h>
+#include <visp3/core/vpImageConvert.h>
+#include <visp3/core/vpImageTools.h>
+
+int main()
+{
+  vpImage<vpRGBa> I;
+  vpImageIo::read(I, "ballons.jpg");
+
+  unsigned int width = I.getWidth();
+  unsigned int height = I.getHeight();
+
+  vpImage<unsigned char> H(height, width);
+  vpImage<unsigned char> S(height, width);
+  vpImage<unsigned char> V(height, width);
+
+  vpImageConvert::RGBaToHSV(reinterpret_cast<unsigned char *>(I.bitmap),
+                            reinterpret_cast<unsigned char *>(H.bitmap),
+                            reinterpret_cast<unsigned char *>(S.bitmap),
+                            reinterpret_cast<unsigned char *>(V.bitmap), I.getSize());
+
+  int h = 14, s = 255, v = 209;
+  int offset = 30;
+  int h_low = std::max<int>(0, h - offset), h_high = std::min<int>(h + offset, 255);
+  int s_low = std::max<int>(0, s - offset), s_high = std::min<int>(s + offset, 255);
+  int v_low = std::max<int>(0, v - offset), v_high = std::min<int>(v + offset, 255);
+  std::vector<int> hsv_range({ h_low, h_high, s_low, s_high, v_low, v_high });
+
+  vpImage<unsigned char> mask(height, width);
+  vpImageTools::inRange(reinterpret_cast<unsigned char *>(H.bitmap),
+                        reinterpret_cast<unsigned char *>(S.bitmap),
+                        reinterpret_cast<unsigned char *>(V.bitmap),
+                        hsv_range,
+                        reinterpret_cast<unsigned char *>(mask.bitmap),
+                        mask.getSize());
+}
+\endcode
+
+Using the mask we can create a segmented color image. The following snippet shows how to combine the mask and the
+color image using vpImageTools::inMask() to create the segmented image as given in the next snippet also available in
+tutorial-hsv-segmentation-basic.cpp
+
+\include tutorial-hsv-segmentation-basic.cpp
+
+The end of the previous snippet shows also how to display the following images.
+
+\image html ballons-segmented.jpg
+
+\section hsv_next Next tutorial
+
+You are now ready to see how to continue with \ref tutorial-grabber.
+
+*/

doc/tutorial/tutorial-users.dox

@@ -17,6 +17,8 @@ This page references all the tutorials to use and contribute to ViSP.
 
 - \subpage tutorial_detection_dnn
 
+- \subpage tutorial_segmentation
+
 - \subpage tutorial_computer_vision
 
 - \subpage tutorial_vs
@@ -123,6 +125,14 @@ This page introduces the user to the way to detect features or objects in images
 
 */
 
+/*! \page tutorial_segmentation Segmentation
+This page introduces the user to the way to achieve image and object segmentation.
+
+- \subpage tutorial-hsv-segmentation <br>This tutorial shows how to use HSV color scale to segment a given color in
+  an image.
+
+*/
+
 /*! \page tutorial_computer_vision Computer vision
 This page introduces the user to the way to estimate a pose or an homography.