Struct opencv::face::FaceRecognizer

pub struct FaceRecognizer { /* private fields */ }

Abstract base class for all face recognition models

All face recognition models in OpenCV are derived from the abstract base class FaceRecognizer, which provides a unified access to all face recongition algorithms in OpenCV.

Description

I’ll go a bit more into detail explaining FaceRecognizer, because it doesn’t look like a powerful interface at first sight. But: Every FaceRecognizer is an Algorithm, so you can easily get/set all model internals (if allowed by the implementation). Algorithm is a relatively new OpenCV concept, which is available since the 2.4 release. I suggest you take a look at its description.

Algorithm provides the following features for all derived classes:

• So called “virtual constructor”. That is, each Algorithm derivative is registered at program start and you can get the list of registered algorithms and create instance of a particular algorithm by its name (see Algorithm::create). If you plan to add your own algorithms, it is good practice to add a unique prefix to your algorithms to distinguish them from other algorithms.
• Setting/Retrieving algorithm parameters by name. If you used video capturing functionality from OpenCV highgui module, you are probably familar with cv::cvSetCaptureProperty, ocvcvGetCaptureProperty, VideoCapture::set and VideoCapture::get. Algorithm provides similar method where instead of integer id’s you specify the parameter names as text Strings. See Algorithm::set and Algorithm::get for details.
• Reading and writing parameters from/to XML or YAML files. Every Algorithm derivative can store all its parameters and then read them back. There is no need to re-implement it each time.

Moreover every FaceRecognizer supports the:

• Training of a FaceRecognizer with FaceRecognizer::train on a given set of images (your face database!).
• Prediction of a given sample image, that means a face. The image is given as a Mat.
• Loading/Saving the model state from/to a given XML or YAML.
• Setting/Getting labels info, that is stored as a string. String labels info is useful for keeping names of the recognized people.

Note: When using the FaceRecognizer interface in combination with Python, please stick to Python 2. Some underlying scripts like create_csv will not work in other versions, like Python 3. Setting the Thresholds +++++++++++++++++++++++

Sometimes you run into the situation, when you want to apply a threshold on the prediction. A common scenario in face recognition is to tell, whether a face belongs to the training dataset or if it is unknown. You might wonder, why there’s no public API in FaceRecognizer to set the threshold for the prediction, but rest assured: It’s supported. It just means there’s no generic way in an abstract class to provide an interface for setting/getting the thresholds of every possible FaceRecognizer algorithm. The appropriate place to set the thresholds is in the constructor of the specific FaceRecognizer and since every FaceRecognizer is a Algorithm (see above), you can get/set the thresholds at runtime!

Here is an example of setting a threshold for the Eigenfaces method, when creating the model:

// Let's say we want to keep 10 Eigenfaces and have a threshold value of 10.0
int num_components = 10;
double threshold = 10.0;
// Then if you want to have a cv::FaceRecognizer with a confidence threshold,
// create the concrete implementation with the appropriate parameters:
Ptr<FaceRecognizer> model = EigenFaceRecognizer::create(num_components, threshold);

Sometimes it’s impossible to train the model, just to experiment with threshold values. Thanks to Algorithm it’s possible to set internal model thresholds during runtime. Let’s see how we would set/get the prediction for the Eigenface model, we’ve created above:

// The following line reads the threshold from the Eigenfaces model:
double current_threshold = model->getDouble("threshold");
// And this line sets the threshold to 0.0:
model->set("threshold", 0.0);

If you’ve set the threshold to 0.0 as we did above, then:

//
Mat img = imread("person1/3.jpg", IMREAD_GRAYSCALE);
// Get a prediction from the model. Note: We've set a threshold of 0.0 above,
// since the distance is almost always larger than 0.0, you'll get -1 as
// label, which indicates, this face is unknown
int predicted_label = model->predict(img);
// ...

is going to yield -1 as predicted label, which states this face is unknown.

Getting the name of a FaceRecognizer

Since every FaceRecognizer is a Algorithm, you can use Algorithm::name to get the name of a FaceRecognizer:

// Create a FaceRecognizer:
Ptr<FaceRecognizer> model = EigenFaceRecognizer::create();
// And here's how to get its name:
String name = model->name();

Trait Implementations

impl AlgorithmTrait for FaceRecognizer

fn as_raw_mut_Algorithm(&mut self) -> *mut c_void

fn clear(&mut self) -> Result<()>

Clears the algorithm state

fn read(&mut self, fn_: &impl FileNodeTraitConst) -> Result<()>

Reads algorithm parameters from a file storage

impl AlgorithmTraitConst for FaceRecognizer

fn as_raw_Algorithm(&self) -> *const c_void

fn write(&self, fs: &mut impl FileStorageTrait) -> Result<()>

Stores algorithm parameters in a file storage

fn write_1(&self, fs: &mut impl FileStorageTrait, name: &str) -> Result<()>

Stores algorithm parameters in a file storage

fn write_with_name(&self, fs: &Ptr<FileStorage>, name: &str) -> Result<()>

@deprecated

fn write_with_name_def(&self, fs: &Ptr<FileStorage>) -> Result<()>

