OpenCV の YuNet によるリアルタイム顔検出
OpenCV の YuNet 検出器を使い、動画プレビューに顔の枠と 5 つの顔ランドマークを描画します。以下の Python の例では、ローカル動画ファイル、またはオプションで Web カメラを処理します。検出結果は元のフレームに対応づけたまま扱い、停止時にキャプチャーを解放します。
リアルタイム顔検出を使う理由は?
ストリーミングプレビューでは、顔の移動、消失、縮小に伴う検出結果の変化を確認できます。YuNet は顔の位置を検出しますが、人物を識別したり、フレーム間で人物を追跡したりはしません。ループがライブ映像の速度に追従できるかどうかは、ハードウェアと入力解像度に依存します。
環境のセットアップ
この Bash の手順は、Linux 上で Python 3.11.2、GUI 版の opencv-python 4.13.0.92、NumPy 2.2.6 を使ってテストしました。これらはテスト済みのバージョンであり、必須の最小バージョンではありません。venv と pip を備えた
python3 のインストールと、動作するデスクトップディスプレイが必要です。ほかの OS は、この手順のテスト対象外です。
バージョンの固定は、2023 年 3 月のモデルと OpenCV 4.x を意図的に組み合わせるためです。OpenCV 5 も利用できますが、その ONNX Runtime エンジンで可変画像サイズを扱うには、新しい動的形状の YuNet エクスポートが必要です。YuNet モデルリポジトリを参照してください。モデルとランタイムを組み合わせてテストせずに、この例をアップグレードしないでください。
yunet-stream を作成するディレクトリで、次のブロックを貼り付けて実行します。サブシェルで実行するため、成功しても失敗しても、元のシェルのディレクトリは変わりません。同名のプロジェクトがすでにある場合は処理を拒否します。
(
set -eu
command -v python3 >/dev/null || { printf '%s\n' 'Install Python with venv and pip first.' >&2; exit 1; }
mkdir yunet-stream &&
cd yunet-stream &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'opencv-python==4.13.0.92' 'numpy==2.2.6' &&
.venv/bin/python - <<'PY'
from hashlib import sha256
from pathlib import Path
from urllib.request import urlopen
revision = '47534e27c9851bb1128ccc0102f1145e27f23f98'
filename = 'face_detection_yunet_2023mar.onnx'
url = f'https://media.githubusercontent.com/media/opencv/opencv_zoo/{revision}/models/face_detection_yunet/{filename}'
with urlopen(url, timeout=60) as response:
data = response.read()
expected = '8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4'
if sha256(data).hexdigest() != expected:
raise SystemExit('Model checksum mismatch; do not run this download.')
Path(filename).write_bytes(data)
PY
)
セットアップに失敗した場合は、作成途中のディレクトリを確認し、新しいプロジェクト名を選んでから再実行します。その際は mkdir と cd の両方を変更してください。このブロックは既存のファイルを削除しません。新しい仮想環境により、ほかの OpenCV インストールの影響をこの手順から排除します。OpenCV Python パッケージガイドでは、ディストリビューションを一つだけ選ぶ必要があります。また、ヘッドレスパッケージではこのプレビューウィンドウを表示できません。モデルのダウンロードには 60 秒のソケットタイムアウトがあります。タイムアウトやチェックサムの不一致が発生すると、モデルファイルを正式な保存先に配置する前にセットアップが停止します。接続を確認してから、新しいディレクトリで再試行してください。
基本的なストリーミング顔検出パイプラインの構築
次のプログラム全体を yunet-stream/stream.py として保存します。検出器を一つだけ使って逐次処理し、OpenCV の処理を一つのスレッドに制限します。動画のデコードと GUI はそれぞれ独自のスレッドを持つ場合がありますが、アプリケーションのワーカーキューはありません。
import argparse
import sys
from time import perf_counter
import cv2
import numpy as np
def draw_faces(frame, faces):
if faces is None:
return
for face in faces:
x, y, width, height = face[:4].astype(np.int32)
cv2.rectangle(frame, (x, y), (x + width, y + height), (0, 255, 0), 2)
for point in face[4:14].astype(np.int32).reshape(-1, 2):
cv2.circle(frame, tuple(point), 2, (0, 255, 255), -1)
def run(args):
cv2.setNumThreads(1)
capture = None
displayed = inferred = 0
inference_seconds = loop_seconds = 0.0
source = args.video if args.video is not None else args.camera
try:
detector = cv2.FaceDetectorYN.create(
args.model, '', (320, 320), args.score, args.nms, 5000
)
capture = cv2.VideoCapture(source)
if not capture.isOpened():
raise RuntimeError(f'Could not open capture: {source!r}')
while True:
started = perf_counter()
valid, frame = capture.read()
if not valid:
if displayed == 0 or args.camera is not None:
raise RuntimeError(f'Capture stopped without a usable frame: {source!r}')
print('File capture ended; EOF and decode failure share this signal.')
break
if frame is None or frame.size == 0:
raise RuntimeError(f'Capture returned an empty frame: {source!r}')
# Results belong only to this decoded frame, including skipped frames.
faces = None
if displayed % args.every == 0:
height, width = frame.shape[:2]
small_width = round(width * args.scale)
small_height = round(height * args.scale)
if min(small_width, small_height) < 32:
raise RuntimeError('Scaled frames must be at least 32 by 32 pixels.')
small = cv2.resize(frame, (small_width, small_height))
detector.setInputSize((small_width, small_height))
inference_started = perf_counter()
_, faces = detector.detect(small)
inference_seconds += perf_counter() - inference_started
inferred += 1
if faces is not None:
faces[:, 0:14:2] *= width / small_width
faces[:, 1:14:2] *= height / small_height
draw_faces(frame, faces)
cv2.imshow('YuNet stream', frame)
key = cv2.waitKey(1) & 0xFF
displayed += 1
loop_seconds += perf_counter() - started
if key == ord('q'):
break
finally:
if capture is not None:
capture.release()
cv2.destroyAllWindows()
print(f'Frames displayed: {displayed}; frames inferred: {inferred}')
if inferred:
print(f'Mean detect() time: {1000 * inference_seconds / inferred:.2f} ms')
if loop_seconds > 0:
print(f'Capture-to-display loop: {displayed / loop_seconds:.2f} frames/s')
if args.video is not None:
print('File feed is unpaced; these timings do not prove webcam performance or accuracy.')
def main():
parser = argparse.ArgumentParser(description='Preview YuNet face detections.')
source = parser.add_mutually_exclusive_group(required=True)
source.add_argument('--video', help='Local video filename, not a camera index.')
source.add_argument('--camera', type=int, help='Camera device index.')
parser.add_argument('--model', default='face_detection_yunet_2023mar.onnx')
parser.add_argument('--scale', type=float, default=1.0)
parser.add_argument('--every', type=int, default=1)
parser.add_argument('--score', type=float, default=0.9)
parser.add_argument('--nms', type=float, default=0.3)
args = parser.parse_args()
if not 0 < args.scale <= 1 or args.every < 1:
parser.error('--scale must be in (0, 1] and --every must be positive.')
if not 0 < args.score <= 1 or not 0 < args.nms <= 1:
parser.error('--score and --nms must be in (0, 1].')
if args.camera is not None and args.camera < 0:
parser.error('--camera must be nonnegative.')
run(args)
if __name__ == '__main__':
try:
main()
except KeyboardInterrupt:
print('Stopped by Ctrl+C.', file=sys.stderr)
sys.exit(130)
except cv2.error:
print('OpenCV failed. Check the model, decoded frames, and display.', file=sys.stderr)
sys.exit(1)
except RuntimeError as error:
print(str(error), file=sys.stderr)
sys.exit(1)
OpenCV でデコードできるローカル動画を yunet-stream/input.mkv に配置し、親ディレクトリで次のブロックを貼り付けて実行します。スペースを含むファイル名も、引用符で囲まれた一つの引数として扱われます。
(
cd yunet-stream &&
.venv/bin/python stream.py --video './input.mkv'
)
YuNet stream ウィンドウには、検出した顔の緑色の枠と黄色のランドマークが表示されます。顔がないフレームには注釈を付けません。このウィンドウにフォーカスを移し、q を押すか、ターミナルで Ctrl+C を押すと停止します。少なくとも一つのフレームを読み込んだ後、ファイルの読み取りが false を返すとループが終了します。OpenCV は EOF とデコード失敗に同じシグナルを使うため、録画の完全性を検証するものではありません。キャプチャーを利用できない場合、空のフレームを受け取った場合、モデルエラーが発生した場合は、失敗として終了し、クリーンアップを実行します。
Web カメラを使う場合は、同じコマンド内の --video './input.mkv' の代わりに
--camera 0 を指定します。この方法には、カメラ、OS の権限、デスクトップディスプレイが必要です。ファイル入力の例は GUI ディスプレイを使って動作確認しましたが、実際の Web カメラからのキャプチャーは未検証です。ディスプレイがないと GUI バックエンドがプロセスを中断する場合があるため、起動前にこの前提条件を確認してください。
高度な使い方:複数の顔の処理とパラメーター調整
描画ヘルパーは、すでにすべての検出結果をループ処理します。各行には (x, y, width, height)、5 つの (x, y) ランドマーク、インデックス 14 のスコアが格納されます。詳細は
OpenCV 顔検出チュートリアルに記載されています。
スコアのしきい値を下げて試すには、動画用のコマンドに --score 0.7 を追加します。誤検出を含め、より多くの候補が残る可能性があります。--nms は重複の抑制を制御し、既定値は 0.3 です。top_k の固定値 5,000 は抑制前の候補数を制限するもので、5,000 個の顔の検出を保証するものではありません。設定を変更する前に、代表的な映像で検出結果を比較してください。
パフォーマンスの最適化
コマンドに --scale 0.5 --every 2 を追加すると、最初のフレームと、その後は 2 フレームごとに、縮小した画像で推論します。プレビューには引き続き、デコードしたすべてのフレームを表示します。スキップしたフレームには注釈を付けず、直前のフレームの検出結果も再利用しません。推論をスキップしてもデコードはスキップせず、追跡も行いません。そのため、短時間だけ映った顔を見逃す可能性があります。
コードでは、リサイズ後の実際の幅と高さを使って、枠とランドマークを元の座標に戻します。奇数の寸法で丸め方に差が出る場合は、縦横それぞれの比率が重要です。また、縮小すると小さな顔を検出しにくくなる場合があります。計測によって別の設計が妥当と判断できるまでは、一つの検出器による逐次処理を維持してください。変更可能な入力サイズを並行呼び出し間で共有するには、別途、同期方針が必要です。
実用例:セキュリティ監視
顔のプレビューは、監視アプリケーションを構築する前に映像を確認するのに役立ちます。このプログラムは、訪問者の識別、動画の録画、検出結果の永続化、アラートの送信を行いません。処理したフレーム内の顔の数は、重複を除いた人数ではありません。また、結果が空だったりスキップされたりしても、その場を誰も通らなかったとは断定できません。
パフォーマンス上の考慮事項
ターミナルには、detect() に費やした平均時間と、キャプチャーから表示までのループのスループットが別々に表示されます。ループの計測には、キャプチャー、リサイズ、対象フレームでの推論、描画、GUI イベント処理が含まれます。モデルの初期化と最後のクリーンアップは含まれません。ファイル入力は再生速度を調整せずに処理するため、そのスループットは録画のフレームレートやライブカメラの遅延を表しません。
動画ファイルでの実行では、キャプチャー、推論、表示を確認します。Web カメラの性能や検出精度を実証するものではありません。対象のハードウェアと解像度で計測したうえで、難しい照明条件、遮蔽、小さな顔、顔が映る状態から顔がない状態への遷移を確認してください。推論時間が短いという計測結果だけでは、アプリケーション全体がリアルタイム動画の処理を維持できるとはいえません。
まとめ
新しい入力映像を使う前に、原寸で枠とランドマークを確認し、使用予定の縮小やスキップのオプションを指定して再確認してください。モデルや OpenCV のバージョンを変更するときに繰り返し確認できるよう、ファイルでの実行を残しておきます。ここで使ったキャプチャーと表示の API については、OpenCV 動画ガイドで説明されています。
