cv::face::FaceRecognizer クラス

すべての顔認識モデルの抽象基底クラス。 続き...

#include <opencv2/face.hpp>

Collaboration diagram for 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
Public Member Functions inherited from 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

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())
	ファイルからアルゴリズムを読み込む。
template<typename _Tp >
static Ptr< _Tp >	loadFromString (const String &strModel, const String &objname=String())
	文字列からアルゴリズムを読み込む。
template<typename _Tp >
static Ptr< _Tp >	read (const FileNode &fn)
	ファイルノードからアルゴリズムを読み込む。
Protected Member Functions inherited from cv::Algorithm
void	writeFormat (FileStorage &fs) const

詳細説明

すべての顔認識モデルの抽象基底クラス。

OpenCVのすべての顔認識モデルは、抽象基底クラスFaceRecognizerから派生しており、OpenCVのすべての顔認識アルゴリズムへの統一的なアクセスを提供する。

説明

FaceRecognizerについて、もう少し詳しく説明する。一見すると強力なインターフェースには見えないからである。しかし、すべてのFaceRecognizerはAlgorithmであるため、（実装で許可されていれば）モデルの内部状態をすべて簡単に取得・設定できる。Algorithmは2.4リリース以降で利用できる、比較的新しいOpenCVの概念である。その説明にも目を通すことを勧める。

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を用いたFaceRecognizerの学習。
• 与えられたサンプル画像、すなわち顔の予測。画像はMatとして与えられる。
• 与えられたXMLまたはYAMLとの間でのモデル状態の読み込み/保存。
• 文字列として保存されるラベル情報の設定/取得。文字列のラベル情報は、認識した人物の名前を保持するのに便利である。

覚え書き

FaceRecognizerインターフェースをPythonと組み合わせて使う場合は、Python 2を使うこと。create_csvのような一部の基盤スクリプトは、Python 3など他のバージョンでは動作しない。しきい値の設定 +++++++++++++++++++++++

予測にしきい値を適用したい状況に出くわすことがある。顔認識でよくあるシナリオは、ある顔が学習データセットに属するか、それとも未知のものかを判定することである。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();

メンバ関数詳解

empty()

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

pure virtual

これは利便性のために提供されているオーバーロードされたメンバ関数である。上記の関数とは、受け取る引数のみが異なる。

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

pure virtual

しきい値パラメータのアクセサ - デフォルトの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;
// 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);

predict() [3/3]

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

pure virtual

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 )

pure virtual

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 )

pure virtual

モデルのしきい値を設定する。

cv::face::BasicFaceRecognizer と cv::face::LBPHFaceRecognizer で実装されている。

train()

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

pure virtual

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 ではラベルの順序に注意を払う必要はなく、同じ人物が同じラベルを持つようにするだけでよい:

// 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 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 を更新するが、アルゴリズムがそれをサポートしている場合に限る。Local Binary Patterns Histograms (LBPH) 認識器(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!

更新をサポートしない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 は学習用画像を保存しない。保存すると非常にメモリを消費し、それを行うのは 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

pure virtual

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

protected

---

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

• opencv2/face.hpp