👎Deprecated:

Note

Deprecated: ## Note This alternative version of AlgorithmTraitConst::write_with_name function uses the following default values for its arguments:

fn empty(&self) -> Result<bool>

Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read

fn save(&self, filename: &str) -> Result<()>

Saves the algorithm to a file. In order to make this method work, the derived class must implement Algorithm::write(FileStorage& fs).

fn get_default_name(&self) -> Result<String>

Returns the algorithm string identifier. This string is used as top level xml/yml node tag when the object is saved to a file or string.

impl Boxed for FaceRecognizer

unsafe fn from_raw( ptr: <FaceRecognizer as OpenCVFromExtern>::ExternReceive ) -> Self

Wrap the specified raw pointer

fn into_raw( self ) -> <FaceRecognizer as OpenCVTypeExternContainer>::ExternSendMut

Return the underlying raw pointer while consuming this wrapper.

fn as_raw(&self) -> <FaceRecognizer as OpenCVTypeExternContainer>::ExternSend

Return the underlying raw pointer.

fn as_raw_mut( &mut self ) -> <FaceRecognizer as OpenCVTypeExternContainer>::ExternSendMut

Return the underlying mutable raw pointer

impl Debug for FaceRecognizer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for FaceRecognizer

fn drop(&mut self)

Executes the destructor for this type.

impl FaceRecognizerTrait for FaceRecognizer

fn as_raw_mut_FaceRecognizer(&mut self) -> *mut c_void

fn train( &mut self, src: &impl ToInputArray, labels: &impl ToInputArray ) -> Result<()>

Trains a FaceRecognizer with given data and associated labels.

fn update( &mut self, src: &impl ToInputArray, labels: &impl ToInputArray ) -> Result<()>

Updates a FaceRecognizer with given data and associated labels.

fn read(&mut self, filename: &str) -> Result<()>

Loads a FaceRecognizer and its model state.

fn read_1(&mut self, fn_: &impl FileNodeTraitConst) -> Result<()>

Loads a FaceRecognizer and its model state.

fn set_label_info(&mut self, label: i32, str_info: &str) -> Result<()>

Sets string info for the specified model’s label.

fn set_threshold(&mut self, val: f64) -> Result<()>

Sets threshold of model

impl FaceRecognizerTraitConst for FaceRecognizer

fn as_raw_FaceRecognizer(&self) -> *const c_void

fn predict_label(&self, src: &impl ToInputArray) -> Result<i32>

Predicts a label and associated confidence (e.g. distance) for a given input image.

fn predict( &self, src: &impl ToInputArray, label: &mut i32, confidence: &mut f64 ) -> Result<()>

Predicts a label and associated confidence (e.g. distance) for a given input image.

fn predict_collect( &self, src: &impl ToInputArray, collector: Ptr<PredictCollector> ) -> Result<()>

if implemented - send all result of prediction to collector that can be used for somehow custom result handling

fn write(&self, filename: &str) -> Result<()>

Saves a FaceRecognizer and its model state.

fn write_1(&self, fs: &mut impl FileStorageTrait) -> Result<()>

Saves a FaceRecognizer and its model state.

fn empty(&self) -> Result<bool>

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

fn get_label_info(&self, label: i32) -> Result<String>

Gets string information by label.

fn get_labels_by_string(&self, str: &str) -> Result<Vector<i32>>

Gets vector of labels by string.

fn get_threshold(&self) -> Result<f64>

threshold parameter accessor - required for default BestMinDist collector

impl From<BasicFaceRecognizer> for FaceRecognizer

fn from(s: BasicFaceRecognizer) -> Self

Converts to this type from the input type.

impl From<EigenFaceRecognizer> for FaceRecognizer

fn from(s: EigenFaceRecognizer) -> Self

Converts to this type from the input type.

impl From<FaceRecognizer> for Algorithm

fn from(s: FaceRecognizer) -> Self

Converts to this type from the input type.

impl From<FisherFaceRecognizer> for FaceRecognizer

fn from(s: FisherFaceRecognizer) -> Self

Converts to this type from the input type.

impl From<LBPHFaceRecognizer> for FaceRecognizer

fn from(s: LBPHFaceRecognizer) -> Self

Converts to this type from the input type.

impl TryFrom<FaceRecognizer> for BasicFaceRecognizer

type Error = Error

The type returned in the event of a conversion error.

fn try_from(s: FaceRecognizer) -> Result<Self>

Performs the conversion.

impl TryFrom<FaceRecognizer> for EigenFaceRecognizer

type Error = Error

The type returned in the event of a conversion error.

fn try_from(s: FaceRecognizer) -> Result<Self>

Performs the conversion.

impl TryFrom<FaceRecognizer> for FisherFaceRecognizer

type Error = Error

The type returned in the event of a conversion error.

fn try_from(s: FaceRecognizer) -> Result<Self>

Performs the conversion.

impl TryFrom<FaceRecognizer> for LBPHFaceRecognizer

type Error = Error

The type returned in the event of a conversion error.

fn try_from(s: FaceRecognizer) -> Result<Self>

Performs the conversion.

impl Send for FaceRecognizer