Grammar and Formatting fixes. Added link to the Yale Facedatabase A. Added…

Grammar and Formatting fixes. Added link to the Yale Facedatabase A. Added download directive links for linking to the sample source code samples.

modules/contrib/doc/facerec/colormaps.rst

@@ -4,7 +4,7 @@ ColorMaps in OpenCV
 applyColorMap
 ---------------------
 
-Trains a FaceRecognizer with given data and associated labels.
+Applies a GNU Octave/MATLAB equivalent colormap on a given image.
 
 .. ocv:function:: void applyColorMap(InputArray src, OutputArray dst, int colormap)
 

modules/contrib/doc/facerec/facerec_changelog.rst

@@ -5,7 +5,7 @@ Release 0.05
 ------------
 
 This library is now included in the official OpenCV distribution (from 2.4 on). 
-The cv::FaceRecognizer is now a cv::Algorithm, which better fits into the overall
+The :ocv:class`FaceRecognizer` is now an :ocv:class:`Algorithm`, which better fits into the overall
 OpenCV API. 
 
 To reduce the confusion on user side and minimize my work, libfacerec and OpenCV 
@@ -22,7 +22,7 @@ The library now has an extensive documentation:
 Release highlights
 ++++++++++++++++++
 
-- There are no single highlights to pick from, this release is a highlight itself.
+* There are no single highlights to pick from, this release is a highlight itself.
 
 Release 0.04
 ------------
@@ -33,8 +33,8 @@ bugfixes, but none influenced the recognition rate.
 Release highlights
 ++++++++++++++++++
 
-- A whole lot of exceptions with meaningful error messages.
-- A tutorial for Windows users: `http://bytefish.de/blog/opencv_visual_studio_and_libfacerec <http://bytefish.de/blog/opencv_visual_studio_and_libfacerec>`_
+* A whole lot of exceptions with meaningful error messages.
+* A tutorial for Windows users: `http://bytefish.de/blog/opencv_visual_studio_and_libfacerec <http://bytefish.de/blog/opencv_visual_studio_and_libfacerec>`_
 
 
 Release 0.03
@@ -48,8 +48,8 @@ documentation for details.
 Release highlights
 ++++++++++++++++++
 
-- New Unit Tests (for LBP Histograms) make the library more robust.
-- Added more documentation.
+* New Unit Tests (for LBP Histograms) make the library more robust.
+* Added more documentation.
 
 
 Release 0.02
@@ -63,8 +63,8 @@ documentation for details.
 Release highlights
 ++++++++++++++++++
 
-- New Unit Tests (for LBP Histograms) make the library more robust.
-- Added a documentation and changelog in reStructuredText.
+* New Unit Tests (for LBP Histograms) make the library more robust.
+* Added a documentation and changelog in reStructuredText.
 
 Release 0.01
 ------------
@@ -74,13 +74,13 @@ Initial release as header-only library.
 Release highlights
 ++++++++++++++++++
 
-- Colormaps for OpenCV to enhance the visualization.
-- Face Recognition algorithms implemented:
+* Colormaps for OpenCV to enhance the visualization.
+* Face Recognition algorithms implemented:
 
-  - Eigenfaces [TP91]_
-  - Fisherfaces [BHK97]_
-  - Local Binary Patterns Histograms [AHP04]_
+  * Eigenfaces [TP91]_
+  * Fisherfaces [BHK97]_
+  * Local Binary Patterns Histograms [AHP04]_
   
-- Added persistence facilities to store the models with a common API.
-- Unit Tests (using `gtest <http://code.google.com/p/googletest/>`_).
-- Providing a CMakeLists.txt to enable easy cross-platform building.
+* Added persistence facilities to store the models with a common API.
+* Unit Tests (using `gtest <http://code.google.com/p/googletest/>`_).
+* Providing a CMakeLists.txt to enable easy cross-platform building.

modules/contrib/doc/facerec/facerec_tutorial.rst

@@ -13,11 +13,11 @@ OpenCV 2.4 now comes with the very new :ocv:class:`FaceRecognizer` class for fac
 
 The currently available algorithms are:
 
