cv::face::Facemark Class Reference

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

#include "facemark.hpp"

Inheritance diagram for cv::face::Facemark:

Public Member Functions
virtual bool	addTrainingSample (InputArray image, InputArray landmarks)=0
	Add one training sample to the trainer. More...
virtual bool	fit (InputArray image, InputArray faces, InputOutputArray landmarks, void *config=0)=0
	Trains a Facemark algorithm using the given dataset. More...
virtual bool	getData (void *items=0)=0
	Get data from an algorithm. More...
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. More...
virtual void	loadModel (String model)=0
	A function to load the trained model before the fitting process. More...
virtual void	read (const FileNode &fn)=0
	Reads algorithm parameters from a file storage. More...
virtual bool	setFaceDetector (FN_FaceDetector detector, void *userData=0)=0
	Set a user defined face detector for the Facemark algorithm. More...
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. More...
virtual void	write (FileStorage &fs) const =0
	Stores algorithm parameters in a file storage. More...
Public Member Functions inherited from cv::Algorithm
	Algorithm ()
virtual	~Algorithm ()
virtual void	clear ()
	Clears the algorithm state. More...
virtual bool	empty () const
	Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read. More...
virtual String	getDefaultName () const
virtual void	save (const String &filename) const
void	write (const Ptr< FileStorage > &fs, const String &name=String()) const
	simplified API for language bindings This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

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. More...
template<typename _Tp >
static Ptr< _Tp >	loadFromString (const String &strModel, const String &objname=String())
	Loads algorithm from a String. More...
template<typename _Tp >
static Ptr< _Tp >	read (const FileNode &fn)
	Reads algorithm from the file node. More...
Protected Member Functions inherited from cv::Algorithm
void	writeFormat (FileStorage &fs) const

Detailed Description

Abstract base class for all facemark models.

All facemark models in OpenCV are derived from the abstract base class Facemark, which provides a unified access to all facemark algorithms in OpenCV.

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

Description

Facemark is a base class which provides universal access to any specific facemark algorithm. Therefore, the users should declare a desired algorithm before they can use it in their application.

Here is an example on how to declare facemark algorithm:

// Using Facemark in your code:
Ptr<Facemark> facemark = FacemarkLBF::create();

The typical pipeline for facemark detection is listed as follows:

• (Non-mandatory) Set a user defined face detection using Facemark::setFaceDetector. The facemark algorithms are desgined 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 Facemark::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::Facemark::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);
}

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

fit()

virtual bool cv::face::Facemark::fit ( InputArray  image, InputArray  faces, InputOutputArray  landmarks, void *  config = 0  )

pure virtual

Trains a Facemark algorithm using the given dataset.

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.
landmarks	The detected landmark points for each faces.
config	Algorithm specific for running time parameters.

Example of usage

Mat image = imread("image.jpg");
std::vector<Rect> faces;
std::vector<std::vector<Point2f> > landmarks;
facemark->fit(image, faces, landmarks);

TODO remove "config" from here

getData()

virtual bool cv::face::Facemark::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;

getFaces()

virtual bool cv::face::Facemark::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));
}

loadModel()

virtual void cv::face::Facemark::loadModel ( String  model )

pure virtual

A function to load the trained model before the fitting process.

Parameters

model

A string represent the filename of a trained model.

Example of usage

facemark->loadModel("../data/lbf.model");

read()

virtual void cv::face::Facemark::read ( const FileNode &  fn )

pure virtual

Reads algorithm parameters from a file storage.

Reimplemented from cv::Algorithm.

setFaceDetector()

virtual bool cv::face::Facemark::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 --------
}

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

training()

virtual void cv::face::Facemark::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();

write()

virtual void cv::face::Facemark::write ( FileStorage &  fs ) const

pure virtual

Stores algorithm parameters in a file storage.

Reimplemented from cv::Algorithm.

---

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

• /build/master-contrib_docs-lin64/opencv_contrib/modules/face/include/opencv2/face/facemark.hpp