facerec.hpp

00001 // This file is part of OpenCV project.
00002 // It is subject to the license terms in the LICENSE file found in the top-level directory
00003 // of this distribution and at http://opencv.org/license.html.
00004 
00005 // Copyright (c) 2011,2012. Philipp Wagner <bytefish[at]gmx[dot]de>.
00006 // Third party copyrights are property of their respective owners.
00007 
00008 #ifndef __OPENCV_FACEREC_HPP__
00009 #define __OPENCV_FACEREC_HPP__
00010 
00011 #include "opencv2/face.hpp"
00012 #include "opencv2/core.hpp"
00013 
00014 namespace cv { namespace face {
00015 
00016 //! @addtogroup face
00017 //! @{
00018 
00019 // base for two classes
00020 class CV_EXPORTS_W BasicFaceRecognizer : public FaceRecognizer
00021 {
00022 public:
00023     /** @see setNumComponents */
00024     CV_WRAP virtual int getNumComponents() const = 0;
00025     /** @copybrief getNumComponents @see getNumComponents */
00026     CV_WRAP virtual void setNumComponents(int val) = 0;
00027     /** @see setThreshold */
00028     CV_WRAP virtual double getThreshold() const = 0;
00029     /** @copybrief getThreshold @see getThreshold */
00030     CV_WRAP virtual void setThreshold(double val) = 0;
00031     CV_WRAP virtual std::vector<cv::Mat> getProjections() const = 0;
00032     CV_WRAP virtual cv::Mat getLabels() const = 0;
00033     CV_WRAP virtual cv::Mat getEigenValues() const = 0;
00034     CV_WRAP virtual cv::Mat getEigenVectors() const = 0;
00035     CV_WRAP virtual cv::Mat getMean() const = 0;
00036 };
00037 
00038 /**
00039 @param num_components The number of components (read: Eigenfaces) kept for this Principal
00040 Component Analysis. As a hint: There's no rule how many components (read: Eigenfaces) should be
00041 kept for good reconstruction capabilities. It is based on your input data, so experiment with the
00042 number. Keeping 80 components should almost always be sufficient.
00043 @param threshold The threshold applied in the prediction.
00044 
00045 ### Notes:
00046 
00047 -   Training and prediction must be done on grayscale images, use cvtColor to convert between the
00048     color spaces.
00049 -   **THE EIGENFACES METHOD MAKES THE ASSUMPTION, THAT THE TRAINING AND TEST IMAGES ARE OF EQUAL
00050     SIZE.** (caps-lock, because I got so many mails asking for this). You have to make sure your
00051     input data has the correct shape, else a meaningful exception is thrown. Use resize to resize
00052     the images.
00053 -   This model does not support updating.
00054 
00055 ### Model internal data:
00056 
00057 -   num_components see createEigenFaceRecognizer.
00058 -   threshold see createEigenFaceRecognizer.
00059 -   eigenvalues The eigenvalues for this Principal Component Analysis (ordered descending).
00060 -   eigenvectors The eigenvectors for this Principal Component Analysis (ordered by their
00061     eigenvalue).
00062 -   mean The sample mean calculated from the training data.
00063 -   projections The projections of the training data.
00064 -   labels The threshold applied in the prediction. If the distance to the nearest neighbor is
00065     larger than the threshold, this method returns -1.
00066  */
00067 CV_EXPORTS_W Ptr<BasicFaceRecognizer> createEigenFaceRecognizer (int num_components = 0, double threshold = DBL_MAX);
00068 
00069 /**
00070 @param num_components The number of components (read: Fisherfaces) kept for this Linear
00071 Discriminant Analysis with the Fisherfaces criterion. It's useful to keep all components, that
00072 means the number of your classes c (read: subjects, persons you want to recognize). If you leave
00073 this at the default (0) or set it to a value less-equal 0 or greater (c-1), it will be set to the
00074 correct number (c-1) automatically.
00075 @param threshold The threshold applied in the prediction. If the distance to the nearest neighbor
00076 is larger than the threshold, this method returns -1.
00077 
00078 ### Notes:
00079 
00080 -   Training and prediction must be done on grayscale images, use cvtColor to convert between the
00081     color spaces.
00082 -   **THE FISHERFACES METHOD MAKES THE ASSUMPTION, THAT THE TRAINING AND TEST IMAGES ARE OF EQUAL
00083     SIZE.** (caps-lock, because I got so many mails asking for this). You have to make sure your
00084     input data has the correct shape, else a meaningful exception is thrown. Use resize to resize
00085     the images.
00086 -   This model does not support updating.
00087 
00088 ### Model internal data:
00089 
00090 -   num_components see createFisherFaceRecognizer.
00091 -   threshold see createFisherFaceRecognizer.
00092 -   eigenvalues The eigenvalues for this Linear Discriminant Analysis (ordered descending).
00093 -   eigenvectors The eigenvectors for this Linear Discriminant Analysis (ordered by their
00094     eigenvalue).
00095 -   mean The sample mean calculated from the training data.
00096 -   projections The projections of the training data.
00097 -   labels The labels corresponding to the projections.
00098  */
00099 CV_EXPORTS_W Ptr<BasicFaceRecognizer> createFisherFaceRecognizer (int num_components = 0, double threshold = DBL_MAX);
00100 
00101 class CV_EXPORTS_W LBPHFaceRecognizer : public FaceRecognizer
00102 {
00103 public:
00104     /** @see setGridX */
00105     CV_WRAP virtual int getGridX() const = 0;
00106     /** @copybrief getGridX @see getGridX */
00107     CV_WRAP virtual void setGridX(int val) = 0;
00108     /** @see setGridY */
00109     CV_WRAP virtual int getGridY() const = 0;
00110     /** @copybrief getGridY @see getGridY */
00111     CV_WRAP virtual void setGridY(int val) = 0;
00112     /** @see setRadius */
00113     CV_WRAP virtual int getRadius() const = 0;
00114     /** @copybrief getRadius @see getRadius */
00115     CV_WRAP virtual void setRadius(int val) = 0;
00116     /** @see setNeighbors */
00117     CV_WRAP virtual int getNeighbors() const = 0;
00118     /** @copybrief getNeighbors @see getNeighbors */
00119     CV_WRAP virtual void setNeighbors(int val) = 0;
00120     /** @see setThreshold */
00121     CV_WRAP virtual double getThreshold() const = 0;
00122     /** @copybrief getThreshold @see getThreshold */
00123     CV_WRAP virtual void setThreshold(double val) = 0;
00124     CV_WRAP virtual std::vector<cv::Mat> getHistograms() const = 0;
00125     CV_WRAP virtual cv::Mat getLabels() const = 0;
00126 };
00127 
00128 /**
00129 @param radius The radius used for building the Circular Local Binary Pattern. The greater the
00130 radius, the
00131 @param neighbors The number of sample points to build a Circular Local Binary Pattern from. An
00132 appropriate value is to use `8` sample points. Keep in mind: the more sample points you include,
00133 the higher the computational cost.
00134 @param grid_x The number of cells in the horizontal direction, 8 is a common value used in
00135 publications. The more cells, the finer the grid, the higher the dimensionality of the resulting
00136 feature vector.
00137 @param grid_y The number of cells in the vertical direction, 8 is a common value used in
00138 publications. The more cells, the finer the grid, the higher the dimensionality of the resulting
00139 feature vector.
00140 @param threshold The threshold applied in the prediction. If the distance to the nearest neighbor
00141 is larger than the threshold, this method returns -1.
00142 
00143 ### Notes:
00144 
00145 -   The Circular Local Binary Patterns (used in training and prediction) expect the data given as
00146     grayscale images, use cvtColor to convert between the color spaces.
00147 -   This model supports updating.
00148 
00149 ### Model internal data:
00150 
00151 -   radius see createLBPHFaceRecognizer.
00152 -   neighbors see createLBPHFaceRecognizer.
00153 -   grid_x see createLBPHFaceRecognizer.
00154 -   grid_y see createLBPHFaceRecognizer.
00155 -   threshold see createLBPHFaceRecognizer.
00156 -   histograms Local Binary Patterns Histograms calculated from the given training data (empty if
00157     none was given).
00158 -   labels Labels corresponding to the calculated Local Binary Patterns Histograms.
00159  */
00160 CV_EXPORTS_W Ptr<LBPHFaceRecognizer> createLBPHFaceRecognizer (int radius=1, int neighbors=8, int grid_x=8, int grid_y=8, double threshold = DBL_MAX);
00161 
00162 //! @}
00163 
00164 }} //namespace cv::face
00165 
00166 #endif //__OPENCV_FACEREC_HPP__
00167