ドキュメント

HOME
ドキュメント
【ドキュメント】オプション変数・戻り値詳細 FACE01 GRAPHICS ver.1.2.8

2021年9月17日 / 最終更新日時 : 2021年10月2日 --- ドキュメント

【ドキュメント】オプション変数・戻り値詳細 FACE01 GRAPHICS ver.1.2.8

FACE01 GRAPHICSのオプション変数と戻り値について解説します。ここではFACE01 GRAPHICSバージョン1.2.8を例に取ります。

このバージョンでは設定ファイルとしてconfig_FACE01GRAPHICS128.iniが標準となりました。設定例の一例をご紹介します。

[DEFAULT]
; 指定した数値%以上を本人とする
similar_percentage=99.0
; 検出顔画像エンコーディング回数（削除予定・変更非推奨）
jitters=0
; 登録顔画像エンコーディング回数
priset_face_images_jitters=100
; 顔検出面積（0: 80x80px, 1: 40x40px）
upsampling=0
; 深層学習モデルを使い顔検出('hog' or 'cnn')
mode=cnn
; フレームドロップ指定（-1:自動）
frame_skip=-1
; 入力映像データ指定
movie=金正恩_ひとり.mp4
; 入力映像に対して処理対象エリアを指定
set_area=NONE
; 入力映像に対してリサイズする横幅指定
SET_WIDTH=600
; 顔領域にクラシックなな枠を表示
rectangle=False
; 顔領域にモダンな枠を表示
target_rectangle=True
; opencv-pythonによるウィンドウの描画
show_video=False
; 顔領域の自動保存
crop_face_image=False
; 顔領域自動保存の頻度（フレーム数指定）
frequency_crop_image=80
; デフォルト顔画像の描画
default_face_image_draw=True
; 情報を半透明で表示
show_overlay=True
; 顔の下に%を表示
show_percentage=True
; 顔の下に名前を表示
show_name=True
; 入力映像データのプロパティを表示して終了
print_property=False
; 1フレーム処理にかかるミリ秒を標準出力
calculate_time=False
; 複数人検出された時に警告を出す
multiple_faces=False
; ウィンドウ下部に情報を表示
bottom_area=False

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

では一つづつオプション変数を確認していきましょう。

各オプション変数の働き

similar_percentage

[float]本人であるか何%で指定します。デフォルト値99.0

閾値(tolerance)から変更になりました。99.0%より低ければ他人と判断されます。

jitters

[int]ゆらぎ値。デフォルト値0

入力画像を受け取り、色を乱し、ランダムな移動、回転、スケーリングを適用します。この変数の変更は処理速度に大きく影響します。リアムタイム性を重視する場合通常は0、大きな値でも10程度に押さえたほうがよろしいでしょう。もし100にした場合、速度は100分の1になるかわりに認証精度が5%程度向上します。

jitters の値を大きくするほどランダムな変換の平均値をとるようになります。
しかしながら大きな値をとることによって処理時間が長くなりリアルタイム性は損なわれます。

（参照箇所：…/dlib/python_examples/face_jitter.py）

priset_face_images_jitters

[int]登録顔画像のゆらぎ値。デフォルト値100

入力画像を受け取り、色を乱し、ランダムな移動、回転、スケーリングを適用します。

登録顔画像の計算は最初の1回しか行われないためデフォルト値を100としています。NVIDIA製GPUカードが必須です。

upsampling

[int]最小顔検出範囲。デフォルト値0

1フレームの画像のうち、顔探索するピクセル範囲を決定する変数。
80×80では80X80ピクセル位上の範囲を、40×40 ピクセルでは40X40ピクセル以上の範囲を顔探索します。

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

mode

[string]顔検出方式。デフォルト値cnn

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

HOG方式はマスクをした顔の検出を苦手とします。
マスクをした顔を顔検出する場合はCNN方式を選択すると良い結果を出します。CNNまたはHOGを指定する際は小文字にして下さい。

CNN方式にはNVIDIA GPUカードが必須です。

model

この変数設定は廃止されました。

frame_skip

[int]フレームドロップの割合。デフォルト値-1

-1を指定すると自動的にframe_skip値を内部で変更します。

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