-    * Eigenfaces (see :ocv:func:`createEigenFaceRecognizer`)
-    * Fisherfaces (see :ocv:func:`createFisherFaceRecognizer`)
-    * Local Binary Patterns Histograms (see :ocv:func:`createLBPHFaceRecognizer`)
+* Eigenfaces (see :ocv:func:`createEigenFaceRecognizer`)
+* Fisherfaces (see :ocv:func:`createFisherFaceRecognizer`)
+* Local Binary Patterns Histograms (see :ocv:func:`createLBPHFaceRecognizer`)
 
-You don't need to copy and paste the source code examples from this page, because they are available in the ``samples/cpp`` folder coming with OpenCV. If you have built OpenCV with the samples turned on, chances are good you have them compiled already! Although it might be interesting for very advanced users, I've decided to leave the implementation details out as I am afraid they confuse new users.
+You don't need to copy and paste the source code examples from this page, because they are available in the ``src`` folder coming with this documentation. If you have built OpenCV with the samples turned on, chances are good you have them compiled already! Although it might be interesting for very advanced users, I've decided to leave the implementation details out as I am afraid they confuse new users.
 
 All code in this document is released under the `BSD license <http://www.opensource.org/licenses/bsd-license>`_, so feel free to use it for your projects.
 
@@ -39,16 +39,16 @@ Let's get some data to experiment with first. I don't want to do a toy example h
 
 * `AT&T Facedatabase <http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html>`_ The AT&T Facedatabase, sometimes also referred to as *ORL Database of Faces*, contains ten different images of each of 40 distinct subjects. For some subjects, the images were taken at different times, varying the lighting, facial expressions (open / closed eyes, smiling / not smiling) and facial details (glasses / no glasses). All the images were taken against a dark homogeneous background with the subjects in an upright, frontal position (with tolerance for some side movement).
 
-* `Yale Facedatabase A <http://cvc.yale.edu/projects/yalefaces/yalefaces.html>`_ The AT&T Facedatabase is good for initial tests, but it's a fairly easy database. The Eigenfaces method already has a 97% recognition rate, so you won't see any improvements with other algorithms. The Yale Facedatabase A is a more appropriate dataset for initial experiments, because the recognition problem is harder. The database consists of 15 people (14 male, 1 female) each with 11 grayscale images sized :math:`320 \times 243` pixel. There are changes in the light conditions (center light, left light, right light), facial expressions (happy, normal, sad, sleepy, surprised, wink) and glasses (glasses, no-glasses).
+* `Yale Facedatabase A <http://vision.ucsd.edu/content/yale-face-database>`_, also known as Yalefaces. The AT&T Facedatabase is good for initial tests, but it's a fairly easy database. The Eigenfaces method already has a 97% recognition rate on it, so you won't see any great improvements with other algorithms. The Yale Facedatabase A (also known as Yalefaces) is a more appropriate dataset for initial experiments, because the recognition problem is harder. The database consists of 15 people (14 male, 1 female) each with 11 grayscale images sized :math:`320 \times 243` pixel. There are changes in the light conditions (center light, left light, right light), facial expressions (happy, normal, sad, sleepy, surprised, wink) and glasses (glasses, no-glasses).
 
-  Bad news is it's not available for public download anymore, because the original server seems to be down. You can find some sites mirroring it (`like the MIT <http://vismod.media.mit.edu/vismod/classes/mas622-00/datasets/>`_), but I can't make guarantees about the integrity. If you need to crop and align the images yourself, read my notes at `bytefish.de/blog/fisherfaces <http://bytefish.de/blog/fisherfaces>`_.
+  The original images are not cropped and aligned. Please look into the :ref:`appendixft` for a Python script, that does the job for you.
 
 * `Extended Yale Facedatabase B <http://vision.ucsd.edu/~leekc/ExtYaleDatabase/ExtYaleB.html>`_ The Extended Yale Facedatabase B contains 2414 images of 38 different people in its cropped version. The focus of this database is set on extracting features that are robust to illumination, the images have almost no variation in emotion/occlusion/... . I personally think, that this dataset is too large for the experiments I perform in this document. You better use the `AT&T Facedatabase <http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html>`_ for intial testing. A first version of the Yale Facedatabase B was used in [BHK97]_ to see how the Eigenfaces and Fisherfaces method perform under heavy illumination changes. [Lee05]_ used the same setup to take 16128 images of 28 people. The Extended Yale Facedatabase B is the merge of the two databases, which is now known as Extended Yalefacedatabase B.
 
 Preparing the data
 -------------------
 
