Added the cv::FaceRecognizer documentation (API, Face Recognition Guide, Tutorials).

modules/contrib/doc/contrib.rst

@@ -8,3 +8,4 @@ The module contains some recently added functionality that has not been stabiliz
     :maxdepth: 2
 
     stereo
+    FaceRecognizer Documentation <facerec/index>

modules/contrib/doc/facerec/colormaps.rst

+ColorMaps in OpenCV
+===================
+
+applyColorMap
+---------------------
+
+Trains a FaceRecognizer with given data and associated labels.
+
+.. ocv:function:: void applyColorMap(InputArray src, OutputArray dst, int colormap)
+    
+    :param src: The source image, grayscale or colored does not matter.
+    :param dst: The result is the colormapped source image. Note: :ocv:func:`Mat::create` is called on dst.
+    :param colormap: The colormap to apply, see the list of available colormaps below.
+
+Currently the following GNU Octave/MATLAB equivalent colormaps are implemented:
+
+.. code-block:: cpp
+
+    enum
+    {
+        COLORMAP_AUTUMN = 0,
+        COLORMAP_BONE = 1,
+        COLORMAP_JET = 2,
+        COLORMAP_WINTER = 3,
+        COLORMAP_RAINBOW = 4,
+        COLORMAP_OCEAN = 5,
+        COLORMAP_SUMMER = 6,
+        COLORMAP_SPRING = 7,
+        COLORMAP_COOL = 8,
+        COLORMAP_HSV = 9,
+        COLORMAP_PINK = 10,
+        COLORMAP_HOT = 11
+    }
+
+
+Description
+-----------
+
+The human perception isn't built for observing fine changes in grayscale images. Human eyes are more sensitive to observing changes between colors, so you often need to recolor your grayscale images to get a clue about them. OpenCV now comes with various colormaps to enhance the visualization in your computer vision application.
+
+In OpenCV 2.4 you only need :ocv:func:`applyColorMap` to apply a colormap on a given image. The following sample code reads the path to an image from command line, applies a Jet colormap on it and shows the result:
+
+.. code-block:: cpp
+
+    #include <opencv2/contrib/contrib.hpp>
+    #include <opencv2/core/core.hpp>
+    #include <opencv2/highgui/highgui.hpp>
+
+    using namespace cv;
+
+    int main(int argc, const char *argv[]) {
+        // Get the path to the image, if it was given
+        // if no arguments were given.
+        string filename;
+        if (argc > 1) {
+            filename = string(argv[1]);
+        }
+	    // The following lines show how to apply a colormap on a given image
+	    // and show it with cv::imshow example with an image. An exception is
+	    // thrown if the path to the image is invalid.
+	    if(!filename.empty()) {
+            Mat img0 = imread(filename);
+            // Throw an exception, if the image can't be read:
+            if(img0.empty()) {
+                CV_Error(CV_StsBadArg, "Sample image is empty. Please adjust your path, so it points to a valid input image!");
+            }
+            // Holds the colormap version of the image:
+            Mat cm_img0;
+            // Apply the colormap:
+            applyColorMap(img0, cm_img0, COLORMAP_JET);
+            // Show the result:
+            imshow("cm_img0", cm_img0);
+            waitKey(0);
+	    }
+
+	    return 0;
+    }
+
+And here are the color scales for each of the available colormaps:
+
++-----------------------+---------------------------------------------------+
+| Class                 | Scale                                             |
++=======================+===================================================+
+| COLORMAP_AUTUMN       | .. image:: img/colormaps/colorscale_autumn.jpg    |
++-----------------------+---------------------------------------------------+
+| COLORMAP_BONE         | .. image:: img/colormaps/colorscale_bone.jpg      |
++-----------------------+---------------------------------------------------+
+| COLORMAP_COOL         | .. image:: img/colormaps/colorscale_cool.jpg      |
++-----------------------+---------------------------------------------------+
+| COLORMAP_HOT          | .. image:: img/colormaps/colorscale_hot.jpg       |
++-----------------------+---------------------------------------------------+
+| COLORMAP_HSV          | .. image:: img/colormaps/colorscale_hsv.jpg       |
++-----------------------+---------------------------------------------------+
+| COLORMAP_JET          | .. image:: img/colormaps/colorscale_jet.jpg       |
++-----------------------+---------------------------------------------------+
+| COLORMAP_OCEAN        | .. image:: img/colormaps/colorscale_ocean.jpg     |
++-----------------------+---------------------------------------------------+
+| COLORMAP_PINK         | .. image:: img/colormaps/colorscale_pink.jpg      |
++-----------------------+---------------------------------------------------+
+| COLORMAP_RAINBOW      | .. image:: img/colormaps/colorscale_rainbow.jpg   |
++-----------------------+---------------------------------------------------+
+| COLORMAP_SPRING       | .. image:: img/colormaps/colorscale_spring.jpg    |
++-----------------------+---------------------------------------------------+
+| COLORMAP_SUMMER       | .. image:: img/colormaps/colorscale_summer.jpg    |
++-----------------------+---------------------------------------------------+
+| COLORMAP_WINTER       | .. image:: img/colormaps/colorscale_winter.jpg    |
++-----------------------+---------------------------------------------------+

modules/contrib/doc/facerec/facerec_changelog.rst

