cv::seamlessClone の使い方【OpenCV/C++】〜シームレス合成で自然な画像合成を実現する〜
cv::seamlessClone は、ある画像の一部を別の画像に境界線が目立たない形で合成する関数です。単純なコピー&ペーストと異なり、色の差異や輝度のムラを自動的に補正してくれるため、背景合成・コンテンツ編集・データ拡張に幅広く活用できます。
最小の呼び出しは以下のとおりです。
cv::seamlessClone(src, dst, mask, center, result, cv::NORMAL_CLONE);
動作環境
- OpenCV 4.x
- ビルド・実行コマンド:
g++ -std=c++17 main.cpp `pkg-config --cflags --libs opencv4` -o main && ./main
環境構築がまだの方は環境構築ガイドを先にどうぞ。
基本の使い方
#include <opencv2/opencv.hpp>
#include <opencv2/photo.hpp>
#include <iostream>
int main() {
// 合成元(貼り付けたい画像)と合成先(背景)を読み込む
cv::Mat src = cv::imread("src.png");
cv::Mat dst = cv::imread("dst.png");
if (src.empty() || dst.empty()) {
std::cerr << "画像を読み込めませんでした。パスを確認してください。" << std::endl;
return -1;
}
// マスク: src の貼り付けたい領域を白(255)で描く
cv::Mat mask = cv::Mat::zeros(src.size(), CV_8UC1);
// ここでは src のほぼ全体を対象にする(外周 1px は関数内で 0 として扱われる)
cv::rectangle(mask,
cv::Point(5, 5),
cv::Point(src.cols - 5, src.rows - 5),
cv::Scalar(255), cv::FILLED);
// 合成先画像上での貼り付け中心座標
cv::Point center(dst.cols / 2, dst.rows / 2);
cv::Mat result;
// NORMAL_CLONE: 色を背景に馴染ませながら合成
cv::seamlessClone(src, dst, mask, center, result, cv::NORMAL_CLONE);
cv::imwrite("result.png", result);
std::cout << "result.png に保存しました。" << std::endl;
cv::imshow("Seamless Clone Result", result);
cv::waitKey(0);
return 0;
}
実行結果
result.png に保存しました。
ウィンドウには、src の内容が dst の中央に自然に溶け込んだ合成画像が表示されます。境界付近の色差は自動的に補正されるため、単純なαブレンドよりもはるかに自然な仕上がりになります。
コード解説
| 行の内容 | 説明 |
|---|---|
cv::Mat::zeros(src.size(), CV_8UC1) |
マスクは 1 チャンネル 8bit グレースケール |
cv::rectangle(mask, ...) |
白塗りが「合成する領域」。白領域の外接矩形が貼り付け範囲になる(後述) |
center |
dst 画像上における貼り付け中心。src の中心ではない点に注意 |
cv::NORMAL_CLONE |
通常のシームレス合成フラグ |
result |
合成結果が格納される出力 Mat |
引数と戻り値
| 引数名 | 型 | 内容 |
|---|---|---|
src |
cv::InputArray |
合成元画像(貼り付けたい画像) |
dst |
cv::InputArray |
合成先画像(背景画像) |
mask |
cv::InputArray |
合成領域を示す 8bit グレースケールマスク |
p |
cv::Point |
dst 上の貼り付け中心座標 |
blend |
cv::OutputArray |
出力画像 |
flags |
int |
合成アルゴリズムの種別(下表参照) |
戻り値: なし(結果は blend に格納)
flags の種別
| フラグ定数 | 動作 |
|---|---|
cv::NORMAL_CLONE |
色・輝度を背景に馴染ませながら合成。最も汎用的 |
cv::MIXED_CLONE |
src と dst のグラジェントをミックス。テクスチャが透けて見える効果 |
cv::MONOCHROME_TRANSFER |
src の形状(エッジ)のみを dst に転写。色は dst に依存 |
実践例
例1: MIXED_CLONE で背景テクスチャを透過させる
#include <opencv2/opencv.hpp>
#include <opencv2/photo.hpp>
#include <iostream>
int main() {
cv::Mat src = cv::imread("object.png");
cv::Mat dst = cv::imread("background.png");
if (src.empty() || dst.empty()) {
std::cerr << "画像読み込み失敗" << std::endl;
return -1;
}
// 楕円マスクで対象物の輪郭に近い形状を指定
cv::Mat mask = cv::Mat::zeros(src.size(), CV_8UC1);
cv::ellipse(mask,
cv::Point(src.cols / 2, src.rows / 2),
cv::Size(src.cols / 2 - 10, src.rows / 2 - 10),
0, 0, 360, cv::Scalar(255), cv::FILLED);
cv::Point center(dst.cols / 2, dst.rows / 2);
cv::Mat result;
// MIXED_CLONE: 背景テクスチャが薄く透けて見える合成
cv::seamlessClone(src, dst, mask, center, result, cv::MIXED_CLONE);
cv::imwrite("result_mixed.png", result);
std::cout << "result_mixed.png に保存しました。" << std::endl;
return 0;
}
MIXED_CLONE は、草原や砂地など背景テクスチャを src の内容に自然に混ぜたいときに有効です。
例2: マスクを精密に切り出して合成する
実務では、GrabCut や輪郭抽出で得たマスクをそのまま渡すことが多いです。
#include <opencv2/opencv.hpp>
#include <opencv2/photo.hpp>
#include <iostream>
int main() {
cv::Mat src = cv::imread("src.png");
cv::Mat dst = cv::imread("dst.png");
cv::Mat mask = cv::imread("mask.png", cv::IMREAD_GRAYSCALE); // 外部マスク画像
if (src.empty() || dst.empty() || mask.empty()) {
std::cerr << "画像読み込み失敗" << std::endl;
return -1;
}
// マスクを二値化して白黒をはっきりさせる
cv::threshold(mask, mask, 128, 255, cv::THRESH_BINARY);
cv::Point center(dst.cols / 2, dst.rows / 2);
cv::Mat result;
cv::seamlessClone(src, dst, mask, center, result, cv::NORMAL_CLONE);
cv::imwrite("result_precise.png", result);
std::cout << "result_precise.png に保存しました。" << std::endl;
return 0;
}
つまずきポイント
⚠️ 貼り付け範囲は src 全体ではなく「マスクの白領域の外接矩形」
cv::seamlessClone は、マスクの白領域を囲む外接矩形を切り出し、その矩形の中心が center に来るように dst へ貼り付けます。src の中心やサイズは使われません。白領域が src の左上に偏っていても、合成されるのは center を中心とした位置です。なお、マスクの外周 1px は関数の中で 0 に置き換えられるので、端まで白く塗ってもエラーにはなりません。
// src 全体を白にしても動く(外周 1px は自動的に除かれる)
cv::Mat mask(src.size(), CV_8UC1, cv::Scalar(255));
// 白領域が 60x40 なら、dst 上の center を中心に約 60x40 の範囲だけが合成される
cv::rectangle(mask2, cv::Rect(0, 0, 60, 40), 255, cv::FILLED);
⚠️ center が dst の範囲外に出るとアサーションエラーになる
center は dst 画像の内側に収まっていなければなりません。また、マスクの白領域の外接矩形を center 中心に置いた貼り付け矩形が dst をはみ出す場合も (-215:Assertion failed) 0 <= roi.x && 0 <= roi.width && roi.x + roi.width <= m.cols ... のエラーになります。はみ出さないよう center を調整するか、dst を事前にパディングしてください。
⚠️ opencv2/photo.hpp のインクルード忘れ
cv::seamlessClone は photo モジュールに属します。opencv2/opencv.hpp だけでコンパイルできる環境もありますが、個別ヘッダを管理している場合は opencv2/photo.hpp を明示的にインクルードしないとコンパイルエラーになります。リンク時は -lopencv_photo が必要です(pkg-config --libs opencv4 には含まれます)。ライブラリを個別に指定する場合は、imread / imwrite 用の opencv_imgcodecs、rectangle 用の opencv_imgproc も必要です。
g++ -std=c++17 main.cpp `pkg-config --cflags opencv4` -L`pkg-config --variable=libdir opencv4` -lopencv_core -lopencv_imgproc -lopencv_imgcodecs -lopencv_highgui -lopencv_photo -o main
関連する関数
cv::inpaint(photoモジュール): 指定領域を周囲のテクスチャで自動補完する。seamlessClone と同じ photo モジュール系の合成処理。cv::grabCut: 前景/背景を半自動で分離してマスクを作成できる。seamlessClone のマスク生成に組み合わせると効果的。cv::threshold/cv::findContours: 外部マスク画像の前処理に使用する定番関数。
まとめ
cv::seamlessClone は、マスク・合成先座標・フラグの3要素を正しく設定するだけで、プロフェッショナルな画像合成が実現できる強力な関数です。貼り付け範囲がマスクの白領域の外接矩形になること・その矩形が center を中心に dst 内に収まるようにすること、の2点を押さえれば安定して動作します。フラグ(NORMAL_CLONE / MIXED_CLONE / MONOCHROME_TRANSFER)を使い分けることで、用途に応じた多彩な合成表現が可能です。
🛠 画像処理のプロが開発するSDK/API
本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。
→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