-Once we have acquired some data, we'll need to read it in our program. In the demo I have decided to read the images from a very simple CSV file. Why? Because it's the simplest platform-independent approach I can think of. However, if you know a simpler solution please ping me about it. Basically all the CSV file needs to contain are lines composed of a ``filename`` followed by a ``;`` followed by the ``label`` (as *integer number*), making up a line like this:
+Once we have acquired some data, we'll need to read it in our program. In the demo applications I have decided to read the images from a very simple CSV file. Why? Because it's the simplest platform-independent approach I can think of. However, if you know a simpler solution please ping me about it. Basically all the CSV file needs to contain are lines composed of a ``filename`` followed by a ``;`` followed by the ``label`` (as *integer number*), making up a line like this:
 
 .. code-block:: none
 
@@ -201,6 +201,11 @@ For the first source code example, I'll go through it with you. I am first givin
 .. literalinclude:: src/facerec_eigenfaces.cpp
    :language: cpp
    :linenos:
+   
+The source code for this demo application is also available in the ``src`` folder coming with this documentation:
+
+* :download:`src/facerec_eigenfaces.cpp <src/facerec_eigenfaces.cpp>`
+
 
 I've used the jet colormap, so you can see how the grayscale values are distributed within the specific Eigenfaces. You can see, that the Eigenfaces do not only encode facial features, but also the illumination in the images (see the left light in Eigenface \#4, right light in Eigenfaces \#5):
 
@@ -319,6 +324,11 @@ Fisherfaces in OpenCV
    :language: cpp
    :linenos:
 
+The source code for this demo application is also available in the ``src`` folder coming with this documentation:
+
+* :download:`src/facerec_fisherfaces.cpp <src/facerec_fisherfaces.cpp>`
+
+
 For this example I am going to use the Yale Facedatabase A, just because the plots are nicer. Each Fisherface has the same length as an original image, thus it can be displayed as an image. The demo shows (or saves) the first, at most 16 Fisherfaces:
 
 .. image:: img/fisherfaces_opencv.png
@@ -440,6 +450,10 @@ Local Binary Patterns Histograms in OpenCV
    :language: cpp
    :linenos:
 
+The source code for this demo application is also available in the ``src`` folder coming with this documentation:
+
+* :download:`src/facerec_lbph.cpp <src/facerec_lbph.cpp>`
+
 Conclusion
 ==========
 

modules/contrib/doc/facerec/tutorial/facerec_gender_classification.rst

@@ -9,10 +9,10 @@ Introduction
 
 A lot of people interested in face recognition, also want to know how to perform image classification tasks like:
 
-    * Gender Classification (Gender Detection)
-    * Emotion Classification (Emotion Detection)
-    * Glasses Classification (Glasses Detection)
-    * ...
+* Gender Classification (Gender Detection)
+* Emotion Classification (Emotion Detection)
+* Glasses Classification (Glasses Detection)
+* ...
 
 This is has become very, very easy with the new :ocv:class:`FaceRecognizer` class. In this tutorial I'll show you how to perform gender classification with OpenCV on a set of face images. You'll also learn how to align your images to enhance the recognition results. If you want to do emotion classification instead of gender classification, all you need to do is to update is your training data and the configuration you pass to the demo.
 
@@ -35,7 +35,7 @@ For gender classification of faces, you'll need some images of male and female f
 * Patrick Stewart
 * Tom Cruise
 
-Once you have acquired some images, you'll need to read them. In the demo I have decided to read the images from a very simple CSV file. Why? Because it's the simplest platform-independent approach I can think of. However, if you know a simpler solution please ping me about it. Basically all the CSV file needs to contain are lines composed of a ``filename`` followed by a ``;`` followed by the ``label`` (as *integer number*), making up a line like this:
+Once you have acquired some images, you'll need to read them. In the demo application I have decided to read the images from a very simple CSV file. Why? Because it's the simplest platform-independent approach I can think of. However, if you know a simpler solution please ping me about it. Basically all the CSV file needs to contain are lines composed of a ``filename`` followed by a ``;`` followed by the ``label`` (as *integer number*), making up a line like this:
 
 .. code-block:: none
 
@@ -71,14 +71,16 @@ You really don't want to create the CSV file by hand. And you really don't want
 Fisherfaces for Gender Classification
 --------------------------------------
 
