設定ファイル解説 FACE01 v2.0.02

ここではv2.0.02のFACE01_SAMPLE/docs/config_ini.mdの日本語訳と、簡単な説明をつけてご紹介したいと思います。

最新バージョンのドキュメントは以下からご覧になれます。

• FACE01_SAMPLE/docs/config_ini.md
  • FACE01の設定ファイルについてのドキュメントです。この記事で解説します。
• FACE01 Document
  • ミドルウェアに含まれる、全ての関数の包括的なドキュメントです。
• Step-by-step to use FACE01 library
  • はじめてFACE01を扱う方は、まずこちらのドキュメントをご覧ください。

config.ini を変更する前に、ConfigParser モジュールに精通している必要があります。ConfigParser モジュールを参照するには、以下を参照してください。
https://docs.python.org/3/library/configparser.html

config.iniの例

# License for the Code.
# 
# Copyright Owner: Yoshitsugu Kesamaru
# Please refer to the separate license file for the license of the code.


# -------------------------------------------------------
# This config.ini file is *ONLY FOR FACE01 v1.4.10* or later.
# -------------------------------------------------------


########################################################

# About config.ini

#    'config.ini' is the configuration file of FACE01 using 
#    Python ConfigParser module.
#    
#    The [DEFAULT] section specifies standard default values.
#    Each section inherits from the [DEFAULT] section.
#    Therefore, specify only items & values that override [DEFAULT] 
#    in each section.

#    Before modifying config.ini, you should be familiar with the 
#    ConfigParser module.
#    To refere ConfigParser module, see bellow.
#    https://docs.python.org/3/library/configparser.html

#    Document is bellow.
#    https://github.com/yKesamaru/FACE01_SAMPLE/blob/master/docs/config_ini.md#about-configini-file

# Note:
#    `number_of_people` and `same_time_recognize` in config.ini are disabled 
#     when using `mp_face_detection_func`.

########################################################


[DEFAULT]
# [DEFAULT] section is for simple example.
# This [DEFAULT] setting for only use CUI mode.
# Also, This setting is for user who's PC is not installed Nvidia GPU card.
# [DEFAULT] section is the inheritor of all sections.
headless = True
deep_learning_model = 0
anti_spoof = False
output_debug_log = False
log_level = info
set_width = 750
similar_percentage = 99.1
jitters = 0
preset_face_images_jitters = 10
upsampling = 0
mode = hog
frame_skip = 5
number_of_people = 10
use_pipe = False
model_selection = 0
min_detection_confidence = 0.6
person_frame_face_encoding = False
same_time_recognize = 2
set_area = NONE
movie = ../FACE01_IOT_dev_assets/test.mp4
user = 
passwd = 
rectangle = False
target_rectangle = False
draw_telop_and_logo = False
default_face_image_draw = False
show_overlay = False
alpha = 0.3
show_percentage = False
show_name = False
crop_face_image = True
frequency_crop_image = 5
crop_with_multithreading = False
Python_version = 3.8.10
cpu_freq = 2.5
cpu_count = 4
memory = 4
gpu_check = True
calculate_time = False
show_video = False
number_of_crops = 0


[CUDA]
# This [CUDA] setting is example which for use not only CUI mode but also GUI mode.
# [CUDA] section inherits from the [DEFAULT] section.
# Also, This setting is for user who's PC is installed Nvidia GPU card and
# assuming Nvidia's proprietary driver is properly installed.
preset_face_images_jitters = 100
mode = cnn


[DISPLAY_GUI]
# [DISPLAY_GUI] section is example for display window.
# [DISPLAY_GUI] section inherits from the [DEFAULT] section.
headless = False
preset_face_images_jitters = 100
mode = cnn
use_pipe = False
same_time_recognize = 3
movie = ../FACE01_IOT_dev_assets/some_people.mp4
target_rectangle = True
show_overlay = True
show_percentage = True
show_name = True