+Changelog
+=========
+
+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
+OpenCV API. 
+
+To reduce the confusion on user side and minimize my work, libfacerec and OpenCV 
+have been synchronized and are now based on the same interfaces and implementation. 
+
+The library now has an extensive documentation:
+
+* The API is explained in detail and with a lot of code examples.
+* The face recognition guide I had written for Python and GNU Octave/MATLAB has been adapted to the new OpenCV C++ ``cv::FaceRecognizer``. 
+* A tutorial for gender classification with Fisherfaces.
+* A tutorial for face recognition in videos (e.g. webcam). 
+
+
+Release highlights
+++++++++++++++++++
+
+- There are no single highlights to pick from, this release is a highlight itself.
+
+Release 0.04
+------------
+
+This version is fully Windows-compatible and works with OpenCV 2.3.1. Several 
+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>`_
+
+
+Release 0.03
+------------
+
+Reworked the library to provide separate implementations in cpp files, because 
+it's the preferred way of contributing OpenCV libraries. This means the library 
+is not header-only anymore. Slight API changes were done, please see the 
+documentation for details.
+
+Release highlights
+++++++++++++++++++
+
+- New Unit Tests (for LBP Histograms) make the library more robust.
+- Added more documentation.
+
+
+Release 0.02
+------------
+
+Reworked the library to provide separate implementations in cpp files, because 
+it's the preferred way of contributing OpenCV libraries. This means the library 
+is not header-only anymore. Slight API changes were done, please see the 
+documentation for details.
+
+Release highlights
+++++++++++++++++++
+
+- New Unit Tests (for LBP Histograms) make the library more robust.
+- Added a documentation and changelog in reStructuredText.
+
+Release 0.01
+------------
+
+Initial release as header-only library.
+
+Release highlights
+++++++++++++++++++
+
+- Colormaps for OpenCV to enhance the visualization.
+- Face Recognition algorithms implemented:
+
+  - Eigenfaces [TP91]_
+  - Fisherfaces [Belhumeur97]_
+  - Local Binary Patterns Histograms [Ahonen04]_
+  
+- 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/index.rst

+FaceRecognizer - Face Recognition with OpenCV
+##############################################
+
+OpenCV 2.4 now comes with the very new :ocv:class:`FaceRecognizer` class for face recognition. This documentation is going to explain you `the API <facerec_api.rst>`_ in detail and it will give you a lot of help to get started (full source code examples). `Face Recognition with OpenCV <facerec_tutorial.rst>`_ is the definite guide to the new :ocv:class:`FaceRecognizer`. There's also a `tutorial on gender classification <tutorial/facerec_gender_classification.rst>`_, a `tutorial for face recognition in videos <tutorial/facerec_video_recognition.rst>`_ and it's shown `how to load & save your results <tutorial/facerec_save_load.rst>`_. 
+
+These documents are the help I have wished for, when I was working myself into face recognition. I hope you also think the new :ocv:class:`FaceRecognizer` is a useful addition to OpenCV. 
+
+Please issue any feature requests and/or bugs on the official OpenCV bug tracker at:
+
+  * http://code.opencv.org/projects/opencv/issues
+
+Contents
+========
+
+
+.. toctree::
+   :maxdepth: 1
+   
+   FaceRecognizer API <facerec_api>
+   Guide to Face Recognition with OpenCV <facerec_tutorial>
+   Tutorial on Gender Classification <tutorial/facerec_gender_classification>
+   Tutorial on Face Recognition in Videos <tutorial/facerec_video_recognition>
+   Tutorial On Saving & Loading a FaceRecognizer <tutorial/facerec_save_load>
+   How to use Colormaps in OpenCV <colormaps>
+   Changelog <facerec_changelog>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

modules/contrib/doc/facerec/src/create_csv.py

+import sys
+import os.path
+
+# This is a tiny script to help you creating a CSV file from a face
+# database with a similar hierarchie:
+# 
+#  philipp@mango:~/facerec/data/at$ tree
+#  .
+#  |-- README
+#  |-- s1
+#  |   |-- 1.pgm
+#  |   |-- ...
+#  |   |-- 10.pgm
+#  |-- s2
+#  |   |-- 1.pgm
+#  |   |-- ...
+#  |   |-- 10.pgm
+#  ...
+#  |-- s40
+#  |   |-- 1.pgm
+#  |   |-- ...
+#  |   |-- 10.pgm
+#
+
+if __name__ == "__main__":
+    
+    if len(sys.argv) != 2:
+        print "usage: create_csv <base_path>"
+        sys.exit(1)
+    
+    BASE_PATH=sys.argv[1]
+    SEPARATOR=";"
+
+    label = 0
+    for dirname, dirnames, filenames in os.walk(BASE_PATH):
+        for subdirname in dirnames:
+            subject_path = os.path.join(dirname, subdirname)
+            for filename in os.listdir(subject_path):
+                abs_path = "%s/%s" % (subject_path, filename)
+                print "%s%s%d" % (abs_path, SEPARATOR, label)
+            label = label + 1

modules/contrib/doc/facerec/src/crop_face.py

+#!/usr/bin/env python
+# Software License Agreement (BSD License)
+#
+# Copyright (c) 2012, Philipp Wagner
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above
+#    copyright notice, this list of conditions and the following
+#    disclaimer in the documentation and/or other materials provided
+#    with the distribution.
+#  * Neither the name of the author nor the names of its
+#    contributors may be used to endorse or promote products derived
+#    from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import sys, math, Image
+
+def Distance(p1,p2):
+  dx = p2[0] - p1[0]
+  dy = p2[1] - p1[1]
+  return math.sqrt(dx*dx+dy*dy)
+
+def ScaleRotateTranslate(image, angle, center = None, new_center = None, scale = None, resample=Image.BICUBIC):
+  if (scale is None) and (center is None):
+    return image.rotate(angle=angle, resample=resample)
+  nx,ny = x,y = center
+  sx=sy=1.0
+  if new_center:
+    (nx,ny) = new_center
+  if scale:
+    (sx,sy) = (scale, scale)
+  cosine = math.cos(angle)
+  sine = math.sin(angle)
+  a = cosine/sx
+  b = sine/sx
+  c = x-nx*a-ny*b
+  d = -sine/sy
+  e = cosine/sy
+  f = y-nx*d-ny*e
+  return image.transform(image.size, Image.AFFINE, (a,b,c,d,e,f), resample=resample)
+
+def CropFace(image, eye_left=(0,0), eye_right=(0,0), offset_pct=(0.2,0.2), dest_sz = (70,70)):
+  # calculate offsets in original image
+  offset_h = math.floor(float(offset_pct[0])*dest_sz[0])
+  offset_v = math.floor(float(offset_pct[1])*dest_sz[1])
+  # get the direction
+  eye_direction = (eye_right[0] - eye_left[0], eye_right[1] - eye_left[1])
+  # calc rotation angle in radians
+  rotation = -math.atan2(float(eye_direction[1]),float(eye_direction[0]))
+  # distance between them
+  dist = Distance(eye_left, eye_right)
+  # calculate the reference eye-width
+  reference = dest_sz[0] - 2.0*offset_h
+  # scale factor
+  scale = float(dist)/float(reference)
+  # rotate original around the left eye
+  image = ScaleRotateTranslate(image, center=eye_left, angle=rotation)
+  # crop the rotated image
+  crop_xy = (eye_left[0] - scale*offset_h, eye_left[1] - scale*offset_v)
+  crop_size = (dest_sz[0]*scale, dest_sz[1]*scale)
+  image = image.crop((int(crop_xy[0]), int(crop_xy[1]), int(crop_xy[0]+crop_size[0]), int(crop_xy[1]+crop_size[1])))
+  # resize it
+  image = image.resize(dest_sz, Image.ANTIALIAS)
+  return image
+  
+if __name__ == "__main__":
+  image =  Image.open("arnie.jpg")
+  CropFace(image, eye_left=(252,364), eye_right=(420,366), offset_pct=(0.1,0.1), dest_sz=(200,200)).save("arnie_10_10_200_200.jpg")
+  CropFace(image, eye_left=(252,364), eye_right=(420,366), offset_pct=(0.2,0.2), dest_sz=(200,200)).save("arnie_20_20_200_200.jpg")
+  CropFace(image, eye_left=(252,364), eye_right=(420,366), offset_pct=(0.3,0.3), dest_sz=(200,200)).save("arnie_30_30_200_200.jpg")
+  CropFace(image, eye_left=(252,364), eye_right=(420,366), offset_pct=(0.2,0.2)).save("arnie_20_20_70_70.jpg")

modules/contrib/doc/facerec/src/facerec_demo.cpp

+/*
+ * Copyright (c) 2011. Philipp Wagner <bytefish[at]gmx[dot]de>.
+ * Released to public domain under terms of the BSD Simplified license.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *   * Neither the name of the organization nor the names of its contributors
+ *     may be used to endorse or promote products derived from this software
+ *     without specific prior written permission.
+ *
+ *   See <http://www.opensource.org/licenses/bsd-license>
+ */
+
+#include "opencv2/core/core.hpp"
+#include "opencv2/contrib/contrib.hpp"
+#include "opencv2/highgui/highgui.hpp"
+
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace std;
+
+static Mat norm_0_255(InputArray _src) {
+    Mat src = _src.getMat();
+    // Create and return normalized image:
+    Mat dst;
+    switch(src.channels()) {
+    case 1:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC1);
+        break;
+    case 3:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC3);
+        break;
+    default:
+        src.copyTo(dst);
+        break;
+    }
+    return dst;
+}
+
+static void read_csv(const string& filename, vector<Mat>& images, vector<int>& labels, char separator = ';') {
+    std::ifstream file(filename.c_str(), ifstream::in);
+    if (!file) {
+        string error_message = "No valid input file was given, please check the given filename.";
+        CV_Error(CV_StsBadArg, error_message);
+    }
+    string line, path, classlabel;
+    while (getline(file, line)) {
+        stringstream liness(line);
+        getline(liness, path, separator);
+        getline(liness, classlabel);
+        if(!path.empty() && !classlabel.empty()) {
+            images.push_back(imread(path, 0));
+            labels.push_back(atoi(classlabel.c_str()));
+        }
+    }
+}
+
+int main(int argc, const char *argv[]) {
+    // Check for valid command line arguments, print usage
+    // if no arguments were given.
+    if (argc != 2) {
+        cout << "usage: " << argv[0] << " <csv.ext>" << endl;
+        exit(1);
+    }
+    // Get the path to your CSV.
+    string fn_csv = string(argv[1]);
+    // These vectors hold the images and corresponding labels.
+    vector<Mat> images;
+    vector<int> labels;
+    // Read in the data. This can fail if no valid
+    // input filename is given.
+    try {
+        read_csv(fn_csv, images, labels);
+    } catch (cv::Exception& e) {
+        cerr << "Error opening file \"" << fn_csv << "\". Reason: " << e.msg << endl;
+        // nothing more we can do
+        exit(1);
+    }
+    // Quit if there are not enough images for this demo.
+    if(images.size() <= 1) {
+        string error_message = "This demo needs at least 2 images to work. Please add more images to your data set!";
+        CV_Error(CV_StsError, error_message);
+    }
+    // Get the height from the first image. We'll need this
+    // later in code to reshape the images to their original
+    // size:
+    int height = images[0].rows;
+    // The following lines simply get the last images from
+    // your dataset and remove it from the vector. This is
+    // done, so that the training data (which we learn the
+    // cv::FaceRecognizer on) and the test data we test
+    // the model with, do not overlap.
+    Mat testSample = images[images.size() - 1];
+    int testLabel = labels[labels.size() - 1];
+    images.pop_back();
+    labels.pop_back();
+    // The following lines create an Eigenfaces model for
+    // face recognition and train it with the images and
+    // labels read from the given CSV file.
+    // This here is a full PCA, if you just want to keep
+    // 10 principal components (read Eigenfaces), then call
+    // the factory method like this:
+    //
+    //      cv::createEigenFaceRecognizer(10);
+    //
+    // If you want to create a FaceRecognizer with a
+    // confidennce threshold, call it with:
+    //
+    //      cv::createEigenFaceRecognizer(10, 123.0);
+    //
+    Ptr<FaceRecognizer> model = createFisherFaceRecognizer();
+    model->train(images, labels);
+    // The following line predicts the label of a given
+    // test image:
+    int predictedLabel = model->predict(testSample);
+    //
+    // To get the confidence of a prediction call the model with:
+    //
+    //      int predictedLabel = -1;
+    //      double confidence = 0.0;
+    //      model->predict(testSample, predictedLabel, confidence);
+    //
+    string result_message = format("Predicted class = %d / Actual class = %d.", predictedLabel, testLabel);
+    cout << result_message << endl;
+    // Sometimes you'll need to get/set internal model data,
+    // which isn't exposed by the public cv::FaceRecognizer.
+    // Since each cv::FaceRecognizer is derived from a
+    // cv::Algorithm, you can query the data.
+    //
+    // First we'll use it to set the threshold of the FaceRecognizer
+    // to 0.0 without retraining the model. This can be useful if
+    // you are evaluating the model:
+    //
+    model->set("threshold", 0.0);
+    // Now the threshold of this model is set to 0.0. A prediction
+    // now returns -1, as it's impossible to have a distance below
+    // it
+    predictedLabel = model->predict(testSample);
+    cout << "Predicted class = " << predictedLabel << endl;
+    // Here is how to get the eigenvalues of this Eigenfaces model:
+    Mat eigenvalues = model->getMat("eigenvalues");
+    // And we can do the same to display the Eigenvectors (read Eigenfaces):
+    Mat W = model->getMat("eigenvectors");
+    // From this we will display the (at most) first 10 Eigenfaces:
+    for (int i = 0; i < min(10, W.cols); i++) {
+        string msg = format("Eigenvalue #%d = %.5f", i, eigenvalues.at<double>(i));
+        cout << msg << endl;
+        // get eigenvector #i
+        Mat ev = W.col(i).clone();
+        // Reshape to original size & normalize to [0...255] for imshow.
+        Mat grayscale = norm_0_255(ev.reshape(1, height));
+        // Show the image & apply a Jet colormap for better sensing.
+        Mat cgrayscale;
+        applyColorMap(grayscale, cgrayscale, COLORMAP_JET);
+        imshow(format("%d", i), cgrayscale);
+    }
+    waitKey(0);
+
+    return 0;
+}

modules/contrib/doc/facerec/src/facerec_eigenfaces.cpp

+/*
+ * Copyright (c) 2011. Philipp Wagner <bytefish[at]gmx[dot]de>.
+ * Released to public domain under terms of the BSD Simplified license.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *   * Neither the name of the organization nor the names of its contributors
+ *     may be used to endorse or promote products derived from this software
+ *     without specific prior written permission.
+ *
+ *   See <http://www.opensource.org/licenses/bsd-license>
+ */
+
+#include "opencv2/core/core.hpp"
+#include "opencv2/contrib/contrib.hpp"
+#include "opencv2/highgui/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace std;
+
+static Mat norm_0_255(InputArray _src) {
+    Mat src = _src.getMat();
+    // Create and return normalized image:
+    Mat dst;
+    switch(src.channels()) {
+    case 1:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC1);
+        break;
+    case 3:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC3);
+        break;
+    default:
+        src.copyTo(dst);
+        break;
+    }
+    return dst;
+}
+
+static void read_csv(const string& filename, vector<Mat>& images, vector<int>& labels, char separator = ';') {
+    std::ifstream file(filename.c_str(), ifstream::in);
+    if (!file) {
+        string error_message = "No valid input file was given, please check the given filename.";
+        CV_Error(CV_StsBadArg, error_message);
+    }
+    string line, path, classlabel;
+    while (getline(file, line)) {
+        stringstream liness(line);
+        getline(liness, path, separator);
+        getline(liness, classlabel);
+        if(!path.empty() && !classlabel.empty()) {
+            images.push_back(imread(path, 0));
+            labels.push_back(atoi(classlabel.c_str()));
+        }
+    }
+}
+
+int main(int argc, const char *argv[]) {
+    // Check for valid command line arguments, print usage
+    // if no arguments were given.
+    if (argc < 2) {
+        cout << "usage: " << argv[0] << " <csv.ext> <output_folder> " << endl;
+        exit(1);
+    }
+    string output_folder;
+    if (argc == 3) {
+        output_folder = string(argv[2]);
+    }
+    // Get the path to your CSV.
+    string fn_csv = string(argv[1]);
+    // These vectors hold the images and corresponding labels.
+    vector<Mat> images;
+    vector<int> labels;
+    // Read in the data. This can fail if no valid
+    // input filename is given.
+    try {
+        read_csv(fn_csv, images, labels);
+    } catch (cv::Exception& e) {
+        cerr << "Error opening file \"" << fn_csv << "\". Reason: " << e.msg << endl;
+        // nothing more we can do
+        exit(1);
+    }
+    // Quit if there are not enough images for this demo.
+    if(images.size() <= 1) {
+        string error_message = "This demo needs at least 2 images to work. Please add more images to your data set!";
+        CV_Error(CV_StsError, error_message);
+    }
+    // Get the height from the first image. We'll need this
+    // later in code to reshape the images to their original
+    // size:
+    int height = images[0].rows;
+    // The following lines simply get the last images from
+    // your dataset and remove it from the vector. This is
+    // done, so that the training data (which we learn the
+    // cv::FaceRecognizer on) and the test data we test
+    // the model with, do not overlap.
+    Mat testSample = images[images.size() - 1];
+    int testLabel = labels[labels.size() - 1];
+    images.pop_back();
+    labels.pop_back();
+    // The following lines create an Eigenfaces model for
+    // face recognition and train it with the images and
+    // labels read from the given CSV file.
+    // This here is a full PCA, if you just want to keep
+    // 10 principal components (read Eigenfaces), then call
+    // the factory method like this:
+    //
+    //      cv::createEigenFaceRecognizer(10);
+    //
+    // If you want to create a FaceRecognizer with a
+    // confidence threshold (e.g. 123.0), call it with:
+    //
+    //      cv::createEigenFaceRecognizer(10, 123.0);
+    //
+    // If you want to use _all_ Eigenfaces and have a threshold,
+    // then call the method like this:
+    //
+    //      cv::createEigenFaceRecognizer(0, 123.0);
+    //
+    Ptr<FaceRecognizer> model = createEigenFaceRecognizer();
+    model->train(images, labels);
+    // The following line predicts the label of a given
+    // test image:
+    int predictedLabel = model->predict(testSample);
+    //
+    // To get the confidence of a prediction call the model with:
+    //
+    //      int predictedLabel = -1;
+    //      double confidence = 0.0;
+    //      model->predict(testSample, predictedLabel, confidence);
+    //
+    string result_message = format("Predicted class = %d / Actual class = %d.", predictedLabel, testLabel);
+    cout << result_message << endl;
+    // Here is how to get the eigenvalues of this Eigenfaces model:
+    Mat eigenvalues = model->getMat("eigenvalues");
+    // And we can do the same to display the Eigenvectors (read Eigenfaces):
+    Mat W = model->getMat("eigenvectors");
+    // Get the sample mean from the training data
+    Mat mean = model->getMat("mean");
+    // Display or save:
+    if(argc == 2) {
+        imshow("mean", norm_0_255(mean.reshape(1, images[0].rows)));
+    } else {
+        imwrite(format("%s/mean.png", output_folder.c_str()), norm_0_255(mean.reshape(1, images[0].rows)));
+    }
+    // Display or save the Eigenfaces:
+    for (int i = 0; i < min(10, W.cols); i++) {
+        string msg = format("Eigenvalue #%d = %.5f", i, eigenvalues.at<double>(i));
+        cout << msg << endl;
+        // get eigenvector #i
+        Mat ev = W.col(i).clone();
+        // Reshape to original size & normalize to [0...255] for imshow.
+        Mat grayscale = norm_0_255(ev.reshape(1, height));
+        // Show the image & apply a Jet colormap for better sensing.
+        Mat cgrayscale;
+        applyColorMap(grayscale, cgrayscale, COLORMAP_JET);
+        // Display or save:
+        if(argc == 2) {
+            imshow(format("eigenface_%d", i), cgrayscale);
+        } else {
+            imwrite(format("%s/eigenface_%d.png", output_folder.c_str(), i), norm_0_255(cgrayscale));
+        }
+    }
+    // Display or save the image reconstruction at some predefined steps:
+    for(int num_components = 10; num_components < 300; num_components+=15) {
+        // slice the eigenvectors from the model
+        Mat evs = Mat(W, Range::all(), Range(0, num_components));
+        Mat projection = subspaceProject(evs, mean, images[0].reshape(1,1));
+        Mat reconstruction = subspaceReconstruct(evs, mean, projection);
+        // Normalize the result:
+        reconstruction = norm_0_255(reconstruction.reshape(1, images[0].rows));
+        // Display or save:
+        if(argc == 2) {
+            imshow(format("eigenface_reconstruction_%d", num_components), reconstruction);
+        } else {
+            imwrite(format("%s/eigenface_reconstruction_%d.png", output_folder.c_str(), num_components), reconstruction);
+        }
+    }
+    // Display if we are not writing to an output folder:
+    if(argc == 2) {
+        waitKey(0);
+    }
+    return 0;
+}

modules/contrib/doc/facerec/src/facerec_fisherfaces.cpp

+/*
+ * Copyright (c) 2011. Philipp Wagner <bytefish[at]gmx[dot]de>.
+ * Released to public domain under terms of the BSD Simplified license.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *   * Neither the name of the organization nor the names of its contributors
+ *     may be used to endorse or promote products derived from this software
+ *     without specific prior written permission.
+ *
+ *   See <http://www.opensource.org/licenses/bsd-license>
+ */
+
+#include "opencv2/core/core.hpp"
+#include "opencv2/contrib/contrib.hpp"
+#include "opencv2/highgui/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace std;
+
+static Mat norm_0_255(InputArray _src) {
+    Mat src = _src.getMat();
+    // Create and return normalized image:
+    Mat dst;
+    switch(src.channels()) {
+    case 1:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC1);
+        break;
+    case 3:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC3);
+        break;
+    default:
+        src.copyTo(dst);
+        break;
+    }
+    return dst;
+}
+
+static void read_csv(const string& filename, vector<Mat>& images, vector<int>& labels, char separator = ';') {
+    std::ifstream file(filename.c_str(), ifstream::in);
+    if (!file) {
+        string error_message = "No valid input file was given, please check the given filename.";
+        CV_Error(CV_StsBadArg, error_message);
+    }
+    string line, path, classlabel;
+    while (getline(file, line)) {
+        stringstream liness(line);
+        getline(liness, path, separator);
+        getline(liness, classlabel);
+        if(!path.empty() && !classlabel.empty()) {
+            images.push_back(imread(path, 0));
+            labels.push_back(atoi(classlabel.c_str()));
+        }
+    }
+}
+
+int main(int argc, const char *argv[]) {
+    // Check for valid command line arguments, print usage
+    // if no arguments were given.
+    if (argc < 2) {
+        cout << "usage: " << argv[0] << " <csv.ext> <output_folder> " << endl;
+        exit(1);
+    }
+    string output_folder;
+    if (argc == 3) {
+        output_folder = string(argv[2]);
+    }
+    // Get the path to your CSV.
+    string fn_csv = string(argv[1]);
+    // These vectors hold the images and corresponding labels.
+    vector<Mat> images;
+    vector<int> labels;
+    // Read in the data. This can fail if no valid
+    // input filename is given.
+    try {
+        read_csv(fn_csv, images, labels);
+    } catch (cv::Exception& e) {
+        cerr << "Error opening file \"" << fn_csv << "\". Reason: " << e.msg << endl;
+        // nothing more we can do
+        exit(1);
+    }
+    // Quit if there are not enough images for this demo.
+    if(images.size() <= 1) {
+        string error_message = "This demo needs at least 2 images to work. Please add more images to your data set!";
+        CV_Error(CV_StsError, error_message);
+    }
+    // Get the height from the first image. We'll need this
+    // later in code to reshape the images to their original
+    // size:
+    int height = images[0].rows;
+    // The following lines simply get the last images from
+    // your dataset and remove it from the vector. This is
+    // done, so that the training data (which we learn the
+    // cv::FaceRecognizer on) and the test data we test
+    // the model with, do not overlap.
+    Mat testSample = images[images.size() - 1];
+    int testLabel = labels[labels.size() - 1];
+    images.pop_back();
+    labels.pop_back();
+    // The following lines create an Fisherfaces model for
+    // face recognition and train it with the images and
+    // labels read from the given CSV file.
+    // If you just want to keep 10 Fisherfaces, then call
+    // the factory method like this:
+    //
+    //      cv::createFisherFaceRecognizer(10);
+    //
+    // However it is not useful to discard Fisherfaces! Please
+    // always try to use _all_ available Fisherfaces for
+    // classification.
+    //
+    // If you want to create a FaceRecognizer with a
+    // confidence threshold (e.g. 123.0) and use _all_
+    // Fisherfaces, then call it with:
+    //
+    //      cv::createFisherFaceRecognizer(0, 123.0);
+    //
+    Ptr<FaceRecognizer> model = createFisherFaceRecognizer();
+    model->train(images, labels);
+    // The following line predicts the label of a given
+    // test image:
+    int predictedLabel = model->predict(testSample);
+    //
+    // To get the confidence of a prediction call the model with:
+    //
+    //      int predictedLabel = -1;
+    //      double confidence = 0.0;
+    //      model->predict(testSample, predictedLabel, confidence);
+    //
+    string result_message = format("Predicted class = %d / Actual class = %d.", predictedLabel, testLabel);
+    cout << result_message << endl;
+    // Here is how to get the eigenvalues of this Eigenfaces model:
+    Mat eigenvalues = model->getMat("eigenvalues");
+    // And we can do the same to display the Eigenvectors (read Eigenfaces):
+    Mat W = model->getMat("eigenvectors");
+    // Get the sample mean from the training data
+    Mat mean = model->getMat("mean");
+    // Display or save:
+    if(argc == 2) {
+        imshow("mean", norm_0_255(mean.reshape(1, images[0].rows)));
+    } else {
+        imwrite(format("%s/mean.png", output_folder.c_str()), norm_0_255(mean.reshape(1, images[0].rows)));
+    }
+    // Display or save the first, at most 16 Fisherfaces:
+    for (int i = 0; i < min(16, W.cols); i++) {
+        string msg = format("Eigenvalue #%d = %.5f", i, eigenvalues.at<double>(i));
+        cout << msg << endl;
+        // get eigenvector #i
+        Mat ev = W.col(i).clone();
+        // Reshape to original size & normalize to [0...255] for imshow.
+        Mat grayscale = norm_0_255(ev.reshape(1, height));
+        // Show the image & apply a Bone colormap for better sensing.
+        Mat cgrayscale;
+        applyColorMap(grayscale, cgrayscale, COLORMAP_BONE);
+        // Display or save:
+        if(argc == 2) {
+            imshow(format("fisherface_%d", i), cgrayscale);
+        } else {
+            imwrite(format("%s/fisherface_%d.png", output_folder.c_str(), i), norm_0_255(cgrayscale));
+        }
+    }
+    // Display or save the image reconstruction at some predefined steps:
+    for(int num_component = 0; num_component < min(16, W.cols); num_component++) {
+        // Slice the Fisherface from the model:
+        Mat ev = W.col(num_component);
+        Mat projection = subspaceProject(ev, mean, images[0].reshape(1,1));
+        Mat reconstruction = subspaceReconstruct(ev, mean, projection);
+        // Normalize the result:
+        reconstruction = norm_0_255(reconstruction.reshape(1, images[0].rows));
+        // Display or save:
+        if(argc == 2) {
+            imshow(format("fisherface_reconstruction_%d", num_component), reconstruction);
+        } else {
+            imwrite(format("%s/fisherface_reconstruction_%d.png", output_folder.c_str(), num_component), reconstruction);
+        }
+    }
+    // Display if we are not writing to an output folder:
+    if(argc == 2) {
+        waitKey(0);
+    }
+    return 0;
+}

modules/contrib/doc/facerec/src/facerec_lbph.cpp

+/*
+ * Copyright (c) 2011. Philipp Wagner <bytefish[at]gmx[dot]de>.
+ * Released to public domain under terms of the BSD Simplified license.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *   * Neither the name of the organization nor the names of its contributors
+ *     may be used to endorse or promote products derived from this software
+ *     without specific prior written permission.
+ *
+ *   See <http://www.opensource.org/licenses/bsd-license>
+ */
+
+#include "opencv2/core/core.hpp"
+#include "opencv2/contrib/contrib.hpp"
+#include "opencv2/highgui/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace std;
+
+static void read_csv(const string& filename, vector<Mat>& images, vector<int>& labels, char separator = ';') {
+    std::ifstream file(filename.c_str(), ifstream::in);
+    if (!file) {
+        string error_message = "No valid input file was given, please check the given filename.";
+        CV_Error(CV_StsBadArg, error_message);
+    }
+    string line, path, classlabel;
+    while (getline(file, line)) {
+        stringstream liness(line);
+        getline(liness, path, separator);
+        getline(liness, classlabel);
+        if(!path.empty() && !classlabel.empty()) {
+            images.push_back(imread(path, 0));
+            labels.push_back(atoi(classlabel.c_str()));
+        }
+    }
+}
+
+int main(int argc, const char *argv[]) {
+    // Check for valid command line arguments, print usage
+    // if no arguments were given.
+    if (argc != 2) {
+        cout << "usage: " << argv[0] << " <csv.ext>" << endl;
+        exit(1);
+    }
+    // Get the path to your CSV.
+    string fn_csv = string(argv[1]);
+    // These vectors hold the images and corresponding labels.
+    vector<Mat> images;
+    vector<int> labels;
+    // Read in the data. This can fail if no valid
+    // input filename is given.
+    try {
+        read_csv(fn_csv, images, labels);
+    } catch (cv::Exception& e) {
+        cerr << "Error opening file \"" << fn_csv << "\". Reason: " << e.msg << endl;
+        // nothing more we can do
+        exit(1);
+    }
+    // Quit if there are not enough images for this demo.
+    if(images.size() <= 1) {
+        string error_message = "This demo needs at least 2 images to work. Please add more images to your data set!";
+        CV_Error(CV_StsError, error_message);
+    }
+    // Get the height from the first image. We'll need this
+    // later in code to reshape the images to their original
+    // size:
+    int height = images[0].rows;
+    // The following lines simply get the last images from
+    // your dataset and remove it from the vector. This is
+    // done, so that the training data (which we learn the
+    // cv::FaceRecognizer on) and the test data we test
+    // the model with, do not overlap.
+    Mat testSample = images[images.size() - 1];
+    int testLabel = labels[labels.size() - 1];
+    images.pop_back();
+    labels.pop_back();
+    // The following lines create an LBPH model for
+    // face recognition and train it with the images and
+    // labels read from the given CSV file.
+    //
+    // The LBPHFaceRecognizer uses Extended Local Binary Patterns
+    // (it's probably configurable with other operators at a later
+    // point), and has the following default values
+    //
+    //      radius = 1
+    //      neighbors = 8
+    //      grid_x = 8
+    //      grid_y = 8
+    //
+    // So if you want a LBPH FaceRecognizer using a radius of
+    // 2 and 16 neighbors, call the factory method with:
+    //
+    //      cv::createLBPHFaceRecognizer(2, 16);
+    //
+    // And if you want a threshold (e.g. 123.0) call it with its default values:
+    //
+    //      cv::createLBPHFaceRecognizer(1,8,8,8,123.0)
+    //
+    Ptr<FaceRecognizer> model = createLBPHFaceRecognizer();
+    model->train(images, labels);
+    // The following line predicts the label of a given
+    // test image:
+    int predictedLabel = model->predict(testSample);
+    //
+    // To get the confidence of a prediction call the model with:
+    //
+    //      int predictedLabel = -1;
+    //      double confidence = 0.0;
+    //      model->predict(testSample, predictedLabel, confidence);
+    //
+    string result_message = format("Predicted class = %d / Actual class = %d.", predictedLabel, testLabel);
+    cout << result_message << endl;
+    // Sometimes you'll need to get/set internal model data,
+    // which isn't exposed by the public cv::FaceRecognizer.
+    // Since each cv::FaceRecognizer is derived from a
+    // cv::Algorithm, you can query the data.
+    //
+    // First we'll use it to set the threshold of the FaceRecognizer
+    // to 0.0 without retraining the model. This can be useful if
+    // you are evaluating the model:
+    //
+    model->set("threshold", 0.0);
+    // Now the threshold of this model is set to 0.0. A prediction
+    // now returns -1, as it's impossible to have a distance below
+    // it
+    predictedLabel = model->predict(testSample);
+    cout << "Predicted class = " << predictedLabel << endl;
+    // Show some informations about the model, as there's no cool
+    // Model data to display as in Eigenfaces/Fisherfaces.
+    // Due to efficiency reasons the LBP images are not stored
+    // within the model:
+    cout << "Model Information:" << endl;
+    string model_info = format("\tLBPH(radius=%i, neighbors=%i, grid_x=%i, grid_y=%i, threshold=%.2f)",
+            model->getInt("radius"),
+            model->getInt("neighbors"),
+            model->getInt("grid_x"),
+            model->getInt("grid_y"),
+            model->getDouble("threshold"));
+    cout << model_info << endl;
+    // We could get the histograms for example:
+    vector<Mat> histograms = model->getMatVector("histograms");
+    // But should I really visualize it? Probably the length is interesting:
+    cout << "Size of the histograms: " << histograms[0].total() << endl;
+    return 0;
+}

modules/contrib/doc/facerec/src/facerec_save_load.cpp

+/*
+ * Copyright (c) 2011. Philipp Wagner <bytefish[at]gmx[dot]de>.
+ * Released to public domain under terms of the BSD Simplified license.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *   * Neither the name of the organization nor the names of its contributors
+ *     may be used to endorse or promote products derived from this software
+ *     without specific prior written permission.
+ *
+ *   See <http://www.opensource.org/licenses/bsd-license>
+ */
+
+#include "opencv2/contrib/contrib.hpp"
+#include "opencv2/core/core.hpp"
+#include "opencv2/highgui/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace std;
+
+static Mat norm_0_255(InputArray _src) {
+    Mat src = _src.getMat();
+    // Create and return normalized image:
+    Mat dst;
+    switch(src.channels()) {
+    case 1:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC1);
+        break;
+    case 3:
+        cv::normalize(_src, dst, 0, 255, NORM_MINMAX, CV_8UC3);
+        break;
+    default:
+        src.copyTo(dst);
+        break;
+    }
+    return dst;
+}
+
+static void read_csv(const string& filename, vector<Mat>& images, vector<int>& labels, char separator = ';') {
+    std::ifstream file(filename.c_str(), ifstream::in);
+    if (!file) {
+        string error_message = "No valid input file was given, please check the given filename.";
+        CV_Error(CV_StsBadArg, error_message);
+    }
+    string line, path, classlabel;
+    while (getline(file, line)) {
+        stringstream liness(line);
+        getline(liness, path, separator);
+        getline(liness, classlabel);
+        if(!path.empty() && !classlabel.empty()) {
+            images.push_back(imread(path, 0));
+            labels.push_back(atoi(classlabel.c_str()));
+        }
+    }
+}
+
+int main(int argc, const char *argv[]) {
+    // Check for valid command line arguments, print usage
+    // if no arguments were given.
+    if (argc < 2) {
+        cout << "usage: " << argv[0] << " <csv.ext> <output_folder> " << endl;
+        exit(1);
+    }
+    string output_folder;
+    if (argc == 3) {
+        output_folder = string(argv[2]);
+    }
+    // Get the path to your CSV.
+    string fn_csv = string(argv[1]);
+    // These vectors hold the images and corresponding labels.
+    vector<Mat> images;
+    vector<int> labels;
+    // Read in the data. This can fail if no valid
+    // input filename is given.
+    try {
+        read_csv(fn_csv, images, labels);
+    } catch (cv::Exception& e) {
+        cerr << "Error opening file \"" << fn_csv << "\". Reason: " << e.msg << endl;
+        // nothing more we can do
+        exit(1);
+    }
+    // Quit if there are not enough images for this demo.
+    if(images.size() <= 1) {
+        string error_message = "This demo needs at least 2 images to work. Please add more images to your data set!";
+        CV_Error(CV_StsError, error_message);
+    }
+    // Get the height from the first image. We'll need this
+    // later in code to reshape the images to their original
+    // size:
+    int height = images[0].rows;
+    // The following lines simply get the last images from
+    // your dataset and remove it from the vector. This is
+    // done, so that the training data (which we learn the
+    // cv::FaceRecognizer on) and the test data we test
+    // the model with, do not overlap.
+    Mat testSample = images[images.size() - 1];
+    int testLabel = labels[labels.size() - 1];
+    images.pop_back();
+    labels.pop_back();
+    // The following lines create an Eigenfaces model for
+    // face recognition and train it with the images and
+    // labels read from the given CSV file.
+    // This here is a full PCA, if you just want to keep
+    // 10 principal components (read Eigenfaces), then call
+    // the factory method like this:
+    //
+    //      cv::createEigenFaceRecognizer(10);
+    //
+    // If you want to create a FaceRecognizer with a
+    // confidence threshold (e.g. 123.0), call it with:
+    //
+    //      cv::createEigenFaceRecognizer(10, 123.0);
+    //
+    // If you want to use _all_ Eigenfaces and have a threshold,
+    // then call the method like this:
+    //
+    //      cv::createEigenFaceRecognizer(0, 123.0);
+    //
+    Ptr<FaceRecognizer> model0 = createEigenFaceRecognizer();
+    model0->train(images, labels);
+    // save the model to eigenfaces_at.yaml
+    model0->save("eigenfaces_at.yml");
+    //
+    //
+    // Now create a new Eigenfaces Recognizer
+    //
+    Ptr<FaceRecognizer> model1 = createEigenFaceRecognizer();
+    model1->load("eigenfaces_at.yml");
+    // The following line predicts the label of a given
+    // test image:
+    int predictedLabel = model1->predict(testSample);
+    //
+    // To get the confidence of a prediction call the model with:
+    //
+    //      int predictedLabel = -1;
+    //      double confidence = 0.0;
+    //      model->predict(testSample, predictedLabel, confidence);
+    //
+    string result_message = format("Predicted class = %d / Actual class = %d.", predictedLabel, testLabel);
+    cout << result_message << endl;
+    // Here is how to get the eigenvalues of this Eigenfaces model:
+    Mat eigenvalues = model1->getMat("eigenvalues");
+    // And we can do the same to display the Eigenvectors (read Eigenfaces):
+    Mat W = model1->getMat("eigenvectors");
+    // Get the sample mean from the training data
+    Mat mean = model1->getMat("mean");
+    // Display or save:
+    if(argc == 2) {
+        imshow("mean", norm_0_255(mean.reshape(1, images[0].rows)));
+    } else {
+        imwrite(format("%s/mean.png", output_folder.c_str()), norm_0_255(mean.reshape(1, images[0].rows)));
+    }
+    // Display or save the Eigenfaces:
+    for (int i = 0; i < min(10, W.cols); i++) {
+        string msg = format("Eigenvalue #%d = %.5f", i, eigenvalues.at<double>(i));
+        cout << msg << endl;
+        // get eigenvector #i
+        Mat ev = W.col(i).clone();
+        // Reshape to original size & normalize to [0...255] for imshow.
+        Mat grayscale = norm_0_255(ev.reshape(1, height));
+        // Show the image & apply a Jet colormap for better sensing.
+        Mat cgrayscale;
+        applyColorMap(grayscale, cgrayscale, COLORMAP_JET);
+        // Display or save:
+        if(argc == 2) {
+            imshow(format("eigenface_%d", i), cgrayscale);
+        } else {
+            imwrite(format("%s/eigenface_%d.png", output_folder.c_str(), i), norm_0_255(cgrayscale));
+        }
+    }
+    // Display or save the image reconstruction at some predefined steps:
+    for(int num_components = 10; num_components < 300; num_components+=15) {
+        // slice the eigenvectors from the model
+        Mat evs = Mat(W, Range::all(), Range(0, num_components));
+        Mat projection = subspaceProject(evs, mean, images[0].reshape(1,1));
+        Mat reconstruction = subspaceReconstruct(evs, mean, projection);
+        // Normalize the result:
+        reconstruction = norm_0_255(reconstruction.reshape(1, images[0].rows));
+        // Display or save:
+        if(argc == 2) {
+            imshow(format("eigenface_reconstruction_%d", num_components), reconstruction);
+        } else {
+            imwrite(format("%s/eigenface_reconstruction_%d.png", output_folder.c_str(), num_components), reconstruction);
+        }
+    }
+    // Display if we are not writing to an output folder:
+    if(argc == 2) {
+        waitKey(0);
+    }
+    return 0;
+}

modules/contrib/doc/facerec/src/facerec_video.cpp

+/*
+ * Copyright (c) 2011. Philipp Wagner <bytefish[at]gmx[dot]de>.
+ * Released to public domain under terms of the BSD Simplified license.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *   * Neither the name of the organization nor the names of its contributors
+ *     may be used to endorse or promote products derived from this software
+ *     without specific prior written permission.
+ *
+ *   See <http://www.opensource.org/licenses/bsd-license>
+ */
+
+#include "opencv2/core/core.hpp"
+#include "opencv2/contrib/contrib.hpp"
+#include "opencv2/highgui/highgui.hpp"
+#include "opencv2/imgproc/imgproc.hpp"
+#include "opencv2/objdetect/objdetect.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace std;
+
+static void read_csv(const string& filename, vector<Mat>& images, vector<int>& labels, char separator = ';') {
+    std::ifstream file(filename.c_str(), ifstream::in);
+    if (!file) {
+        string error_message = "No valid input file was given, please check the given filename.";
+        CV_Error(CV_StsBadArg, error_message);
+    }
+    string line, path, classlabel;
+    while (getline(file, line)) {
+        stringstream liness(line);
+        getline(liness, path, separator);
+        getline(liness, classlabel);
+        if(!path.empty() && !classlabel.empty()) {
+            images.push_back(imread(path, 0));
+            labels.push_back(atoi(classlabel.c_str()));
+        }
+    }
+}
+
+int main(int argc, const char *argv[]) {
+    // Check for valid command line arguments, print usage
+    // if no arguments were given.
+    if (argc != 4) {
+        cout << "usage: " << argv[0] << " </path/to/haar_cascade> </path/to/csv.ext> </path/to/device id>" << endl;
+        cout << "\t </path/to/haar_cascade> -- Path to the Haar Cascade for face detection." << endl;
+        cout << "\t </path/to/csv.ext> -- Path to the CSV file with the face database." << endl;
+        cout << "\t <device id> -- The webcam device id to grab frames from." << endl;
+        exit(1);
+    }
+    // Get the path to your CSV:
+    string fn_haar = string(argv[1]);
+    string fn_csv = string(argv[2]);
+    int deviceId = atoi(argv[3]);
+    // These vectors hold the images and corresponding labels:
+    vector<Mat> images;
+    vector<int> labels;
+    // Read in the data (fails if no valid input filename is given, but you'll get an error message):
+    try {
+        read_csv(fn_csv, images, labels);
+    } catch (cv::Exception& e) {
+        cerr << "Error opening file \"" << fn_csv << "\". Reason: " << e.msg << endl;
+        // nothing more we can do
+        exit(1);
+    }
+    // Get the height from the first image. We'll need this
+    // later in code to reshape the images to their original
+    // size AND we need to reshape incoming faces to this size:
+    int im_width = images[0].cols;
+    int im_height = images[0].rows;
+    // Create a FaceRecognizer and train it on the given images:
+    Ptr<FaceRecognizer> model = createFisherFaceRecognizer();
+    model->train(images, labels);
+    // That's it for learning the Face Recognition model. You now
+    // need to create the classifier for the task of Face Detection.
+    // We are going to use the haar cascade you have specified in the
+    // command line arguments:
+    //
+    CascadeClassifier haar_cascade;
+    haar_cascade.load(fn_haar);
+    // Get a handle to the Video device:
+    VideoCapture cap(deviceId);
+    // Check if we can use this device at all:
+    if(!cap.isOpened()) {
+        cerr << "Capture Device ID " << deviceId << "cannot be opened." << endl;
+        return -1;
+    }
+    // Holds the current frame from the Video device:
+    Mat frame;
+    for(;;) {
+        cap >> frame;
+        // Clone the current frame:
+        Mat original = frame.clone();
+        // Convert the current frame to grayscale:
+        Mat gray;
+        cvtColor(original, gray, CV_BGR2GRAY);
+        // Find the faces in the frame:
+        vector< Rect_<int> > faces;
+        haar_cascade.detectMultiScale(gray, faces);
+        // At this point you have the position of the faces in
+        // faces. Now we'll get the faces, make a prediction and
+        // annotate it in the video. Cool or what?
+        for(int i = 0; i < faces.size(); i++) {
+            // Process face by face:
+            Rect face_i = faces[i];
+            // Crop the face from the image. So simple with OpenCV C++:
+            Mat face = gray(face_i);
+            // Resizing the face is necessary for Eigenfaces and Fisherfaces. You can easily
+            // verify this, by reading through the face recognition tutorial coming with OpenCV.
+            // Resizing IS NOT NEEDED for Local Binary Patterns Histograms, so preparing the
+            // input data really depends on the algorithm used.
+            //
+            // I strongly encourage you to play around with the algorithms. See which work best
+            // in your scenario, LBPH should always be a contender for robust face recognition.
+            //
+            // Since I am showing the Fisherfaces algorithm here, I also show how to resize the
+            // face you have just found:
+            Mat face_resized;
+            cv::resize(face, face_resized, Size(im_width, im_height), 1.0, 1.0, INTER_CUBIC);
+            // Now perform the prediction, see how easy that is:
+            int prediction = model->predict(face_resized);
+            // And finally write all we've found out to the original image!
+            // First of all draw a green rectangle around the detected face:
+            rectangle(original, face_i, CV_RGB(0, 255,0), 1);
+            // Create the text we will annotate the box with:
+            string box_text = format("Prediction = %d", prediction);
+            // Calculate the position for annotated text (make sure we don't
+            // put illegal values in there):
+            int pos_x = std::max(face_i.tl().x - 10, 0);
+            int pos_y = std::max(face_i.tl().y - 10, 0);
+            // And now put it into the image:
+            putText(original, box_text, Point(pos_x, pos_y), FONT_HERSHEY_PLAIN, 1.0, CV_RGB(0,255,0), 2.0);
+        }
+        // Show the result:
+        imshow("face_recognizer", original);
+        // And display it:
+        char key = (char) waitKey(20);
+        // Exit this loop on escape:
+        if(key == 27)
+            break;
+    }
+    return 0;
+}

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

+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. 
+
+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.
+ 
+From the loaded model, we'll get a prediction, show the mean, eigenfaces and the image reconstruction.
+  
+Using FaceRecognizer::save and FaceRecognizer::load
+-----------------------------------------------------
+
+.. literalinclude:: ../src/facerec_save_load.cpp
+   :language: cpp
+   :linenos:
+  
+Results
+-------
+
+``eigenfaces_at.yml`` then contains the model state, we'll simply look at the first 10 lines with ``head eigenfaces_at.yml``: 
+
+.. code-block:: none
+
+  philipp@mango:~/github/libfacerec-build$ head eigenfaces_at.yml
+  %YAML:1.0
+  num_components: 399
+  mean: !!opencv-matrix
+     rows: 1
+     cols: 10304
+     dt: d
+     data: [ 8.5558897243107765e+01, 8.5511278195488714e+01,
+         8.5854636591478695e+01, 8.5796992481203006e+01,
+         8.5952380952380949e+01, 8.6162907268170414e+01,
+         8.6082706766917283e+01, 8.5776942355889716e+01,
+
+And here is the Reconstruction, which is the same as the original:
+
+.. image:: ../img/eigenface_reconstruction_opencv.png
+    :align: center
+

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

+Face Recognition in Videos with OpenCV
+=======================================
+
+.. contents:: Table of Contents
+   :depth: 3
+
+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.
+
+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. 
+
+.. 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:
+  
+* 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``.
+
+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!
+
+Prerequisites
+--------------
+
+You want to do face recognition, so you need some face images to learn a :ocv:class:`FaceRecognizer` on. I have decided to reuse the images from the gender classification example: :doc:`../facerec_gender_classification`.
+
+I have the following celebrities in my training data set:
+
+* Angelina Jolie
+* Arnold Schwarzenegger
+* Brad Pitt
+* George Clooney
+* Johnny Depp
+* Justin Timberlake
+* Katy Perry
+* Keanu Reeves
+* Patrick Stewart
+* Tom Cruise
+
+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: 
+
+.. code-block:: none
+
+    /path/to/image.ext;0
+    
+Let's dissect the line. ``/path/to/image.ext`` is the path to an image, probably something like this if you are in Windows: ``C:/faces/person0/image0.jpg``. Then there is the separator ``;`` and finally we assign a label ``0`` to the image. Think of the label as the subject (the person, the gender or whatever comes to your mind). In the face recognition scenario, the label is the person this image belongs to. In the gender classification scenario, the label is the gender the person has. So my CSV file looks like this:
+
+.. code-block:: none
+
+    /home/philipp/facerec/data/c/keanu_reeves/keanu_reeves_01.jpg;0
+    /home/philipp/facerec/data/c/keanu_reeves/keanu_reeves_02.jpg;0
+    /home/philipp/facerec/data/c/keanu_reeves/keanu_reeves_03.jpg;0
+    ...
+    /home/philipp/facerec/data/c/katy_perry/katy_perry_01.jpg;1
+    /home/philipp/facerec/data/c/katy_perry/katy_perry_02.jpg;1
+    /home/philipp/facerec/data/c/katy_perry/katy_perry_03.jpg;1
+    ...
+    /home/philipp/facerec/data/c/brad_pitt/brad_pitt_01.jpg;2
+    /home/philipp/facerec/data/c/brad_pitt/brad_pitt_02.jpg;2
+    /home/philipp/facerec/data/c/brad_pitt/brad_pitt_03.jpg;2
+    ...
+    /home/philipp/facerec/data/c1/crop_arnold_schwarzenegger/crop_08.jpg;6
+    /home/philipp/facerec/data/c1/crop_arnold_schwarzenegger/crop_05.jpg;6
+    /home/philipp/facerec/data/c1/crop_arnold_schwarzenegger/crop_02.jpg;6
+    /home/philipp/facerec/data/c1/crop_arnold_schwarzenegger/crop_03.jpg;6
+    
+All images for this example were chosen to have a frontal face perspective. They have been cropped, scaled and rotated to be aligned at the eyes, just like this set of George Clooney images:
+
+.. image:: ../img/tutorial/gender_classification/clooney_set.png
+    :align: center
+
+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`:
+
+.. literalinclude:: ../src/facerec_video.cpp
+   :language: cpp
+   :linenos:
+
+Running the Demo
+----------------
+
+You'll need:
+
+* The path to a valid Haar-Cascade for detecting a face with a :ocv:class:`CascadeClassifier`.    
+* The path to a valid CSV File for learning a :ocv:class:`FaceRecognizer`.
+* A webcam and its device id (you don't know the device id? Simply start from 0 on and see what happens).
+
+If you are in Windows, then simply start the demo by running (from command line):
+
+.. code-block:: none
+
+    facerec_video.exe <C:/path/to/your/haar_cascade.xml> <C:/path/to/your/csv.ext> <video device>
+    
+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>
+
+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:
+
+.. code-block:: none
+
+    facerec_video.exe C:/opencv/data/haarcascades/haarcascade_frontalface_default.xml C:/facerec/data/celebrities.txt 1
+
+Results
+-------
+
+Enjoy!
+
+Appendix
+--------
+
+Creating the CSV File
++++++++++++++++++++++
+
+You don't really want to create the CSV file by hand. I have prepared you a little Python script ``create_csv.py`` (you find it at ``/src/create_csv.py`` coming with this tutorial) that automatically creates you a CSV file. If you have your images in hierarchie like this (``/basepath/<subject>/<image.ext>``):
+
+.. code-block:: none
+
+    philipp@mango:~/facerec/data/at$ tree
+    .
+    |-- s1
+    |   |-- 1.pgm
+    |   |-- ...
+    |   |-- 10.pgm
+    |-- s2
+    |   |-- 1.pgm
+    |   |-- ...
+    |   |-- 10.pgm
+    ...
+    |-- s40
+    |   |-- 1.pgm
+    |   |-- ...
+    |   |-- 10.pgm
+    
+    
+Then simply call ``create_csv.py`` with the path to the folder, just like this and you could save the output:
+
+.. code-block:: none
+
+    philipp@mango:~/facerec/data$ python create_csv.py
+    at/s13/2.pgm;0
+    at/s13/7.pgm;0
+    at/s13/6.pgm;0
+    at/s13/9.pgm;0
+    at/s13/5.pgm;0
+    at/s13/3.pgm;0
+    at/s13/4.pgm;0
+    at/s13/10.pgm;0
+    at/s13/8.pgm;0
+    at/s13/1.pgm;0
+    at/s17/2.pgm;1
+    at/s17/7.pgm;1
+    at/s17/6.pgm;1
+    at/s17/9.pgm;1
+    at/s17/5.pgm;1
+    at/s17/3.pgm;1
+    [...]
+
+Here is the script, if you can't find it:
+
+.. literalinclude:: ../src/create_csv.py
+   :language: python
+   :linenos:
+   
+Aligning Face Images
+++++++++++++++++++++
+
+An accurate alignment of your image data is especially important in tasks like emotion detection, were you need as much detail as possible. Believe me... You don't want to do this by hand. So I've prepared you a tiny Python script. The code is really easy to use. To scale, rotate and crop the face image you just need to call *CropFace(image, eye_left, eye_right, offset_pct, dest_sz)*, where:
+
+* *eye_left* is the position of the left eye
+* *eye_right* is the position of the right eye
+* *offset_pct* is the percent of the image you want to keep next to the eyes (horizontal, vertical direction)
+* *dest_sz* is the size of the output image
+
+If you are using the same *offset_pct* and *dest_sz* for your images, they are all aligned at the eyes.
+
+.. literalinclude:: ../src/crop_face.py
+   :language: python
+   :linenos:
+
+Imagine we are given `this photo of Arnold Schwarzenegger <http://en.wikipedia.org/wiki/File:Arnold_Schwarzenegger_edit%28ws%29.jpg>`_, which is under a Public Domain license. The (x,y)-position of the eyes is approximately *(252,364)* for the left and *(420,366)* for the right eye. Now you only need to define the horizontal offset, vertical offset and the size your scaled, rotated & cropped face should have. 
+
+Here are some examples: 
+
++---------------------------------+----------------------------------------------------------------------------+
+| Configuration                   | Cropped, Scaled, Rotated Face                                              |
++=================================+============================================================================+
+| 0.1 (10%), 0.1 (10%), (200,200) | .. image:: ../img/tutorial/gender_classification/arnie_10_10_200_200.jpg   |
++---------------------------------+----------------------------------------------------------------------------+
+| 0.2 (20%), 0.2 (20%), (200,200) | .. image:: ../img/tutorial/gender_classification/arnie_20_20_200_200.jpg   |
++---------------------------------+----------------------------------------------------------------------------+
+| 0.3 (30%), 0.3 (30%), (200,200) | .. image:: ../img/tutorial/gender_classification/arnie_30_30_200_200.jpg   |
++---------------------------------+----------------------------------------------------------------------------+
+| 0.2 (20%), 0.2 (20%), (70,70)   | .. image:: ../img/tutorial/gender_classification/arnie_20_20_70_70.jpg     |
++---------------------------------+----------------------------------------------------------------------------+
+
+