the do / gr-peach-opencv-project

Opencv 3.1 project on GR-PEACH board

Fork of gr-peach-opencv-project by the do

opencv_3_1/opencv2/face.hpp@170:54ff26da7eb6, 2017-07-04 (annotated)

Committer:
thedo
Date:
Tue Jul 04 06:23:13 2017 +0000
Revision:
170:54ff26da7eb6
Parent:
166:3a9487d57a5c 
project opencv 3.1 on GR PEACH board, no use SD card.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
thedo 166:3a9487d57a5c 1 /*
thedo 166:3a9487d57a5c 2 By downloading, copying, installing or using the software you agree to this
thedo 166:3a9487d57a5c 3 license. If you do not agree to this license, do not download, install,
thedo 166:3a9487d57a5c 4 copy or use the software.
thedo 166:3a9487d57a5c 5
thedo 166:3a9487d57a5c 6 License Agreement
thedo 166:3a9487d57a5c 7 For Open Source Computer Vision Library
thedo 166:3a9487d57a5c 8 (3-clause BSD License)
thedo 166:3a9487d57a5c 9
thedo 166:3a9487d57a5c 10 Copyright (C) 2013, OpenCV Foundation, all rights reserved.
thedo 166:3a9487d57a5c 11 Third party copyrights are property of their respective owners.
thedo 166:3a9487d57a5c 12
thedo 166:3a9487d57a5c 13 Redistribution and use in source and binary forms, with or without modification,
thedo 166:3a9487d57a5c 14 are permitted provided that the following conditions are met:
thedo 166:3a9487d57a5c 15
thedo 166:3a9487d57a5c 16 * Redistributions of source code must retain the above copyright notice,
thedo 166:3a9487d57a5c 17 this list of conditions and the following disclaimer.
thedo 166:3a9487d57a5c 18
thedo 166:3a9487d57a5c 19 * Redistributions in binary form must reproduce the above copyright notice,
thedo 166:3a9487d57a5c 20 this list of conditions and the following disclaimer in the documentation
thedo 166:3a9487d57a5c 21 and/or other materials provided with the distribution.
thedo 166:3a9487d57a5c 22
thedo 166:3a9487d57a5c 23 * Neither the names of the copyright holders nor the names of the contributors
thedo 166:3a9487d57a5c 24 may be used to endorse or promote products derived from this software
thedo 166:3a9487d57a5c 25 without specific prior written permission.
thedo 166:3a9487d57a5c 26
thedo 166:3a9487d57a5c 27 This software is provided by the copyright holders and contributors "as is" and
thedo 166:3a9487d57a5c 28 any express or implied warranties, including, but not limited to, the implied
thedo 166:3a9487d57a5c 29 warranties of merchantability and fitness for a particular purpose are
thedo 166:3a9487d57a5c 30 disclaimed. In no event shall copyright holders or contributors be liable for
thedo 166:3a9487d57a5c 31 any direct, indirect, incidental, special, exemplary, or consequential damages
thedo 166:3a9487d57a5c 32 (including, but not limited to, procurement of substitute goods or services;
thedo 166:3a9487d57a5c 33 loss of use, data, or profits; or business interruption) however caused
thedo 166:3a9487d57a5c 34 and on any theory of liability, whether in contract, strict liability,
thedo 166:3a9487d57a5c 35 or tort (including negligence or otherwise) arising in any way out of
thedo 166:3a9487d57a5c 36 the use of this software, even if advised of the possibility of such damage.
thedo 166:3a9487d57a5c 37 */
thedo 166:3a9487d57a5c 38
thedo 166:3a9487d57a5c 39 #ifndef __OPENCV_FACE_HPP__
thedo 166:3a9487d57a5c 40 #define __OPENCV_FACE_HPP__
thedo 166:3a9487d57a5c 41
thedo 166:3a9487d57a5c 42 /**
thedo 166:3a9487d57a5c 43 @defgroup face Face Recognition
thedo 166:3a9487d57a5c 44
thedo 166:3a9487d57a5c 45 - @ref face_changelog
thedo 166:3a9487d57a5c 46 - @ref tutorial_face_main
thedo 166:3a9487d57a5c 47
thedo 166:3a9487d57a5c 48 */
thedo 166:3a9487d57a5c 49
thedo 166:3a9487d57a5c 50 #include "opencv2/core.hpp"
thedo 166:3a9487d57a5c 51 #include "face/predict_collector.hpp"
thedo 166:3a9487d57a5c 52 #include <map>
thedo 166:3a9487d57a5c 53
thedo 166:3a9487d57a5c 54 namespace cv { namespace face {
thedo 166:3a9487d57a5c 55
thedo 166:3a9487d57a5c 56 //! @addtogroup face
thedo 166:3a9487d57a5c 57 //! @{
thedo 166:3a9487d57a5c 58
thedo 166:3a9487d57a5c 59 /** @brief Abstract base class for all face recognition models
thedo 166:3a9487d57a5c 60
thedo 166:3a9487d57a5c 61 All face recognition models in OpenCV are derived from the abstract base class FaceRecognizer, which
thedo 166:3a9487d57a5c 62 provides a unified access to all face recongition algorithms in OpenCV.
thedo 166:3a9487d57a5c 63
thedo 166:3a9487d57a5c 64 ### Description
thedo 166:3a9487d57a5c 65
thedo 166:3a9487d57a5c 66 I'll go a bit more into detail explaining FaceRecognizer, because it doesn't look like a powerful
thedo 166:3a9487d57a5c 67 interface at first sight. But: Every FaceRecognizer is an Algorithm, so you can easily get/set all
thedo 166:3a9487d57a5c 68 model internals (if allowed by the implementation). Algorithm is a relatively new OpenCV concept,
thedo 166:3a9487d57a5c 69 which is available since the 2.4 release. I suggest you take a look at its description.
thedo 166:3a9487d57a5c 70
thedo 166:3a9487d57a5c 71 Algorithm provides the following features for all derived classes:
thedo 166:3a9487d57a5c 72
thedo 166:3a9487d57a5c 73 - So called “virtual constructor”. That is, each Algorithm derivative is registered at program
thedo 166:3a9487d57a5c 74 start and you can get the list of registered algorithms and create instance of a particular
thedo 166:3a9487d57a5c 75 algorithm by its name (see Algorithm::create). If you plan to add your own algorithms, it is
thedo 166:3a9487d57a5c 76 good practice to add a unique prefix to your algorithms to distinguish them from other
thedo 166:3a9487d57a5c 77 algorithms.
thedo 166:3a9487d57a5c 78 - Setting/Retrieving algorithm parameters by name. If you used video capturing functionality from
thedo 166:3a9487d57a5c 79 OpenCV highgui module, you are probably familar with cv::cvSetCaptureProperty,
thedo 166:3a9487d57a5c 80 ocvcvGetCaptureProperty, VideoCapture::set and VideoCapture::get. Algorithm provides similar
thedo 166:3a9487d57a5c 81 method where instead of integer id's you specify the parameter names as text Strings. See
thedo 166:3a9487d57a5c 82 Algorithm::set and Algorithm::get for details.
thedo 166:3a9487d57a5c 83 - Reading and writing parameters from/to XML or YAML files. Every Algorithm derivative can store
thedo 166:3a9487d57a5c 84 all its parameters and then read them back. There is no need to re-implement it each time.
thedo 166:3a9487d57a5c 85
thedo 166:3a9487d57a5c 86 Moreover every FaceRecognizer supports the:
thedo 166:3a9487d57a5c 87
thedo 166:3a9487d57a5c 88 - **Training** of a FaceRecognizer with FaceRecognizer::train on a given set of images (your face
thedo 166:3a9487d57a5c 89 database!).
thedo 166:3a9487d57a5c 90 - **Prediction** of a given sample image, that means a face. The image is given as a Mat.
thedo 166:3a9487d57a5c 91 - **Loading/Saving** the model state from/to a given XML or YAML.
thedo 166:3a9487d57a5c 92 - **Setting/Getting labels info**, that is stored as a string. String labels info is useful for
thedo 166:3a9487d57a5c 93 keeping names of the recognized people.
thedo 166:3a9487d57a5c 94
thedo 166:3a9487d57a5c 95 @note When using the FaceRecognizer interface in combination with Python, please stick to Python 2.
thedo 166:3a9487d57a5c 96 Some underlying scripts like create_csv will not work in other versions, like Python 3. Setting the
thedo 166:3a9487d57a5c 97 Thresholds +++++++++++++++++++++++
thedo 166:3a9487d57a5c 98
thedo 166:3a9487d57a5c 99 Sometimes you run into the situation, when you want to apply a threshold on the prediction. A common
thedo 166:3a9487d57a5c 100 scenario in face recognition is to tell, whether a face belongs to the training dataset or if it is
thedo 166:3a9487d57a5c 101 unknown. You might wonder, why there's no public API in FaceRecognizer to set the threshold for the
thedo 166:3a9487d57a5c 102 prediction, but rest assured: It's supported. It just means there's no generic way in an abstract
thedo 166:3a9487d57a5c 103 class to provide an interface for setting/getting the thresholds of *every possible* FaceRecognizer
thedo 166:3a9487d57a5c 104 algorithm. The appropriate place to set the thresholds is in the constructor of the specific
thedo 166:3a9487d57a5c 105 FaceRecognizer and since every FaceRecognizer is a Algorithm (see above), you can get/set the
thedo 166:3a9487d57a5c 106 thresholds at runtime!
thedo 166:3a9487d57a5c 107
thedo 166:3a9487d57a5c 108 Here is an example of setting a threshold for the Eigenfaces method, when creating the model:
thedo 166:3a9487d57a5c 109
thedo 166:3a9487d57a5c 110 @code
thedo 166:3a9487d57a5c 111 // Let's say we want to keep 10 Eigenfaces and have a threshold value of 10.0
thedo 166:3a9487d57a5c 112 int num_components = 10;
thedo 166:3a9487d57a5c 113 double threshold = 10.0;
thedo 166:3a9487d57a5c 114 // Then if you want to have a cv::FaceRecognizer with a confidence threshold,
thedo 166:3a9487d57a5c 115 // create the concrete implementation with the appropiate parameters:
thedo 166:3a9487d57a5c 116 Ptr<FaceRecognizer> model = createEigenFaceRecognizer(num_components, threshold);
thedo 166:3a9487d57a5c 117 @endcode
thedo 166:3a9487d57a5c 118
thedo 166:3a9487d57a5c 119 Sometimes it's impossible to train the model, just to experiment with threshold values. Thanks to
thedo 166:3a9487d57a5c 120 Algorithm it's possible to set internal model thresholds during runtime. Let's see how we would
thedo 166:3a9487d57a5c 121 set/get the prediction for the Eigenface model, we've created above:
thedo 166:3a9487d57a5c 122
thedo 166:3a9487d57a5c 123 @code
thedo 166:3a9487d57a5c 124 // The following line reads the threshold from the Eigenfaces model:
thedo 166:3a9487d57a5c 125 double current_threshold = model->getDouble("threshold");
thedo 166:3a9487d57a5c 126 // And this line sets the threshold to 0.0:
thedo 166:3a9487d57a5c 127 model->set("threshold", 0.0);
thedo 166:3a9487d57a5c 128 @endcode
thedo 166:3a9487d57a5c 129
thedo 166:3a9487d57a5c 130 If you've set the threshold to 0.0 as we did above, then:
thedo 166:3a9487d57a5c 131
thedo 166:3a9487d57a5c 132 @code
thedo 166:3a9487d57a5c 133 //
thedo 166:3a9487d57a5c 134 Mat img = imread("person1/3.jpg", CV_LOAD_IMAGE_GRAYSCALE);
thedo 166:3a9487d57a5c 135 // Get a prediction from the model. Note: We've set a threshold of 0.0 above,
thedo 166:3a9487d57a5c 136 // since the distance is almost always larger than 0.0, you'll get -1 as
thedo 166:3a9487d57a5c 137 // label, which indicates, this face is unknown
thedo 166:3a9487d57a5c 138 int predicted_label = model->predict(img);
thedo 166:3a9487d57a5c 139 // ...
thedo 166:3a9487d57a5c 140 @endcode
thedo 166:3a9487d57a5c 141
thedo 166:3a9487d57a5c 142 is going to yield -1 as predicted label, which states this face is unknown.
thedo 166:3a9487d57a5c 143
thedo 166:3a9487d57a5c 144 ### Getting the name of a FaceRecognizer
thedo 166:3a9487d57a5c 145
thedo 166:3a9487d57a5c 146 Since every FaceRecognizer is a Algorithm, you can use Algorithm::name to get the name of a
thedo 166:3a9487d57a5c 147 FaceRecognizer:
thedo 166:3a9487d57a5c 148
thedo 166:3a9487d57a5c 149 @code
thedo 166:3a9487d57a5c 150 // Create a FaceRecognizer:
thedo 166:3a9487d57a5c 151 Ptr<FaceRecognizer> model = createEigenFaceRecognizer();
thedo 166:3a9487d57a5c 152 // And here's how to get its name:
thedo 166:3a9487d57a5c 153 String name = model->name();
thedo 166:3a9487d57a5c 154 @endcode
thedo 166:3a9487d57a5c 155
thedo 166:3a9487d57a5c 156 */
thedo 166:3a9487d57a5c 157 class CV_EXPORTS_W FaceRecognizer : public Algorithm
thedo 166:3a9487d57a5c 158 {
thedo 166:3a9487d57a5c 159 public:
thedo 166:3a9487d57a5c 160 /** @brief Trains a FaceRecognizer with given data and associated labels.
thedo 166:3a9487d57a5c 161
thedo 166:3a9487d57a5c 162 @param src The training images, that means the faces you want to learn. The data has to be
thedo 166:3a9487d57a5c 163 given as a vector\<Mat\>.
thedo 166:3a9487d57a5c 164 @param labels The labels corresponding to the images have to be given either as a vector\<int\>
thedo 166:3a9487d57a5c 165 or a
thedo 166:3a9487d57a5c 166
thedo 166:3a9487d57a5c 167 The following source code snippet shows you how to learn a Fisherfaces model on a given set of
thedo 166:3a9487d57a5c 168 images. The images are read with imread and pushed into a std::vector\<Mat\>. The labels of each
thedo 166:3a9487d57a5c 169 image are stored within a std::vector\<int\> (you could also use a Mat of type CV_32SC1). Think of
thedo 166:3a9487d57a5c 170 the label as the subject (the person) this image belongs to, so same subjects (persons) should have
thedo 166:3a9487d57a5c 171 the same label. For the available FaceRecognizer you don't have to pay any attention to the order of
thedo 166:3a9487d57a5c 172 the labels, just make sure same persons have the same label:
thedo 166:3a9487d57a5c 173
thedo 166:3a9487d57a5c 174 @code
thedo 166:3a9487d57a5c 175 // holds images and labels
thedo 166:3a9487d57a5c 176 vector<Mat> images;
thedo 166:3a9487d57a5c 177 vector<int> labels;
thedo 166:3a9487d57a5c 178 // images for first person
thedo 166:3a9487d57a5c 179 images.push_back(imread("person0/0.jpg", CV_LOAD_IMAGE_GRAYSCALE)); labels.push_back(0);
thedo 166:3a9487d57a5c 180 images.push_back(imread("person0/1.jpg", CV_LOAD_IMAGE_GRAYSCALE)); labels.push_back(0);
thedo 166:3a9487d57a5c 181 images.push_back(imread("person0/2.jpg", CV_LOAD_IMAGE_GRAYSCALE)); labels.push_back(0);
thedo 166:3a9487d57a5c 182 // images for second person
thedo 166:3a9487d57a5c 183 images.push_back(imread("person1/0.jpg", CV_LOAD_IMAGE_GRAYSCALE)); labels.push_back(1);
thedo 166:3a9487d57a5c 184 images.push_back(imread("person1/1.jpg", CV_LOAD_IMAGE_GRAYSCALE)); labels.push_back(1);
thedo 166:3a9487d57a5c 185 images.push_back(imread("person1/2.jpg", CV_LOAD_IMAGE_GRAYSCALE)); labels.push_back(1);
thedo 166:3a9487d57a5c 186 @endcode
thedo 166:3a9487d57a5c 187
thedo 166:3a9487d57a5c 188 Now that you have read some images, we can create a new FaceRecognizer. In this example I'll create
thedo 166:3a9487d57a5c 189 a Fisherfaces model and decide to keep all of the possible Fisherfaces:
thedo 166:3a9487d57a5c 190
thedo 166:3a9487d57a5c 191 @code
thedo 166:3a9487d57a5c 192 // Create a new Fisherfaces model and retain all available Fisherfaces,
thedo 166:3a9487d57a5c 193 // this is the most common usage of this specific FaceRecognizer:
thedo 166:3a9487d57a5c 194 //
thedo 166:3a9487d57a5c 195 Ptr<FaceRecognizer> model = createFisherFaceRecognizer();
thedo 166:3a9487d57a5c 196 @endcode
thedo 166:3a9487d57a5c 197
thedo 166:3a9487d57a5c 198 And finally train it on the given dataset (the face images and labels):
thedo 166:3a9487d57a5c 199
thedo 166:3a9487d57a5c 200 @code
thedo 166:3a9487d57a5c 201 // This is the common interface to train all of the available cv::FaceRecognizer
thedo 166:3a9487d57a5c 202 // implementations:
thedo 166:3a9487d57a5c 203 //
thedo 166:3a9487d57a5c 204 model->train(images, labels);
thedo 166:3a9487d57a5c 205 @endcode
thedo 166:3a9487d57a5c 206 */
thedo 166:3a9487d57a5c 207 CV_WRAP virtual void train(InputArrayOfArrays src, InputArray labels) = 0;
thedo 166:3a9487d57a5c 208
thedo 166:3a9487d57a5c 209 /** @brief Updates a FaceRecognizer with given data and associated labels.
thedo 166:3a9487d57a5c 210
thedo 166:3a9487d57a5c 211 @param src The training images, that means the faces you want to learn. The data has to be given
thedo 166:3a9487d57a5c 212 as a vector\<Mat\>.
thedo 166:3a9487d57a5c 213 @param labels The labels corresponding to the images have to be given either as a vector\<int\> or
thedo 166:3a9487d57a5c 214 a
thedo 166:3a9487d57a5c 215
thedo 166:3a9487d57a5c 216 This method updates a (probably trained) FaceRecognizer, but only if the algorithm supports it. The
thedo 166:3a9487d57a5c 217 Local Binary Patterns Histograms (LBPH) recognizer (see createLBPHFaceRecognizer) can be updated.
thedo 166:3a9487d57a5c 218 For the Eigenfaces and Fisherfaces method, this is algorithmically not possible and you have to
thedo 166:3a9487d57a5c 219 re-estimate the model with FaceRecognizer::train. In any case, a call to train empties the existing
thedo 166:3a9487d57a5c 220 model and learns a new model, while update does not delete any model data.
thedo 166:3a9487d57a5c 221
thedo 166:3a9487d57a5c 222 @code
thedo 166:3a9487d57a5c 223 // Create a new LBPH model (it can be updated) and use the default parameters,
thedo 166:3a9487d57a5c 224 // this is the most common usage of this specific FaceRecognizer:
thedo 166:3a9487d57a5c 225 //
thedo 166:3a9487d57a5c 226 Ptr<FaceRecognizer> model = createLBPHFaceRecognizer();
thedo 166:3a9487d57a5c 227 // This is the common interface to train all of the available cv::FaceRecognizer
thedo 166:3a9487d57a5c 228 // implementations:
thedo 166:3a9487d57a5c 229 //
thedo 166:3a9487d57a5c 230 model->train(images, labels);
thedo 166:3a9487d57a5c 231 // Some containers to hold new image:
thedo 166:3a9487d57a5c 232 vector<Mat> newImages;
thedo 166:3a9487d57a5c 233 vector<int> newLabels;
thedo 166:3a9487d57a5c 234 // You should add some images to the containers:
thedo 166:3a9487d57a5c 235 //
thedo 166:3a9487d57a5c 236 // ...
thedo 166:3a9487d57a5c 237 //
thedo 166:3a9487d57a5c 238 // Now updating the model is as easy as calling:
thedo 166:3a9487d57a5c 239 model->update(newImages,newLabels);
thedo 166:3a9487d57a5c 240 // This will preserve the old model data and extend the existing model
thedo 166:3a9487d57a5c 241 // with the new features extracted from newImages!
thedo 166:3a9487d57a5c 242 @endcode
thedo 166:3a9487d57a5c 243
thedo 166:3a9487d57a5c 244 Calling update on an Eigenfaces model (see createEigenFaceRecognizer), which doesn't support
thedo 166:3a9487d57a5c 245 updating, will throw an error similar to:
thedo 166:3a9487d57a5c 246
thedo 166:3a9487d57a5c 247 @code
thedo 166:3a9487d57a5c 248 OpenCV Error: The function/feature is not implemented (This FaceRecognizer (FaceRecognizer.Eigenfaces) does not support updating, you have to use FaceRecognizer::train to update it.) in update, file /home/philipp/git/opencv/modules/contrib/src/facerec.cpp, line 305
thedo 166:3a9487d57a5c 249 terminate called after throwing an instance of 'cv::Exception'
thedo 166:3a9487d57a5c 250 @endcode
thedo 166:3a9487d57a5c 251
thedo 166:3a9487d57a5c 252 @note The FaceRecognizer does not store your training images, because this would be very
thedo 166:3a9487d57a5c 253 memory intense and it's not the responsibility of te FaceRecognizer to do so. The caller is
thedo 166:3a9487d57a5c 254 responsible for maintaining the dataset, he want to work with.
thedo 166:3a9487d57a5c 255 */
thedo 166:3a9487d57a5c 256 CV_WRAP virtual void update(InputArrayOfArrays src, InputArray labels);
thedo 166:3a9487d57a5c 257
thedo 166:3a9487d57a5c 258 /** @overload */
thedo 166:3a9487d57a5c 259 CV_WRAP_AS(predict_label) int predict(InputArray src) const;
thedo 166:3a9487d57a5c 260
thedo 166:3a9487d57a5c 261
thedo 166:3a9487d57a5c 262 /** @brief Predicts a label and associated confidence (e.g. distance) for a given input image.
thedo 166:3a9487d57a5c 263
thedo 166:3a9487d57a5c 264 @param src Sample image to get a prediction from.
thedo 166:3a9487d57a5c 265 @param label The predicted label for the given image.
thedo 166:3a9487d57a5c 266 @param confidence Associated confidence (e.g. distance) for the predicted label.
thedo 166:3a9487d57a5c 267
thedo 166:3a9487d57a5c 268 The suffix const means that prediction does not affect the internal model state, so the method can
thedo 166:3a9487d57a5c 269 be safely called from within different threads.
thedo 166:3a9487d57a5c 270
thedo 166:3a9487d57a5c 271 The following example shows how to get a prediction from a trained model:
thedo 166:3a9487d57a5c 272
thedo 166:3a9487d57a5c 273 @code
thedo 166:3a9487d57a5c 274 using namespace cv;
thedo 166:3a9487d57a5c 275 // Do your initialization here (create the cv::FaceRecognizer model) ...
thedo 166:3a9487d57a5c 276 // ...
thedo 166:3a9487d57a5c 277 // Read in a sample image:
thedo 166:3a9487d57a5c 278 Mat img = imread("person1/3.jpg", CV_LOAD_IMAGE_GRAYSCALE);
thedo 166:3a9487d57a5c 279 // And get a prediction from the cv::FaceRecognizer:
thedo 166:3a9487d57a5c 280 int predicted = model->predict(img);
thedo 166:3a9487d57a5c 281 @endcode
thedo 166:3a9487d57a5c 282
thedo 166:3a9487d57a5c 283 Or to get a prediction and the associated confidence (e.g. distance):
thedo 166:3a9487d57a5c 284
thedo 166:3a9487d57a5c 285 @code
thedo 166:3a9487d57a5c 286 using namespace cv;
thedo 166:3a9487d57a5c 287 // Do your initialization here (create the cv::FaceRecognizer model) ...
thedo 166:3a9487d57a5c 288 // ...
thedo 166:3a9487d57a5c 289 Mat img = imread("person1/3.jpg", CV_LOAD_IMAGE_GRAYSCALE);
thedo 166:3a9487d57a5c 290 // Some variables for the predicted label and associated confidence (e.g. distance):
thedo 166:3a9487d57a5c 291 int predicted_label = -1;
thedo 166:3a9487d57a5c 292 double predicted_confidence = 0.0;
thedo 166:3a9487d57a5c 293 // Get the prediction and associated confidence from the model
thedo 166:3a9487d57a5c 294 model->predict(img, predicted_label, predicted_confidence);
thedo 166:3a9487d57a5c 295 @endcode
thedo 166:3a9487d57a5c 296 */
thedo 166:3a9487d57a5c 297 CV_WRAP void predict(InputArray src, CV_OUT int &label, CV_OUT double &confidence) const;
thedo 166:3a9487d57a5c 298
thedo 166:3a9487d57a5c 299
thedo 166:3a9487d57a5c 300 /** @brief - if implemented - send all result of prediction to collector that can be used for somehow custom result handling
thedo 166:3a9487d57a5c 301 @param src Sample image to get a prediction from.
thedo 166:3a9487d57a5c 302 @param collector User-defined collector object that accepts all results
thedo 166:3a9487d57a5c 303
thedo 166:3a9487d57a5c 304 To implement this method u just have to do same internal cycle as in predict(InputArray src, CV_OUT int &label, CV_OUT double &confidence) but
thedo 166:3a9487d57a5c 305 not try to get "best@ result, just resend it to caller side with given collector
thedo 166:3a9487d57a5c 306 */
thedo 166:3a9487d57a5c 307 CV_WRAP_AS(predict_collect) virtual void predict(InputArray src, Ptr<PredictCollector> collector) const = 0;
thedo 166:3a9487d57a5c 308
thedo 166:3a9487d57a5c 309 /** @brief Saves a FaceRecognizer and its model state.
thedo 166:3a9487d57a5c 310
thedo 166:3a9487d57a5c 311 Saves this model to a given filename, either as XML or YAML.
thedo 166:3a9487d57a5c 312 @param filename The filename to store this FaceRecognizer to (either XML/YAML).
thedo 166:3a9487d57a5c 313
thedo 166:3a9487d57a5c 314 Every FaceRecognizer overwrites FaceRecognizer::save(FileStorage& fs) to save the internal model
thedo 166:3a9487d57a5c 315 state. FaceRecognizer::save(const String& filename) saves the state of a model to the given
thedo 166:3a9487d57a5c 316 filename.
thedo 166:3a9487d57a5c 317
thedo 166:3a9487d57a5c 318 The suffix const means that prediction does not affect the internal model state, so the method can
thedo 166:3a9487d57a5c 319 be safely called from within different threads.
thedo 166:3a9487d57a5c 320 */
thedo 166:3a9487d57a5c 321 CV_WRAP virtual void save(const String& filename) const;
thedo 166:3a9487d57a5c 322
thedo 166:3a9487d57a5c 323 /** @brief Loads a FaceRecognizer and its model state.
thedo 166:3a9487d57a5c 324
thedo 166:3a9487d57a5c 325 Loads a persisted model and state from a given XML or YAML file . Every FaceRecognizer has to
thedo 166:3a9487d57a5c 326 overwrite FaceRecognizer::load(FileStorage& fs) to enable loading the model state.
thedo 166:3a9487d57a5c 327 FaceRecognizer::load(FileStorage& fs) in turn gets called by
thedo 166:3a9487d57a5c 328 FaceRecognizer::load(const String& filename), to ease saving a model.
thedo 166:3a9487d57a5c 329 */
thedo 166:3a9487d57a5c 330 CV_WRAP virtual void load(const String& filename);
thedo 166:3a9487d57a5c 331
thedo 166:3a9487d57a5c 332 /** @overload
thedo 166:3a9487d57a5c 333 Saves this model to a given FileStorage.
thedo 166:3a9487d57a5c 334 @param fs The FileStorage to store this FaceRecognizer to.
thedo 166:3a9487d57a5c 335 */
thedo 166:3a9487d57a5c 336 virtual void save(FileStorage& fs) const = 0;
thedo 166:3a9487d57a5c 337
thedo 166:3a9487d57a5c 338 /** @overload */
thedo 166:3a9487d57a5c 339 virtual void load(const FileStorage& fs) = 0;
thedo 166:3a9487d57a5c 340
thedo 166:3a9487d57a5c 341 /** @brief Sets string info for the specified model's label.
thedo 166:3a9487d57a5c 342
thedo 166:3a9487d57a5c 343 The string info is replaced by the provided value if it was set before for the specified label.
thedo 166:3a9487d57a5c 344 */
thedo 166:3a9487d57a5c 345 CV_WRAP virtual void setLabelInfo(int label, const String& strInfo);
thedo 166:3a9487d57a5c 346
thedo 166:3a9487d57a5c 347 /** @brief Gets string information by label.
thedo 166:3a9487d57a5c 348
thedo 166:3a9487d57a5c 349 If an unknown label id is provided or there is no label information associated with the specified
thedo 166:3a9487d57a5c 350 label id the method returns an empty string.
thedo 166:3a9487d57a5c 351 */
thedo 166:3a9487d57a5c 352 CV_WRAP virtual String getLabelInfo(int label) const;
thedo 166:3a9487d57a5c 353
thedo 166:3a9487d57a5c 354 /** @brief Gets vector of labels by string.
thedo 166:3a9487d57a5c 355
thedo 166:3a9487d57a5c 356 The function searches for the labels containing the specified sub-string in the associated string
thedo 166:3a9487d57a5c 357 info.
thedo 166:3a9487d57a5c 358 */
thedo 166:3a9487d57a5c 359 CV_WRAP virtual std::vector<int> getLabelsByString(const String& str) const;
thedo 166:3a9487d57a5c 360 /** @brief threshold parameter accessor - required for default BestMinDist collector */
thedo 166:3a9487d57a5c 361 virtual double getThreshold() const = 0;
thedo 166:3a9487d57a5c 362 /** @brief Sets threshold of model */
thedo 166:3a9487d57a5c 363 virtual void setThreshold(double val) = 0;
thedo 166:3a9487d57a5c 364 protected:
thedo 166:3a9487d57a5c 365 // Stored pairs "label id - string info"
thedo 166:3a9487d57a5c 366 std::map<int, String> _labelsInfo;
thedo 166:3a9487d57a5c 367 };
thedo 166:3a9487d57a5c 368
thedo 166:3a9487d57a5c 369 //! @}
thedo 166:3a9487d57a5c 370
thedo 166:3a9487d57a5c 371 }}
thedo 166:3a9487d57a5c 372
thedo 166:3a9487d57a5c 373 #include "opencv2/face/facerec.hpp"
thedo 166:3a9487d57a5c 374
thedo 166:3a9487d57a5c 375 #endif
thedo 166:3a9487d57a5c 376