cv::face::FaceRecognizer 类参考

所有面部识别模型（face recognition models）的抽象基类。更多...

#include <opencv2/face.hpp>

cv::face::FaceRecognizer 的协作图

公开成员函数
virtual bool	empty () const CV_OVERRIDE=0
virtual String	getLabelInfo (int label) const
	根据标签获取字符串信息。
virtual std::vector< int >	getLabelsByString (const String &str) const
	根据字符串获取标签向量。
virtual double	getThreshold () const =0
	阈值参数访问器 - 默认的 BestMinDist 收集器必需
int	predict (InputArray src) const
void	predict (InputArray src, int &label, double &confidence) const
	为给定的输入图像预测标签和相关的置信度（例如，距离）。
virtual void	predict (InputArray src, Ptr< PredictCollector > collector) const =0
	如果已实现 - 将所有预测结果发送给收集器，可用于某种自定义结果处理。
virtual void	read (const FileNode &fn) CV_OVERRIDE=0
virtual void	read (const String &filename)
	加载一个 FaceRecognizer 及其模型状态。
virtual void	setLabelInfo (int label, const String &strInfo)
	为指定的模型标签设置字符串信息。
virtual void	setThreshold (double val)=0
	设置模型的阈值。
virtual void	train (InputArrayOfArrays src, InputArray labels)=0
	使用给定数据和关联标签训练一个 FaceRecognizer。
virtual void	update (InputArrayOfArrays src, InputArray labels)
	使用给定数据和关联标签更新一个 FaceRecognizer。
virtual void	write (const String &filename) const
	保存一个 FaceRecognizer 及其模型状态。
virtual void	write (FileStorage &fs) const CV_OVERRIDE=0
从 cv::Algorithm 继承的公共成员函数
	Algorithm ()
virtual	~Algorithm ()
virtual void	clear ()
	清除算法状态。
virtual String	getDefaultName () const
virtual void	save (const String &filename) const
void	write (const Ptr< FileStorage > &fs, const String &name=String()) const
void	write (FileStorage &fs, const String &name) const

保护属性
std::map< int, String >	_labelsInfo

更多继承的成员
从 cv::Algorithm 继承的静态公共成员函数
template<typename _Tp >
static Ptr< _Tp >	load (const String &filename, const String &objname=String())
	从文件中加载算法。
template<typename _Tp >
static Ptr< _Tp >	loadFromString (const String &strModel, const String &objname=String())
	从字符串中加载算法。
template<typename _Tp >
static Ptr< _Tp >	read (const FileNode &fn)
	从文件节点中读取算法。
从 cv::Algorithm 继承的保护成员函数
void	writeFormat (FileStorage &fs) const

详细说明

所有面部识别模型（face recognition models）的抽象基类。

OpenCV 中所有面部识别模型都继承自抽象基类 FaceRecognizer，它提供了对 OpenCV 中所有面部识别算法的统一访问。

描述

我将更详细地解释 FaceRecognizer，因为它乍一看似乎不是一个强大的接口。但是：每个 FaceRecognizer 都是一个 Algorithm，因此您可以轻松地获取/设置所有模型内部（如果实现允许）。Algorithm 是一个相对较新的 OpenCV 概念，自 2.4 版本起可用。我建议您看一下它的说明。

Algorithm 为所有派生类提供以下功能：

• 所谓的“虚拟构造函数”。也就是说，每个 Algorithm 派生类在程序启动时注册，您可以通过其名称获取已注册算法的列表并创建特定算法的实例（请参阅 Algorithm::create）。如果您计划添加自己的算法，最好为您的算法添加一个唯一前缀，以将其与其他算法区分开。
• 按名称设置/检索算法参数。如果您使用了 OpenCV highgui 模块中的视频捕获功能，您可能熟悉 cv::cvSetCaptureProperty、ocvcvGetCaptureProperty、VideoCapture::set 和 VideoCapture::get。Algorithm 提供类似的方法，其中您指定参数名称为文本字符串，而不是整数 ID。有关详细信息，请参阅 Algorithm::set 和 Algorithm::get。
• 从/到 XML 或 YAML 文件读取和写入参数。每个 Algorithm 派生类都可以存储其所有参数，然后将其读回。无需每次都重新实现。

此外，每个 FaceRecognizer 都支持

• 训练一个 FaceRecognizer::train 在给定的图像集（您的面部数据库！）上。
• 预测给定的样本图像，即一张面部图像。该图像以 Mat 的形式提供。
• 加载/保存模型状态，从/到给定的 XML 或 YAML 文件。
• 设置/获取标签信息，该信息以字符串形式存储。字符串标签信息对于保留识别人员的姓名很有用。

注意

