cv::findHomography の使い方【OpenCV/C++】〜ホモグラフィ行列を求める〜
cv::findHomography は、2枚の画像間の対応点群からホモグラフィ行列(3×3の射影変換行列)を推定する関数です。特徴点マッチングと組み合わせることで、画像の位置合わせ・パノラマ合成・平面物体の姿勢推定などを実現できます。
最小限の呼び出しは次のとおりです。
cv::Mat H = cv::findHomography(srcPoints, dstPoints, cv::RANSAC);
動作環境
- OpenCV 4.x
- C++17
- ビルドコマンド:
g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4)
環境構築がまだの方は環境構築ガイドを先にどうぞ。
基本の使い方
下記のサンプルは、あらかじめ用意した4点の対応座標からホモグラフィを推定し、cv::warpPerspective で変換結果を保存するシンプルな例です。
#include <iostream>
#include <vector>
#include <opencv2/opencv.hpp>
int main()
{
// 変換元座標(src 画像上の4点)
std::vector<cv::Point2f> srcPts = {
{100.0f, 100.0f},
{400.0f, 100.0f},
{400.0f, 400.0f},
{100.0f, 400.0f}
};
// 変換先座標(dst 画像上の4点)
std::vector<cv::Point2f> dstPts = {
{ 50.0f, 150.0f},
{450.0f, 80.0f},
{480.0f, 450.0f},
{ 20.0f, 420.0f}
};
// ホモグラフィ推定(4点ちょうどのときは method によらず4点から直接計算される)
cv::Mat H = cv::findHomography(srcPts, dstPts, cv::LMEDS);
if (H.empty()) {
std::cerr << "findHomography に失敗しました" << std::endl;
return 1;
}
std::cout << "ホモグラフィ行列:\n" << H << std::endl;
// 元画像を読み込んで射影変換
cv::Mat src = cv::imread("input.jpg");
if (src.empty()) {
std::cerr << "画像の読み込みに失敗しました" << std::endl;
return 1;
}
cv::Mat dst;
// 変換後のサイズは src と同じに設定
cv::warpPerspective(src, dst, H, src.size());
cv::imwrite("output.jpg", dst);
std::cout << "output.jpg を保存しました" << std::endl;
return 0;
}
実行結果
ホモグラフィ行列:
[0.8372133730089268, -0.09562401540346606, -29.70768422895135;
-0.2693330999474882, 0.6589707684228948, 94.38998774724315;
-0.0007736740766672507, -0.0003360756170138283, 0.9999999999999999]
output.jpg を保存しました
実行すると、srcPts → dstPts の対応を満たす射影変換が output.jpg に書き出されます。行列の値は入力座標によって変わります。
各処理の要点
| 処理 | 説明 |
|---|---|
findHomography(srcPts, dstPts, cv::LMEDS) |
対応点から3×3のホモグラフィ行列を推定 |
H.empty() チェック |
RANSAC などで推定できなかった場合(縮退配置など)に空Matが返る |
warpPerspective |
推定した H を使って画像を射影変換 |
引数と戻り値
cv::Mat cv::findHomography(
InputArray srcPoints, // 変換元の2D点群(N×1 または 1×N, CV_32FC2 / Point2f)
InputArray dstPoints, // 変換先の2D点群(同形式)
int method = 0, // 推定手法(下表参照)
double ransacReprojThreshold = 3.0, // RANSAC の許容再投影誤差 [px]
OutputArray mask = noArray(), // 外れ値マスク出力(CV_8U, 0/1)
const int maxIters = 2000, // RANSAC 最大反復回数
double confidence = 0.995 // RANSAC 信頼度
);
| 引数 | 型 | 説明 |
|---|---|---|
srcPoints |
InputArray |
変換元の対応点。vector<Point2f> が扱いやすい |
dstPoints |
InputArray |
変換先の対応点。要素数は srcPoints と同じ |
method |
int |
推定手法(後述) |
ransacReprojThreshold |
double |
RANSAC 判定の再投影誤差閾値 [px]。デフォルト 3.0 |
mask |
OutputArray |
インライア=1、アウトライア=0 のマスク行列 |
maxIters |
int |
RANSAC の最大反復回数(OpenCV 4.x 時点) |
confidence |
double |
RANSAC の信頼度。0〜1の範囲 |
| 戻り値 | cv::Mat |
3×3 の CV_64F ホモグラフィ行列。失敗時は空Mat |
method の選択肢
| 定数 | 説明 |
|---|---|
0(デフォルト) |
最小二乗法(外れ値なし前提) |
cv::RANSAC |
RANSAC。外れ値が多い実データに最適 |
cv::LMEDS |
最小メジアン法。外れ値 < 50% のとき有効 |
cv::RHO |
PROSAC ベースの高速版 RANSAC |
実践例
特徴点マッチングと組み合わせてオブジェクト検出
特徴点マッチングで得た対応点を findHomography に渡し、RANSAC でロバストに推定する実務的なパターンです。cv::BFMatcher / FLANN の使い方やcv::SIFT の使い方と組み合わせる場面が典型例です。
#include <iostream>
#include <vector>
#include <opencv2/opencv.hpp>
int main()
{
cv::Mat imgQuery = cv::imread("query.jpg", cv::IMREAD_GRAYSCALE);
cv::Mat imgScene = cv::imread("scene.jpg", cv::IMREAD_GRAYSCALE);
if (imgQuery.empty() || imgScene.empty()) {
std::cerr << "画像の読み込みに失敗しました" << std::endl;
return 1;
}
// AKAZE で特徴点・記述子を検出
auto akaze = cv::AKAZE::create();
std::vector<cv::KeyPoint> kpQuery, kpScene;
cv::Mat descQuery, descScene;
akaze->detectAndCompute(imgQuery, cv::noArray(), kpQuery, descQuery);
akaze->detectAndCompute(imgScene, cv::noArray(), kpScene, descScene);
if (descQuery.empty() || descScene.empty()) {
std::cerr << "記述子の抽出に失敗しました" << std::endl;
return 1;
}
// BFMatcher でマッチング(knn + ratio test)
cv::BFMatcher matcher(cv::NORM_HAMMING);
std::vector<std::vector<cv::DMatch>> knnMatches;
matcher.knnMatch(descQuery, descScene, knnMatches, 2);
std::vector<cv::Point2f> srcPts, dstPts;
const float ratioThresh = 0.75f;
for (const auto& m : knnMatches) {
if (m[0].distance < ratioThresh * m[1].distance) {
srcPts.push_back(kpQuery[m[0].queryIdx].pt);
dstPts.push_back(kpScene[m[0].trainIdx].pt);
}
}
if (srcPts.size() < 4) {
std::cerr << "対応点が不足しています: " << srcPts.size() << std::endl;
return 1;
}
// RANSAC でホモグラフィ推定(inlier マスク付き)
cv::Mat mask;
cv::Mat H = cv::findHomography(srcPts, dstPts, cv::RANSAC, 3.0, mask);
if (H.empty()) {
std::cerr << "ホモグラフィの推定に失敗しました" << std::endl;
return 1;
}
// インライア数を表示
int inlierCount = cv::countNonZero(mask);
std::cout << "対応点数: " << srcPts.size()
<< " / インライア数: " << inlierCount << std::endl;
// クエリ画像の四隅を scene 上に射影して検出枠を描画
std::vector<cv::Point2f> corners = {
{0.0f, 0.0f},
{(float)imgQuery.cols, 0.0f},
{(float)imgQuery.cols, (float)imgQuery.rows},
{0.0f, (float)imgQuery.rows}
};
std::vector<cv::Point2f> projectedCorners;
cv::perspectiveTransform(corners, projectedCorners, H);
cv::Mat result;
cv::cvtColor(imgScene, result, cv::COLOR_GRAY2BGR);
for (int i = 0; i < 4; ++i) {
cv::line(result, projectedCorners[i], projectedCorners[(i + 1) % 4],
cv::Scalar(0, 255, 0), 2);
}
cv::imwrite("result.jpg", result);
std::cout << "result.jpg を保存しました" << std::endl;
return 0;
}
実行結果
対応点数: 58 / インライア数: 57
result.jpg を保存しました
実行すると、scene.jpg 上にクエリ画像の検出枠が緑の四角形で描かれた result.jpg が出力されます。インライア数が少ない場合は ransacReprojThreshold を緩める(例: 5.0)か、特徴点検出器のパラメータを調整してください。
cv::AKAZE の使い方も合わせて参照すると、特徴点検出から一連の流れを把握しやすくなります。
つまずきポイント
⚠️ 対応点が4点未満だと例外、縮退配置だと空 Mat が返る
ホモグラフィの推定には最低4点が必要で、4点未満を渡すと cv::Exception(The input arrays should have at least 4 corresponding point sets to calculate Homography)が投げられます。また点が一直線上に並ぶ(縮退)配置では、RANSAC / LMEDS / RHO を指定した findHomography は空 Mat を返します(method=0 や4点ちょうどのときは空にならず、意味のない行列が返ります)。必ず H.empty() を確認してください。さらに RANSAC を使う場合、ratio test 後の対応点が十分(目安: 10点以上)ないと RANSAC が収束しないことがあります。
if (H.empty()) { /* 推定失敗 */ }
⚠️ mask の型と使い方を誤る
mask 出力は CV_8U の N×1 行列で、インライア=1、アウトライア=0 です。要素は uchar なので、mask.at<uchar>(i) != 0 で判定するか cv::countNonZero(mask) で数えてください。mask.at<int>(i) や mask.at<float>(i) のように要素サイズの違う型で読むと assertion エラーになります。
// 正しいインライア判定
if (mask.at<uchar>(i) != 0) { /* インライア */ }
⚠️ 戻り値の H は CV_64F(要素は double で読む)
findHomography の戻り値は CV_64F(double)の 3×3 Mat です。要素を直接読むときは H.at<double>(r, c) を使ってください(H.at<float>(r, c) は assertion エラーになります)。なお warpPerspective や perspectiveTransform は CV_32F の行列も受け付けるので、渡す前の型変換は不要です。
関連する関数
- cv::warpPerspective — findHomography で得た行列を使って画像を射影変換する。本記事のサンプルで使用
- cv::perspectiveTransform — 点群をホモグラフィ行列で変換する(画像全体ではなく座標のみ変換したい場合)
- cv::BFMatcher / FLANN の使い方【OpenCV/C++】〜特徴点マッチングを実装する〜
- cv::SIFT の使い方【OpenCV/C++】〜SIFT特徴点の検出と記述子抽出〜
- cv::drawKeypoints / drawMatches の使い方【OpenCV/C++】〜特徴点・マッチング結果を可視化する〜
まとめ
cv::findHomography は対応点群から3×3のホモグラフィ行列を推定する関数です。外れ値が多い実データでは cv::RANSAC を指定し、mask でインライア判定を活用するのが基本パターンです。推定後は cv::warpPerspective や cv::perspectiveTransform と組み合わせて、画像の位置合わせや平面物体の検出に応用できます。
🛠 画像処理のプロが開発するSDK/API
本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。
→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