-If you want to decide wether a person is *male* or *female*, you have to learn the discriminative features of both classes. The Eigenfaces method is based on the Principal Component Analysis, which is an unsupervised statistical model and not suitable for this task. Please see the Face Recognition tutorial for insights into the algorithms. The Fisherfaces instead yields a class-specific linear projection, so it is much better suited for the gender classification task. `http://www.bytefish.de/blog/gender_classification <http://www.bytefish.de/blog/gender_classification>`_  shows the recongition rate of the Fisherfaces method for gender classification.
+If you want to decide wether a person is *male* or *female*, you have to learn the discriminative features of both classes. The Eigenfaces method is based on the Principal Component Analysis, which is an unsupervised statistical model and not suitable for this task. Please see the Face Recognition tutorial for insights into the algorithms. The Fisherfaces instead yields a class-specific linear projection, so it is much better suited for the gender classification task. `http://www.bytefish.de/blog/gender_classification <http://www.bytefish.de/blog/gender_classification>`_  shows the recognition rate of the Fisherfaces method for gender classification.
 
 The Fisherfaces method achieves a 98% recognition rate in a subject-independent cross-validation. A subject-independent cross-validation means *images of the person under test are never used for learning the model*. And could you believe it: you can simply use the facerec_fisherfaces demo, that's inlcuded in OpenCV.
 
 Fisherfaces in OpenCV
 ---------------------
 
-The source code for the demo is available in the ``samples/cpp`` folder of your OpenCV installation. If you have built OpenCV with samples turned on, chances are good you have the executable already.
+The source code for this demo application is also available in the ``src`` folder coming with this documentation:
+
+* :download:`src/facerec_fisherfaces.cpp <../src/facerec_fisherfaces.cpp>`
 
 .. literalinclude:: ../src/facerec_fisherfaces.cpp
    :language: cpp

modules/contrib/doc/facerec/tutorial/facerec_save_load.rst

@@ -4,22 +4,19 @@ Saving and Loading a FaceRecognizer
 Introduction
 ------------
 
-Saving and loading a :ocv:class:`FaceRecognizer` is very important. Training a FaceRecognizer can be a very
-time-intense task, plus it's often impossible to ship the whole face database to the user of your product.
+Saving and loading a :ocv:class:`FaceRecognizer` is very important. Training a FaceRecognizer can be a very time-intense task, plus it's often impossible to ship the whole face database to the user of your product. The task of saving and loading a FaceRecognizer is easy with :ocv:class:`FaceRecognizer`. You only have to call :ocv:func:`FaceRecognizer::load` for loading and :ocv:func:`FaceRecognizer::save` for saving a :ocv:class:`FaceRecognizer`.
 
-The task of saving and loading a FaceRecognizer is easy with :ocv:class:`FaceRecognizer`. You only have to
-call :ocv:func:`FaceRecognizer::load` for loading and :ocv:func:`FaceRecognizer::save` for saving a
-:ocv:class:`FaceRecognizer`.
+I'll adapt the Eigenfaces example from the :doc:`../facerec_tutorial`: Imagine we want to learn the Eigenfaces of the `AT&T Facedatabase <http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html>`_, store the model to a YAML file and then load it again. 
 
-I'll adapt the Eigenfaces example from the :doc:`../facerec_tutorial`: Imagine we want to learn the Eigenfaces
- of the `AT&T Facedatabase <http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html>`_ store the
- model to a YAML file and then load it again.
-
-From the loaded model, we'll get a prediction, show the mean, eigenfaces and the image reconstruction.
+From the loaded model, we'll get a prediction, show the mean, Eigenfaces and the image reconstruction.
 
 Using FaceRecognizer::save and FaceRecognizer::load
 -----------------------------------------------------
 
+The source code for this demo application is also available in the ``src`` folder coming with this documentation:
+
+* :download:`src/facerec_save_load.cpp <../src/facerec_save_load.cpp>`
+
 .. literalinclude:: ../src/facerec_save_load.cpp
    :language: cpp
    :linenos:

modules/contrib/doc/facerec/tutorial/facerec_video_recognition.rst

@@ -7,19 +7,19 @@ Face Recognition in Videos with OpenCV
 Introduction
 ------------
 