当将 FaceRecognizer 接口与 Python 结合使用时，请坚持使用 Python 2。一些底层脚本，如 create_csv，在其他版本（如 Python 3）中将无法工作。设置阈值 +++++++++++++++

有时您会遇到需要对预测应用阈值的情况。面部识别中的一个常见场景是判断一张脸是属于训练数据集还是未知的。您可能想知道为什么 FaceRecognizer 中没有公共 API 来设置预测的阈值，但请放心：它是支持的。这只是意味着在一个抽象类中没有通用的方法来为所有可能的 FaceRecognizer 算法提供设置/获取阈值的接口。设置阈值的适当位置是在特定 FaceRecognizer 的构造函数中，并且由于每个 FaceRecognizer 都是一个 Algorithm（见上文），您可以在运行时获取/设置阈值！

以下是创建模型时设置 Eigenfaces 方法阈值的示例：

// 假设我们想保留 10 个 Eigenfaces 并设置阈值为 10.0
int num_components = 10;
double threshold = 10.0;
// 然后，如果您想拥有一个具有置信度阈值的 cv::FaceRecognizer，
// 请使用适当的参数创建具体的实现。
Ptr<FaceRecognizer> model = EigenFaceRecognizer::create(num_components, threshold);

有时无法训练模型，只能尝试阈值。感谢 Algorithm，可以在运行时设置内部模型阈值。让我们看看如何设置/获取上面创建的 Eigenface 模型的预测：

// 下一行从 Eigenfaces 模型读取阈值
double current_threshold = model->getDouble("threshold");
// 这一行将阈值设置为 0.0
model->set("threshold", 0.0);

如果您像上面一样将阈值设置为 0.0，那么

//
Mat img = imread("person1/3.jpg", IMREAD_GRAYSCALE);
// 从模型中获取预测。注意：我们上面设置了阈值为 0.0，
// 由于距离几乎总是大于 0.0，您将收到 -1 作为
// 标签，这表示此面部未知。
int predicted_label = model->predict(img);
// ...

将产生 -1 作为预测标签，表示此面部未知。

获取 FaceRecognizer 的名称

由于每个 FaceRecognizer 都是一个 Algorithm，您可以使用 Algorithm::name 来获取 FaceRecognizer 的名称。

// 创建一个 FaceRecognizer
Ptr<FaceRecognizer> model = EigenFaceRecognizer::create();
// 这里是如何获取它的名称
String name = model->name();

成员函数说明

empty()

virtual bool cv::face::FaceRecognizer::empty ( ) const

纯虚函数

这是一个重载的成员函数，为方便起见而提供。它与上述函数的区别仅在于所接受的参数不同。

从 cv::Algorithm 重新实现。

在 cv::face::BasicFaceRecognizer 中实现。

getLabelInfo()

virtual String cv::face::FaceRecognizer::getLabelInfo ( int label ) const

virtual

Python
	cv.face.FaceRecognizer.getLabelInfo(	label	) ->	retval

根据标签获取字符串信息。

如果提供了未知标签 ID 或没有与指定标签 ID 关联的标签信息，则方法返回一个空字符串。

getLabelsByString()

virtual std::vector< int > cv::face::FaceRecognizer::getLabelsByString ( const String & str ) const

virtual

Python
	cv.face.FaceRecognizer.getLabelsByString(	str	) ->	retval

根据字符串获取标签向量。

该函数在关联的字符串信息中搜索包含指定子字符串的标签。

getThreshold()

virtual double cv::face::FaceRecognizer::getThreshold ( ) const

纯虚函数

阈值参数访问器 - 默认的 BestMinDist 收集器必需

在 cv::face::BasicFaceRecognizer 和 cv::face::LBPHFaceRecognizer 中实现。

predict() [1/3]

int cv::face::FaceRecognizer::predict

(

InputArray

src

)

const

Python
	cv.face.FaceRecognizer.predict(	src	) ->	label, confidence
	cv.face.FaceRecognizer.predict_collect(	src, collector	) ->	None
	cv.face.FaceRecognizer.predict_label(	src	) ->	retval

这是一个重载的成员函数，为方便起见而提供。它与上述函数的区别仅在于所接受的参数不同。

predict() [2/3]

void cv::face::FaceRecognizer::predict	(	InputArray	src,
		int &	label,
		double &	confidence ) const

Python
	cv.face.FaceRecognizer.predict(	src	) ->	label, confidence
	cv.face.FaceRecognizer.predict_collect(	src, collector	) ->	None
	cv.face.FaceRecognizer.predict_label(	src	) ->	retval

为给定的输入图像预测标签和相关的置信度（例如，距离）。

参数

src	用于获取预测的样本图像。
label	给定图像的预测标签。
confidence	预测标签的关联置信度（例如，距离）。

后缀 const 意味着预测不会影响内部模型状态，因此可以安全地从不同线程调用该方法。

以下示例展示了如何从训练好的模型中获取预测：

using namespace cv;
// 在此处执行您的初始化（创建 cv::FaceRecognizer 模型）...
// ...
// 读取样本图像
Mat img = imread("person1/3.jpg", IMREAD_GRAYSCALE);
// 并从 cv::FaceRecognizer 获取预测
int predicted = model->predict(img);

或者获取预测和相关的置信度（例如，距离）：

using namespace cv;
// 在此处执行您的初始化（创建 cv::FaceRecognizer 模型）...
// ...
Mat img = imread("person1/3.jpg", IMREAD_GRAYSCALE);
// 用于预测标签和相关置信度（例如，距离）的变量
int predicted_label = -1;
double predicted_confidence = 0.0;
// 从模型中获取预测和相关置信度
model->predict(img, predicted_label, predicted_confidence);

predict() [3/3]

virtual void cv::face::FaceRecognizer::predict ( InputArray src, Ptr< PredictCollector > collector ) const

纯虚函数

Python
	cv.face.FaceRecognizer.predict(	src	) ->	label, confidence
	cv.face.FaceRecognizer.predict_collect(	src, collector	) ->	None
	cv.face.FaceRecognizer.predict_label(	src	) ->	retval

• 如果已实现 - 将所有预测结果发送给收集器，可用于某种自定义结果处理。

参数

src	用于获取预测的样本图像。
collector	用户定义的收集器对象，可接受所有结果。

要实现此方法，您只需执行与 predict(InputArray src, CV_OUT int &label, CV_OUT double &confidence) 相同的内部循环，但不要尝试获取“最佳”结果，只需将其通过给定的收集器发送回调用方。

read() [1/2]

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

纯虚函数

Python
	cv.face.FaceRecognizer.read(	filename	) ->	None

这是一个重载的成员函数，为方便起见而提供。它与上述函数的区别仅在于所接受的参数不同。

从 cv::Algorithm 中重新实现。

在 cv::face::BasicFaceRecognizer 中实现。

read() [2/2]

virtual void cv::face::FaceRecognizer::read ( const String & filename )

virtual

Python
	cv.face.FaceRecognizer.read(	filename	) ->	None

加载一个 FaceRecognizer 及其模型状态。

从给定的 XML 或 YAML 文件加载持久化的模型和状态。每个 FaceRecognizer 都必须重写 FaceRecognizer::load(FileStorage& fs) 以启用加载模型状态。FaceRecognizer::load(FileStorage& fs) 又被 FaceRecognizer::load(const String& filename) 调用，以方便保存模型。

在 cv::face::BasicFaceRecognizer 中重新实现。

setLabelInfo()

virtual void cv::face::FaceRecognizer::setLabelInfo ( int label, const String & strInfo )

virtual

Python
	cv.face.FaceRecognizer.setLabelInfo(	label, strInfo	) ->	None

为指定的模型标签设置字符串信息。

如果为指定标签之前设置了字符串信息，则该信息将被提供的值替换。

setThreshold()

virtual void cv::face::FaceRecognizer::setThreshold ( double val )

纯虚函数

设置模型的阈值。

在 cv::face::BasicFaceRecognizer 和 cv::face::LBPHFaceRecognizer 中实现。

train()

virtual void cv::face::FaceRecognizer::train ( InputArrayOfArrays src, InputArray labels )

纯虚函数

Python
	cv.face.FaceRecognizer.train(	src, labels	) ->	None

使用给定数据和关联标签训练一个 FaceRecognizer。

参数

src	训练图像，即您想学习的面部。数据必须以 vector<Mat> 的形式提供。
labels	图像的对应标签必须以 vector<int> 或 CV_32SC1 类型的 Mat 的形式提供。

以下源代码片段向您展示了如何在给定图像集上学习 Fisherfaces 模型。图像使用 imread 读取并放入 std::vector<Mat> 中。每个图像的标签存储在 std::vector<int> 中（您也可以使用 CV_32SC1 类型的 Mat）。将标签视为图像所属的主体（人），因此相同主体（人）应具有相同的标签。对于可用的 FaceRecognizer，您无需关注标签的顺序，只需确保相同的人具有相同的标签即可。

// 存储图像和标签
vector<Mat> images;
vector<int> labels;
// 使用 CV_32SC1 类型的 Mat
// Mat labels(number_of_samples, 1, CV_32SC1);
// 第一位人员的图像
images.push_back(imread("person0/0.jpg", IMREAD_GRAYSCALE)); labels.push_back(0);
images.push_back(imread("person0/1.jpg", IMREAD_GRAYSCALE)); labels.push_back(0);
images.push_back(imread("person0/2.jpg", IMREAD_GRAYSCALE)); labels.push_back(0);
// 第二位人员的图像
images.push_back(imread("person1/0.jpg", IMREAD_GRAYSCALE)); labels.push_back(1);
images.push_back(imread("person1/1.jpg", IMREAD_GRAYSCALE)); labels.push_back(1);
images.push_back(imread("person1/2.jpg", IMREAD_GRAYSCALE)); labels.push_back(1);

现在您已经读取了一些图像，我们可以创建一个新的 FaceRecognizer。在这个例子中，我将创建一个 Fisherfaces 模型并决定保留所有可用的 Fisherfaces。

// 创建一个新的 Fisherfaces 模型并保留所有可用的 Fisherfaces，
// 这是这个特定 FaceRecognizer 最常见的用法。
//
Ptr<FaceRecognizer> model = FisherFaceRecognizer::create();

然后用给定的数据集（面部图像和标签）训练它。

// 这是训练所有可用的 cv::FaceRecognizer 的通用接口
// 实现。
//
model->train(images, labels);

update()

virtual void cv::face::FaceRecognizer::update ( InputArrayOfArrays src, InputArray labels )

virtual

Python
	cv.face.FaceRecognizer.update(	src, labels	) ->	None

使用给定数据和关联标签更新一个 FaceRecognizer。

参数

src	训练图像，即您想学习的面部。数据必须以 vector<Mat> 的形式提供。
labels	图像的对应标签必须以 vector<int> 或 CV_32SC1 类型的 Mat 的形式提供。

此方法更新一个（可能已训练的） FaceRecognizer，但前提是该算法支持它。局部二值模式直方图（LBPH）识别器（请参阅 createLBPHFaceRecognizer）可以被更新。对于 Eigenfaces 和 Fisherfaces 方法，这在算法上是不可能的，您必须使用 FaceRecognizer::train 重新估计模型。无论如何，调用 train 会清空现有模型并学习一个新模型，而 update 不会删除任何模型数据。

// 创建一个新的 LBPH 模型（可以更新）并使用默认参数，
// 这是这个特定 FaceRecognizer 最常见的用法。
//
Ptr<FaceRecognizer> model = LBPHFaceRecognizer::create();
// 这是训练所有可用的 cv::FaceRecognizer 的通用接口
// 实现。
//
model->train(images, labels);
// 用于容纳新图像的一些容器
vector<Mat> newImages;
vector<int> newLabels;
// 您应该向容器中添加一些图像
//
// ...
//
// 现在更新模型就像调用一样简单
model->update(newImages,newLabels);
// 这将保留旧模型数据，并用从 newImages 中提取的新特征扩展现有模型！
// 带有新提取特征的现有模型。

对不支持更新的 Eigenfaces 模型（请参阅 EigenFaceRecognizer::create）调用 update 将引发类似以下的错误：

OpenCV Error: 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
terminate called after throwing an instance of 'cv::Exception'

注意

FaceRecognizer 不存储您的训练图像，因为这将占用大量内存，而且这也不是 FaceRecognizer 的职责。调用者负责维护他想要使用的那个数据集。

write() [1/2]

virtual void cv::face::FaceRecognizer::write ( const String & filename ) const

virtual

Python
	cv.face.FaceRecognizer.write(	filename	) ->	None

保存一个 FaceRecognizer 及其模型状态。

将此模型保存到给定的文件名，可以是 XML 或 YAML 格式。

参数

filename

要将此 FaceRecognizer 保存到的文件名（XML/YAML）。

每个 FaceRecognizer 都重写 FaceRecognizer::save(FileStorage& fs) 来保存内部模型状态。FaceRecognizer::save(const String& filename) 将模型的状态保存到给定的文件名。

后缀 const 意味着预测不会影响内部模型状态，因此可以安全地从不同线程调用该方法。

在 cv::face::BasicFaceRecognizer 中重新实现。

write() [2/2]

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

纯虚函数

Python
	cv.face.FaceRecognizer.write(	filename	) ->	None

这是一个重载成员函数，为了方便起见提供。它仅在接受的参数方面与上面的函数不同。将此模型保存到给定的 FileStorage。

参数

fs	要将此 FaceRecognizer 保存到的 FileStorage。

从 cv::Algorithm 中重新实现。

在 cv::face::BasicFaceRecognizer 中实现。

成员数据文档

_labelsInfo

std::map<int, String> cv::face::FaceRecognizer::_labelsInfo

保护

---

该类的文档由以下文件生成：

• opencv2/face.hpp