next up previous contents
次へ: パラメータサブライブラリ 上へ: MACAOライブラリ 戻る: MACAOライブラリ   目次

Subsections

MACAOライブラリ(本体)

本節では、MACAOライブラリの本体部分を構成するへッダファイルおよびソース ファイルについての解説を行なう。ただし個々のパラメータクラスの親クラスに 相当するMacaoParamおよび同じく教師クラスの親クラスに相当するMacaoTeacher クラスの説明を含む。これらは抽象クラスとして定義され、個別の実装は 実際にはサブライブラリに含まれる各クラスが提供する。

共通ヘッダファイル

概要

まずMACAOライブラリに備えられている共通のヘッダファイルについて説明する。

MACAOライブラリでは、ユーザの利便性とMACAOライブラリの機能の調整を目的と して、共通のヘッダファイル macao.h および macao-common.h が用意されてい る。これらは基本的には自動で生成されるものであるので、MACAOライブラリ そのものの開発に関して、通常の開発者が意識する必要はないものである。

macao.h

本ライブラリの利用者の便宜を図るために、本ライブラリが提供する データ型定義や関数プロトタイプ宣言を含む全てのヘッダファイルをまとめて インクルードするためのヘッダファイルである。

なお本ヘッダファイルは、Perl スクリプト mk_macao_h.pl により自動的に 生成されるため、ライブラリ開発者が手動で修正を加える必要はない。

macao_common.h

MACAOライブラリで共通に利用されるヘッダファイルである。

macao_common.h は configure スクリプトによって macao_common-h.in から 自動的に生成される。通常、autotools によって調整されるプログラムは、 config-h.in から生成される config.h ヘッダファイルに機能の有無を示す マクロ定義が記載される。しかし、本ソースファイルはライブラリを提供するも のであるため、config.h は利用できない。何故ならば、config.h の利用を 想定した場合、本来は本ライブラリを利用するプログラムにおいて使用すべき config.h との衝突が生じるからである。

本ライブラリからインクルードすべき config.h と、本ライブラリを利用する プログラムからインクルードすべき config.h が一致することはまずあり得ない ため、本ライブラリでは config.h のインクルードを仮定すべきではない。 そこで、本ライブラリでは config.h の代用として macao_common.h に 調整用マクロ定義の記述を生成する。

その他、共通項目はあらかじめ macao_common-h.in に記載しておくことにより macao_common.h に含めることができる。例えば本ライブラリでは C++ ソフト ウェアからの利用を可能にするためのヘッダファイルにおけるマクロ BEGIN_C_DECLS および END_C_DECLS の定義を、macao_common-h.in に 用意しておくことで共通の利用を図っている。

MacaoGaborRg

概要

白黒濃淡画像にガボールウェーブレットフィルタを適用し、JETによる 顔グラフのグラフマッチングを利用して顔領域を抽出するクラスである。 MacaoTrackを継承する。

顔領域のトラッキングは以下の手順で行なう。

  1. QVGAサイズの濃淡画像として入力される原画像を、1/4の大きさに縮小する。
  2. 縮小した画像に対し、0度、90度、180度、270度の方向を持つ ガボールウェーブレットフィルタを適用する。
  3. フィルタを適用した各画像をさらに1/5の大きさに縮小する。
  4. 縮小した4個の画像を対象に、別途用意されるテンプレートを適用、 テンプレートの各ノードの積和が最大となる位置を判定し、 顔領域の大まかな位置と判定する。

ヘッダファイル

ヘッダファイル gaborrg.h では、MacaoGaborRg に関するマクロ定義、 列挙型、構造体の定義、それらに関する型定義、およびソースファイル gaborrg.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

マクロ定義

本ファイルで定義されるマクロ定義の詳細を以下に示す。
MACAO_GABORRG_NAME
本クラスの名前を表す文字列である。
MACAO_GABORRG_BLOCK
フィルタ適用後に平均化するブロック のサイズを表す。
MACAO_GABORRG_DEFAULT_FREQ
ガボールウェーブレットの周波数を表す。
MACAO_GABORRG_C
ガボールウェーブレット適用式の係数を表す。
MACAO_GABORRG_DEFAULT_NODEFILE
ノードファイルのファイル名を表す。
MACAO_GABORRG_LABEL_NODEFILE
データファイルパラメータ のラベルを示す文字列である。
MACAO_GABORRG_WARN_OPEN_DATAFILE_FAILURE
データファ イルをオープンできない場合のエラーメッセージ文字列である。
MACAO_GABORRG_WARN_SAVE_DATAFILE_FAILURE
データファ イルが書き込み不能の場合のエラーメッセージ文字列である。
MACAO_GABORRG_WARN_READ_DATAFILE_FAILURE
データファ イルを読み取り不能の場合のエラーメッセージ文字列である。
MACAO_GABORRG_XML_TAG_GABORRG
XMLデータ中の``GaborRg''タグである。
MACAO_GABORRG_XML_TAG_TEMPLATES
XMLデータ中の``Templates''タグである。
MACAO_GABORRG_XML_TAG_TEMPLATE
XMLデータ中の``Template''タグである。
MACAO_GABORRG_XML_TAG_CELLS
XMLデータ中の``Cells''タグである。
MACAO_GABORRG_XML_TAG_CELL
XMLデータ中の``Cell''タグである。
MACAO_GABORRG_XML_DTD_URL
DTDを示すURLを表す文字列である。
MACAO_GABORRG_XML_EMPTY_ERR_MSG
XMLデータが空である ことを示すエラーメッセージ文字列である。
MACAO_GABORRG_XML_TAG_GABORRG_ERR_MSG
XMLデータの ``GaborRg''タグ処理に問題が生じたことを示すエラーメッセージ文字列である。
MACAO_GABORRG_XML_TAG_CELL_PROP_DIR_ERR_MSG
XMLデータの ``Cell''タグ処理において、ウェーブレットの向きを示す文字列に規格外のものが 存在したことを示すエラーメッセージ文字列である。

列挙型

本ファイルで定義される列挙型の詳細を以下に示す。
MacaoGaborSize
ガボールウェーブレットの大きさの種別を表す。 大きさの実体は、gaborrg.c の静的配列に格納されている(単位はピクセル)。 本列挙型は、その配列のインデクスを与えるものである。
MACAO_GABOR_SMALL
ガボールウェーブレット(小)を示す。
MACAO_GABOR_BIG
ガボールウェーブレット(大)を示す。
MACAO_GABOR_SIZE_NUM
MacaoGaborSize の要素数を表す。

