Loading...
Searching...
No Matches
cv::face::FacemarkTrain Class Referenceabstract

Abstract base class for trainable facemark models. More...

#include <opencv2/face/facemark_train.hpp>

Inheritance diagram for cv::face::FacemarkTrain:
cv::face::Facemark cv::Algorithm cv::face::FacemarkAAM cv::face::FacemarkLBF

Public Member Functions

virtual bool addTrainingSample (InputArray image, InputArray landmarks)=0
 Add one training sample to the trainer.
 
virtual bool getData (void *items=0)=0
 Get data from an algorithm.
 
virtual bool getFaces (InputArray image, OutputArray faces)=0
 Detect faces from a given image using default or user defined face detector. Some Algorithm might not provide a default face detector.
 
virtual bool setFaceDetector (FN_FaceDetector detector, void *userData=0)=0
 Set a user defined face detector for the Facemark algorithm.
 
virtual void training (void *parameters=0)=0
 Trains a Facemark algorithm using the given dataset. Before the training process, training samples should be added to the trainer using face::addTrainingSample function.
 
- Public Member Functions inherited from cv::face::Facemark
virtual bool fit (InputArray image, InputArray faces, OutputArrayOfArrays landmarks)=0
 Detect facial landmarks from an image.
 
virtual void loadModel (String model)=0
 A function to load the trained model before the fitting process.
 
- Public Member Functions inherited from cv::Algorithm
 Algorithm ()
 
virtual ~Algorithm ()
 
virtual void clear ()
 Clears the algorithm state.
 
virtual bool empty () const
 Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read.
 
virtual String getDefaultName () const
 
virtual void read (const FileNode &fn)
 Reads algorithm parameters from a file storage.
 
virtual void save (const String &filename) const
 
void write (const Ptr< FileStorage > &fs, const String &name=String()) const
 
virtual void write (FileStorage &fs) const
 Stores algorithm parameters in a file storage.
 
void write (FileStorage &fs, const String &name) const
 

Additional Inherited Members

- Static Public Member Functions inherited from cv::Algorithm
template<typename _Tp >
static Ptr< _Tpload (const String &filename, const String &objname=String())
 Loads algorithm from the file.
 
template<typename _Tp >
static Ptr< _TploadFromString (const String &strModel, const String &objname=String())
 Loads algorithm from a String.
 
template<typename _Tp >
static Ptr< _Tpread (const FileNode &fn)
 Reads algorithm from the file node.
 
- Protected Member Functions inherited from cv::Algorithm
void writeFormat (FileStorage &fs) const
 

Detailed Description

Abstract base class for trainable facemark models.

To utilize this API in your program, please take a look at the Tutorial on Facial Landmark Detector API

Description

The AAM and LBF facemark models in OpenCV are derived from the abstract base class FacemarkTrain, which provides a unified access to those facemark algorithms in OpenCV.

Here is an example on how to declare facemark algorithm:

// Using Facemark in your code:
static Ptr< FacemarkLBF > create(const FacemarkLBF::Params &parameters=FacemarkLBF::Params())
std::shared_ptr< _Tp > Ptr
Definition: cvstd_wrapper.hpp:23

The typical pipeline for facemark detection is listed as follows:

  • (Non-mandatory) Set a user defined face detection using FacemarkTrain::setFaceDetector. The facemark algorithms are designed to fit the facial points into a face. Therefore, the face information should be provided to the facemark algorithm. Some algorithms might provides a default face recognition function. However, the users might prefer to use their own face detector to obtains the best possible detection result.
  • (Non-mandatory) Training the model for a specific algorithm using FacemarkTrain::training. In this case, the model should be automatically saved by the algorithm. If the user already have a trained model, then this part can be omitted.
  • Load the trained model using Facemark::loadModel.
  • Perform the fitting via the Facemark::fit.

Member Function Documentation

◆ addTrainingSample()

virtual bool cv::face::FacemarkTrain::addTrainingSample ( InputArray  image,
InputArray  landmarks 
)
pure virtual

Add one training sample to the trainer.

Parameters
imageInput image.
landmarksThe ground-truth of facial landmarks points corresponds to the image.

Example of usage