[bug_DISPLAY_GUI]
# [DISPLAY_GUI] section is example for display window.
# [DISPLAY_GUI] section inherits from the [DEFAULT] section.
headless = False
preset_face_images_jitters = 100
mode = cnn
use_pipe = False
same_time_recognize = 3
; movie = ../FACE01_IOT_dev_assets/biyouseikei.mp4
movie = ../FACE01_IOT_dev_assets/test_video_including_faceless_section.mp4
target_rectangle = True
show_overlay = True
show_percentage = True
show_name = True


[USB_CAMERA]
# [USB_CAMERA] section is example for using USB camera.
# [USB_CAMERA] section inherits from the [DEFAULT] section.
headless = False
preset_face_images_jitters = 100
mode = cnn
use_pipe = False
same_time_recognize = 3
movie = USB
target_rectangle = True
show_overlay = True
show_percentage = True
show_name = True


[HLS]
# [HLS] section is example for to use HTL (HTTP LIVE STREAMING).
# [HLS] section inherits from the [DEFAULT] section.
# User must define value (URL) to movie = '', otherwise the application will exit.
headless = False
preset_face_images_jitters = 100
mode = cnn
use_pipe = False
same_time_recognize = 3
movie = 
target_rectangle = True
show_overlay = True
show_percentage = True
show_name = True


[RTSP]
# [RTSP] section is example for to use RTSP (RAPID SPANNING TREE PROTOCOL).
# [RTSP] section inherits from the [DEFAULT] section.
# User must define values (URL, username, password) to movie = '', user = '', 
# and passwd = '' otherwise the application will exit.
headless = False
preset_face_images_jitters = 100
mode = cnn
use_pipe = False
same_time_recognize = 3
movie = 
user = 
passwd = 
target_rectangle = True
show_overlay = True
show_percentage = True
show_name = True


[FACE-COORDINATE]
headless = True
anti_spoof = False
output_debug_log = False
log_level = info
set_width = 750
similar_percentage = 99.1
jitters = 0
preset_face_images_jitters = 100
upsampling = 0
frame_skip = 5
use_pipe = False
number_of_people = 10
model_selection = 0
min_detection_confidence = 0.4
person_frame_face_encoding = False
same_time_recognize = 10
set_area = NONE
movie = ../FACE01_IOT_dev_assets/test.mp4
crop_face_image = True
frequency_crop_image = 5
crop_with_multithreading = False
number_of_crops = 0
show_overlay = True


[MAKE_QR_CODE]
headless = False
mode = cnn
frame_skip = 0
use_pipe = True
same_time_recognize = 1
movie = USB
target_rectangle = True
default_face_image_draw = True
show_overlay = True
alpha = 0.3
crop_face_image = False


[LIGHTWEIGHT_GUI]
# [LIGHTWEIGHT_GUI] section is example for to make LIGHTWEIGHT GUI application.
# [LIGHTWEIGHT_GUI] section inherits from the [DEFAULT] section.
headless = False
preset_face_images_jitters = 100
mode = cnn
use_pipe = False
same_time_recognize = 3
; target_rectangle = True
; show_overlay = True
; show_percentage = True
; show_name = True


[EFFICIENTNETV2_ARCFACE_MODEL]
deep_learning_model = 1
similar_percentage = 90.0


[EFFICIENTNETV2_ARCFACE_MODEL_GUI]
headless = False
frame_skip = 2
; movie = ../FACE01_IOT_dev_assets/some_people.mp4
; movie = ../FACE01_IOT_dev_assets/test_video_including_faceless_section.mp4
; movie = ../FACE01_IOT_dev_assets/ROMAN_HOLIDAY.mp4
; movie = ../FACE01_IOT_dev_assets/金正恩_ひとり.mp4
deep_learning_model = 1
similar_percentage = 90.0
target_rectangle = True
draw_telop_and_logo = True
default_face_image_draw = True
show_overlay = True
alpha = 0.3
show_percentage = True
show_name = True

[USER_SETTING]
# [USER_SETTING] section is for you're original section, and
# which inherits from the [DEFAULT] section.

About config.ini部分

この部分の日本語訳を下に記載します。

‘config.ini’は、PythonのConfigParserモジュールを使用して設定された
FACE01の設定ファイルです。

[DEFAULT]セクションは、標準のデフォルト値を指定します。
各セクションは[DEFAULT]セクションから継承されます。
したがって、各セクションで[DEFAULT]をオーバーライドする項目と値のみを指定します。

config.iniを変更する前に、ConfigParserモジュールについて理解しておく必要があります。
ConfigParserモジュールについて参照するには、以下をご覧ください。
https://docs.python.org/3/library/configparser.html

ドキュメントは以下です。
https://github.com/yKesamaru/FACE01_SAMPLE/blob/master/docs/config_ini.md#about-configini-file

注意:
number_of_peopleとsame_time_recognizeは、mp_face_detection_funcを使用する際に無効になります。

FACE01_SAMPLE/docs/config_ini.md

設定値の継承

各セクションは [DEFAULT] セクションから継承します。

そのため、各セクションで [DEFAULT] をオーバーライドする項目 (キーと値) のみを指定してください。

編集

docker Image を使用している場合は、config.ini を vim で編集して変更できます。

# Example
$ vim ./config.ini

各セクション別の解説

[DEFAULT]セクション

もっとも基本的な使用方法が設定されています。

この [DEFAULT] 設定は、CUI モードのみを使用します。そのため、この設定は、PC に Nvidia GPU カードがインストールされていないユーザー向けとして最適です。またIOT デバイス上で動作させるのにも役に立ちます。

headless

headless は「CUI モードで動作する」ことを意味します。 GUI ウィンドウを表示したい場合は、値を False に設定しますが、処理速度は遅くなります。

• Type: bool
• Default: True

deep_learning_model

• 従来のdlibモデル(汎用顔学習モデル: dlib_face_recognition_resnet_model_v1.dat)と日本人の顔認証に特化したモデル(JAPANESE FACE: efficientnetv2_arcface.onnx)を切り替えることが出来ます。
• int: 0 or 1
  • dlib_face_recognition_resnet_model_v1.dat: 0
    • 汎用顔学習モデルを使用する場合（マスクをした顔を藩閥したい場合）、0を指定します。
  • efficientnetv2_arcface.onnx: 1
    • 日本人の顔に対して精度を高めたい場合、1をしていします。

anti_spoof

• 将来、内部が置き換えられます。
• このサンプルにはなりすまし対策モデルが含まれていますが、このモデルをそのまま商用利用しないでください。詳しくは私達までお問い合わせください。
  • Type: bool
  • Default: False

output_debug_log

• Trueに設定すると、デバッグログが出力されます。
  • type: bool
  • Default: False

log_level

• デバッグログとメッセージを出力したい場合は、この値を debug に変更します。
  • Type: str
  • Default: info

set_width

• GUIウィンドウの幅を指定します。単位はpxです。
  • Type: int
  • Default: 750

similar_percentage

• 画面上の人物が、登録されている顔情報の人物であるかどうかを判定する閾値を、百分率で指定します。
  • Type: float
  • Default: 99.1

jitters

• FACE01 の実行時に、frame内に検出された顔領域に対して、ジッターを計算する回数を指定します。
  • Type: int
  • Default: 0

入力画像を受け取り、色を乱し、ランダムな移動、回転、スケーリングを適用します。
jittersの値を大きくするほどランダムな変換の平均値をとるようになります。
大きな値をとることによって入力画像が不確かなものになりやすく、また処理時間が長くなりますが、ロバスト性が高くなります。

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

preset_face_images_jitters

• peset_face_images のジッターをどれくらいの回数処理するか、その値を指定します。
  • Type: int
  • Default: 100

upsampling

• 検出した顔の領域を指定します。( 0: 80×80ピクセル、1: 40×40ピクセル)
  • Type: int
  • Default: 0

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

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

1フレームごとにより細かく顔探索するように指示するため、処理時間とトレードオフになります。

mode

• cnnモードはAIモデルから作成したモデルを使用します。 CUDA を使用しない場合は、hog を設定します。
  • Type: Type: str
  • Default: hog

顔検出方式。

顔検出に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を指定する際は小文字にして下さい。

frame_skip

• ドロップするフレーム数を指定します。 HLS を使用する場合は、2 未満にしないでください。
  • Type: int
  • Default: 5

フレームドロップの割合。

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

number_of_people

• Do not ‘analyze’ (Encode and Recognize Process) more than the specified number of people.
• Type: int
• Default: 10

use_pipe

• Use mediapipe for face detection (coordinate calculation) instead of dlib face detection model.
• Type: bool
• Default: True

model_selection

• O OR 1
  • 0: Within 2 meters from the camera,
  • 1: Within 5 meters.
• NOTE: This value is set only when use_pipe is True.
• Type: int
• Default: 1

min_detection_confidence

The minimum confidence value from the face detection model for the detection to be considered successful. If wearing the mask, set it to about 0.3. The lower the number, the higher the possibility of erroneous recognition other than the face. The standard is 0.4 to 0.5.

• NOTE: You can set person_frame_face_encoding to True only if use_pipe is True.
• Type: float
• Default: 0.4

person_frame_face_encoding

• You can set person_frame_face_encoding to True only if use_pipe is True.
• Type: bool
• Default: False

same_time_recognize

• Number of people to recognize at the same time. Default is 2. Valid only if use_pipe is True.
• Type: int
• Default: 2

set_area

• Zoom. You can select from NONE, TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT, CENTER.
• Type: Type: str
• Default: NONE

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

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

movie

• For test, you can select from bellow.
  • usb (or USB)
    • USB Cam
  • assets/test.mp4 (Only a person.)
  • assets/顔無し区間を含んだテスト動画.mp4
    • Movie file which contain no person frames.
  • rtsp://wowzaec2demo.Type: Type: streamlock.net/vod/mp4:BigBuckBunny_115k.mp4
    • RTSP Type: Type: stream for test.
  • http://219.102.239.58/cgi-bin/camera?resolution=750
    • Live Type: Type: stream using HTTP for test: Live cam at Tokyo.
• Type: Type: str
• Default: assets/test.mp4

user

• User ID for RTSP.
• Type: str
• Default: None

passwd

• User password for RTSP.
• Type: str
• Default: None

rectangle

• Display a legacy face frame on the screen.
• Type: bool
• Default: False

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

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

target_rectangle

• Display a modern face frame on the screen
• NOTE: You can select only one of rectangle or target_rectangle.
• Type: bool
• Default: False

draw_telop_and_logo

• Display of telop and log
• Type: bool
• Default: False

show_overlay

• Make the information display on the screen semi-transparent
• Type: bool
• Default: False

alpha

• Adjust the translucency of ‘overlay
• Type: float
• Default: 0.3

show_percentage

• Draw similarity in window.
• Type: bool
• Default: False

crop_face_image

• Save face image.
• Type: bool
• Default: True

frequency_crop_image

• Save face images per frame to storage.
• Type: int
• Default: 5

n 枚のフレームごとに 1 つの顔画像ファイルを出力することを指定。

frequency_crop_imageを指定することで運用するマシンのi/o速度がFACE01の処理速度に影響を与えることを抑える効果があると同時にoutputフォルダが顔画像ファイルであふれることを予防します。

crop_with_multithreading

• Save face images using multi-threading. If using slower storage, set ‘True’.
• Type: bool
• Default: False

まとめ

こちらのページもご参照下さい。もし疑問点・不明な点があればお問い合わせからご連絡いただけると幸いです。

最後までお読み頂きありがとうございました。