MacaoGaborDirId
ガボールウェーブレットの向きの種別を表す。 向きを示す数値の実体は、gaborrg.c の静的配列に格納されている(単位は「度」)。 本列挙型は、その配列のインデクスを与えるものである。
MACAO_GABOR_DIR_0
0度の方向のガボールウェーブレットを示す。
MACAO_GABOR_DIR_90
90度の方向のガボールウェーブレットを示す。
MACAO_GABOR_DIR_180
180度の方向のガボールウェーブレットを示す。
MACAO_GABOR_DIR_270
270度の方向のガボールウェーブレットを示す。
MACAO_GABOR_DIR_NUM
MacaoGaborDirId の要素数を表す。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoGaborRgXmlCell
MacaoGaborRgXmlCell から MacaoGaborRgXmlGaborRg までの構造体は、XMLデータとして表記された テンプレートノードのデータを libxml2 APIを利用してパーズする際に XMLノードをトラバースした結果を格納するために用いられる。 MacaoGaborRgXmlCell はノードのトラバースに従いリンクリストを構成する。
int x, y
ノードの$(x, y)$座標を格納する。単位はピクセル。
MacaoGaborDirId dir
ガボールウェーブレットの方向を格納する。
MacaoGaborRgXmlCell* next
次のデータへのポインタである。 リンクリストの最後尾においてはNULLとなる。
MacaoGaborRgXmlTemplate
ひとつのテンプレートに関する 情報を格納するXMLノード用構造体である。本構造体も MacaoGaborRgXmlCell と 同様、リンクリストを構成する。
int width
テンプレートの幅を示す。単位はピクセルである。
int height
テンプレートの高さを示す。単位はピクセルである。
int num_cells
テンプレートに含まれる MacaoGaborRgXmlCell の数 を格納する。
MacaoGaborRgXmlCell* cell
複数の MacaoGaborRgXmlCell による リンクリストの先頭へのポインタである。
MacaoGaborRgXmlTemplate* next
次のデータへのポインタである。 リンクリストの最後尾においてはNULLとなる。
MacaoGaborRgXmlGaborRg
XMLデータのルートノードに相当する 構造体である。
int num_templates
テンプレートの数を格納する。
MacaoGaborRgXmlTemplate* template
複数の MacaoGaborRgXmlTemplate による リンクリストの先頭へのポインタである。
MacaoGaborPatch
ひとつのガボールウェーブレットを表現する ためのデータを格納する構造体である。
int radius
ガボールウェーブレットの半径を表す。実際には、 一辺が radius * 2 + 1 ピクセルの長さを持つ正方形データとして表現される。
MacaoGaborDirId dir
ガボールウェーブレットの向きを表す。
double* data
ガボールウェーブレットの形状を表すデータ領域へのポ インタである。ウェーブレットデータは初期化時にあらかじめ計 算され、ガボールウェーブレットの正方形パッチにおける各座標 の値がこのポインタが差すメモリ領域にあらかじめ記録される。 フィルタ計算時には本メモリデータと画像データの畳み込み演算 が行なわれる。
MacaoGaborRgNode
顔グラフにおけるガボールウェーブレットノード を表現する構造体である。ただし現在のところ未使用となっている。
int x, y
顔グラフにおけるガボールウェーブレットノードの座標を格 納する。
MacaoGaborDirId dir
そのノードにおける、ガボールウェーブレット の方向を格納する。
MacaoGaborRgClass
ガボールウェーブレットフィルタによる顔 領域抽出を行なうクラスのバーチャル関数テーブルである。 MacaoGaborRgはMacaoTrackを継承する。 本クラスで新たに追加されるバーチャル関数は存在しない。
MacaoTrackClass super
親クラスの内容を継承する。
MacaoGaborRg
ガボールウェーブレットフィルタによる顔 領域抽出を行なうクラスの本体を定義する構造体である。
MacaoTrack super
親クラスの内容を継承する。
int template_width
テンプレートの幅(単位ピクセル)を記録する。
int template_height
テンプレートの高さ(単位ピクセル)を記録する。
int num_nodes
ガボールウェーブレットノードの数を表す(未使用)。
MacaoGaborRgNode* nodes
ガボールウェーブレットノード配列へのポ インタを記録する(未使用)。
unsigned char* nodefile
ノードテンプレートの定義を行なっている XMLファイルのファイル名を表す。
MacaoGaborPatch* patches
ガボールウェーブレットのパッチデータを 表す配列へのポインタを格納する。

ソースファイル

MacaoGaborRgの各機能を実現する関数群は、ソースファイルgaborrg.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_gaborrg_new ()
引数
なし。
返値
生成されたMacaoGaborRgオブジェクトへのポインタを返す。
概要
MacaoGaborRgのコンストラクタである。 この時点で必要なメモリが確保され、ガボールウェーブレットの データ生成が行なわれる。

macao_gaborrg_new_with_buf (MalibBuffer* buf)
引数
本関数は以下の引数をとる。
MalibBuffer* buf
入力となるバッファへのポインタ。
返値
生成されたMacaoGaborRgオブジェクトへのポインタを返す。
概要
バッファを指定して生成するMacaoGaborRgのコンストラクタであ る。MacaoGaborRgオブジェクト生成の内容はmacao_gaborrg_new に準じる。

macao_gaborrg_create_params (MacaoGaborRg* gabor)
引数
本関数は以下の引数をとる。
MacaoGaborRg* gabor
パラメータを生成する対象のMacaoGaborRgオブジェ クトへのポインタ。
返値
生成されたパラメータへのポインタを含む配列の、先頭ポインタを返す。
概要
本クラスで利用するパラメータの配列を生成し、 各パラメータの実体の生成と関連するメンバ変数の初期化を行なう。

