cv::grabCut の使い方【OpenCV/C++】〜前景抽出を実装する〜

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

cv::grabCut の使い方【OpenCV/C++】〜前景抽出を実装する〜

cv::grabCut は、矩形またはマスクを初期ヒントとして与えるだけで、ピクセル単位の前景抽出を行う関数です。グラフカット最適化とガウス混合モデル(GMM)を組み合わせており、背景差分では難しい静止画中の物体切り抜きに適しています。

最小限の呼び出し例:

cv::grabCut(src, mask, rect, bgdModel, fgdModel, 5, cv::GC_INIT_WITH_RECT);

動作環境

  • OpenCV 4.x
  • ビルド: g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4) -o grabcut_demo

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


基本の使い方

以下のサンプルは、画像を読み込んで矩形を初期ヒントとして cv::grabCut を実行し、前景マスクを二値化して元画像に合成するまでの一連の流れです。

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

int main()
{
    // 画像の読み込み
    cv::Mat src = cv::imread("input.jpg");
    if (src.empty()) {
        std::cerr << "画像を読み込めませんでした" << std::endl;
        return 1;
    }

    // GrabCut の出力マスク(CV_8UC1 で初期化)
    cv::Mat mask(src.size(), CV_8UC1, cv::Scalar(cv::GC_BGD));

    // GMM 用の内部モデルバッファ(変更しない・サイズ固定)
    cv::Mat bgdModel, fgdModel;

    // 前景が含まれる矩形領域を指定(画像端を除いた領域)
    cv::Rect rect(50, 30, src.cols - 100, src.rows - 60);

    // GrabCut 実行(矩形モードで初期化・5回繰り返し)
    cv::grabCut(src, mask, rect, bgdModel, fgdModel, 5, cv::GC_INIT_WITH_RECT);

    // マスクを二値化: GC_FGD または GC_PR_FGD を前景として扱う
    cv::Mat fgMask;
    cv::compare(mask, cv::GC_PR_BGD, fgMask, cv::CMP_GT);
    // ※ GC_PR_BGD(2) より大きいのは GC_PR_FGD(3) だけで、GC_FGD(1) を取りこぼす
    // 確実な方法: GC_FGD(1) と GC_PR_FGD(3) を OR で拾う
    fgMask = (mask == cv::GC_FGD) | (mask == cv::GC_PR_FGD);

    // 前景マスクを元画像に合成
    cv::Mat result;
    src.copyTo(result, fgMask);

    // 確認用に矩形を描画した画像も保存
    cv::Mat debugSrc = src.clone();
    cv::rectangle(debugSrc, rect, cv::Scalar(0, 255, 0), 2);

    cv::imwrite("result.png", result);
    cv::imwrite("debug_rect.png", debugSrc);

    std::cout << "保存完了: result.png / debug_rect.png" << std::endl;
    return 0;
}

実行結果:

保存完了: result.png / debug_rect.png

result.png には指定矩形内の前景オブジェクトだけが残り、背景は黒(透明ではなく黒塗り)になります。debug_rect.png には初期指定した矩形の緑枠が重なって表示されます。

各ステップの補足

ステップ ポイント
mask の初期化 cv::GC_BGD で全体を「確実な背景」として初期化。矩形モード時は関数内部で上書きされる
bgdModel / fgdModel 65要素の CV_64F 行列。初回は空で渡せばよい
iterCount=5 増やすほど精度は上がるが処理時間も増える
mode 初回は GC_INIT_WITH_RECT。追加繰り返し時は GC_EVAL を指定

引数と戻り値

void cv::grabCut(
    InputArray      img,        // 入力画像(CV_8UC3・BGR)
    InputOutputArray mask,      // 前景/背景マスク(CV_8UC1)
    Rect            rect,       // 前景を含む矩形(INIT_WITH_RECT 時のみ使用)
    InputOutputArray bgdModel,  // 背景 GMM モデル(内部用・変更しない)
    InputOutputArray fgdModel,  // 前景 GMM モデル(内部用・変更しない)
    int             iterCount,  // 反復回数
    int             mode        // GC_INIT_WITH_RECT / GC_INIT_WITH_MASK / GC_EVAL
);

mask の画素値(定数):

定数 値 意味
cv::GC_BGD 0 確実な背景
cv::GC_FGD 1 確実な前景
cv::GC_PR_BGD 2 おそらく背景
cv::GC_PR_FGD 3 おそらく前景

戻り値は void。結果は mask に書き込まれます。


実践例

追加イテレーションで精度を上げる

初回実行後に GC_EVAL モードで繰り返すことで精度を段階的に向上させられます。大きな画像や複雑な背景で有効です。

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

int main()
{
    cv::Mat src = cv::imread("input.jpg");
    if (src.empty()) {
        std::cerr << "画像を読み込めませんでした" << std::endl;
        return 1;
    }

    cv::Mat mask(src.size(), CV_8UC1, cv::Scalar(cv::GC_BGD));
    cv::Mat bgdModel, fgdModel;
    cv::Rect rect(60, 40, src.cols - 120, src.rows - 80);

    // 第1フェーズ: 矩形で初期化(3回)
    cv::grabCut(src, mask, rect, bgdModel, fgdModel, 3, cv::GC_INIT_WITH_RECT);

    // 第2フェーズ: 追加反復(5回)
    // bgdModel / fgdModel を引き継いでいる点がポイント
    cv::grabCut(src, mask, rect, bgdModel, fgdModel, 5, cv::GC_EVAL);

    // 前景マスクを生成して合成
    cv::Mat fgMask = (mask == cv::GC_FGD) | (mask == cv::GC_PR_FGD);
    cv::Mat result;
    src.copyTo(result, fgMask);

    cv::imwrite("result_refined.png", result);
    std::cout << "保存完了: result_refined.png" << std::endl;
    return 0;
}

実行結果:

保存完了: result_refined.png

初回よりエッジ付近の前景/背景判定が改善されます。bgdModel / fgdModel を再利用することで学習済みの GMM パラメータを引き継げる点が重要です。


つまずきポイント

⚠️ mask の型を間違えると例外になる(GC_INIT_WITH_MASK / GC_EVAL)

GC_INIT_WITH_MASK や GC_EVAL で渡す mask は CV_8UC1(uchar 1チャンネル)でなければなりません。CV_8UC3 や CV_32F を渡すと (-5:Bad argument) mask must have CV_8UC1 type in function 'checkMask' の例外が発生します。GC_INIT_WITH_RECT では関数の中で mask が CV_8UC1 に作り直されるため、型が違ってもエラーにはなりません。

// NG: 3チャンネルで初期化してしまう例
cv::Mat mask(src.size(), CV_8UC3, cv::Scalar::all(0));

// OK
cv::Mat mask(src.size(), CV_8UC1, cv::Scalar(cv::GC_BGD));

⚠️ 矩形で画像全体を囲むとエラーになる

GC_INIT_WITH_RECT では、rect の外側が「確実な背景」として背景モデルの学習に使われます。rect で画像全体を囲むと背景の画素が1つも無くなり、(-215:Assertion failed) !bgdSamples.empty() && !fgdSamples.empty() in function 'initGMMs' で止まります。背景を学習できるよう、矩形の外側に背景が十分写るマージンを設けてください。

// NG: 画像全体をそのまま渡す(例外になる)
cv::Rect rect(0, 0, src.cols, src.rows);

// OK: マージンを取る
cv::Rect rect(30, 30, src.cols - 60, src.rows - 60);

⚠️ 前景マスクの二値化を > 0 だけでやると抜けが生じる

GC_FGD=1 と GC_PR_FGD=3 の両方を前景として扱う必要があります。mask > 0 と書くと GC_BGD=0 を除くだけなので、GC_PR_BGD=2 も前景として混入します。

// NG: GC_PR_BGD(=2) も含まれてしまう
cv::Mat fgMask = mask > 0;

// OK: FGD と PR_FGD だけを明示的に取る
cv::Mat fgMask = (mask == cv::GC_FGD) | (mask == cv::GC_PR_FGD);

関連する関数

  • cv::compare / cv::bitwise_and — grabCut の結果マスクを加工する際に使います
  • cv::watershed — マーカーを起点にした領域分割(流域分割)。複数の領域を一度に分けられる
  • 動体の前景抽出には grabCut より BackgroundSubtractorMOG2 の使い方【OpenCV/C++】〜背景差分で動体を検出する〜 が適しています。動画ストリームから前景を高速に分離したい場合はそちらを参照してください。

まとめ

cv::grabCut は矩形1つから始められるシンプルなインタフェースで、実装コストに対して精度の高い前景抽出を実現できます。mask の型・矩形マージン・二値化方法の3点を押さえれば、静止画の物体切り抜きに即活用できます。追加イテレーション(GC_EVAL)で段階的に精度を高める運用も実務でよく使うパターンです。

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

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

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

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