YuNet 顔検出の使い方【OpenCV/C++】〜DNNで高速顔検出〜
cv::FaceDetectorYN(YuNet)は、OpenCV 4.5.4 で objdetect モジュールに追加された DNN ベースの顔検出器です(本記事で使う 2023mar 版のモデルは OpenCV 4.8 以降が必要)。軽量モデルながら高い精度を持ち、CPU だけでもリアルタイムに近い速度で動作します。最小限の呼び出しは次の通りです。
auto detector = cv::FaceDetectorYN::create("face_detection_yunet_2023mar.onnx", "", inputSize);
detector->detect(image, faces);
動作環境
- OpenCV 4.8 以降(
cv::FaceDetectorYNが 2023mar 版モデルの出力形式に対応したバージョン) - コンパイル例:
g++ -std=c++17 main.cpp `pkg-config --cflags --libs opencv4` -o yunet_demo
環境構築がまだの方は環境構築ガイドを先にどうぞ。
基本の使い方
モデルファイルの入手
OpenCV の公式リポジトリからモデルを取得します。
wget https://github.com/opencv/opencv_zoo/raw/main/models/face_detection_yunet/face_detection_yunet_2023mar.onnx
完全サンプル
#include <opencv2/opencv.hpp>
#include <iostream>
int main(int argc, char* argv[])
{
if (argc < 2) {
std::cerr << "Usage: " << argv[0] << " <image_path>" << std::endl;
return 1;
}
// 画像読み込み
cv::Mat image = cv::imread(argv[1]);
if (image.empty()) {
std::cerr << "画像を読み込めませんでした: " << argv[1] << std::endl;
return 1;
}
const std::string modelPath = "face_detection_yunet_2023mar.onnx";
// YuNet 検出器を生成(入力サイズを画像サイズに合わせる)
cv::Ptr<cv::FaceDetectorYN> detector = cv::FaceDetectorYN::create(
modelPath,
"", // config: ONNX の場合は空文字
cv::Size(image.cols, image.rows),
0.9f, // スコア閾値
0.3f, // NMS 閾値
5000 // 検出上限数
);
if (detector.empty()) {
std::cerr << "モデルの読み込みに失敗しました: " << modelPath << std::endl;
return 1;
}
// 顔検出
cv::Mat faces;
detector->detect(image, faces);
// 検出数は faces の行数(detect の戻り値は検出数ではない)
std::cout << "検出数: " << faces.rows << std::endl;
// 結果を描画
for (int i = 0; i < faces.rows; ++i) {
// faces の各行: [x, y, w, h, 右目x, 右目y, 左目x, 左目y,
// 鼻x, 鼻y, 口右x, 口右y, 口左x, 口左y, score]
float x = faces.at<float>(i, 0);
float y = faces.at<float>(i, 1);
float w = faces.at<float>(i, 2);
float h = faces.at<float>(i, 3);
float score = faces.at<float>(i, 14);
cv::Rect faceRect(
static_cast<int>(x), static_cast<int>(y),
static_cast<int>(w), static_cast<int>(h)
);
cv::rectangle(image, faceRect, cv::Scalar(0, 255, 0), 2);
// 5 つのランドマーク(右目・左目・鼻・口右・口左)を描画
for (int j = 0; j < 5; ++j) {
float lx = faces.at<float>(i, 4 + j * 2);
float ly = faces.at<float>(i, 4 + j * 2 + 1);
cv::circle(image, cv::Point(static_cast<int>(lx), static_cast<int>(ly)),
3, cv::Scalar(0, 0, 255), cv::FILLED);
}
// スコアを矩形の上に表示
std::string label = cv::format("%.2f", score);
cv::putText(image, label, cv::Point(faceRect.x, faceRect.y - 5),
cv::FONT_HERSHEY_SIMPLEX, 0.5, cv::Scalar(0, 255, 0), 1);
}
cv::imwrite("result.jpg", image);
std::cout << "result.jpg に保存しました" << std::endl;
return 0;
}
実行結果
検出数: 3
result.jpg に保存しました
result.jpg を開くと、各顔に緑の矩形と信頼スコア、目・鼻・口の 5 点ランドマークが赤丸で描画されています。
主要行の解説
| 箇所 | 説明 |
|---|---|
FaceDetectorYN::create(...) |
ONNX モデルをロードし、検出器を生成する |
第 3 引数 cv::Size |
推論時の入力解像度。画像サイズと一致させる必要がある |
detector->detect(image, faces) |
検出を実行。検出数は faces.rows(戻り値は検出数ではなく、処理したら 1・空画像なら 0) |
faces の形状 |
CV_32F で [N × 15]。最後の列がスコア |
| ランドマーク列 | インデックス 4〜13 に 5 点 × (x, y) が格納される |
引数と戻り値
FaceDetectorYN::create
| 引数 | 型 | 説明 |
|---|---|---|
model |
String |
ONNX モデルファイルのパス |
config |
String |
設定ファイルパス(ONNX の場合は "") |
input_size |
Size |
推論入力サイズ(画像サイズと合わせる) |
score_threshold |
float |
顔スコアの下限(デフォルト 0.9) |
nms_threshold |
float |
NMS の IoU 閾値(デフォルト 0.3) |
top_k |
int |
NMS 前の候補数上限(デフォルト 5000) |
| 戻り値 | Ptr<FaceDetectorYN> |
検出器オブジェクト |
detect
| 引数 | 型 | 説明 |
|---|---|---|
image |
InputArray |
入力画像(BGR・CV_8UC3) |
faces |
OutputArray |
検出結果(CV_32F・N×15) |
| 戻り値 | int |
処理したら 1、空画像なら 0(検出数ではない。検出数は faces.rows) |
実践例
入力サイズをフレームに追従させてカメラ映像を処理する
カメラ解像度が変わるタイミングや、画像ごとにサイズが異なるバッチ処理では setInputSize で都度更新します。
#include <opencv2/opencv.hpp>
#include <iostream>
int main()
{
cv::VideoCapture cap(0);
if (!cap.isOpened()) {
std::cerr << "カメラを開けませんでした" << std::endl;
return 1;
}
const std::string modelPath = "face_detection_yunet_2023mar.onnx";
// 最初のフレームでサイズを決定
cv::Mat frame;
cap >> frame;
if (frame.empty()) return 1;
cv::Ptr<cv::FaceDetectorYN> detector = cv::FaceDetectorYN::create(
modelPath, "", cv::Size(frame.cols, frame.rows), 0.9f, 0.3f, 5000);
cv::Size prevSize(frame.cols, frame.rows);
while (true) {
cap >> frame;
if (frame.empty()) break;
// フレームサイズが変わったら入力サイズを更新
if (frame.size() != prevSize) {
detector->setInputSize(frame.size());
prevSize = frame.size();
}
cv::Mat faces;
detector->detect(frame, faces);
for (int i = 0; i < faces.rows; ++i) {
cv::Rect r(
static_cast<int>(faces.at<float>(i, 0)),
static_cast<int>(faces.at<float>(i, 1)),
static_cast<int>(faces.at<float>(i, 2)),
static_cast<int>(faces.at<float>(i, 3))
);
cv::rectangle(frame, r, cv::Scalar(0, 255, 0), 2);
}
cv::imshow("YuNet", frame);
if (cv::waitKey(1) == 'q') break;
}
return 0;
}
検出した顔の矩形をリアルタイムで描画し続けます。q キーで終了します。
つまずきポイント
⚠️ create 時と画像サイズが違うと detect が例外を投げる
FaceDetectorYN::create の第 3 引数に指定したサイズと、detect に渡す画像のサイズが一致していなければなりません。サイズが違うと detect が cv::Exception(Size does not match. Call setInputSize(size) if input size does not match the preset size)を投げます。画像ごとにサイズが変わる場合は必ず setInputSize を呼んでください。
detector->setInputSize(cv::Size(image.cols, image.rows));
⚠️ モデルファイルが見つからず create が例外を投げる
実行ファイルのカレントディレクトリに .onnx ファイルが存在しないと cv::Exception が投げられます。絶対パスで指定するか、実行前に ls / dir でファイルの存在を確認してください。日本語を含むパスは文字コードの問題でロードに失敗することがあります。
⚠️ faces の型は CV_32F・インデックス誤りに注意
faces は Mat ですが要素型は float(CV_32F)です。uchar や double でアクセスすると assertion エラーになり、int は要素のバイト数が同じためエラーにならず意味のない値が返ります。また列インデックスのレイアウトは [x, y, w, h, lm0x, lm0y, ..., lm4x, lm4y, score] の 15 列固定であることを押さえておきましょう。
関連する関数
顔検出後の追跡処理に組み合わせることが多い関数を紹介します。
- cv::calcOpticalFlowPyrLK の使い方【OpenCV/C++】〜LK法でオプティカルフローを追跡する〜 — 検出した顔のランドマーク点をフレーム間で追跡する際に有効です
- cv::KalmanFilter の使い方【OpenCV/C++】〜カルマンフィルタで物体追跡〜 — 顔矩形の位置をスムージングしたい場合に組み合わせます
特徴量ベースの手法と比較したい場合は cv::SIFT の使い方【OpenCV/C++】 も参考にしてください。
まとめ
cv::FaceDetectorYN::createで ONNX モデルをロードし、detectを呼ぶだけで顔検出と 5 点ランドマーク取得が一度にできます。- 入力サイズが画像と違うと
detectは例外を投げます。画像・フレームごとにsetInputSizeを使って必ず合わせてください。 - CPU 推論でも実用的な速度で動作するため、組込・業務システムへの導入コストが低いのが大きな利点です。
🛠 画像処理のプロが開発するSDK/API
本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。
→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

