cv::findHomography の使い方【OpenCV/C++】〜ホモグラフィ行列を求める〜

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

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::findHomography は対応点群から3×3のホモグラフィ行列を推定する関数です。外れ値が多い実データでは cv::RANSAC を指定し、mask でインライア判定を活用するのが基本パターンです。推定後は cv::warpPerspective や cv::perspectiveTransform と組み合わせて、画像の位置合わせや平面物体の検出に応用できます。

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

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

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

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