cv::face::FaceRecognizer クラス

Abstract base class for all face recognition models [詳解]

#include <face.hpp>

cv::Algorithmを継承しています。

cv::face::BasicFaceRecognizer, cv::face::LBPHFaceRecognizerに継承されています。

公開メンバ関数
virtual CV_WRAP void	train (InputArrayOfArrays src, InputArray labels)=0
	モデルを学習します。FaceRecognizerを、与えられたデータと関連付けられたラベルで訓練します。[【詳解】（英語］
virtual CV_WRAP void	update (InputArrayOfArrays src, InputArray labels)
	aを更新します。FaceRecognizerを、与えられたデータと関連付けられたラベルで訓練します。[【詳解】（英語］
	CV_WRAP_AS (predict_label) int predict(InputArray src) const
CV_WRAP void	predict (InputArray src, CV_OUT int &label, CV_OUT double &confidence) const
	与えられた入力画像に対して、ラベルとそれに関連する信頼度（例：距離）を予測します。[【詳解】（英語］
	CV_WRAP_AS (predict_collect) virtual void predict(InputArray src
	実装されている場合 - 予測結果をすべてコレクターに送り、カスタム結果処理に利用できます。 [【詳解】（英語］
virtual CV_WRAP void	write (const String &filename) const
	モデルを保存するFaceRecognizerとそのモデルの状態を読み込みます．[【詳解】（英語］
virtual CV_WRAP void	read (const String &filename)
	をロードします．FaceRecognizerとそのモデルの状態を読み込みます．[【詳解】（英語］
virtual void	write (FileStorage &fs) const CV_OVERRIDE=0
virtual void	read (const FileNode &fn) CV_OVERRIDE=0
virtual bool	empty () const CV_OVERRIDE=0
virtual CV_WRAP void	setLabelInfo (int label, const String &strInfo)
	指定されたモデルのラベルの文字列情報を設定します。[【詳解】（英語］
virtual CV_WRAP String	getLabelInfo (int label) const
	ラベルの文字列情報を取得します。[【詳解】（英語］
virtual CV_WRAP std::vector< int >	getLabelsByString (const String &str) const
	文字列によるラベルのベクトルを取得します。[【詳解】（英語］
virtual double	getThreshold () const =0
	threshold パラメータアクセッサ - デフォルトの BestMinDist コレクターに必要です。[【詳解】（英語］
virtual void	setThreshold (double val)=0
	モデルの閾値設定[【詳解】（英語］
基底クラス cv::Algorithm に属する継承公開メンバ関数
virtual CV_WRAP void	clear ()
	アルゴリズムの状態をクリアする[【詳解】（英語］
CV_WRAP void	write (const Ptr< FileStorage > &fs, const String &name=String()) const
	これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。
virtual CV_WRAP void	save (const String &filename) const
virtual CV_WRAP String	getDefaultName () const

公開変数類
Ptr< PredictCollector > collector	const = 0

限定公開変数類
std::map< int, String >	_labelsInfo

その他の継承メンバ
基底クラス cv::Algorithm に属する継承静的公開メンバ関数
template<typename _Tp >
static Ptr< _Tp >	read (const FileNode &fn)
	ファイル・ノードからアルゴリズムを読み込む[【詳解】（英語］
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())
	文字列からアルゴリズムを読み込む[【詳解】（英語］
基底クラス cv::Algorithm に属する継承限定公開メンバ関数
void	writeFormat (FileStorage &fs) const

詳解

すべての顔認識モデルのための抽象ベースクラス

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を用いたFaceRecognizer::train与えられた画像セット（あなたの顔データベース！）に対する
• 予測与えられたサンプル画像（つまり顔）の予測。画像は次のように与えられます。Mat.
• 読み込み/保存モデルの状態を、与えられたXMLやYAMLとの間でやり取りします。
• ラベル情報の設定／取得ラベル情報は、文字列として保存されます。文字列のラベル情報は、認識した人の名前を保持するのに便利です。

覚え書き

このインターフェースをPythonと組み合わせて使用する場合はFaceRecognizerインターフェースをPythonと組み合わせて使用する場合は、Python 2を使用してください。create_csv のような基本的なスクリプトは、Python 3 のような他のバージョンでは動作しません。しきい値の設定 +++++++++++++++++++++++

予測値にしきい値を適用したい状況に遭遇することがあります。顔認識でよくあるのは、ある顔が学習データセットに含まれているのか、それとも未知の顔なのかを判断することです。予測の閾値を設定するためのパブリックAPIが、なぜFaceRecognizerには、予測に閾値を設定するためのパブリックAPIがないのかと思うかもしれませんが、安心してください。それはサポートされています。これは、抽象クラスの中に、あらゆる可能性の閾値を設定/取得するためのインターフェースを提供する汎用的な方法がないということです。すべての可能な FaceRecognizerアルゴリズム。しきい値を設定する適切な場所は、特定のFaceRecognizerそして、すべてのFaceRecognizerはAlgorithm(であるため（上記参照）、実行時にしきい値を取得・設定することができます。

ここでは、モデル作成時にEigenfacesメソッドに閾値を設定する例を示します。

// 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);

しきい値を試すために、モデルをトレーニングすることができない場合もあります。のおかげでAlgorithmのおかげで、ランタイム中にモデル内部のしきい値を設定することができます。上記で作成したEigenfaceモデルの予測値をどのように設定/取得するかを見てみましょう。

// 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);

上記のようにしきい値を0.0に設定した場合、:

//

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);

// ...

とすると、予測されるラベルは-1となり、この顔は未知であるということになります。

FaceRecognizerの名前の取得

では、すべてのFaceRecognizerはAlgorithmの名前を取得するにはAlgorithm::nameを使います。FaceRecognizer:

// Create a FaceRecognizer:

Ptr<FaceRecognizer> model =
EigenFaceRecognizer::create();

// And here's how to get its name:

String name = model->name();

関数詳解

CV_WRAP_AS() [1/2]

cv::face::FaceRecognizer::CV_WRAP_AS

(

predict_collect

)

• 実装されている場合 - 予測結果をすべてコレクターに送り、カスタム結果処理に利用できます。

引数

src	予測値を得るためのサンプル画像。
collector	すべての結果を受け入れるユーザー定義のコレクターオブジェクト

このメソッドを実装するためには， predict(InputArray src, CV_OUT int &label, CV_OUT double &confidence) と同じ内部サイクルを行う必要がありますが，「最良の結果」を得ようとはせず，与えられたコレクターを用いて呼び出し側に再送します．

CV_WRAP_AS() [2/2]

cv::face::FaceRecognizer::CV_WRAP_AS

(

predict_label

)

const

これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。

empty()

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

pure virtual

これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。

cv::Algorithmを再実装します。

cv::face::BasicFaceRecognizerで実装されています．

getLabelInfo()

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

virtual

ラベルの文字列情報を取得します。

未知のラベルIDが指定された場合や，指定されたラベルIDに関連するラベル情報がない場合，このメソッドは空の文字列を返します．

getLabelsByString()

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

virtual

文字列によるラベルのベクトルを取得します。

この関数は、関連付けられた文字列情報の中で、指定されたサブストリングを含むラベルを検索します。

getThreshold()

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

pure virtual

threshold パラメータアクセッサ - デフォルトの BestMinDist コレクターに必要です。

cv::face::BasicFaceRecognizer,cv::face::LBPHFaceRecognizerで実装されています．

predict()

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

与えられた入力画像に対して、ラベルとそれに関連する信頼度（例：距離）を予測します。

引数

src	予測値を得るためのサンプル画像。
label	与えられた画像に対する，予測されたラベルです．
confidence	予測されたラベルに関連付けられた信頼度（例：距離）。

constという接尾辞は、予測がモデルの内部状態に影響を与えないことを意味していますので、このメソッドは異なるスレッド内から安全に呼び出すことができます。

以下の例では、学習済みモデルから予測値を取得する方法を示しています。

using namespace

cv;

// Do your initialization here (create the cv::FaceRecognizer model) ...


// ...


// Read in a sample image:

Mat img =
imread("person1/3.jpg",
IMREAD_GRAYSCALE);

// And get a prediction from the cv::FaceRecognizer:


int
predicted = model->predict(img);

または、予測値と関連する信頼度（距離など）を取得する。

using namespace

cv;

// Do your initialization here (create the cv::FaceRecognizer model) ...


// ...

Mat img =
imread("person1/3.jpg",
IMREAD_GRAYSCALE);

// Some variables for the predicted label and associated confidence (e.g. distance):


int
predicted_label = -1;

double
predicted_confidence = 0.0;

// Get the prediction and associated confidence from the model

model->predict(img, predicted_label, predicted_confidence);

read() [1/2]

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

pure virtual

これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。

cv::Algorithmを再実装します。

cv::face::BasicFaceRecognizer,cv::face::BasicFaceRecognizerで実装されています．

read() [2/2]

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

virtual

をロードします．FaceRecognizerとそのモデルの状態を読み込みます．

与えられたXMLまたはYAMLファイルから，永続化されたモデルとその状態を読み込みます．すべてのFaceRecognizerはモデルの状態を読み込むために FaceRecognizer::load(FileStorage& fs) を上書きする必要があります。FaceRecognizer::load(FileStorage& fs) は、モデルの保存を容易にするために FaceRecognizer::load(const String& filename) によって呼び出されます。

cv::face::BasicFaceRecognizer出再実装されます。

setLabelInfo()

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

virtual

指定されたモデルのラベルの文字列情報を設定します。

文字列 info は、指定されたラベルに対して以前に設定されていた場合は、指定された値に置き換えられます。

setThreshold()

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

pure virtual

モデルの閾値設定

cv::face::BasicFaceRecognizer,cv::face::LBPHFaceRecognizerで実装されています．

train()

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

pure virtual

モデルを学習します。FaceRecognizerを、与えられたデータと関連付けられたラベルで訓練します。

引数

src	学習画像、つまり学習したい顔のデータ。データはvector<br>として与えられなければなりません。Mat>.
labels	画像に対応するラベルは，vector<int> またはCV_32SC1型のMatCV_32SC1 型の

次のソースコードは，与えられた画像の集合に対して，Fisherfaces モデルを学習する方法を示しています．画像は imread によって読み込まれ，std::vector<Mat>. 各画像のラベルは，std::vector<int>（CV_32SC1 型のMatCV_32SC1型の）．ラベルとは，その画像が属する被写体（人）のことであり，同じ被写体（人）は同じラベルを持つべきです．利用できるものFaceRecognizerについては，ラベルの順番を気にする必要はなく，同じ人が同じラベルを持つようにすればよい．

// holds images and labels

vector<Mat> images;
vector<int> labels;

// using Mat of type CV_32SC1


// Mat labels(number_of_samples, 1, CV_32SC1);


// images for first person

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 for second person

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を保持することにします。

// Create a new Fisherfaces model and retain all available Fisherfaces,


// this is the most common usage of this specific FaceRecognizer:


//

Ptr<FaceRecognizer> model =
FisherFaceRecognizer::create();

そして最後に，与えられたデータセット（顔画像とラベル）で訓練します．

// This is the common interface to train all of the available cv::FaceRecognizer


// implementations:


//

model->train(images, labels);

update()

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

virtual

aを更新します。FaceRecognizerを、与えられたデータと関連付けられたラベルで訓練します。

引数

src	学習画像、つまり学習したい顔のデータ。データはvector<br>として与えられなければなりません。Mat>.
labels	画像に対応するラベルは，vector<int> またはCV_32SC1型のMatCV_32SC1 型の

この方法は，（おそらく訓練された）モデルを更新します．FaceRecognizerを更新するが，アルゴリズムがそれをサポートしている場合に限る．LBPH（Local Binary Patterns Histograms）認識器（createLBPHFaceRecognizer参照）を更新することができます。EigenfacesやFisherfaces法では，アルゴリズム的に不可能で，次の方法でモデルを再推定する必要があります．FaceRecognizer::train. いずれにせよ、train の呼び出しは既存のモデルを空にして新しいモデルを学習しますが、update はモデルデータを削除しません。

// Create a new LBPH model (it can be updated) and use the default parameters,


// this is the most common usage of this specific FaceRecognizer:


//

Ptr<FaceRecognizer> model =
LBPHFaceRecognizer::create();

// This is the common interface to train all of the available cv::FaceRecognizer


// implementations:


//

model->train(images, labels);

// Some containers to hold new image:

vector<Mat> newImages;
vector<int> newLabels;

// You should add some images to the containers:


//


// ...


//


// Now updating the model is as easy as calling:

model->update(newImages,newLabels);

// This will preserve the old model data and extend the existing model


// with the new features extracted from newImages!

updateの呼び出しは、Eigenfacesモデル（参照EigenFaceRecognizer::create)でupdateを呼び出すと、以下のようなエラーが発生します。

OpenCV Error: The
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は学習画像を保存しません。なぜなら、これは非常に大きなメモリを必要とするからであり、それはteFaceRecognizerの責任ではないからです。呼び出し側は，自分が扱いたいデータセットを管理する責任があります．

write() [1/2]

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

virtual

モデルを保存する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

pure virtual

これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。 このモデルを、与えられたFileStorage.

引数

fs	のクラスはスレッドセーフではありません。FileStorageにこのモデルを保存します。FaceRecognizerに保存します。

cv::Algorithmを再実装します。

cv::face::BasicFaceRecognizer,cv::face::BasicFaceRecognizerで実装されています．

---

このクラス詳解は次のファイルから抽出されました:

• face.hpp