FACE01 GRAPHICS 1.2.0 の呼び出し方について解説します

FACE01 GRAPHICSバージョン1.2.0について引数の説明をいたします。

従来、設定を変更する時は呼び出す側の test_script_for_face01_119 ファイルを直接変更しておりました。バージョン1.2.0よりGUIによる設定ウィンドウからオプション変数の変更を行います。

それぞれの関数に与えるオプション変数を自由に変えられます。これによって呼び出す側に自由度を与えますが、反対に顔認証のアルゴリズムや各々のオプション変数の働きが分かっていないと期待しない動作になってしまいます。

内部があまりよく理解できていない最初は「オプション変数を変更しない」というのも一つの手です。オプション変数を変更しなくてもある程度よろしくやってくれるようになっています。
では一つづつオプション変数を確認していきましょう。

各オプション変数の働き

jitters

dlib を git clone した場所、私の場合なら $HOME/dlib/python_examples/ ディレクトリの face_jitter.py ファイルには以下のように記述してあります。
It takes an input image and disturbs the colors as well as applies random translations, rotations, and scaling.
「入力画像を受け取り、色を乱し、ランダムな移動、回転、スケーリングを適用します。」
jitters の値を大きくするほどランダムな変換の平均値をとるようになります。
しかしながら大きな値をとることによって入力画像が不確かなものになっていくこと、処理時間が長くなることが懸念されます。
通常は 5 〜 10 あたりが良いように感じます。

upsampling

1フレームの画像のうち、顔探索するピクセル範囲を決定する変数（アップサンプリング変数）。
upsampling は 80×80 ピクセルと40×40 ピクセルを選ぶことが出来ます。この時80×80では80X80ピクセル位上の範囲を、40×40 ピクセルでは40X40ピクセル以上の範囲を顔探索します。

1フレームごとにより細かく顔探索するように指示するため、処理時間とトレードオフになります。
下の例ではそれぞれの顔は80X80ピクセルの面積以上になっています。この場合は80×80を選択することで良好な結果を出します。

mode

