cv::dnn::NMSBoxes の使い方【OpenCV/C++】〜非最大抑制で重複検出を除去する〜

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

cv::dnn::NMSBoxes の使い方【OpenCV/C++】〜非最大抑制で重複検出を除去する〜

物体検出モデルの出力には、同一物体に対して複数の重複したバウンディングボックスが含まれます。cv::dnn::NMSBoxes は IoU(Intersection over Union)とスコアをもとに重複ボックスを絞り込む 非最大抑制(NMS)の関数です。YOLOや SSD など多くの検出モデルのポストプロセスに必須の一本です。

最小の呼び出し形はこちらです。

std::vector<int> indices;
cv::dnn::NMSBoxes(boxes, scores, scoreThreshold, nmsThreshold, indices);

動作環境

  • OpenCV 4.x(dnn モジュール付きビルド)
  • C++17
  • ビルド例: g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4)

環境構築がまだの方は環境構築ガイドを先にどうぞ。

基本の使い方

ここでは画像ファイルなしでも確認できるよう、ダミーのボックスとスコアを用意して NMS を実行するサンプルを示します。

#include <opencv2/opencv.hpp>
#include <opencv2/dnn.hpp>
#include <iostream>
#include <vector>

int main()
{
    // ダミーのバウンディングボックス(x, y, w, h)
    std::vector<cv::Rect> boxes = {
        cv::Rect(100, 100, 200, 200),
        cv::Rect(110, 105, 195, 198), // 上と大きく重複
        cv::Rect(300, 300, 150, 150),
        cv::Rect(305, 295, 148, 155), // 上と大きく重複
        cv::Rect(500, 100, 100, 100)  // 単独
    };

    // 各ボックスの信頼度スコア
    std::vector<float> scores = { 0.9f, 0.75f, 0.85f, 0.60f, 0.95f };

    float scoreThreshold = 0.5f; // これ未満のボックスは除外
    float nmsThreshold   = 0.4f; // IoU がこれを超えたら抑制

    std::vector<int> indices; // 残ったボックスのインデックスが入る
    cv::dnn::NMSBoxes(boxes, scores, scoreThreshold, nmsThreshold, indices);

    std::cout << "NMS 後に残ったボックス数: " << indices.size() << std::endl;
    for (int idx : indices)
    {
        std::cout << "  index=" << idx
                  << "  score=" << scores[idx]
                  << "  box=(" << boxes[idx].x << "," << boxes[idx].y
                  << "," << boxes[idx].width << "," << boxes[idx].height << ")"
                  << std::endl;
    }

    return 0;
}

実行結果(標準出力)

NMS 後に残ったボックス数: 3
  index=4  score=0.95  box=(500,100,100,100)
  index=0  score=0.9  box=(100,100,200,200)
  index=2  score=0.85  box=(300,300,150,150)

5 本あったボックスのうち、重複する 2 ペアはそれぞれスコアの低い方(index=1, 3)が除去され、3 本だけ残りました。indices の並び順はスコアの降順になります。

コードのポイント

行 説明
boxes cv::Rect の vector。検出モデルの出力をそのまま詰める
scores 各ボックスの信頼度。float の vector
scoreThreshold まずこの値で足切り。超えたボックスのみ NMS にかける
nmsThreshold 2 ボックスの IoU がこれを超えたら低スコア側を除去
indices 出力。関数の中で clear() されてから詰め直されるので、前回の結果は残らない

引数と戻り値

void cv::dnn::NMSBoxes(
    const std::vector<cv::Rect>& bboxes,
    const std::vector<float>&    scores,
    float                        score_threshold,
    float                        nms_threshold,
    std::vector<int>&            indices,
    float                        eta   = 1.f,  // 適応的閾値の係数(1.0 = 閾値を固定)
    int                          top_k = 0     // 0 = 制限なし
);
引数 型 説明
bboxes const std::vector<cv::Rect>& バウンディングボックス群
scores const std::vector<float>& 各ボックスの信頼度スコア
score_threshold float スコアの足切り閾値
nms_threshold float IoU 閾値(0〜1)。小さいほど厳しく抑制
indices std::vector<int>& 出力: 残ったボックスのインデックス(スコア降順)
eta float 適応的閾値の係数。1 未満にすると、ボックスを1つ残すたびに IoU 閾値へ eta を掛けて下げる(閾値が 0.5 を超えている間だけ)。1.0 で閾値は固定
top_k int NMS 前にスコア上位 k 件に絞る(0 = 全件)

