| OpenCV 5.0.0alpha Open Source Computer Vision

Loading...
Searching...
No Matches
Public Member Functions | List of all members
cv::face::FacemarkTrain Class Referenceabstract
Face Analysis

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

`#include <opencv2/face/facemark_train.hpp>`

Collaboration diagram for cv::face::FacemarkTrain:

## 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
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< _Tp > | load (const String &filename, const String &objname=String())
| Loads algorithm from the file.
template<typename _Tp >
static Ptr< _Tp > | loadFromString (const String &strModel, const String &objname=String())
| Loads algorithm from a String.
template<typename _Tp >
static Ptr< _Tp > | read (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:
Ptr<Facemark> facemark = FacemarkLBF::create();
cv::face::FacemarkLBF::create
static Ptr< FacemarkLBF > create(const FacemarkLBF::Params &parameters=FacemarkLBF::Params())
cv::Ptr
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

  image | Input image.
  landmarks | The 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);
}
cv::Mat
n-dimensional dense array class
Definition mat.hpp:951
cv::String
std::string String
Definition cvstd.hpp:151
cv::face::loadDatasetList
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.
cv::face::loadFacePoints
bool loadFacePoints(String filename, OutputArray points, float offset=0.0f)
A utility to load facial landmark information from a given file.
cv::imread
CV_EXPORTS_W Mat imread(const String &filename, int flags=IMREAD_COLOR_BGR)
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

  items | The obtained data, algorithm dependent.

Example of usage

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

  image | Input image.
  faces | Output 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));
}
cv::Scalar_< double >
cv::rectangle
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

  detector | The user defined face detector function
  userData | Detector 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 --------
}
cv::_InputArray
This is the proxy class for passing read-only input arrays into OpenCV functions.
Definition mat.hpp:268
cv::_OutputArray
This type is very similar to InputArray except that it is used for input/output and output function p...
Definition mat.hpp:401

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

  parameters | Optional extra parameters (algorithm dependent).

Example of usage

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

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

- opencv2/face/facemark_train.hpp