顔検出にCNN方式または HOG方式のどちらを用いるかを選びます。
CNN: Convolutional Neural Network
HOG: Histogram of Oriented Gradients
CPUのみの場合HOG方式の方が処理速度は高くなります。反対にNvideaのGPUが使える場合、CNN方式の処理速度が早くなります。
( $HOME/dlib/python_examples/dnn_mmod_face_detection_ex.cpp 参照 ）

HOG方式はマスクをした顔の検出を苦手とします。
マスクをした顔を顔検出する場合はCNN方式を選択すると良い結果を出します。

model

顔検出には2つの方式があります
small: 5-point landmark model
large: 68-point landmark model
ライセンスの問題からsmall のみの選択になっています。（画面上に選択する箇所はありません）

tolerance

0.6 を基準としてトレーニングしてあります。これより大きければ他人と判断されます。
初期設定値は0.5です。それ以上の distance ( 顔データ間の距離 ) は足切りされます。

frame_skip

フレームドロップの割合です。入力が 30fps の場合 frame_skip=2 では 15fps となります。処理するコンピュータの性能によってさばけるフレーム数は異なります。CPUしか使えない状況でmodeにCNN方式を選んだ時などに負荷がかかって処理速度が落ちる場合、このオプション変数によりフレームを適切にドロップします。

入力映像元

入力映像元を同階層のtest.mp4ファイルから選ぶ場合、test.mp4を選択して下さい。Webカメラを用いる時は「web camera」を選択します。その他の入力元の場合は「その他の入力映像ファイル」ボタンを押してファイル選択ダイアログから適切な動画ファイルを選択して下さい。

rectangle

顔周囲に枠を描画するかどうかを指定します。

• simple
  四角形を描画する
• standard
  通常枠を描画する
• noting
  枠を表示しない

show video

openCV 由来の GUI 表示をするかしないかを選べます。
独自に GUI を作りその中に顔認証済み動画を埋め込みたいときなどに使います。下図では簡単な例として matplotlab を用いて関数の返り値から GUI ウィンドウを開いています。

frequency crop image

これまで（バージョン 1.1.3 ）は 1 フレームごとに output として顔をクロップした顔画像ファイルを出力していましたが、これだと I/O 速度が律速ポイントとなってしまいます。
バージョン 1.1.4 からは n 枚のフレームごとに 1 つの顔画像ファイルを出力することが指定できます。これにより運用するマシンのi/o速度がFACE01 GRAPHICSの処理速度に影響を与えることを抑える効果があります。

mode と model の使い分け

まず各関数がどのような働きをしているか簡単に説明します。

load_priset_image() 関数

pictures_of_people_i_know ディレクトリに登録されている顔画像ファイルを 128D 顔識別子にエンコードする際に用いられます。
マスクの有り無しも含めて通常は
mode: ‘hog’
model: ‘small’
pictures_of_people_i_know フォルダにぼやっとした顔やマスクをはめた顔を登録するした場合 HOG モードでは読み込めない事があり、この様なときはプログラム内部でその部分だけ CNN モードで顔探索処理を行います。

face_attestation() 関数

load_priset_image() 関数で 128D 顔識別子でエンコードされたデータと比較するためにここでも 128D エンコードを行います。
先と同じようにマスクの有り無しに関わらず
mode: ‘cnn’
model: ‘small’
を指定してください。ただし mode の項で触れたとおり顔認識の精度の高い cnn を選択する場合は速度とトレードオフになることに注意してください。十分な性能の NVIDIA 製 GPU を搭載していれば速度的には問題になりませんがサーバで使用する場合など CPU のみと制約がある場合もあります。
チェックされる画像の照明の当たり具合や焦点ボケが発生している場合、cnn 形式でないと顔を認識できない場合がありますので注意してください。現場で用いる場合、なるべくしっかりと顔が映るようにすると hog で通用する場合も多いですので「実際の使われる環境」にも留意しましょう。

設定ファイル詳細とデフォルト値

ここからは設定ウィンドウではなく設定ファイルそのものについて解説をしていきたいと思います。

マスクをした状態をCPUのみで処理を行うこと前提の引数値になっています。

load_priset_image() 関数の場合

known_face_encodings, known_face_names = f.load_priset_image(
    kaoninshoDir,
    pictures_of_people_i_knowDir, 
    jitters=3, 
    upsampling=0, 
    mode='hog', 
    model='small'
)
""" オプション変数の説明
jitters                     ゆらぎ値。ランダムにスケールアップや色の修正をして平均値を返す。デフォルト値 0
upsampling                  サンプリング指定値。0 の時 80x80 ピクセルで顔探索をする。1 では 40x40 ピクセル。デフォルト値：0
mode                        CNN, HOG 両形式を指定する。顔検出しにくい場合は'cnn'を指定する。デフォルト値：'hog'
model                       small -> 5-points method, large -> 68-points method　デフォルト値：'small' """

80×80 ピクセルでの顔探索、jitters ( ゆらぎ値 ) は3 、HOG 形式、5-point landmark model となっています。

xs = f.face_attestation(
    kaoninshoDir, 
    known_face_encodings, 
    known_face_names, 
    tolerance=0.5, 
    jitters=0,
    upsampling=0,
    mode='hog', 
    model='small',
    frame_skip=15,
    movie='test.mp4',
    rectangle='false',
    target_rectangle='true',
    show_video='true',
    frequency_crop_image=5
)
""" オプション変数の説明
jitters                     ゆらぎ値。ランダムにスケールアップや色の修正をして平均値を返す。デフォルト値 0
upsampling                  サンプリング指定値。0 の時 80x80 ピクセルで顔探索をする。1 では 40x40 ピクセル。デフォルト値：0
mode                        CNN, HOG 両形式を指定する。顔検出しにくい場合は'cnn'を指定する。デフォルト値：'hog'
model                       small -> 5-points method, large -> 68-points method　デフォルト値：'small'
tolerance                   閾値。顔認証の厳格さを指定する。低いほど厳格。デフォルト値：0.5
frame_skip                  フレームドロップの割合。入力が 30fps の場合 frame_skip=2 では 15fps となる
                            マシン速度によって調節すること。デフォルト値：0
movie                       動画入力元を test.mp4 と USB カメラの 2 種類から選ぶ。デフォルト値：'test.mp4'
rectangle                   顔周囲に四角枠（直接描画）を描画するか否かを指定。デフォルト値：'false'
target_rectangle            顔周囲に四角枠（png画像）を描画するか否かを指定。デフォルト値：'true'
show_video                  openCV 由来の GUI による動画表示の有無。デフォルト値：'true'
frequency_crop_image        フレームをいくつ飛ばして output するか調節する。frame_skip値に影響される。デフォルト値：10 """

GPU が使える場合には

NVIDIA 製の GPU が使える場合にはまず dlib と face-recognition を CUDA 仕様にしてください。
以下はマスクをはめた状態を想定しています。

load_priset_image() 関数の場合

known_face_encodings, known_face_names = f.load_priset_image(
    kaoninshoDir,
    pictures_of_people_i_knowDir, 
    jitters=10, 
    upsampling=0, 
    mode='cnn', 
    model='small'
)
""" オプション変数の説明
jitters                     ゆらぎ値。ランダムにスケールアップや色の修正をして平均値を返す。デフォルト値 0
upsampling                  サンプリング指定値。0 の時 80x80 ピクセルで顔探索をする。1 では 40x40 ピクセル。デフォルト値：0
mode                        CNN, HOG 両形式を指定する。顔検出しにくい場合は'cnn'を指定する。デフォルト値：'hog'
model                       small -> 5-points method, large -> 68-points method　デフォルト値：'small' """

face_attestation() 関数の場合

xs = f.face_attestation(
    kaoninshoDir, 
    known_face_encodings, 
    known_face_names, 
    tolerance=0.5, 
    jitters=0,
    upsampling=0,
    mode='cnn', 
    model='small',
    frame_skip=0,
    movie='test.mp4',
    rectangle='false',
    target_rectangle='true',
    show_video='true',
    frequency_crop_image=2
)
""" オプション変数の説明
jitters                     ゆらぎ値。ランダムにスケールアップや色の修正をして平均値を返す。デフォルト値 0
upsampling                  サンプリング指定値。0 の時 80x80 ピクセルで顔探索をする。1 では 40x40 ピクセル。デフォルト値：0
mode                        CNN, HOG 両形式を指定する。顔検出しにくい場合は'cnn'を指定する。デフォルト値：'hog'
model                       small -> 5-points method, large -> 68-points method　デフォルト値：'small'
tolerance                   閾値。顔認証の厳格さを指定する。低いほど厳格。デフォルト値：0.5
frame_skip                  フレームドロップの割合。入力が 30fps の場合 frame_skip=2 では 15fps となる
                            マシン速度によって調節すること。デフォルト値：0
movie                       動画入力元を test.mp4 と USB カメラの 2 種類から選ぶ。デフォルト値：'test.mp4'
rectangle                   顔周囲に四角枠（直接描画）を描画するか否かを指定。デフォルト値：'false'
target_rectangle            顔周囲に四角枠（png画像）を描画するか否かを指定。デフォルト値：'true'
show_video                  openCV 由来の GUI による動画表示の有無。デフォルト値：'true'
frequency_crop_image        フレームをいくつ飛ばして output するか調節する。frame_skip値に影響される。デフォルト値：10 """

返り値

(name, pict, date, img, location, percentage) = (x['name'], x['pict'], x['date'], x['img'], x['location'], x['percentage'])

• name
  顔認証処理の結果返される名前。未登録の顔の場合は「Unknown」
• pict
  出力される顔画像ファイル名
• date
  顔認証処理された日付時刻
• img
  numpy 配列で返されるフレーム画像
• location
  顔が存在する座標
• percentage
  顔認証処理により何 % の確率でその人物か数値で返す

まとめ

• 顔認証が顔を識別する仕組み
• 許容値、ゆらぎ値について
• 顔認証、マスクをつけたらどうなるの？
• マスクをした顔を正しく判断！ 精度の違いは？

上記リンク先も参照してください。

今回の変更により、現場でマスクあり・なしの状況変化や使用するコンピュータの負荷、テスト使用か Web カメラ入力かに柔軟に対応できるようするなど様々なアップデートを施しました。
変更できるオプション変数が多いため、バージョン1.2.0から設定ウィンドウを使って勘弁に指定できるようにしました。

もし疑問点・不明な点があればお問い合わせからご連絡いただけると幸いです。

Follow me!

@dFtXsgqfJ4mH4ON