String imageFiles = "../data/images_train.txt";
String ptsFiles = "../data/points_train.txt";
std::vector<String> images_train;
std::vector<String> landmarks_train;
// load the list of dataset: image paths and landmark file paths
loadDatasetList(imageFiles,ptsFiles,images_train,landmarks_train);
Mat image;
std::vector<Point2f> facial_points;
for(size_t i=0;i<images_train.size();i++){
image = imread(images_train[i].c_str());
loadFacePoints(landmarks_train[i],facial_points);
facemark->addTrainingSample(image, facial_points);
}
n-dimensional dense array class
Definition: mat.hpp:811
std::string String
Definition: cvstd.hpp:152
bool loadDatasetList(String imageList, String annotationList, std::vector< String > &images, std::vector< String > &annotations)
A utility to load list of paths to training image and annotation file.
bool loadFacePoints(String filename, OutputArray points, float offset=0.0f)
A utility to load facial landmark information from a given file.
CV_EXPORTS_W Mat imread(const String &filename, int flags=IMREAD_COLOR)
Loads an image from a file.

The contents in the training files should follows the standard format. Here are examples for the contents in these files. example of content in the images_train.txt

/home/user/ibug/image_003_1.jpg
/home/user/ibug/image_004_1.jpg
/home/user/ibug/image_005_1.jpg
/home/user/ibug/image_006.jpg

example of content in the points_train.txt

/home/user/ibug/image_003_1.pts
/home/user/ibug/image_004_1.pts
/home/user/ibug/image_005_1.pts
/home/user/ibug/image_006.pts

◆ getData()

virtual bool cv::face::FacemarkTrain::getData ( void *  items = 0)
pure virtual

Get data from an algorithm.

Parameters
itemsThe obtained data, algorithm dependent.

Example of usage

facemark->loadModel("AAM.yml");
facemark->getData(&data);
std::vector<Point2f> s0 = data.s0;
cout<<s0<<endl;
static Ptr< FacemarkAAM > create(const FacemarkAAM::Params &parameters=FacemarkAAM::Params())
initializer
Data container for the facemark::getData function.
Definition: facemarkAAM.hpp:99
std::vector< Point2f > s0
Definition: facemarkAAM.hpp:100

◆ getFaces()

virtual bool cv::face::FacemarkTrain::getFaces ( InputArray  image,
OutputArray  faces 
)
pure virtual

Detect faces from a given image using default or user defined face detector. Some Algorithm might not provide a default face detector.

Parameters
imageInput image.
facesOutput of the function which represent region of interest of the detected faces. Each face is stored in cv::Rect container.

Example of usage

std::vector<cv::Rect> faces;
facemark->getFaces(img, faces);
for(int j=0;j<faces.size();j++){
cv::rectangle(img, faces[j], cv::Scalar(255,0,255));
}
void rectangle(InputOutputArray img, Point pt1, Point pt2, const Scalar &color, int thickness=1, int lineType=LINE_8, int shift=0)
Draws a simple, thick, or filled up-right rectangle.

◆ setFaceDetector()

virtual bool cv::face::FacemarkTrain::setFaceDetector ( FN_FaceDetector  detector,
void *  userData = 0 
)
pure virtual

Set a user defined face detector for the Facemark algorithm.

Parameters
detectorThe user defined face detector function
userDataDetector parameters

Example of usage

MyDetectorParameters detectorParameters(...);
facemark->setFaceDetector(myDetector, &detectorParameters);

Example of a user defined face detector

bool myDetector( InputArray image, OutputArray faces, void* userData)
{
MyDetectorParameters* params = (MyDetectorParameters*)userData;
// -------- do something --------
}
This is the proxy class for passing read-only input arrays into OpenCV functions.
Definition: mat.hpp:159
This type is very similar to InputArray except that it is used for input/output and output function p...
Definition: mat.hpp:295

TODO Lifetime of detector parameters is uncontrolled. Rework interface design to "Ptr<FaceDetector>".

◆ training()

virtual void cv::face::FacemarkTrain::training ( void *  parameters = 0)
pure virtual

Trains a Facemark algorithm using the given dataset. Before the training process, training samples should be added to the trainer using face::addTrainingSample function.

Parameters
parametersOptional extra parameters (algorithm dependent).

Example of usage

params.model_filename = "ibug68.model"; // filename to save the trained model
// add training samples (see Facemark::addTrainingSample)
facemark->training();
Definition: facemarkLBF.hpp:52

The documentation for this class was generated from the following file: