YuNet と CLI 自動化による画像・動画への顔検出枠の描画
YuNet は OpenCV で利用できるコンパクトな顔検出器です。小さな CLI で、ローカルの画像や固定フレームレートの短い動画を処理し、検出した顔を緑色の枠で囲めます。以下の例では、デコード後の画像の寸法を維持し、バッチ入力ごとに個別の出力を生成します。検出するのは顔に似た領域であり、個人の識別や認証の判定は行いません。
YuNet の概要
YuNet は、顔と顔のランドマークを検出するための、CPU 向けの軽量な選択肢です。精度と速度は、画像サイズ、顔のサイズ、姿勢、照明、しきい値、ハードウェアによって異なります。モデルの公開評価は、OpenCV Zoo のモデルドキュメントを参照してください。このチュートリアルはローカルファイルを処理するもので、カメラのリアルタイム処理性能を実証するものではありません。
YuNet の簡単なセットアップ
Linux 上の Bash、venv と pip を備えた Python、cURL、ハードリンクに対応したファイルシステムを使用します。このチュートリアルは Linux x86-64 上で、Python 3.14.7、opencv-python-headless 5.0.0.93 の wheel(OpenCV 5.0.0)、NumPy 2.4.6 を使用してテストしています。Python のパッチバージョンと wheel のビルドは、テスト済みの固定バージョンです。動画処理では OpenCV 5 のブール値の書き込みステータスを使用します。サポート対象の Python リリースと、パッケージのリリースページにある互換性のある wheel を使用してください。それ以外のランタイムとプラットフォームの組み合わせは、個別に検証する必要があります。
空の作業ディレクトリから始めてください。この CLI は GUI ウィンドウを開かないため、ヘッドレス版の wheel をインストールします。OpenCV の wheel は
cv2 名前空間を共有します。環境ごとに一種類だけインストールしてください。
(
set -e
command -v python3 >/dev/null || { printf 'Missing prerequisite: python3\n' >&2; exit 1; }
if [ -e venv ] || [ -L venv ]; then
printf 'Choose a fresh directory; venv already exists\n' >&2
exit 1
fi
python3 -m venv venv
venv/bin/python -m pip install opencv-python-headless==5.0.0.93 numpy==2.4.6
)
括弧によって、失敗時の処理がサブシェル内に収まります。環境の作成に失敗すると、インストール前に停止します。インストールに失敗すると、不完全な
venv が残る場合があります。その環境は再利用せず、新しい空のディレクトリで続けてください。以下の各コマンドはインタープリターを明示するため、環境を有効化する必要はありません。
固定した OpenCV Zoo のリビジョンからテスト済みモデルのバイト列をダウンロードし、チェックサムを検証してから、スクリプトが使用するファイル名で配置します。
(
set -e
for tool in curl mktemp ln rm; do
command -v "$tool" >/dev/null || { printf 'Missing prerequisite: %s\n' "$tool" >&2; exit 1; }
done
test -x venv/bin/python
if [ -e face_detection_yunet.onnx ] || [ -L face_detection_yunet.onnx ]; then
printf 'Model already exists; verify it or choose a fresh directory\n' >&2
exit 1
fi
model_tmp=$(mktemp './.yunet-model.XXXXXX')
trap 'rm -f "$model_tmp"' EXIT
curl -fsSLo "$model_tmp" \
https://media.githubusercontent.com/media/opencv/opencv_zoo/47534e27c9851bb1128ccc0102f1145e27f23f98/models/face_detection_yunet/face_detection_yunet_2023mar.onnx
venv/bin/python - "$model_tmp" <<'PY'
import hashlib
from pathlib import Path
import sys
expected = '8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4'
if hashlib.sha256(Path(sys.argv[1]).read_bytes()).hexdigest() != expected:
sys.exit('Unexpected model checksum')
PY
ln "$model_tmp" face_detection_yunet.onnx
)
モデルは 232,589 バイトです。リクエストやチェックサムの検証に失敗すると、一時ダウンロードファイルが削除され、最終的なファイル名のファイルは作成されません。失敗の原因を解消してから、同じブロックを再実行してください。既存のモデルは保持されます。以下の三つのスクリプトすべてと同じディレクトリにモデルを配置してください。
単一画像の顔検出の自動化
共通実装を face_tools.py として保存してください。OpenCV の FaceDetectorYN API では、入力サイズを受け取るフレームのサイズと一致させる必要があります。ヘルパーは推論用フレームをリサイズし、検出枠を元の画像の縮尺に戻して描画します。
from contextlib import contextmanager
import math
import os
from pathlib import Path
from tempfile import TemporaryDirectory
# Set before importing OpenCV so image decoding has an explicit pixel ceiling.
os.environ.setdefault('OPENCV_IO_MAX_IMAGE_PIXELS', '20000000')
import cv2
MODEL_PATH = Path(__file__).with_name('face_detection_yunet.onnx')
def create_detector():
return cv2.FaceDetectorYN.create(str(MODEL_PATH), '', (320, 320), 0.9, 0.3, 5000)
def annotate(detector, image, max_side=960):
height, width = image.shape[:2]
if width * height > 20_000_000:
raise ValueError('Frame exceeds the pixel limit')
scale = min(1.0, max_side / max(width, height))
small = cv2.resize(image, (max(1, round(width * scale)), max(1, round(height * scale))))
detector.setInputSize((small.shape[1], small.shape[0]))
_, faces = detector.detect(small)
count = 0 if faces is None else len(faces)
if faces is not None:
scale_x = width / small.shape[1]
scale_y = height / small.shape[0]
for face in faces:
x, y, w, h = face[:4]
left, top = max(0, round(x * scale_x)), max(0, round(y * scale_y))
right = min(width - 1, round((x + w) * scale_x))
bottom = min(height - 1, round((y + h) * scale_y))
cv2.rectangle(image, (left, top), (right, bottom), (0, 255, 0), 2)
return image, count
@contextmanager
def new_output(path):
output = Path(path).absolute()
if output.exists() or output.is_symlink():
raise ValueError('Output must not exist')
with TemporaryDirectory(prefix='.face-output-', dir=output.parent) as temporary:
candidate = Path(temporary) / ('result' + output.suffix)
yield candidate
if not candidate.is_file() or candidate.stat().st_size == 0:
raise ValueError('No nonempty output produced')
os.link(candidate, output)
def detect_image(detector, source, output):
source = Path(source)
if source.suffix.lower() not in {'.jpg', '.jpeg', '.png'}:
raise ValueError('Use a JPEG or PNG image')
if not source.is_file() or source.stat().st_size > 50 * 1024 * 1024:
raise ValueError('Use a regular image file no larger than 50 MiB')
image = cv2.imread(str(source))
if image is None:
raise ValueError('Cannot decode image')
annotated, count = annotate(detector, image)
with new_output(output) as candidate:
if not cv2.imwrite(str(candidate), annotated):
raise ValueError('Cannot encode output image')
return count
def detect_video(detector, source, output):
if not Path(source).is_file():
raise ValueError('Use a local video file')
capture = cv2.VideoCapture(str(Path(source).absolute()))
writer = None
frames = 0
detections = 0
try:
if not capture.isOpened():
raise ValueError('Cannot open video')
fps = capture.get(cv2.CAP_PROP_FPS)
width = int(capture.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(capture.get(cv2.CAP_PROP_FRAME_HEIGHT))
if not math.isfinite(fps) or fps <= 0 or width <= 0 or height <= 0:
raise ValueError('Invalid video timing or dimensions')
if width * height > 20_000_000 or width % 2 or height % 2:
raise ValueError('Use bounded, even video dimensions')
with new_output(output) as candidate:
writer = cv2.VideoWriter(str(candidate), cv2.VideoWriter_fourcc(*'mp4v'), fps, (width, height))
if not writer.isOpened():
raise ValueError('Cannot open video encoder')
while True:
ok, frame = capture.read()
if not ok:
break
if frame.shape[:2] != (height, width):
raise ValueError('Frame dimensions changed')
annotated, count = annotate(detector, frame)
if not writer.write(annotated):
raise ValueError('Cannot encode video frame')
frames += 1
detections += count
writer.release()
writer = None
if frames == 0:
raise ValueError('No frames decoded')
return frames, detections
finally:
capture.release()
if writer is not None:
writer.release()
呼び出し側のコードを、同じディレクトリに detect_faces.py として保存してください。
import argparse
import sys
from face_tools import create_detector, detect_image, detect_video
import cv2
parser = argparse.ArgumentParser()
parser.add_argument('mode', choices=['image', 'video'])
parser.add_argument('input')
parser.add_argument('output')
args = parser.parse_args()
try:
detector = create_detector()
if args.mode == 'image':
print(f'Detected {detect_image(detector, args.input, args.output)} faces')
else:
frames, detections = detect_video(detector, args.input, args.output)
print(f'Processed {frames} frames with {detections} face detections')
except (OSError, ValueError, cv2.error):
sys.exit(f'{args.input}: Face detection failed; check input, model, codec, and destination')
手元の JPEG または PNG を指定して venv/bin/python detect_faces.py image photo.jpg annotated.jpg を実行してください。結果を開き、想定した顔が緑色の枠で囲まれていることを確認します。有効な画像で顔が検出されなかった場合も、出力は生成され、検出数はゼロと報告されます。出力には .jpg または .png を使用し、親ディレクトリを先に作成してください。既存の出力先への書き込みは拒否されます。
OpenCV は、これらの画像を 8 ビットのカラーピクセルとしてデコードします。透明度、より高いビット深度、カラープロファイル、元のメタデータは保持されません。寸法は、OpenCV による自動的な EXIF 方向補正を含む、デコード後の画像の寸法を指します。JPEG 出力は非可逆です。枠の外側のピクセルを変更したくない場合は PNG を使用してください。テストでは、末尾のバイトを削除した JPEG でも、欠落したピクセルが補完されて正常にデコードされました。端も含めて画像全体を確認し、破損のない信頼できる入力を使用してください。この CLI は入力の完全性を検証しません。
フォルダーのバッチ処理
フォルダー直下の JPEG と PNG ファイルに対して、一つの検出器を順次再利用します。以下を batch_detect.py として保存してください。
import argparse
from pathlib import Path
import sys
from face_tools import create_detector, detect_image
import cv2
parser = argparse.ArgumentParser()
parser.add_argument('input_directory')
parser.add_argument('output_directory')
args = parser.parse_args()
try:
source = Path(args.input_directory)
images = sorted(path for path in source.iterdir() if path.is_file() and not path.is_symlink()
and path.suffix.lower() in {'.jpg', '.jpeg', '.png'})
if not images:
sys.exit('No supported images found')
detector = create_detector()
output = Path(args.output_directory)
output.mkdir(mode=0o700)
failures = 0
for image in images:
try:
count = detect_image(detector, image, output / (image.name + '.jpg'))
print(f'{image.name}: {count} faces')
except (OSError, ValueError, cv2.error):
failures += 1
print(f'Failed: {image.name}', file=sys.stderr)
sys.exit(1 if failures else 0)
except (OSError, ValueError, cv2.error):
sys.exit('Cannot prepare batch; check model and directories')
venv/bin/python batch_detect.py images new-results を実行してください。結果用ディレクトリは新規である必要があります。拡張子の照合では大文字と小文字を区別せず、ファイル名順に処理し、サブフォルダーとシンボリックリンクのエントリーはスキップします。元のファイル名全体に .jpg を追加するため、photo.jpg と photo.png からは、それぞれ photo.jpg.jpg と photo.png.jpg が生成されます。失敗したファイル名は標準エラー出力に表示され、バッチの終了ステータスが非ゼロになります。成功した結果は引き続き利用できます。再試行時は、別の新しい結果用ディレクトリを使用してください。
スペースを含むパスは引用符で囲んでください。入力名や出力先名がハイフンで始まる場合は、./-photo.png のようなパスを渡し、argparse が名前をオプションとして解釈しないようにしてください。
動画ストリームの処理
デコード後の縦横の寸法が偶数である、ローカルの短い固定フレームレート動画に対して、venv/bin/python detect_faces.py video input.mp4 annotated.mp4 を実行してください。出力には検出枠を描画した動画だけが含まれ、音声はコピーされません。検出数の合計は、異なる人物の人数ではなく、フレーム全体で観測した検出数です。可変フレームレートのタイミングやライブカメラの再接続には、別のワークフローが必要です。
OpenCV でのフレーム読み取り失敗は、ファイルの終端またはデコーダーの問題を意味します。後半のパケットの途中で切り詰めたテストクリップでは、短くなった再生可能な結果と成功メッセージが得られました。固定バージョンのライターはフレームごとにステータスを返し、この CLI はそれを確認しますが、一部のバックエンドではベストエフォートの成功しか報告されません。結果と元の動画のデコード後のフレーム数とフレームレートを比較し、再生時間がフレーム数をフレームレートで割った値であることを確認して、冒頭と末尾を再生してください。成功メッセージだけでは、メディアの完全性を証明できません。回転メタデータによって符号化上の寸法が変わる場合があります。表示されるデコード後のフレームを比較してください。出力では、その向きに補正された状態で符号化されます。
リアルタイム処理に向けた速度調整
max_side の値を annotate 内で小さくして、推論用フレームを実際にリサイズし、小さい顔や遠くの顔でトレードオフを測定してください。ワーカープロセスごとに一つの検出器を保持し、同時呼び出し間で共有しないでください。CPU 用の wheel で CUDA サポートが自動的に利用できるわけではありません。GPU アクセラレーションには、互換性のある OpenCV ビルドとハードウェアに加え、個別に検証したバックエンド設定が必要です。
信頼できないメディアには、隔離されたワーカーを使用し、ジョブ全体の時間、メモリ、ディスクの上限を設定してください。画像のバイト数とピクセル数のチェックでは、動画デコーダーによるすべてのメモリ割り当てや、合計処理時間までは制限できません。
YuNet が精度やレイテンシーの目標を満たさない場合は、同じ代表的な顔とハードウェアで別の検出器を比較してください。経過時間には、デコード、リサイズ、検出、エンコードを含めます。推論時間だけでは、パイプライン全体がライブソースの速度に追従できるかは判断できません。
マネージド型のビジョン処理ワークフローについては、Transloadit の人工知能サービスを参照してください。
