YuNet 顔検出の使い方【OpenCV/C++】〜DNNで高速顔検出〜

OpenCV for C++
📌 準備: OpenCV の環境構築がまだの方はこちら → C++ 環境構築ガイド / C#(OpenCvSharp)セットアップ

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::SIFT の使い方【OpenCV/C++】 も参考にしてください。


まとめ

  • cv::FaceDetectorYN::create で ONNX モデルをロードし、detect を呼ぶだけで顔検出と 5 点ランドマーク取得が一度にできます。
  • 入力サイズが画像と違うと detect は例外を投げます。画像・フレームごとに setInputSize を使って必ず合わせてください。
  • CPU 推論でも実用的な速度で動作するため、組込・業務システムへの導入コストが低いのが大きな利点です。

🛠 画像処理のプロが開発するSDK/API

本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。

→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

タイトルとURLをコピーしました