cv::watershed の使い方【OpenCV/C++】〜watershed法で領域分割を実装する〜
cv::watershed は、マーカーを起点に画像をセグメント(領域)に分割する関数です。接触している物体を個別に分離するシーンで特に力を発揮します。まず関数シグネチャだけ確認しておきます。
void cv::watershed(InputArray image, InputOutputArray markers);
ポイント: image は 8UC3(カラー)必須、markers は 32SC1 の符号付き整数マットで、事前にマーカーを書き込んでおく必要があります。
動作環境
- OpenCV 4.x
- コンパイル例:
g++ -std=c++17 main.cpp `pkg-config --cflags --libs opencv4` -o main
環境構築がまだの方は環境構築ガイドを先にどうぞ。
基本の使い方
watershed の典型的な使い方は「距離変換 → 局所極大をマーカーに → watershed」の3ステップです。白い複数の円が重なった画像を想定した完全なサンプルを示します。
#include <opencv2/opencv.hpp>
#include <iostream>
int main()
{
// --- 入力画像の読み込み(カラー必須)---
cv::Mat src = cv::imread("circles.png");
if (src.empty()) {
std::cerr << "画像を読み込めませんでした\n";
return 1;
}
// --- グレースケール化 & 二値化 ---
cv::Mat gray, bin;
cv::cvtColor(src, gray, cv::COLOR_BGR2GRAY);
cv::threshold(gray, bin, 0, 255, cv::THRESH_BINARY | cv::THRESH_OTSU);
// --- 距離変換で各ピクセルの「前景らしさ」を計算 ---
cv::Mat dist;
cv::distanceTransform(bin, dist, cv::DIST_L2, 5);
cv::normalize(dist, dist, 0.0, 1.0, cv::NORM_MINMAX);
// --- 距離が十分大きい部分を確実な前景マーカーとして抽出 ---
cv::Mat sure_fg;
cv::threshold(dist, sure_fg, 0.5, 255, cv::THRESH_BINARY);
sure_fg.convertTo(sure_fg, CV_8U);
// --- 連結成分ラベリングでマーカー画像を生成 ---
cv::Mat markers;
int numLabels = cv::connectedComponents(sure_fg, markers); // markers は 32SC1
// ラベル 0 = 背景 → 1 にシフトして 0 を「未確定」に使う
markers += 1;
// 前景のうち「確実な前景」以外(物体の輪郭付近)を 0(未確定)に設定
// ※ 背景(bin が 0)はラベル 1 のまま残す
markers.setTo(0, (bin == 255) & (sure_fg == 0));
// --- watershed 実行(image は 8UC3 必須)---
cv::watershed(src, markers);
// --- 境界線(ラベル -1)を赤で描画して可視化 ---
cv::Mat result = src.clone();
result.setTo(cv::Scalar(0, 0, 255), markers == -1);
cv::imshow("watershed result", result);
cv::waitKey(0);
// numLabels は背景(ラベル 0)を含むので 1 を引く
std::cout << "検出された領域数: " << numLabels - 1 << "\n";
return 0;
}
実行結果
検出された領域数: 5
ウィンドウには、隣接する円の境界が赤いラインで分割された画像が表示されます。markers == -1 の画素が watershed アルゴリズムが判定した境界線です。
コードのポイント
| ステップ | 処理 | 理由 |
|---|---|---|
distanceTransform |
前景画素から距離を計算 | 重なり部分でも物体の中心を推定できる |
connectedComponents |
確実前景をラベリング | マーカーの初期値を自動生成 |
markers += 1 |
ラベルを 1 始まりにシフト | 0 を「未確定ピクセル」として watershed に渡すため |
markers.setTo(0, ...) |
確実前景の周り(物体の輪郭付近)を未確定に | 未確定の領域を watershed が各ラベルへ振り分け、ラベルどうしの境目に境界線(-1)を引く |
引数と戻り値
| 引数 | 型 | 説明 |
|---|---|---|
image |
InputArray |
入力カラー画像(CV_8UC3 必須) |
markers |
InputOutputArray |
入出力マーカー画像(CV_32SC1 必須)。事前にラベルを書き込む |
| 戻り値 | void |
なし。結果は markers に上書きされる |
markers の仕様(OpenCV 4.x 時点):
- 正の整数 → 既知の前景ラベル(1 以上)
0→ 未確定(watershed が自動分類)-1→ 実行後に境界線として書き込まれる
実践例: 外部マーカーを手動で指定する
ユーザーがクリックや矩形指定で「この領域は前景/背景」と明示したい場合、マーカーを直接描画して渡す方法が使えます。
#include <opencv2/opencv.hpp>
#include <iostream>
int main()
{
cv::Mat src = cv::imread("object.png");
if (src.empty()) {
std::cerr << "画像を読み込めませんでした\n";
return 1;
}
// markers を 0 で初期化(全ピクセルが未確定)
cv::Mat markers = cv::Mat::zeros(src.size(), CV_32SC1);
// 前景マーカー: 画像中央付近に楕円を描く(ラベル 1)
cv::ellipse(markers, cv::Point(src.cols / 2, src.rows / 2),
cv::Size(src.cols / 6, src.rows / 6),
0, 0, 360, cv::Scalar(1), -1);
// 背景マーカー: 画像端の矩形(ラベル 2)
cv::rectangle(markers, cv::Rect(0, 0, src.cols, 10), cv::Scalar(2), -1);
cv::rectangle(markers, cv::Rect(0, src.rows - 10, src.cols, 10), cv::Scalar(2), -1);
// watershed 実行
cv::watershed(src, markers);
// 前景(ラベル 1)をマスクとして切り抜き
cv::Mat mask = (markers == 1);
cv::Mat cropped = cv::Mat::zeros(src.size(), src.type());
src.copyTo(cropped, mask);
cv::imshow("segmented", cropped);
cv::waitKey(0);
return 0;
}
手動マーカーを使うと、GrabCut に近い感覚でインタラクティブなセグメンテーションを実装できます。マーカーの形や位置を変えるだけで分割結果をコントロールできるのが利点です。
つまずきポイント
⚠️ image が 8UC3 でないと assertion で落ちる
cv::watershed は カラー画像(CV_8UC3)のみを受け付けます。グレースケール画像をそのまま渡すと実行時に assertion エラーが発生します。
# NG: グレースケール画像を渡すと以下のエラー
(-215:Assertion failed) src.type() == CV_8UC3 && dst.type() == CV_32SC1 in function 'watershed'
グレースケールで処理している場合は必ず cv::cvtColor で BGR に戻してから渡してください。
⚠️ markers が 32SC1 でないと assertion で落ちる
cv::connectedComponents のデフォルト出力型は CV_32SC1 ですが、自分で Mat::zeros を作る場合に CV_32FC1 や CV_8UC1 を誤って指定するミスが多いです。型が違うと、上と同じ (-215:Assertion failed) src.type() == CV_8UC3 && dst.type() == CV_32SC1 で止まります。
// NG例
cv::Mat markers = cv::Mat::zeros(src.size(), CV_8UC1); // 型が違う
// OK
cv::Mat markers = cv::Mat::zeros(src.size(), CV_32SC1);
⚠️ マーカーに 0 以外のラベルがないと何も分割されない
markers の初期値が全て 0(未確定)だと、エラーにはならず、画像の外周 1 画素が -1 になるだけで残りは 0 のまま返ってきます。必ず 1 以上のラベルを持つ既知領域を最低1つ含めてから呼び出してください。距離変換後のしきい値が厳しすぎてマーカーが消えてしまうケースも同様です。sure_fg が空でないか確認する習慣をつけておくと安全です。
関連する関数
watershed と組み合わせて使うことが多い関数です。
cv::distanceTransform— 前景領域内の各点が境界からどれだけ離れているかを計算。マーカー生成に必須cv::connectedComponents— マーカーのラベリングに使用cv::threshold— 二値化処理cv::findContours/cv::drawContours— watershed 後の各ラベル輪郭を取得・描画したいときに使う
動体検出や追跡と組み合わせる場合は以下も参考にしてください。
cv::calcOpticalFlowFarneback の使い方【OpenCV/C++】〜密なオプティカルフローで動き検出〜
まとめ
cv::watershedは マーカー → watershed 実行 → ラベル読み出し の3ステップで使うimageはCV_8UC3、markersはCV_32SC1の型制約を必ず守る- 距離変換 + 連結成分ラベリングでマーカーを自動生成するパターンが最も実用的
🛠 画像処理のプロが開発するSDK/API
本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。
→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード
