1/** 2 3\page tutorial-detection-face Tutorial: Face detection 4\tableofcontents 5 6\section intro_face Introduction 7 8This tutorial shows how to detect one or more faces with ViSP. Face detection is performed using OpenCV Haar cascade capabilities that are used in vpDetectorFace class. At least OpenCV 2.2.0 or a more recent version is requested. 9 10In the next sections you will find examples that show how to detect faces in a video, or in images acquired by a camera connected to your computer. 11 12Note that all the material (source code and video) described in this tutorial is part of ViSP source code and could be downloaded using the following command: 13 14\code 15$ svn export https://github.com/lagadic/visp.git/trunk/tutorial/detection/face 16\endcode 17 18 19\section face_detection_video Face detection in a video 20 21The following example also available in tutorial-face-detector.cpp allows to detect faces in an mpeg video located near the source code. The Haar cascade classifier file requested by OpenCV is also provided in the same folder as the source code. 22 23\include tutorial-face-detector.cpp 24 25To detect the faces just run: 26\code 27$ ./tutorial-face-detector 28\endcode 29You will get the following result: 30 31\htmlonly 32<iframe width="420" height="315" src="https://www.youtube.com/embed/zizukjfNLvE" frameborder="0" allowfullscreen></iframe> 33\endhtmlonly 34 35Now we explain the main lines of the source. 36 37First we have to include the header of the class that allows to detect a face. 38\snippet tutorial-face-detector.cpp Include 39 40Then in the main() function before going further we need to check if OpenCV 2.2.0 is available. 41 42\snippet tutorial-face-detector.cpp Macro defined 43 44We set then the default input data: 45- the name of the Haar cascade classifier file "haarcascade_frontalface_alt.xml" 46- the name of the input video "video.mpeg" 47 48\snippet tutorial-face-detector.cpp Default settings 49 50With command line options it is possible to use other inputs. To know how just run: 51 52\code 53$ ./tutorial-face-detector --help 54Usage: ./tutorial-face-detector [--haar <haarcascade xml filename>] [--video <input video file>] [--help] 55\endcode 56 57Then we open the video stream, create a windows named "ViSP viewer" where images and the resulting face detection will be displayed. 58 59The creation of the face detector is performed using 60 61\snippet tutorial-face-detector.cpp Face detector construction 62 63We need also to set the location and name of the xml file that contains the Haar cascade classifier data used to recognized a face. 64 65\snippet tutorial-face-detector.cpp Face detector setting 66 67Then we enter in the while loop where for each new image, the try to detect one or more faces: 68 69\snippet tutorial-face-detector.cpp Face detection 70 71If a face is detected, vpDetectorFace::detect() returns true. It is then possible to retrieve the number of faces that are detected: 72 73\snippet tutorial-face-detector.cpp Get number faces 74 75For each face, we have access to its location using vpDetectorFace::getPolygon(), its bounding box using vpDetectorFace::getBBox() and its identifier message using vpDetectorFace::getMessage(). 76 77\snippet tutorial-face-detector.cpp Get face characteristics 78 79\note When more than one face is detected, faces are ordered from the largest to the smallest. That means that vpDetectorFace::getPolygon(0), vpDetectorFace::getBBox(0) and vpDetectorFace::getMessage(0) return always the characteristics of the largest face. 80 81\section face_detection_live Face detection from a camera 82 83This other example also available in tutorial-face-detector-live.cpp shows how to detect one or more faces in images acquired by a camera connected to your computer. 84 85\include tutorial-face-detector-live.cpp 86 87The usage of this example is similar to the previous one. Just run 88\code 89$ ./tutorial-face-detector-live 90\endcode 91 92Additional command line options are available to specify the location of the Haar cascade file and also the camera identifier if more than one camera is connected to your computer: 93 94\code 95$ ./tutorial-face-detector-live --help 96Usage: ./tutorial-face-detector-live [--device <camera device>] [--haar <haarcascade xml filename>] [--help] 97\endcode 98 99The source code of this example is very similar to the previous one except that here we use camera framegrabber devices (see \ref tutorial-grabber). Two different grabber may be used: 100- If ViSP was build with Video For Linux (V4L2) support available for example on Fedora or Ubuntu distribution, VISP_HAVE_V4L2 macro is defined. In that case, images coming from an USB camera are acquired using vpV4l2Grabber class. 101- If ViSP wasn't build with V4L2 support, but with OpenCV we use cv::VideoCapture class to grab the images. Notice that when images are acquired with OpenCV there is an additional conversion from cv::Mat to vpImage. 102 103\snippet tutorial-face-detector-live.cpp Construct grabber 104 105Then in the while loop, at each iteration we acquire a new image 106\snippet tutorial-face-detector-live.cpp Acquisition 107 108This new image is then given as input to the face detector. 109 110\section face_detection_next Next tutorial 111 112You are now ready to see the \ref tutorial-multi-threading, that illustrates the case of face detection achieved in a separate thread. 113 114*/ 115