Doc files reorganized

modules/face/samples/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/tutorials/face_tutorial.markdown

@@ -658,7 +658,7 @@ at/s17/3.pgm;1
 
 Here is the script, if you can't find it:
 
-@verbinclude face/doc/src/create_csv.py
+@verbinclude face/samples/src/create_csv.py
 
 ### Aligning Face Images {#tutorial_face_appendix_align}
 
@@ -677,7 +677,7 @@ where:
 If you are using the same *offset_pct* and *dest_sz* for your images, they are all aligned at the
 eyes.
 
-@verbinclude face/doc/src/crop_face.py
+@verbinclude face/samples/src/crop_face.py
 
 Imagine we are given [this photo of Arnold
 Schwarzenegger](http://en.wikipedia.org/wiki/File:Arnold_Schwarzenegger_edit%28ws%29.jpg), which is
@@ -689,11 +689,11 @@ Here are some examples:
 
 Configuration                   | Cropped, Scaled, Rotated Face
 --------------------------------|------------------------------------------------------------------
-0.1 (10%), 0.1 (10%), (200,200) | ![](tutorial/gender_classification/arnie_10_10_200_200.jpg)
-0.2 (20%), 0.2 (20%), (200,200) | ![](tutorial/gender_classification/arnie_20_20_200_200.jpg)
-0.3 (30%), 0.3 (30%), (200,200) | ![](tutorial/gender_classification/arnie_30_30_200_200.jpg)
-0.2 (20%), 0.2 (20%), (70,70)   | ![](tutorial/gender_classification/arnie_20_20_70_70.jpg)
+0.1 (10%), 0.1 (10%), (200,200) | ![](tutorials/gender_classification/arnie_10_10_200_200.jpg)
+0.2 (20%), 0.2 (20%), (200,200) | ![](tutorials/gender_classification/arnie_20_20_200_200.jpg)
+0.3 (30%), 0.3 (30%), (200,200) | ![](tutorials/gender_classification/arnie_30_30_200_200.jpg)
+0.2 (20%), 0.2 (20%), (70,70)   | ![](tutorials/gender_classification/arnie_20_20_70_70.jpg)
 
 ### CSV for the AT&T Facedatabase {#tutorial_face_appendix_attcsv}
 
-@verbinclude face/doc/etc/at.txt
+@verbinclude face/samples/etc/at.txt

modules/surface_matching/doc/surface_matching/src/ppf_load_match.cpp

-//
-//  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) 2014, 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:
-//
-//   * 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.
-//
-// Author: Tolga Birdal <tbirdal AT gmail.com>
-
-#include "opencv2/surface_matching.hpp"
-#include <iostream>
-#include "opencv2/surface_matching/ppf_helpers.hpp"
-#include "opencv2/core/utility.hpp"
-
-using namespace std;
-using namespace cv;
-using namespace ppf_match_3d;
-
-static void help(const string& errorMessage)
-{
-    cout << "Program init error : "<< errorMessage << endl;
-    cout << "\nUsage : ppf_matching [input model file] [input scene file]"<< endl;
-    cout << "\nPlease start again with new parameters"<< endl;
-}
-
-int main(int argc, char** argv)
-{
-    // welcome message
-    cout << "****************************************************" << endl;
-    cout << "* Surface Matching demonstration : demonstrates the use of surface matching"
-             " using point pair features." << endl;
-    cout << "* The sample loads a model and a scene, where the model lies in a different"
-             " pose than the training.\n* It then trains the model and searches for it in the"
-             " input scene. The detected poses are further refined by ICP\n* and printed to the "
-             " standard output." << endl;
-    cout << "****************************************************" << endl;
-    
-    if (argc < 3)
-    {
-        help("Not enough input arguments");
-        exit(1);
-    }
-    
-#if (defined __x86_64__ || defined _M_X64)
-    cout << "Running on 64 bits" << endl;
-#else
-    cout << "Running on 32 bits" << endl;
-#endif
-    
-#ifdef _OPENMP
-    cout << "Running with OpenMP" << endl;
-#else
-    cout << "Running without OpenMP and without TBB" << endl;
-#endif
-    
-    string modelFileName = (string)argv[1];
-    string sceneFileName = (string)argv[2];
-    
-    Mat pc = loadPLYSimple(modelFileName.c_str(), 1);
-    
-    // Now train the model
-    cout << "Training..." << endl;
-    int64 tick1 = cv::getTickCount();
-    ppf_match_3d::PPF3DDetector detector(0.025, 0.05);
-    detector.trainModel(pc);
-    int64 tick2 = cv::getTickCount();
-    cout << endl << "Training complete in "
-         << (double)(tick2-tick1)/ cv::getTickFrequency()
-         << " sec" << endl << "Loading model..." << endl;
-         
-    // Read the scene
-    Mat pcTest = loadPLYSimple(sceneFileName.c_str(), 1);
-    
-    // Match the model to the scene and get the pose
-    cout << endl << "Starting matching..." << endl;
-    vector<Pose3DPtr> results;
-    tick1 = cv::getTickCount();
-    detector.match(pcTest, results, 1.0/40.0, 0.05);
-    tick2 = cv::getTickCount();
-    cout << endl << "PPF Elapsed Time " <<
-         (tick2-tick1)/cv::getTickFrequency() << " sec" << endl;
-         
-    // Get only first N results
-    int N = 2;
-    vector<Pose3DPtr> resultsSub(results.begin(),results.begin()+N);
-    
-    // Create an instance of ICP
-    ICP icp(100, 0.005f, 2.5f, 8);
-    int64 t1 = cv::getTickCount();
-    
-    // Register for all selected poses
-    cout << endl << "Performing ICP on " << N << " poses..." << endl;
-    icp.registerModelToScene(pc, pcTest, resultsSub);
-    int64 t2 = cv::getTickCount();
-    
-    cout << endl << "ICP Elapsed Time " <<
-         (t2-t1)/cv::getTickFrequency() << " sec" << endl;
-         
-    cout << "Poses: " << endl;
-    // debug first five poses
-    for (size_t i=0; i<resultsSub.size(); i++)
-    {
-        Pose3DPtr result = resultsSub[i];
-        cout << "Pose Result " << i << endl;
-        result->printPose();
-        if (i==0)
-        {
-            Mat pct = transformPCPose(pc, result->pose);
-            writePLY(pct, "para6700PCTrans.ply");
-        }
-    }
-    
-    return 0;
-    
-}

modules/surface_matching/include/opencv2/surface_matching.hpp

@@ -111,7 +111,7 @@ point sampling, I will be leaving that aside now in order to respect the general
 methods (Typically for such algorithms training on a CAD model is not needed, and a point cloud
 would be sufficient). Below is the outline of the entire algorithm:
 
-![Outline of the Algorithm](surface_matching/pics/outline.jpg)
+![Outline of the Algorithm](img/outline.jpg)
 
 As explained, the algorithm relies on the extraction and indexing of point pair features, which are
 defined as follows:
@@ -337,11 +337,11 @@ Results
 This section is dedicated to the results of surface matching (point-pair-feature matching and a
 following ICP refinement):
 
-![Several matches of a single frog model using ppf + icp](surface_matching/pics/gsoc_forg_matches.jpg)
+![Several matches of a single frog model using ppf + icp](img/gsoc_forg_matches.jpg)
 
 Matches of different models for Mian dataset is presented below:
 
-![Matches of different models for Mian dataset](surface_matching/pics/snapshot27.jpg)
+![Matches of different models for Mian dataset](img/snapshot27.jpg)
 
 You might checkout the video on [youTube here](http://www.youtube.com/watch?v=uFnqLFznuZU).