macao_gaborrg_load_nodes (MacaoPfile* pfile, MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoPfile* pfile
データファイルの情報を格納するファイルパラ メータへのポインタ。
MacaoTrack* track
読み込み先のMacaoTrackオブジェクト(実体は MacaoGaborRg)へのポインタ。
返値
処理に成功すればTRUE、問題が生じた場合にはFALSEを返す。
概要
データファイルにXML形式で記載されたテンプレート情報を読み 込み、メモリ上にデータを設定する。ファイルからの読み込みは macao_gaborrg_xml_parse_file で行ない、本関数では その下準備、エラーチェックおよび入力されたデータに基づいた メモリ上のオブジェクトの設定を行なう。

macao_gaborrg_update (MacaoTrack* track, MacaoParam* param)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクト(実体はMacaoGaborRg) へのポインタ。
MacaoParam* param
アップデート対象のパラメータオブジェクトへ のポインタ。
返値
なし。
概要
パラメータのアップデート情報に基づき、処理に利用する変数の 値を更新する。

macao_gaborrg_delete (MacaoGaborRg* gabor)
引数
本関数は以下の引数をとる。
MacaoGaborRg* gabor
対象とするMacaoGaborRgオブジェクトへのポインタ。
返値
なし。
概要
MacaoGaborRgオブジェクトを消去する。メモリ上の領域を 解放するとともに、関連するデータの格納用として確保してある メモリ領域があれば、全て解放する。

macao_gaborrg_write_frame_data (MacaoGaborRg* gabor, MalibFrame* frame)
引数
本関数は以下の引数をとる。
MacaoGaborRg* gabor
対象とするMacaoGaborRgオブジェクトへのポインタ。
MalibFrame* frame
書き込み対象の出力画像フレームへのポインタ。
返値
なし。
概要
逐次実行される画像処理の中心となる関数である。 本関数は、MalibSourceに用意されているバーチャル関数 malib_source_write_frame_dataの実体を定義するものである。 顔領域の抽出は次の手順で行なわれる。
  1. 入力画像を1/4の大きさに縮小する。
  2. その画像を対象として、0度、90度、180度、270度のガボー ルウェーブレットフィルタを適用する。
  3. フィルタ適用後の画像をさらに1/5に縮小する。
  4. 縮小した画像に対して、テンプレートとの相関を計算する。
  5. 相関値が最も高い位置を顔画像位置とする。

macao_gaborrg_apply_patch (int* qbuf, MacaoGaborPatch* patch, int x, int y, int width, int height)
引数
本関数は以下の引数をとる。
int* qbuf
1/4に縮小された入力画像データを格納する配 列の先頭ポインタ。
MacaoGaborPatch* patch
適用するガボールウェーブレットを表す構 造体へのポインタ。
int x
1/4入力画像データ中における、ガボールウェーブレット適用 位置の$x$座標。
int y
1/4入力画像データ中における、ガボールウェーブレット適用 位置の$y$座標。
int width
1/4に縮小された入力画像データの幅。
int height
1/4に縮小された入力画像データの高さ。
返値
入力画像に対してガボールウェーブレットを畳み込み演算した結 果の値を返す。
概要
1/4サイズに縮小された入力画像に対して、指定する位置に対す るガボールウェーブレットの畳み込み演算を適用する。

macao_gaborrg_create_gabor_patches (MacaoGaborRg* gabor)
引数
本関数は以下の引数をとる。
MacaoGaborRg* gabor
対象とするMacaoGaborRgオブジェクトへのポインタ。
返値
なし。
概要
ガボールウェーブレットのデータを格納するメモリ領域を確保し、 各種の大きさ、方向を持つガボールウェーブレットを作成する。 個々のガボールウェーブレットの作成は、 macao_gaborrg_create_patch 関数で行なう。

macao_gaborrg_create_patch (MacaoGaborPatch* patch)
引数
本関数は以下の引数をとる。
MacaoGaborPatch* patch
作成するガボールウェーブレットデータを 格納するためのMacaoGaborPatch構造体へのポインタ。
返値
なし。
概要
引数で与えるMacaoGaborPatch構造体で指定されるガボールウェー ブレットを作成し、確保されているメモリ領域にデータを格納する。

macao_gaborrg_xml_parse_file (unsigned char* filename)
引数
本関数は以下の引数をとる。
unsigned char* filename
テンプレートのデータを格納した データファイルのファイル名を指定する。
返値
XMLデータをパーズした結果として構築されるMacaoGaborRgXmlGaborRg オブジェクトへのポインタを返す。不適切なデータが与えられたな ど処理に問題が生じた場合は、NULLを返す。
概要
引数で与えるデータファイルをオープンし、XMLデータをパーズ する。ファイルのオープン、XMLノードデータの構築はlibxml2で 用意されているAPIに従う。構築されたXMLノードツリーは、 以下のmacao_gaborrg_xml_parse_gaborrg 関数により 探索され、結果としてMacaoGaborRgXmlGaborRgをルートノードと するツリー構造のデータを作成する。

macao_gaborrg_xml_parse_gaborrg (xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr node)
引数
本関数は以下の引数をとる。
xmlDocPtr doc
libxml2で用意されるXML文書を表すデータへのポインタ。
xmlNsPtr ns
libxml2で用意されるXMLネームスペースを表すデータへのポインタ。
xmlNodePtr node
libxml2で用意されるXMLノードを表すデータへのポインタ。
返値
XML文書をパーズした結果として生成されるツリー構造の ルートノードであるMacaoGaborRgXmlGaborRgオブジェクトへのポ インタを返す。エラーが生じた場合はNULLを返す。
概要
XML文書をパーズして、XMLとして表現されているデータのツリー 構造を作成する。Templateタグに相当する部分以下のXML構造に関 しては、次のmacao_gaborrg_xml_parse_template 関数が担当 する。

macao_gaborrg_xml_parse_template (xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr node)
引数
本関数は以下の引数をとる。
xmlDocPtr doc
libxml2で用意されるXML文書を表すデータへのポインタ。
xmlNsPtr ns
libxml2で用意されるXMLネームスペースを表すデータへのポインタ。
xmlNodePtr node
libxml2で用意されるXMLノードを表すデータへのポインタ。
返値
XML文書をパーズした結果として生成されるツリー構造のうち、 部分木のルートとなるMacaoGaborRgXmlTemplateオブジェクトへのポ インタを返す。エラーが生じた場合はNULLを返す。
概要
XML文書をパーズして、XMLとして表現されているデータのツリー 構造を作成する。Cellタグに相当する部分以下のXML構造に関 しては、次のmacao_gaborrg_xml_parse_cell 関数が担当 する。

macao_gaborrg_xml_parse_cell (xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr node)
引数
本関数は以下の引数をとる。
xmlDocPtr doc
libxml2で用意されるXML文書を表すデータへのポインタ。
xmlNsPtr ns
libxml2で用意されるXMLネームスペースを表すデータへのポインタ。
xmlNodePtr node
libxml2で用意されるXMLノードを表すデータへのポインタ。
返値
XML文書をパーズした結果として生成されるツリー構造のうち、 リーフノードとなるMacaoGaborRgXmlCellオブジェクトへのポ インタを返す。エラーが生じた場合はNULLを返す。
概要
XML文書をパーズして、XMLとして表現されているデータのツリー 構造を作成する。本関数は、リーフノードであるCellタグに 相当する箇所の属性値の設定を行なう。

MacaoLook

概要

テンプレートマッチを利用した顔認識(視線方向認識)用クラスである。 MacaoRecogを継承する(関連クラス → MacaoLookTeacher、MacaoLookHandler)。

白黒濃淡画像を入力とし、別途行なわれる顔領域抽出クラスの出力である 顔領域を含む閉包長方形の範囲で入力画像を正規化する。

オンライン学習時には、その正規化データに対して 教師信号として、GUIインタフェースから座標値がひとつ入力される。 学習データとしては、閉包長方形の中心座標値と教師座標値の差分座標値と 正規化顔データが組として格納される。

認識モードでは、入力された画像データから顔領域の閉包長方形を切り出した後 の正規化画像を逐次作成し、あらかじめ学習済の各データとの相関値を計算する。 相関値がパラメータとして与えられる閾値より高いもののうち、最大の相関を 示すものを認識結果として、その時点での顔領域の中心座標値と学習済差分座標 値から求まった座標値を出力として、出力画像上に印をプロットする。

ヘッダファイル

ヘッダファイル look.h では、MacaoLook に関するマクロ定義、 構造体の定義、それらに関する型定義、およびソースファイル look.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

マクロ定義

本ファイルで定義されるマクロ定義の詳細を以下に示す。
MACAO_LOOK_NAME
本クラスの名前を表す文字列である。
MACAO_LOOK_ASPECT_RATIO
テンプレートの縦横比を表す。縦/横の値である。
MACAO_LOOK_NORMALIZED_DATA_SIZE
正規化するデータサイズ。 テンプレートの横のピクセル数を示す。
MACAO_LOOK_MAX_SAMPLE_SIZE
学習する最大サンプル数 を示す。これ以上の学習操作を行なった場合は、最初に記録したサンプルから破 棄される。
MACAO_LOOK_DEFAULT_THRESHOLD
テンプレートと比較する 際に、その時点でのデータが意味を持つか否かを決める閾値。すなわち、過去に学習した データとの相関値の最小値である。
MACAO_LOOK_DEFAULT_DATAFILE
学習データを記録するファイ ルのデフォルトファイル名。
MACAO_LOOK_LABEL_SHOW_NORMALIZED_FACE
正規化顔画像を 表示するか否かを決定するパラメータのラベルを示す文字列である。
MACAO_LOOK_LABEL_THRESHOLD
閾値を定義する パラメータのラベルを示す文字列である。
MACAO_LOOK_LABEL_DATAFILE
データファイルパラメータ のラベルを示す文字列である。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoLookSample
学習済データのひとつのサンプルを表す。 本構造体の配列が学習済データセットのテーブルとして用意され、 認識モードにおいてはテーブルに格納された学習済データに対して認識処理の計算が行なわれる。
int* data
学習時における正規化顔画像データを格納するメモリ領域 へのポインタである。
int x, y
学習時における差分座標値の$(x, y)$を表す。
MacaoLookClass
テンプレートマッチを利用した顔認識(視線方向認識)を 行なうクラスのバーチャル関数テーブルである。 MacaoLookはMacaoRecogを継承する。 本クラスで新たに追加されるバーチャル関数は存在しない。
MacaoRecogClass super
親クラスの内容を継承する。
MacaoLook
テンプレートマッチを利用した顔認識(視線方向認識)を 行なうクラスの本体を定義する構造体である。
MacaoRecog super
親クラスの内容を継承する。
int norm_w, norm_h
正規化する幅と高さを示す。単位はピクセルである。
int* normalized
正規化したデータを格納するメモリへのポインタである。
MacaoLookSample* samples
学習データの配列へのポインタを格納する。
int data_size
学習処理により記録したサンプルの数を示す。ただし、 サンプル数の最大数(MACAO_LOOK_MAX_SAMPLE_SIZE)を越えない。
int show_normalized_face
正規化した顔画像を出力画像の左上部分 に表示するか否かのフラグである。
double threshold
テンプレートと比較する際に、その時点でのデータが 意味を持つか否かを決める閾値の現在の値を保持する。
unsigned char* datafile
学習済データを記録するデータファイルの ファイル名を表す。

ソースファイル

MacaoLookの各機能を実現する関数群は、ソースファイルlook.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_look_new ()
引数
なし。
返値
生成されたMacaoLookオブジェクトへのポインタを返す。
概要
MacaoLookのコンストラクタである。 この時点で必要なメモリが確保され、学習データ格納用の 配列、正規化データ用メモリ領域などが用意される。

macao_look_new_with_buf (MalibBuffer* buf, MacaoTrack* tracker)
引数
本関数は以下の引数をとる。
MalibBuffer* buf
入力となるバッファへのポインタ。
MacaoTrack* tracker
対応するMacaoTrackオブジェクトへのポインタ。
返値
生成されたMacaoLookオブジェクトへのポインタを返す。
概要
バッファを指定して生成するMacaoLookのコンストラクタであ る。MacaoLookオブジェクト生成の内容はmacao_look_new に準じる。またこの関数では、対応するMacaoTrackオブジェクト も同時に指定する。

macao_look_update_template (MacaoLook* look, int dx, int dy)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
int dx
中心座標と視点座標の差分値($x$座標)を示す。
int dy
中心座標と視点座標の差分値($y$座標)を示す。
返値
なし。
概要
教師クラスより呼び出される関数であり、学習データを 指定する領域に記録する。サンプル数が最大数まで達していない 場合には、新たに学習データを格納するメモリ領域を確保しサン プル数をひとつ増やす。サンプル数が最大数まで達している場合 は、最も古い学習データを破棄し、学習データ配列の最後尾に 新しい学習データを格納する。

macao_look_delete (MacaoLook* look)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
返値
なし。
概要
MacaoLookオブジェクトを消去する。メモリ上の領域を 解放するとともに、関連するデータの格納用として確保してある メモリ領域があれば、全て解放する。

macao_look_update (MacaoLook* look, MacaoParam* param)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
MacaoParam* param
アップデート対象のパラメータオブジェクトへ のポインタ。
返値
なし。
概要
パラメータのアップデート情報に基づき、処理に利用する変数の 値を更新する。

macao_look_create_params (MacaoLook* look)
引数
本関数は以下の引数をとる。
MacaoLook* look
パラメータを生成する対象のMacaoLookオブジェ クトへのポインタ。
返値
生成されたパラメータへのポインタを含む配列の、先頭ポインタを返す。
概要
本クラスで利用するパラメータの配列を生成し、 各パラメータの実体の生成と関連するメンバ変数の初期化を行なう。

macao_look_write_frame_data (MacaoLook* look, MalibFrame* frame)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
MalibFrame* frame
書き込み対象の出力画像フレームへのポインタ。
返値
なし。
概要
逐次実行される画像処理の中心となる関数である。 本関数は、MalibSourceに用意されているバーチャル関数 malib_source_write_frame_dataの実体を定義するものである。 視線方向の認識は次の手順で行なわれる。
  1. MacaoTrackによる顔領域抽出情報をもとに、顔画像データ を切出す(macao_look_cut_face)。
  2. 上記データを正規化する(macao_look_normalize_face)。
  3. 学習済データと比較し、相関の高いものを選択して視線方 向の出力とする
    (macao_look_compare_stored_data)。

macao_look_cut_face (MacaoLook* look, MalibFrame* frame, int* from, int* to)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
MalibFrame* frame
書き込み対象の出力画像フレームへのポインタ。
int* from
入力画像データ領域先頭へのポインタ。
int* to
出力画像データ領域先頭へのポインタ。
返値
なし。
概要
MacaoTrackによる顔領域抽出情報をもとに、顔画像データを切出す。 なお周辺のノイズを削除することを目的として、縁からの距離に 比例した係数を輝度に乗算する演算を施している。

macao_look_normalize_face (MacaoLook* look, MalibFrame* frame, int* to)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
MalibFrame* frame
書き込み対象の出力画像フレームへのポインタ。
int* to
出力画像データ領域先頭へのポインタ。
返値
なし。
概要
関数 macao_look_cut_face によって切り出された画像データ を、あらかじめ指定する大きさに拡大/縮小することで正規化処理 を行なう。正規化画像を出力するフラグがTRUEである場合には、 出力画像の左上に正規化顔画像を描画する。

macao_look_compare_stored_data (MacaoLook* look, MalibFrame* frame, int* to)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
MalibFrame* frame
書き込み対象の出力画像フレームへのポインタ。
int* to
出力画像データ領域先頭へのポインタ。
返値
なし。
概要
学習済データと比較し、相関の高いものを選択して視線方向の出力とする。 相関値の計算は関数 macao_look_calc_corr で行ない、全ての 学習済データとの比較を行なう。結果と して出力された相関値の最大値が閾値を越えている場合、 その最大値を取る学習データに確保されている視線座標データを 認識結果として出力する。

macao_look_calc_corr (MacaoLook* look, int index, int length)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
int index
比較対象の学習データのインデクスを与える。
int length
比較するデータの大きさを与える。 実際には正規化データ(学習データ)をintの配列と見なしたときの、デー タの長さである。
返値
正規化データと学習データの相関値。
概要
引数(index)で指定する番号の学習データと正規化データの相関 値を計算する。

macao_look_save_data (MacaoPfile* pfile, MacaoLook* look)
引数
本関数は以下の引数をとる。
MacaoPfile* pfile
学習データを格納するファイルを値に持つ ファイルパラメータ(MacaoPfile)オブジェクトへのポインタ。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
返値
処理に成功すればTRUE、問題が生じた場合にはFALSEを返す。
概要
ファイルパラメータに記録されている 学習データを格納するファイルに対し、学習データをセーブする 処理を行なう。

macao_look_load_data (MacaoPfile* pfile, MacaoLook* look)
引数
本関数は以下の引数をとる。
MacaoPfile* pfile
学習データを格納するファイルを値に持つ ファイルパラメータ(MacaoPfile)オブジェクトへのポインタ。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
返値
処理に成功すればTRUE、問題が生じた場合にはFALSEを返す。
概要
ファイルパラメータに記録されている 学習データを格納するファイルから、学習データをロードする 処理を行なう。

macao_look_set_show_normalized_face (MacaoLook* look, int bool_value)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
int bool_value
セットするフラグの値。TRUEまたはFALSEを与える。
返値
なし。
概要
正規化した顔画像を出力画像の左上部分 に表示するか否かのフラグをセットする。

macao_look_set_threshold (MacaoLook* look, double double_value)
引数
本関数は以下の引数をとる。
MacaoLook* look
対象とするMacaoLookオブジェクトへのポインタ。
double double_value
セットする閾値の値。
返値
なし。
概要
テンプレートと比較する際に、その時点でのデータが 意味を持つか否かを決める閾値をセットする。

MacaoParam

概要

MacaoTrackが持つパラメータを表すクラスである。本パラメータは抽象クラス として定義される。

MacaoTrackのサブクラスは、個々の処理で必要とする調整可能なパラメータの セットを持つ。そのパラメータのセットの実装は、MacaoParamオブジェクトへの ポインタの配列である。この配列はパラメータの要素数+1の大きさをとり、 最後のポインタに終端子としてNULLを代入する。なおパラメータをひとつも持た ないことも可能で、その場合はNULLひとつの要素からなる配列とする。

実際の個別のパラメータは、その値の型や種別に応じて具体的な実装が行なわれ る。本クラスは抽象クラスとして定義され、各パラメータの実装に共通インタ フェースを与える目的で用意されている。

ヘッダファイル

ヘッダファイル param.h では、MacaoParam に関するマクロ定義、列挙型 構造体の定義、それらに関する型定義、およびソースファイル param.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

マクロ定義

本ファイルで定義されるマクロ定義の詳細を以下に示す。
MACAO_PARAM_DEFAULT_NAME
パラメータのデフォルト名``(null)''を示す。
MACAO_PARAM_NAME_ERROR
パラメータ名にエラーが 生じた場合(重複する名称等)のエラーメッセージ文字列である。
MACAO_PARAM_VFUNC_TBL(obj)
MacaoParam の持つバーチャル 関数テーブルを取得するためのアクセサである。
macao_param_save(param, fp)
MacaoParam の持つバーチャル 関数テーブルにおけるメンバ(save)へのアクセサである。見かけ上のバーチャル関数を定義する。
macao_param_load(param, fp)
MacaoParam の持つバーチャル 関数テーブルにおけるメンバ(load)へのアクセサである。見かけ上のバーチャル関数を定義する。

列挙型

本ファイルで定義される列挙型の詳細を以下に示す。
MacaoParamType
パラメータクラスのタイプを示す。 新たにパラメータクラスの実体を定義した場合には、この 列挙型に要素を追加して新たなタイプを確保する必要がある。将来の拡張としては、 本要素は動的に追加できるように拡張する必要があろう。
MACAO_PARAM_BOOL
ブーリアン型のパラメータタイプを示す。
MACAO_PARAM_DOUBLE
実数型のパラメータタイプを示す。
MACAO_PARAM_FILE
ファイル型のパラメータタイプを示す。
MACAO_PARAM_INT
整数型のパラメータタイプを示す(未使用)。
MACAO_PARAM_TYPE_NUM
MacaoParamType の要素数を表す。
MACAO_PARAM_NOP
何もしないパラメータを表す。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoParamClass
パラメータクラスのバーチャル関数テーブルである。 MacaoParamはMalibObjectを継承する。値のセーブ、ロード用のバーチャル関数 が追加される。MacaoParamは抽象クラスであり、これらの個々の実装は パラメータサブライブラリとして実装される個々のサブクラスに委ねられる。
MalibObjectClass super
親クラスの内容を継承する。
int (* save) (MacaoParam* param, FILE* fp)
パラメータデータを ファイルに書き出すための関数である。
int (* load) (MacaoParam* param, FILE* fp)
パラメータデータを ファイルから読み込むための関数である。
MacaoParam
パラメータクラスの本体を定義する構造体である。
MalibObject super
親クラスの内容を継承する。
MacaoParamType type
パラメータのタイプを示す。
unsigned char* name
パラメータの名称を記録する。
MacaoTrack* track
本パラメータオブジェクトの所有者である トラッキングオブジェクト(MacaoTrack)へのポインタを格納する。

ソースファイル

MacaoParamの各機能を実現する関数群は、ソースファイルparam.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_param_delete (MacaoParam* param)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
返値
なし。
概要
MacaoParamオブジェクトを消去する。MacaoParam用に確保 されているメモリ上の領域を解放する(実際には、 MalibObjectの解放処理が加えられている)。

macao_param_get_type (MacaoParam* param)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
返値
対象とするMacaoParamオブジェクトが持つパラメータタイプを返す。
概要
パラメータタイプを問い合わせる。

macao_param_set_type (MacaoParam* param, MacaoParamType type)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
MacaoParamType type
設定するパラメータのタイプ。
返値
なし。
概要
パラメータタイプを設定する。

macao_param_get_name (MacaoParam* param)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
返値
対象とするMacaoParamオブジェクトが持つパラメータ名を返す。
概要
パラメータ名を問い合わせる。

macao_param_set_name (MacaoParam* param, unsigned char* name)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
unsigned char* name
設定するパラメータ名を示す文字列へのポインタ。
返値
なし。
概要
パラメータ名を設定する。

macao_param_get_track (MacaoParam* param)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
返値
対応するMacaoTrackオブジェクトへのポインタを返す。
概要
そのパラメータの所有者であるMacaoTrackオブジェクトへのポイ ンタを得る。

macao_param_set_track (MacaoParam* param, MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
MacaoTrack* track
対応するMacaoTrackオブジェクトへのポインタ。
返値
なし。
概要
そのパラメータの所有者であるMacaoTrackオブジェクトへのポインタを設定する。

macao_param_init (MacaoParam* param, MacaoParamType type, unsigned char* name, MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
MacaoParamType type
設定するパラメータタイプ。
unsigned char* name
設定するパラメータ名。
MacaoTrack* track
そのパラメータの所有者であるMacaoTrackオブ ジェクトへのポインタ。
返値
なし。
概要
引数で与える情報によって、パラメータの初期化を行なう。実際 には個々の設定用関数を順番に呼び出す処理を行なう。

macao_param_read_value (MacaoParam* param, FILE* fp, unsigned char* value)
引数
本関数は以下の引数をとる。
MacaoParam* param
対象とするMacaoParamオブジェクトへのポインタ。
FILE* fp
パラメータファイルのファイルポインタ。
unsigned char* value
読み込んだパラメータの値を書き込むべき文 字列領域へのポインタ。
返値
処理に成功すればTRUE、問題が生じた場合にはFALSEを返す。
概要
ファイルポインタで指定するファイルからパラメータに関する設 定の記述を読み込み、その値をあらかじめ用意されているメモリ 領域に書き込む。またその際に、正しいパラメータが選択されて いるかどうか、パラメータ名の情報を比較することによりチェッ クを行なう。

MacaoRecog

概要

顔認識処理を提供するクラスの雛形となる抽象クラスである。

認識処理を行なうMacaoRecogクラスは、顔領域抽出クラスのサブクラスと して実装される。MacaoRecogクラスもMacaoTrackと同様に抽象クラ スであり、個々の実装はサブクラスに委ねられる。 またMacaoRecogはMacaoTrackと対になって利用されることを想定し ている。一般的な処理の流れは次の手順となる。

  1. MacaoTrackクラス(のサブクラス)によって、顔領域の大まかな 位置が抽出される。
  2. MacaoRecogクラス(のサブクラス)は、その情報を参照しつつ、 入力画像から顔認識処理を行なう。

ヘッダファイル

ヘッダファイル recog.h では、MacaoRecog に関する構造体の定義、 それらに関する型定義、およびソースファイル recog.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoRecogClass
抽象クラスとして用意される 認識クラスのバーチャル関数テーブルである。 MacaoRecogはMacaoTrackを継承する。 本クラスで新たに追加されるバーチャル関数は存在しない。
MacaoTrackClass super
親クラスの内容を継承する。
MacaoRecog
抽象クラスとして用意される 認識クラスの本体を定義する構造体である。
MacaoTrack super
親クラスの内容を継承する。
MacaoTrack* tracker
MacaoRecogはMacaoTrackと組にして利用可能で ある(組合わせは、個々のサブクラスのインスタンスが組合される ことに注意する)。本クラスに対応するMacaoTrackへのポインタを格納する。
MacaoTeacher* teacher
MacaoRecogクラスのインスタンスは、そのク ラスの教師クラスとしてMacaoTeacherクラスのサブクラスと組に して利用される。本メンバ変数にはそのオブジェクトへのポイン タを格納する。

ソースファイル

MacaoRecogの各機能を実現する関数群は、ソースファイルrecog.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_recog_set_tracker (MacaoRecog* recog, MacaoTrack* tracker)
引数
本関数は以下の引数をとる。
MacaoRecog* recog
対象とするMacaoRecogオブジェクトへのポインタ。
MacaoTrack* tracker
MacaoRecogに格納するMacaoTrack オブジェクトへのポインタ。
返値
なし。
概要
MacaoRecogが参照すべきMacaoTrackオブジェクトのポインタを格 納する。

macao_recog_get_tracker (MacaoRecog* recog)
引数
本関数は以下の引数をとる。
MacaoRecog* recog
対象とするMacaoRecogオブジェクトへのポインタ。
返値
MacaoRecogが参照するMacaoTrackオブジェクトへのポインタを返す。
概要
MacaoRecogが参照するMacaoTrackオブジェクトへのアクセサである。

macao_recog_set_teacher (MacaoRecog* recog, MacaoTeacher* teacher)
引数
本関数は以下の引数をとる。
MacaoRecog* recog
対象とするMacaoRecogオブジェクトへのポインタ。
MacaoTeacher* teacher
MacaoRecogに格納するMacaoTeacher オブジェクトへのポインタ。
返値
なし。
概要
MacaoRecogが参照すべきMacaoTeacherオブジェクトのポインタを格 納する。

macao_recog_get_teacher (MacaoRecog* recog)
引数
本関数は以下の引数をとる。
MacaoRecog* recog
対象とするMacaoRecogオブジェクトへのポインタ。
返値
MacaoRecogが参照するMacaoTeacherオブジェクトへのポインタを返す。
概要
MacaoRecogが参照するMacaoTeacherオブジェクトへのアクセサである。

MacaoRegion

概要

MacaoTrackにおいて領域抽出処理を行なった結果を格納するための構造体である。

領域抽出処理を行なった結果は、MacaoTrackが持つMacaoRegionクラス の各スロットに値が保持される。

MacaoRegionは現在のところ外接長方形および重心位置のみを保持する。 将来の拡張として、MacaoRegionのサブクラスを定義し、多角形領域、 円形領域等を扱えるようにすることを検討している。

また現在の実装ではMacaoRegionのひとつのインスタンスへのポインタを 保持するが、複数の領域を取扱うことができるよう、MacaoRegionオブジェ クトへのポインタを配列として保持するように変更する予定である。

ヘッダファイル

ヘッダファイル region.h では、MacaoRegion に関するマクロ定義、 構造体の定義、それらに関する型定義、およびソースファイル region.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

マクロ定義

本ファイルで定義されるマクロ定義の詳細を以下に示す。
MACAO_REGION_CROSSBORDER_WIDTH
表示時に用いる十字線の 幅を表す。単位はピクセル。
MACAO_REGION_CROSSBORDER_LENGTH
表示時に用いる十字線の 長さを表す。単位はピクセル。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoCenter
領域の中心もしくは重心を表現するための構造体である。
double x, y
点の$(x, y)$座標値である。 単位はピクセルだが、精度を高めるために実数型として表現される。
MacaoPoint
点を表現するための構造体である。
int x, y
点の$(x, y)$座標値。単位はピクセルである。
MacaoRegion
領域クラスの本体を定義する構造体である。
MacaoPoint min
領域の左上隅の$(x, y)$座標値を示す。
MacaoPoint max
領域の右下隅の$(x, y)$座標値を示す。
MacaoCenter center
領域の中心の$(x, y)$座標値を示す。
MacaoRect
長方形を表現するための構造体である。
int width, height
長方形の幅と高さ。単位はピクセルである。

ソースファイル

MacaoRegionの各機能を実現する関数群は、ソースファイルregion.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_region_new ()
引数
なし。
返値
生成されたMacaoRegionオブジェクトへのポインタを返す。
概要
MacaoRegionのコンストラクタである。

macao_region_set_values (MacaoRegion* region, int min_x, int min_y, int max_x, int max_y)
引数
本関数は以下の引数をとる。
MacaoRegion* region
対象とするMacaoRegionオブジェクトへのポインタ。
int min_x
領域の左上の$x$座標を与える。
int min_y
領域の左上の$y$座標を与える。
int max_x
領域の右下の$x$座標を与える。
int max_y
領域の右下の$y$座標を与える。
返値
なし。
概要
領域の左上、右下の座標値を与える。

macao_region_get_point (MacaoRegion* region, MacaoPoint* min, MacaoPoint* max, MacaoCenter* center)
引数
本関数は以下の引数をとる。
MacaoRegion* region
対象とするMacaoRegionオブジェクトへのポインタ。
MacaoPoint* min
左上の$(x, y)$座標値を格納するために用意する MacaoPointオブジェクトへのポインタ。
MacaoPoint* max
右下の$(x, y)$座標値を格納するために用意する MacaoPointオブジェクトへのポインタ。
MacaoCenter* center
中央(重心)の$(x, y)$座標値を格納するために用意する MacaoCenterオブジェクトへのポインタ。
返値
なし。
概要
領域の情報をまとめて取得する。

macao_region_get_size (MacaoRegion* region, int* width, int* height)
引数
本関数は以下の引数をとる。
MacaoRegion* region
対象とするMacaoRegionオブジェクトへのポインタ。
int* width
幅の値(単位はピクセル)を返すためのint型変数へのポインタ。
int* height
高さの値(単位はピクセル)を返すためのint型変数へのポインタ。
返値
なし。
概要
領域の幅と高さを得る。

MacaoSkin

概要

RGBカラー画像を入力とし、肌色情報を利用して顔領域の抽出を行なうクラスで ある。MacaoTrackを継承する。

肌色領域を構成する画素の判定は、以下の手順で行なわれる。

  1. まず画素のRGB値を以下の式により変換しab平面に射影する ( $R=G=B=0のときは a=b=0とする$)。

    \begin{eqnarray*} a & = & \frac{2 \; R + G}{2 \; (R+G+B)}\\ b & = & \frac{\sqrt{3} \; G}{2 \; (R+G+B)} \end{eqnarray*}



  2. 変換した$a,b$の値が、中心を$(a_0, b_0)$、それぞれの半径を $(r_a, r_b)$とする楕円領域に含まれるか否かどうかを判定する。

肌色画素の判定を行なったのち、肌色画素をブロックにまとめ、各ブロックにつ いて肌色画素を含む指標が閾値を越えているかどうか判定する。

次に、肌色画素ブロックと判定されたものを対象として、領域の連結性を調べる ために各領域のラベリング処理を行なう。この段階で、最大面積を持つ 領域を顔領域と判定する。

判定された顔領域について、内部に含まれる目、眉、口(これらは肌色ではない)も 顔画像領域として取扱うことができるように、その閉包を求める処理を加える (厳密には閉包ではなく、左右、上下いずれかの2辺から到達できない点を顔領域 に含める、という処理を加えて簡易的な閉包の計算としている)。

ヘッダファイル

ヘッダファイル skin.h では、MacaoSkin に関するマクロ定義、 構造体の定義、それらに関する型定義、およびソースファイル skin.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

マクロ定義

本ファイルで定義されるマクロ定義の詳細を以下に示す。
MACAO_SKIN_NAME
本クラスの名前を表す文字列である。
MACAO_SKIN_BLOCKSIZE
デフォルトの画素ブロックの大きさを 示す。デフォルトでは2x2ピクセルからなるブロックを扱う。
MACAO_SKIN_BLOB_THRESHOLD
ラベリング後の領域の最低 面積を示す閾値を表す。
MACAO_SKIN_MASK_OFFSET
画素のグルーピングに関する オフセット値を表す。
MACAO_SKIN_THRESHOLD
画素ピクセルの割合の閾値を示す。
MACAO_SKIN_DEFAULT_ALPHA_MEAN
色パラメータのデフォル トの$\alpha$値(平均)を与える。
MACAO_SKIN_DEFAULT_BETA_MEAN
色パラメータのデフォル トの$\beta$値(平均)を与える。
MACAO_SKIN_DEFAULT_ALPHA_COEF
色パラメータのデフォル トの$\alpha$値(分散)を与える。
MACAO_SKIN_DEFAULT_BETA_COEF
色パラメータのデフォル トの$\beta$値(分散)を与える。
MACAO_SKIN_SHADE_LEVEL
肌色画素以外の部分をグレーアウ トする係数。肌色ブロック以外の部分においては画素値をこの係数で割るため、 大きいほど黒に近くなる。
MACAO_SKIN_DISPLAY_BOUNDINGBOX
閉包長方形を 表示するか否か(現在は別途フラグを持つため未使用)。
MACAO_SKIN_SHADE_INPUTIMAGE
肌色画素以外の部分をグレーアウト 表示するか否か。このマクロを定義しないと、肌色画素以外の部分は黒となる。
MACAO_SKIN_LABEL_SHOW_REGION
閉包長方形を 表示するか否かを決定するパラメータのラベルを示す文字列である。
MACAO_SKIN_LABEL_ALPHA_MEAN
$\alpha$値(平均)値を定義する パラメータのラベルを示す文字列である。
MACAO_SKIN_LABEL_BETA_MEAN
$\beta$値(平均)値を定義する パラメータのラベルを示す文字列である。
MACAO_SKIN_LABEL_ALPHA_COEF
$\alpha$値(分散)値を定義する パラメータのラベルを示す文字列である。
MACAO_SKIN_LABEL_BETA_COEF
$\beta$値(分散)値を定義する パラメータのラベルを示す文字列である。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoSkinClass
RGBカラー画像を入力とし、肌色情報を利用して 顔領域の抽出を行なうクラスのバーチャル関数テーブルである。 MacaoSkinはMacaoTrackを継承する。 本クラスで新たに追加されるバーチャル関数は存在しない。
MacaoTrackClass super
親クラスの内容を継承する。
MacaoSkin
RGBカラー画像を入力とし、肌色情報を利用して 顔領域の抽出を行なうクラスの本体を定義する構造体である。
MacaoTrack super
親クラスの内容を継承する。
int* score
各候補領域のスコア配列へのポインタである。
int* mask
マスクデータ配列(入力画像を処理したブロック画像に相当 する)へのポインタである。
int width, height
入力画像の縦横のサイズ(単位はピクセル)を保持する。
int column, row
画像のサイズ(ピクセル単位)をブロックサイズで割っ た値を保持する。
double a_mean, b_mean
$\alpha, \beta$の平均値である。
double a_coef, b_coef
$\alpha, \beta$の分散である。

ソースファイル

MacaoSkinの各機能を実現する関数群は、ソースファイルskin.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_skin_new ()
引数
なし。
返値
生成されたMacaoSkinオブジェクトへのポインタを返す。
概要
MacaoSkinのコンストラクタである。 メモリ領域の確保および関連するパラメータオブジェクトの生成を行なう。

macao_skin_new_with_buf (MalibBuffer* buf)
引数
本関数は以下の引数をとる。
MalibBuffer* buf
入力となるバッファへのポインタ。
返値
生成されたMacaoSkinオブジェクトへのポインタを返す。
概要
バッファを指定して生成するMacaoSkinのコンストラクタであ る。MacaoSkinオブジェクト生成の内容はmacao_skin_new に準じる。

macao_skin_create_params (MacaoSkin* track)
引数
本関数は以下の引数をとる。
MacaoTrack* track
パラメータを生成する対象のMacaoTrackオブジェ クト(実体はMacaoSkin)へのポインタ。
返値
生成されたパラメータへのポインタを含む配列の、先頭ポインタを返す。
概要
本クラスで利用するパラメータの配列を生成し、 各パラメータの実体の生成と関連するメンバ変数の初期化を行なう。

macao_skin_update (MacaoTrack* track, MacaoParam* param)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェ クト(実体はMacaoSkin)へのポインタ。
MacaoParam* param
アップデート対象のパラメータオブジェクトへ のポインタ。
返値
なし。
概要
パラメータのアップデート情報に基づき、処理に利用する変数の 値を更新する。

macao_skin_delete (MacaoSkin* skin)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
返値
なし。
概要
MacaoSkinオブジェクトを消去する。メモリ上の領域を 解放するとともに、関連するデータの格納用として確保してある メモリ領域があれば、全て解放する。

macao_skin_set_buffer (MacaoSkin* skin, MalibBuffer* buf)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
MalibBuffer* buf
返値
なし。
概要
MacaoSkinクラスでは、score配列やmask配列など 入力する画像の大きさに依存したメモリ領域の確保が行なわれる ため、MalibFilterで定義されるmalib_filter_set_buffer関数 をオーバーライドして、拡張したバッファの接続関数を用意する。 バッファの接続時に、上記関連するメモリ領域の確保が行なわれ る。

macao_skin_write_frame_data (MacaoSkin* skin, MalibFrame* frame)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
MalibFrame* frame
書き込み対象の出力画像フレームへのポインタ。
返値
なし。
概要
逐次実行される画像処理の中心となる関数である。 本関数は、MalibSourceに用意されているバーチャル関数 malib_source_write_frame_dataの実体を定義するものである。 肌色情報を利用した顔画像領域の抽出は、以下の手順で行なわれ る。
  1. ブロックごとに、肌色画素を含む画素数によるスコア を計算する(macao_skin_calc_bloc_score)。
  2. ブロックを、さらにブロックを取り囲む周囲のオフセット 領域を含めた単位で集計し、閾値を越えているか否かの判 定を行なう。この判定により肌色領域を多く含むとされた ブロックは、対応するマスク配列にフラグが立つ (macao_skin_calc_mask)。
  3. マスク情報から、ブロック単位のラベリング処理を行ない、 ノイズと判定できる小領域を排除したうえで最大の連結領域 を探索する(macao_skin_find_face_candidate)。
  4. 結果として抽出された顔領域を出力画像に描画する (macao_skin_draw_output)。

macao_skin_calc_block_score (MacaoSkin* skin, int* input_image)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
int* input_image
入力画像データ領域先頭へのポインタ。
返値
なし。
概要
ブロックごとに、肌色画素を含む画素数によるスコアを計算する。 肌色画素か否かは、$RGB$値から変換した$ab$値が、 $\alpha, \beta$の平均値を中心として 各々の分散を半径とする楕円領域に含まれるか否かの判定による。

macao_skin_fill_label (MacaoSkin* skin, int i, int label)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
int i
マスク配列におけるインデクス。
int label
連結領域につけられるラベル。
返値
ラベル付けされた領域の面積を示す、そのラベルが持つ画素の数 を返す。
概要
マスク配列をサーチし、連結領域のラベリング処理を行なう。 関数macao_skin_labelngからスタートし、本関数を周囲の ブロックに対して再帰的に処理することでラベリング処理を適用 する。

macao_skin_labeling (MacaoSkin* skin, int* pix_num)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
int* pix_num
ラベル番号に対する画素数を格納している配列へのポインタ。
返値
最大の画素数を持つラベル番号を返す。
概要
マスク配列をサーチして、連続領域のラベリング処理を行なう。 その際、各ラベルの面積を示す画素数が、ラベル番号をインデク スとする配列に格納される。ただし面積が閾値を越えない小領域に関し ては画素数が0に設定される(この条件は次の関数で利用する)。

macao_skin_dispose_small_blob (MacaoSkin* skin, int* pix_num)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
int* pix_num
ラベル番号に対する画素数を格納している配列へのポインタ。
返値
なし。
概要
マスク配列をサーチし、ラベル番号に対する画素数が0の場合は マスク値を0に設定する。この関数が呼ばれる段階の前の処理であ るラベリング処理において、面積が閾値を越えない小領域に関し ては画素数が0に設定されていることに注意する。

macao_skin_calc_bounding_box (MacaoSkin* skin, int label, MacaoRegion* closure)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
int label
バウンディングボックスを計算すべきラベルの番号。
MacaoRegion* closure
計算したバウンディングボックスの値を設定 すべきMacaoRegionオブジェクトへのポインタ。
返値
なし。
概要
マスク配列をサーチし、あるラベル番号がついている領域に関し てそのバウンディングボックスを計算する。

macao_skin_calc_centroid (MacaoSkin* skin)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
返値
なし。
概要
領域に含まれる肌色画素(目、眉、口を含む)を構成する画素につ いて、そのデータの重心を求める。計算した重心は、 MacoaSkinオブジェクトのメンバ変数に格納される。

macao_skin_sum_of_valid_pixel (MacaoSkin* skin, int x0, int y0)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
int x0
ブロックからの$x$方向に対するオフセット量。
int y0
ブロックからの$y$方向に対するオフセット量。
返値
肌色画素として有効な画素数の合計を返す。
概要
ブロックの周辺をスキャンして、肌色画素として有効な画素数の合計を求める。

macao_skin_calc_mask (MacaoSkin* skin)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
返値
なし。
概要
ブロックを、さらにブロックを取り囲む周囲のオフセット 領域を含めた単位で集計し、閾値を越えているか否かの判 定を行なう。この判定により肌色領域を多く含むとされた ブロックは、対応するマスク配列にフラグが立つ。

macao_skin_find_face_candidate (MacaoSkin* skin)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
返値
なし。
概要
マスク情報から、ブロック単位のラベリング処理を行ない、 ノイズと判定できる小領域を排除したうえで最大の連結領域 を探索する。なおこの時点で、ノイズの影響による 領域のちらつきを抑えることを目的として、領域の2辺以上が 同時に変化しない場合は前のフレームで求めた領域をそのまま 利用する、という安定化処理を加えている。

macao_skin_clear_mask (MacaoSkin* skin)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
返値
なし。
概要
判定された顔領域について、内部に含まれる目、眉、口(これら は肌色ではない)も顔画像領域として取扱うことができるように、 その閉包を求める処理を加える。実際には、上下いずれかの2辺か ら到達できない点を顔領域に含める処理であり厳密な意味での閉 包ではない。

macao_skin_draw_output (MacaoSkin* skin, int* input_image, int* output_image)
引数
本関数は以下の引数をとる。
MacaoSkin* skin
対象とするMacaoSkinオブジェクトへのポインタ。
int* input_image
入力画像データ領域先頭へのポインタ。
int* output_image
出力画像データ領域先頭へのポインタ。
返値
なし。
概要
処理結果として抽出された顔領域を出力画像に描画する。

MacaoTeacher

概要

MacaoRecogに対する教師クラスである。MacaoTeacherそのものは抽象クラス として定義され、個々の実装はサブクラスに委ねられる。

認識処理を行なうMacaoRecogクラスは、MacaoTrackの持つ性質に 加えて学習可能とするためにMacaoTeacherクラスへのポインタを持つ。

本クラスでは、教師信号の入力が行なわれた場合の処理などが定義される。 個々の認識クラスにより学習処理が異なるため、実際の教師クラスはそれぞれの MacaoRecogサブクラスに対応するクラスとしてMacaoTeacherのサブクラスとして 実装される。本クラスは、それらに共通するインタフェースとデータ構造を 与えるものである。

ヘッダファイル

ヘッダファイル teacher.h では、MacaoTeacher に関するマクロ定義、列挙型、 構造体の定義、それらに関する型定義、およびソースファイル teacher.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

マクロ定義

本ファイルで定義されるマクロ定義の詳細を以下に示す。
MACAO_TEACHER_VFUNC_TBL(obj)
MacaoTeacher の持つバーチャル 関数テーブルを取得するためのアクセサである。
macao_teacher_update(teacher, args)
MacaoTeacher の持つバーチャル 関数テーブルにおけるメンバ(update)へのアクセサである。見かけ上のバーチャル関数を定義する。

列挙型

本ファイルで定義される列挙型の詳細を以下に示す。
MacaoTeacherID
教師クラスのIDを示す。 新たに教師クラスの実体を定義した場合には、この 列挙型に要素を追加して新たなIDを確保する必要がある。将来の拡張としては、 本要素は動的に追加できるように拡張する必要があろう。
MACAO_LOOK_TEACHER
MacaoLook用教師クラスのIDを示す。
MACAO_TEACHER_NUM
MacaoTeacherID の要素数を表す。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoTeacherClass
教師クラスのバーチャル関数 テーブルである。MacaoTeacherはMalibObjectを継承する。 教師信号の入力による状態のアップデートを行なうためのバーチャル 関数がひとつ追加される。この関数の具体的な実装は教師クラスの 具象クラスを実装するサブクラスに委ねられる。
MalibObjectClass super
親クラスの内容を継承する。
void (* update) (MacaoTeacher* teacher, MacaoTeacherArg* args)
教師信号の 入力による状態のアップデートを行なうための関数である。
MacaoTeacher
教師クラスの本体を定義する構造体である。
MalibObject super
親クラスの内容を継承する。
MacaoTeacherID id
教師クラスIDを示す。
MacaoRecog* recog
この教師クラスが対象とする顔認識処理クラス へのポインタを格納する。

ソースファイル

MacaoTeacherの各機能を実現する関数群は、ソースファイルteacher.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_teacher_delete (MacaoTeacher* teacher)
引数
本関数は以下の引数をとる。
MacaoTeacher* teacher
対象とするMacaoTeacherオブジェクトへのポインタ。
返値
なし。
概要
MacaoTeacherオブジェクトを消去する。MacaoTeacher用に確保 されているメモリ上の領域を解放する(実際には、 MalibObjectの解放処理が加えられている)。

macao_teacher_set_id (MacaoTeacher* teacher, MacaoTeacherID id)
引数
本関数は以下の引数をとる。
MacaoTeacher* teacher
対象とするMacaoTeacherオブジェクトへのポインタ。
MacaoTeacherID id
その教師クラスに設定する教師クラスID。
返値
なし。
概要
教師クラスIDを設定する。

macao_teacher_get_id (MacaoTeacher* teacher)
引数
本関数は以下の引数をとる。
MacaoTeacher* teacher
対象とするMacaoTeacherオブジェクトへのポインタ。
返値
その教師クラスが持つ教師クラスID。
概要
教師クラスIDを問い合わせる。

macao_teacher_set_recog (MacaoTeacher* teacher, MacaoRecog* recog)
引数
本関数は以下の引数をとる。
MacaoTeacher* teacher
対象とするMacaoTeacherオブジェクトへのポインタ。
MacaoRecog* recog
対応するMacaoRecogオブジェクトへのポインタ。
返値
なし。
概要
その教師クラスが対応する認識オブジェクト(MacaoRecog)へのポ インタを設定する。

macao_teacher_get_recog (MacaoTeacher* teacher)
引数
本関数は以下の引数をとる。
MacaoTeacher* teacher
対象とするMacaoTeacherオブジェクトへのポインタ。
返値
対応するMacaoRecogオブジェクトへのポインタを返す。
概要
その教師クラスが対応する認識オブジェクト(MacaoRecog)へのポ インタを得る。

MacaoTrack

概要

顔領域抽出処理を提供するクラスの雛形となる抽象クラスである。

顔領域抽出処理を行なうクラスは、MalibFilterのサブクラスとして 実装され、MAlibにおけるフィルタのひとつとしての取り扱いとなる。 MacaoTrackは実際には抽象クラスであり、個々の実装は各サブクラスに 委ねられる。

ヘッダファイル

ヘッダファイル track.h では、MacaoTrack に関するマクロ定義、 構造体の定義、それらに関する型定義、およびソースファイル track.c で定義され外部に公開される関数のプロトタイプ宣言が記述される。

マクロ定義

本ファイルで定義されるマクロ定義の詳細を以下に示す。
MACAO_TRACK_PARAMETER_FILE
".macao"
MACAO_TRACK_VFUNC_TBL(obj)
MacaoTrack の持つバーチャル 関数テーブルを取得するためのアクセサである。
macao_track_update(track, param)
MacaoTrack の持つバーチャル 関数テーブルにおけるメンバ(update)へのアクセサである。見かけ上のバーチャル関数を定義する。
macao_track_save(track, fp)
MacaoTrack の持つバーチャル 関数テーブルにおけるメンバ(save)へのアクセサである。見かけ上のバーチャル関数を定義する。
macao_track_load(track, fp)
MacaoTrack の持つバーチャル 関数テーブルにおけるメンバ(load)へのアクセサである。見かけ上のバーチャル関数を定義する。

構造体

本ファイルで定義される構造体の詳細を以下に示す。
MacaoTrackClass
抽象クラスとして用意される顔領域抽出クラスの バーチャル関数テーブルである。 MacaoTrackはMalibFilterを継承する。 値のアップデート、パラメータのセーブ、ロード用のバーチャル関数が 追加される。MacaoTrackは抽象クラスであり、これらの個々の実装は 顔領域抽出処理の実体を記述する個々のサブクラスに委ねられる。
MalibFilterClass super
親クラスの内容を継承する。
void (* update) (MacaoTrack* track, MacaoParam* param)
値のアッ プデート用の関数である。
int (* save) (MacaoTrack* track, FILE* fp)
パラメータをファイル に書き出すための関数である。
int (* load) (MacaoTrack* track, FILE* fp)
パラメータをファイル から読み込むための関数である。
MacaoTrack
抽象クラスとして用意される顔領域抽出クラスの 本体を定義する構造体である。
MalibFilter super
親クラスの内容を継承する。
unsigned char* name
本クラスの名称を表す文字列へのポインタである。
MacaoParam** params
抽出処理で用いるパラメータを確保するパラメー タテーブルへのポインタである。具体的には、個々のパラメータ オブジェクトへのポインタの配列として実装されている。
MacaoRegion* region
抽出処理の結果として得られた顔領域に関する 情報を記録するMacaoRegionオブジェクトへのポインタを格納する。
int show_region
顔領域の表示を出力画像に描画するか否かのフラグ である。

ソースファイル

MacaoTrackの各機能を実現する関数群は、ソースファイルtrack.cで記述 される。

関数

本ファイルで定義される関数の詳細を以下に示す。
macao_track_get_params (MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
返値
対象とするMacaoTrackオブジェクトが持つパラメータの配列 (正確には、パラメータオブジェクトへのポインタの配列)への ポインタを返す。
概要
パラメータの配列のポインタを取得する。

macao_track_set_params (MacaoTrack* track, MacaoParam** params)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
MacaoParam** params
設定するパラメータの配列へのポインタ。
返値
なし。
概要
パラメータへのポインタを格納する配列を設定する。

macao_track_get_region (MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
返値
MacaoRegionオブジェクトへのポインタを返す。
概要
顔領域抽出結果を格納するMacaoRegionオブジェクトへの ポインタを取得する。

macao_track_is_show_region (MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
返値
顔領域を出力画像に表示するように設定されている場合はTRUEを、 そうでない場合はFALSEを返す。
概要
顔領域を出力画像に表示するか否かのフラグを得る。

macao_track_set_show_region (MacaoTrack* track, int flag)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
int flag
設定するフラグの値。TRUEまたはFALSEを与える。
返値
なし。
概要
顔領域を出力画像に表示するか否かのフラグを設定する。

macao_track_delete (MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
返値
なし。
概要
MacaoTrackオブジェクトを消去する。メモリ上の領域を 解放するとともに、関連するデータの格納用として確保してある メモリ領域があれば、全て解放する。

macao_track_init (MacaoTrack* track, unsigned char* name)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
unsigned char* name
MacaoTrackオブジェクトに設定する名称。
返値
なし。
概要
MacaoTrackオブジェクトの初期化を行なう。

macao_track_save_default (MacaoTrack* track, FILE* fp)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
FILE* fp
出力対象のファイルのファイルポインタ。本関数の呼び出 しの前にファイルが書き出しモードでオープンされていることを前提とする。
返値
処理に成功すればTRUE、問題が生じた場合にはFALSEを返す。
概要
各パラメータの値をセーブする関数の標準的な手段を与える関数 である。ファイルには、各パラメータの名前と値を組として、 プログラムで規定される順番に一行ずつ出力される。

macao_track_load_default (MacaoTrack* track, FILE* fp)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
FILE* fp
入力対象のファイルのファイルポインタ。本関数の呼び出 しの前にファイルが読み込みモードでオープンされていることを前提とする。
返値
処理に成功すればTRUE、問題が生じた場合にはFALSEを返す。
概要
各パラメータの値をロードする関数の標準的な手段を与える関数 である。ファイルには、各パラメータの名前と値が組となり プログラムで規定される順番に一行ずつ並んで記述されているこ とが想定されている。

macao_track_create_params_default (MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoTrack* track
パラメータを生成する対象のMacaoTrackオブジェ クトへのポインタ。
返値
生成されたパラメータへのポインタを含む配列の、先頭ポインタを返す。
概要
本クラスで利用するパラメータの配列を生成する。ただし 本関数はデフォルトとして用意されているものであり、 ひとつもパラメータを持たない場合、すなわちNULLひとつを 格納するポインタ配列の生成を行なう。

macao_track_create_region_default (MacaoTrack* track)
引数
本関数は以下の引数をとる。
MacaoTrack* track
対象とするMacaoTrackオブジェクトへのポインタ。
返値
MacaoRegionオブジェクトのデフォルト値として設定されている 静的オブジェクトのアドレスを返す。
概要
MacaoRegionオブジェクトのデフォルト値を求める。 デフォルト値は、全てが0の値を持つMacaoRegionオブジェクトと して、track.cにハードコーディングされている。

next up previous contents
次へ: パラメータサブライブラリ 上へ: MACAOライブラリ 戻る: MACAOライブラリ   目次
Jun IIO 平成15年5月27日