戻り値はなし(void)。結果は indices に書き込まれます。

実践例

YOLO ポストプロセスへの組み込み

実際の検出パイプラインでは、DNN モデルの出力を解析してから NMSBoxes を呼びます。以下は YOLO 系モデルの出力を想定した典型的なポストプロセスのパターンです。

#include <opencv2/opencv.hpp>
#include <opencv2/dnn.hpp>
#include <iostream>
#include <vector>

int main()
{
    // 画像読み込み(実際の検出ではここでモデルを推論する)
    cv::Mat image = cv::imread("test.jpg");
    if (image.empty())
    {
        std::cerr << "画像を読み込めませんでした" << std::endl;
        return 1;
    }

    // ---- ここはモデル推論結果を模したダミーデータ ----
    std::vector<cv::Rect> boxes  = {
        cv::Rect(50,  50,  120, 100),
        cv::Rect(55,  53,  118,  98),  // 上と重複
        cv::Rect(200, 150, 80,  90),
    };
    std::vector<float> confidences = { 0.92f, 0.70f, 0.88f };
    // ------------------------------------------------

    std::vector<int> indices;
    cv::dnn::NMSBoxes(boxes, confidences, /*scoreThresh=*/0.5f,
                      /*nmsThresh=*/0.45f, indices);

    // 結果を画像に描画
    for (int idx : indices)
    {
        cv::rectangle(image, boxes[idx], cv::Scalar(0, 255, 0), 2);
        std::string label = cv::format("%.2f", confidences[idx]);
        cv::putText(image, label,
                    cv::Point(boxes[idx].x, boxes[idx].y - 5),
                    cv::FONT_HERSHEY_SIMPLEX, 0.6,
                    cv::Scalar(0, 255, 0), 2);
    }

    cv::imwrite("result.jpg", image);
    std::cout << "result.jpg に保存しました(残りボックス数: "
              << indices.size() << ")" << std::endl;

    return 0;
}

実行結果

result.jpg に保存しました(残りボックス数: 2)

重複していた 2 本のうちスコアが低い方(0.70)が除去され、boxes[0] と boxes[2] が緑枠で描画された画像が保存されます。

top_k を使った高速化

検出候補が数百〜数千になる場合、先に上位 N 件に絞ってから NMS をかけると処理が速くなります。

cv::dnn::NMSBoxes(boxes, scores, 0.5f, 0.45f, indices,
                  /*eta=*/1.f, /*top_k=*/300);

つまずきポイント

⚠️ スコアが score_threshold とちょうど等しいボックスは残らない

足切りは「score > score_threshold」(より大きい)で判定されます。scoreThreshold = 0.5f のとき、スコア 0.5f のボックスは NMS の対象にもならず、indices に入りません。境界値を残したいときは閾値を少し下げてください。

// scores = { 0.5f, 0.6f }、2つのボックスは重ならない
cv::dnn::NMSBoxes(boxes, scores, 0.5f, 0.4f, indices);
// indices = { 1 }(スコア 0.5 の index=0 は除外される)

⚠️ boxes と scores のサイズが一致していないと assertion で落ちる

(-215:Assertion failed) bboxes.size() == scores.size() in function 'NMSBoxes' で止まります。モデル出力のパース処理でボックスとスコアを別々に積むコードはずれが起きやすいです。呼び出し直前に assert(boxes.size() == scores.size()) を入れておくと原因の特定が楽になります。

⚠️ nms_threshold の値が大きすぎると重複が残る

0.9 など大きな値に設定すると「IoU が 90% を超えるものだけ抑制」という意味になり、かなり重なっていても残ってしまいます。YOLOv5 系の実装では 0.45 前後を基準にして調整するのが一般的です。値の意味を逆に解釈しているケースがよくあるので注意してください。

関連する関数

物体追跡・動体検出の文脈では、NMS で絞った検出結果を次フレームへ引き継ぐ処理と組み合わせることが多いです。

まとめ

  • cv::dnn::NMSBoxes は scoreThreshold で足切りした後、IoU ベースで重複ボックスを除去する。
  • nms_threshold を小さくするほど厳しく抑制され、残るボックスが減る。
  • 候補数が多い場合は top_k を指定してから NMS をかけると処理効率が上がる。

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

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

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

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