-Whenever you hear the term *face recognition*, you instantly think of surveillance in videos. So performing face recognition in videos (e.g. webcam) is one of the most requested features I got. I have heard your cries, so here it is. For face detection we'll use the awesome :ocv:class:`CascadeClassifier`, and we'll use :ocv:class:`FaceRecognizer` for face recognition. This example uses the Fisherfaces method for face recognition, because it is robust against large changes in illumination.
+Whenever you hear the term *face recognition*, you instantly think of surveillance in videos. So performing face recognition in videos (e.g. webcam) is one of the most requested features I have got. I have heard your cries, so here it is. An application, that shows you how to do face recognition in videos! For the face detection part we'll use the awesome :ocv:class:`CascadeClassifier` and we'll use :ocv:class:`FaceRecognizer` for face recognition. This example uses the Fisherfaces method for face recognition, because it is robust against large changes in illumination.
 
-Here is what the final application looks like, as you can see I am only writing the id of the recognized person (by the way this id is Arnold Schwarzenegger for my data set) above the detected face.
+Here is what the final application looks like. As you can see I am only writing the id of the recognized person above the detected face (by the way this id is Arnold Schwarzenegger for my data set):
 
 .. image:: ../img/tutorial/facerec_video/facerec_video.png
     :align: center
     :scale: 70%
 
-This demo is a basis for your research, and it shows you how to implement face recognition in videos. You probably want to extend the application and make it more sophisticated: You could combine the id with the name, show the confidence of the prediction, recognize the emotion... and and and. But before you send mails, asking what these Haar-Cascade thing is or what a CSV is... Make sure you have read the entire tutorial. It's all explained in here. If you just want to scroll down to the code, please note:
+This demo is a basis for your research and it shows you how to implement face recognition in videos. You probably want to extend the application and make it more sophisticated: You could combine the id with the name, then show the confidence of the prediction, recognize the emotion... and and and. But before you send mails, asking what these Haar-Cascade thing is or what a CSV is: Make sure you have read the entire tutorial. It's all explained in here. If you just want to scroll down to the code, please note:
 
-* The available Haar-Cascades are located in the ``data`` folder of your OpenCV installation! One of the available Haar-Cascades for face detection is for example ``data/haarcascades/haarcascade_frontalface_default.xml``.
+* The available Haar-Cascades for face detection are located in the ``data`` folder of your OpenCV installation! One of the available Haar-Cascades for face detection is for example ``/path/to/opencv/data/haarcascades/haarcascade_frontalface_default.xml``.
 
-I encourage you to experiment with the application. Play around with the available :ocv:class:`FaceRecognizer`, try the available cascades in OpenCV and see if you can improve your results!
+I encourage you to experiment with the application. Play around with the available :ocv:class:`FaceRecognizer` implementations, try the available cascades in OpenCV and see if you can improve your results!
 
 Prerequisites
 --------------
@@ -74,7 +74,11 @@ All images for this example were chosen to have a frontal face perspective. They
 Face Recongition from Videos
 -----------------------------
 
-The source code for the demo is available in the ``samples/cpp`` folder of your OpenCV installation. If you have built OpenCV with samples turned on, chances are good you have the executable already. This demo uses the :ocv:class:`CascadeClassifier`:
+The source code for the demo is available in the ``src`` folder coming with this documentation:
+
+* :download:`src/facerec_video.cpp <../src/facerec_video.cpp>`
+
+This demo uses the :ocv:class:`CascadeClassifier`:
 
 .. literalinclude:: ../src/facerec_video.cpp
    :language: cpp
@@ -99,14 +103,16 @@ If you are in Linux, then simply start the demo by running:
 
 .. code-block:: none
 
-    ./facerec_video </path/to/your/haar_cascade.xml> <C:/path/to/your/csv.ext> <video device>
+    ./facerec_video </path/to/your/haar_cascade.xml> </path/to/your/csv.ext> <video device>
 
-So if the haar-cascade is at ``C:/opencv/data/haarcascades/haarcascade_frontalface_default.xml``, the CSV file at ``C:/facerec/data/celebrities.txt`` and i have a webcam with deviceId ``1``, then I would call the demo with:
+An example. If the haar-cascade is at ``C:/opencv/data/haarcascades/haarcascade_frontalface_default.xml``, the CSV file is at ``C:/facerec/data/celebrities.txt`` and I have a webcam with deviceId ``1``, then I would call the demo with:
 
 .. code-block:: none
 
     facerec_video.exe C:/opencv/data/haarcascades/haarcascade_frontalface_default.xml C:/facerec/data/celebrities.txt 1
 
+That's it. 
+
 Results
 -------