Merge pull request #51 from vpisarev/added_face_module

added face module

modules/face/CMakeLists.txt

+set(the_description "Face recognition etc")
+ocv_define_module(face opencv_core opencv_imgproc)

modules/face/doc/face.rst

+***************************************
+contrib. Contributed/Experimental Stuff
+***************************************
+
+The module contains some recently added functionality that has not been stabilized, or functionality that is considered optional.
+
+.. toctree::
+    :maxdepth: 2
+
+    FaceRecognizer Documentation <facerec/index>

modules/face/doc/facerec/facerec_changelog.rst

+Changelog
+=========
+
+Release 0.05
+------------
+
+This library is now included in the official OpenCV distribution (from 2.4 on).
+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
+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 [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.

modules/face/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 :doc:`the API <facerec_api>` in detail and it will give you a lot of help to get started (full source code examples). :doc:`Face Recognition with OpenCV <facerec_tutorial>` is the definite guide to the new :ocv:class:`FaceRecognizer`. There's also a :doc:`tutorial on gender classification <tutorial/facerec_gender_classification>`, a :doc:`tutorial for face recognition in videos <tutorial/facerec_video_recognition>` and it's shown :doc:`how to load & save your results <tutorial/facerec_save_load>`.
+
+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>
+   Changelog <facerec_changelog>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

modules/face/doc/facerec/src/CMakeLists.txt

+CMAKE_MINIMUM_REQUIRED(VERSION 2.6)
+
+set(name "facerec")
+project(facerec_cpp_samples)
+
+#SET(OpenCV_DIR /path/to/your/opencv/installation)
+
+# packages
+find_package(OpenCV REQUIRED) # http://opencv.org
+
+# probably you should loop through the sample files here
+add_executable(facerec_demo facerec_demo.cpp)
+target_link_libraries(facerec_demo opencv_core opencv_face opencv_imgproc opencv_highgui)
+
+add_executable(facerec_video facerec_video.cpp)
+target_link_libraries(facerec_video opencv_face opencv_core opencv_imgproc opencv_highgui opencv_objdetect opencv_imgproc)
+
+add_executable(facerec_eigenfaces facerec_eigenfaces.cpp)
+target_link_libraries(facerec_eigenfaces opencv_face opencv_core opencv_imgproc opencv_highgui)
+
+add_executable(facerec_fisherfaces facerec_fisherfaces.cpp)
+target_link_libraries(facerec_fisherfaces opencv_face opencv_core opencv_imgproc opencv_highgui)
+
+add_executable(facerec_lbph facerec_lbph.cpp)
+target_link_libraries(facerec_lbph opencv_face opencv_core opencv_imgproc opencv_highgui)

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

+#!/usr/bin/env python
+
+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/face/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
+
+def readFileNames():
+    try:
+        inFile = open('path_to_created_csv_file.csv')
+    except:
+        raise IOError('There is no file named path_to_created_csv_file.csv in current directory.')
+        return False
+
+    picPath = []
+    picIndex = []
+
+    for line in inFile.readlines():
+        if line != '':
+            fields = line.rstrip().split(';')
+            picPath.append(fields[0])
+            picIndex.append(int(fields[1]))
+
+    return (picPath, picIndex)
+
+
+if __name__ == "__main__":
+  [images, indexes]=readFileNames()
+if not os.path.exists("modified"):
+    os.makedirs("modified")
+for img in images:
+    image =  Image.open(img)
+    CropFace(image, eye_left=(252,364), eye_right=(420,366), offset_pct=(0.1,0.1), dest_sz=(200,200)).save("modified/"+img.rstrip().split('/')[1]+"_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("modified/"+img.rstrip().split('/')[1]+"_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("modified/"+img.rstrip().split('/')[1]+"_30_30_200_200.jpg")
+    CropFace(image, eye_left=(252,364), eye_right=(420,366), offset_pct=(0.2,0.2)).save("modified/"+img.rstrip().split('/')[1]+"_20_20_70_70.jpg")

modules/face/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.hpp"
+#include "opencv2/face.hpp"
+#include "opencv2/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace cv::face;
+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/face/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.hpp"
+#include "opencv2/face.hpp"
+#include "opencv2/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace cv::face;
+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 = min(W.cols, 10); num_components < min(W.cols, 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/face/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.hpp"
+#include "opencv2/face.hpp"
+#include "opencv2/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace cv::face;
+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/face/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.hpp"
+#include "opencv2/face.hpp"
+#include "opencv2/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace cv::face;
+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/face/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/core.hpp"
+#include "opencv2/face.hpp"
+#include "opencv2/highgui.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace cv::face;
+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/face/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.hpp"
+#include "opencv2/face.hpp"
+#include "opencv2/highgui.hpp"
+#include "opencv2/imgproc.hpp"
+#include "opencv2/objdetect.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace cv;
+using namespace cv::face;
+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/face/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
+-----------------------------------------------------
+
+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:
+
+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/face/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 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 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, 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 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` implementations, 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 ``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
+   :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> </path/to/your/csv.ext> <video device>
+
+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
+-------
+
+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     |
++---------------------------------+----------------------------------------------------------------------------+

modules/face/include/opencv2/face.hpp

+/*
+By downloading, copying, installing or using the software you agree to this
+license. If you do not agree to this license, do not download, install,
+copy or use the software.
+
+                          License Agreement
+               For Open Source Computer Vision Library
+                       (3-clause BSD License)
+
+Copyright (C) 2013, OpenCV Foundation, all rights reserved.
+Third party copyrights are property of their respective owners.
+
+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 names of the copyright holders nor the names of the 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 copyright holders 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.
+*/
+
+#ifndef __OPENCV_FACE_HPP__
+#define __OPENCV_FACE_HPP__
+
+#include "opencv2/face/facerec.hpp"
+
+#endif

modules/face/include/opencv2/face/facerec.hpp

+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+
+// Copyright (c) 2011,2012. Philipp Wagner <bytefish[at]gmx[dot]de>.
+// Third party copyrights are property of their respective owners.
+
+#ifndef __OPENCV_FACEREC_HPP__
+#define __OPENCV_FACEREC_HPP__
+
+#include "opencv2/core.hpp"
+
+namespace cv { namespace face {
+
+class CV_EXPORTS_W FaceRecognizer : public Algorithm
+{
+public:
+    //! virtual destructor
+    virtual ~FaceRecognizer() {}
+
+    // Trains a FaceRecognizer.
+    CV_WRAP virtual void train(InputArrayOfArrays src, InputArray labels) = 0;
+
+    // Updates a FaceRecognizer.
+    CV_WRAP virtual void update(InputArrayOfArrays src, InputArray labels) = 0;
+
+    // Gets a prediction from a FaceRecognizer.
+    virtual int predict(InputArray src) const = 0;
+
+    // Predicts the label and confidence for a given sample.
+    CV_WRAP virtual void predict(InputArray src, CV_OUT int &label, CV_OUT double &confidence) const = 0;
+
+    // Serializes this object to a given filename.
+    CV_WRAP virtual void save(const String& filename) const = 0;
+
+    // Deserializes this object from a given filename.
+    CV_WRAP virtual void load(const String& filename) = 0;
+
+    // Serializes this object to a given cv::FileStorage.
+    virtual void save(FileStorage& fs) const = 0;
+
+    // Deserializes this object from a given cv::FileStorage.
+    virtual void load(const FileStorage& fs) = 0;
+
+    // Sets additional string info for the label
+    virtual void setLabelInfo(int label, const String& strInfo) = 0;
+
+    // Gets string info by label
+    virtual String getLabelInfo(int label) const = 0;
+
+    // Gets labels by string
+    virtual std::vector<int> getLabelsByString(const String& str) const = 0;
+};
+
+CV_EXPORTS_W Ptr<FaceRecognizer> createEigenFaceRecognizer(int num_components = 0, double threshold = DBL_MAX);
+CV_EXPORTS_W Ptr<FaceRecognizer> createFisherFaceRecognizer(int num_components = 0, double threshold = DBL_MAX);
+CV_EXPORTS_W Ptr<FaceRecognizer> createLBPHFaceRecognizer(int radius=1, int neighbors=8, int grid_x=8, int grid_y=8, double threshold = DBL_MAX);
+
+bool initModule_facerec();
+
+}} //namespace cv::face
+
+#endif //__OPENCV_FACEREC_HPP__

modules/face/samples/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.hpp"
+#include "opencv2/highgui.hpp"
+#include "opencv2/imgproc.hpp"
+#include "opencv2/face.hpp"
+#include "opencv2/core/utility.hpp"
+
+#include <iostream>
+#include <fstream>
+#include <sstream>
+#include <map>
+
+using namespace cv;
+using namespace cv::face;
+using namespace std;
+
+static void read_csv(const string& filename, vector<Mat>& images, vector<int>& labels, std::map<int, string>& labelsInfo, char separator = ';') {
+    ifstream csv(filename.c_str());
+    if (!csv) CV_Error(Error::StsBadArg, "No valid input file was given, please check the given filename.");
+    string line, path, classlabel, info;
+    while (getline(csv, line)) {
+        stringstream liness(line);
+        path.clear(); classlabel.clear(); info.clear();
+        getline(liness, path, separator);
+        getline(liness, classlabel, separator);
+        getline(liness, info, separator);
+        if(!path.empty() && !classlabel.empty()) {
+            cout << "Processing " << path << endl;
+            int label = atoi(classlabel.c_str());
+            if(!info.empty())
+                labelsInfo.insert(std::make_pair(label, info));
+            // 'path' can be file, dir or wildcard path
+            String root(path.c_str());
+            vector<String> files;
+            glob(root, files, true);
+            for(vector<String>::const_iterator f = files.begin(); f != files.end(); ++f) {
+                cout << "\t" << *f << endl;
+                Mat img = imread(*f, IMREAD_GRAYSCALE);
+                static int w=-1, h=-1;
+                static bool showSmallSizeWarning = true;
+                if(w>0 && h>0 && (w!=img.cols || h!=img.rows)) cout << "\t* Warning: images should be of the same size!" << endl;
+                if(showSmallSizeWarning && (img.cols<50 || img.rows<50)) {
+                    cout << "* Warning: for better results images should be not smaller than 50x50!" << endl;
+                    showSmallSizeWarning = false;
+                }
+                images.push_back(img);
+                labels.push_back(label);
+            }
+        }
+    }
+}
+
+int main(int argc, const char *argv[]) {
+    // Check for valid command line arguments, print usage
+    // if no arguments were given.
+    if (argc != 2 && argc != 3) {
+        cout << "Usage: " << argv[0] << " <csv> [arg2]\n"
+             << "\t<csv> - path to config file in CSV format\n"
+             << "\targ2 - if the 2nd argument is provided (with any value) "
+             << "the advanced stuff is run and shown to console.\n"
+             << "The CSV config file consists of the following lines:\n"
+             << "<path>;<label>[;<comment>]\n"
+             << "\t<path> - file, dir or wildcard path\n"
+             << "\t<label> - non-negative integer person label\n"
+             << "\t<comment> - optional comment string (e.g. person name)"
+             << 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;
+    std::map<int, string> labelsInfo;
+    // Read in the data. This can fail if no valid
+    // input filename is given.
+    try {
+        read_csv(fn_csv, images, labels, labelsInfo);
+    } 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(Error::StsError, error_message);
+    }
+    // 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 nlabels = (int)labels.size();
+    int testLabel = labels[nlabels-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 = createEigenFaceRecognizer();
+    for( int i = 0; i < nlabels; i++ )
+        model->setLabelInfo(i, labelsInfo[i]);
+    model->train(images, labels);
+    string saveModelPath = "face-rec-model.txt";
+    cout << "Saving the trained model to " << saveModelPath << endl;
+    model->save(saveModelPath);
+
+    // 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;
+    if( (predictedLabel == testLabel) && !model->getLabelInfo(predictedLabel).empty() )
+        cout << format("%d-th label's info: %s", predictedLabel, model->getLabelInfo(predictedLabel).c_str()) << endl;
+
+    // advanced stuff
+    if(argc>2) {
+        // 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;
+            normalize(ev.reshape(1), grayscale, 0, 255, NORM_MINMAX, CV_8UC1);
+            // 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/face/src/precomp.hpp

+/*M///////////////////////////////////////////////////////////////////////////////////////
+//
+//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+//
+//  By downloading, copying, installing or using the software you agree to this license.
+//  If you do not agree to this license, do not download, install,
+//  copy or use the software.
+//
+//
+//                          License Agreement
+//                For Open Source Computer Vision Library
+//
+// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
+// Copyright (C) 2009, Willow Garage Inc., all rights reserved.
+// Third party copyrights are property of their respective owners.
+//
+// Redistribution and use in source and binary forms, with or without modification,
+// are permitted provided that the following conditions are met:
+//
+//   * Redistribution's of source code must retain the above copyright notice,
+//     this list of conditions and the following disclaimer.
+//
+//   * Redistribution's 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.
+//
+//   * The name of the copyright holders may not 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 Intel Corporation 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.
+//
+//M*/
+
+#ifndef __OPENCV_PRECOMP_H__
+#define __OPENCV_PRECOMP_H__
+
+#include "opencv2/face.hpp"
+#include "opencv2/imgproc.hpp"
+#include "opencv2/core.hpp"
+#include "opencv2/core/utility.hpp"
+#include "opencv2/core/private.hpp"
+
+#include <map>
+
+#endif