処理速度を十分に満たさないマシンをご使用になる場合は-1以外を指定する必要があります。また自動処理の-1はRyzen1400/GeForce1660tiを基準に調整してあります。これよりマシンの処理速度が高い場合Webカメラやttp入力を除いて入力映像が早送りになる場合があります。この場合もframe_skipの値を適切なものに変更してください。

movie

[string]入力映像を指定します。デフォルト値test.mp4

動画ファイル（mp4, aviなど）、Webカメラ、httpプロトコルを使ったストリームのうちから指定します。

入力映像元をhogefuga.mp4ファイルにする場合、hogefuga.mp4を指定します。Webカメラを用いる時は0(int)を指定します。まれに0を指定した場合でもWebカメラが繋がらないバグが報告されておりましたがこのバグについてはFACE01 GRAPHICS ver.1.2.6以降にフィックスされました。

set_area

[string]入力された映像のうち処理する範囲を限定します。入力映像のうち一部分しか使いたくない場合に使用します。デフォルト値NONE

NONE, TOP_LEFT, TOP_RIGHT, CENTER, BOTTOM_LEFT, BOTTOM_RIGHTから指定します。下図のようになります。

SET_WIDTH

[int]入力映像をリサイズします。デフォルト値800

マシンの処理性能や作成するアプリケーションにあわせて設定して下さい。

rectangle, target_rectangle

[boolean]顔枠表示指定。顔周囲に枠を描画するかどうか・どの様な枠にするかを指定します。

デフォルト値 rectangle=False, target_rectangle=True

rectangle=True; target_rectangle=False
四角形を描画する
rectangle=False; target_rectangle=True
通常枠を描画する
rectangle=False; target_rectangle=False
枠を表示しない

FACE01 GRAPHICS通常表示 — rectangle=False; target_rectangle=True

show video

[boolean]openCV 由来のウィンドウ表示をするかしないかを選べます。デフォルト値False

crop_face_image

[boolean]顔領域の自動保存。デフォルト値True

frequency_crop_image

[int]n 枚のフレームごとに 1 つの顔画像ファイルを出力することを指定。デフォルト値80

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

default_face_image_draw

[boolean]デフォルト顔画像の描画を指定します。デフォルメ値True

show_overlay

[boolean]情報を半透明で表示します。デフォルト値True

show_percentage

[boolean]顔の下に%を表示します。デフォルト値True

show_name

[boolean]顔の下に氏名を表示します。デフォルト値True

print_property

[boolean]入力映像のプロパティを表示して終了します。デフォルト値False

fps:  29
frame shape:  (517, 600, 3)
dtype:  uint8
frame size:  930600

calculate_time

[boolean]シングルコア処理下での1フレームにかかる処理時間を計測します。デフォルト値False

通常はマルチコアを使用（並行処理）したりマルチスレッドを使用（並列処理）前提で設定ファイルを書きますのでここで出る値がそのまま使えるわけではありません。目安としてお使い下さい。

multiple_faces

[boolean]複数人検出された時に警告を出し顔認証処理をスキップします。デフォルト値False

bottom_area

[boolean]ウィンドウ下部に情報を表示します。デフォルト値False

戻り値

FACE01 GRAPHICS ver.1.2.8のface_attestation()メソッドから得られる戻り値はジェネレーターオブジェクトであり反復処理によって辞書の集合を得られます。

辞書のキーは以下のとおりです。

name, pict, date, img, location, percentage_and_symbol, stream

以下のコードによりそれぞれの値が得られます。

# 抜粋
for array_x in xs:
    for x in array_x:
        print(f"name: {x['name']}")
        print(f"pict: {x['pict']}")
        print(f"date: {x['date']}")
        print(f"location: {x['location']}")
        print(f"percentage: {x['percentage_and_symbol']}")
        print(f"img: {x['img']}")
        
# 出力結果
name: 安倍晋三
pict: output/安倍晋三_99.6%_2021,08,13,13,34,52,183913_0.24.png
date: 2021,08,13,13,34,52,183913
location: (92, 283, 171, 204)
percentage: 99.6%
img: [[[108  94  62]
  [108  94  62]
  [ 82  94  93]
  ...