cv::undistort の使い方【OpenCV/C++】〜カメラ歪み補正を1関数で実装する〜

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

cv::undistort の使い方【OpenCV/C++】〜カメラ歪み補正を1関数で実装する〜

cv::undistort は、カメラキャリブレーションで得た内部パラメータを使って、レンズ歪みを補正した画像を出力する関数です。歪み補正の一連の処理(マップ生成→リマップ)を1回の呼び出しにまとめてくれるため、手軽に使えます。最小の呼び出しは次のとおりです。

cv::undistort(src, dst, cameraMatrix, distCoeffs);

動作環境

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

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


基本の使い方

以下のサンプルは、あらかじめキャリブレーション済みのカメラ行列と歪み係数をハードコードし、指定画像に歪み補正を適用して保存します。実際のプロジェクトでは cv::calibrateCamera で得た値を使ってください。

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

int main()
{
    // 補正対象の画像を読み込む
    cv::Mat src = cv::imread("input.jpg");
    if (src.empty()) {
        std::cerr << "画像を読み込めませんでした。パスを確認してください。\n";
        return 1;
    }

    // カメラ行列(焦点距離・主点): calibrateCameraの出力値を使う
    cv::Mat cameraMatrix = (cv::Mat_<double>(3, 3)
        << 800.0,   0.0, 320.0,
              0.0, 800.0, 240.0,
              0.0,   0.0,   1.0);

    // 歪み係数 (k1, k2, p1, p2, k3)
    cv::Mat distCoeffs = (cv::Mat_<double>(1, 5)
        << -0.3, 0.1, 0.0, 0.0, 0.0);

    // 歪み補正を適用
    cv::Mat dst;
    cv::undistort(src, dst, cameraMatrix, distCoeffs);

    // 結果を保存
    cv::imwrite("undistorted.jpg", dst);
    std::cout << "補正済み画像を undistorted.jpg に保存しました。\n";

    return 0;
}

実行結果:

補正済み画像を undistorted.jpg に保存しました。

undistorted.jpg を確認すると、樽型または糸巻き型の歪みが補正された画像が得られます。歪みが大きいほど、画像周辺が引き伸ばされたり削られたりします。

コード解説

行 内容
cv::Mat_<double>(3,3) カメラ行列は double(CV_64F)で作るのが一般的(CV_32F でも動作する)
distCoeffs 係数数は 4・5・8・12・14 のいずれでもよい
cv::undistort(src, dst, ...) src と dst には別の変数を渡す(同じ変数だと assertion エラー)

引数と戻り値

引数 型 内容
src cv::InputArray 補正前の入力画像(8U・16U・32Fに対応)
dst cv::OutputArray 補正後の出力画像(srcと同サイズ・同型)
cameraMatrix cv::InputArray 3×3のカメラ内部行列(CV_64F / CV_32F)
distCoeffs cv::InputArray 歪み係数ベクトル(4・5・8・12・14要素)
newCameraMatrix cv::InputArray 省略可。出力画像のカメラ行列(省略時はcameraMatrixと同じ)

戻り値はありません(void)。


実践例

有効画素を最大化する: getOptimalNewCameraMatrix との組み合わせ

cv::undistort 単体では、歪み補正によって画像端に黒帯が出る場合があります。cv::getOptimalNewCameraMatrix で新しいカメラ行列を計算してから渡すと、有効画素領域を制御できます。

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

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

    cv::Mat cameraMatrix = (cv::Mat_<double>(3, 3)
        << 800.0,   0.0, 320.0,
              0.0, 800.0, 240.0,
              0.0,   0.0,   1.0);

    cv::Mat distCoeffs = (cv::Mat_<double>(1, 5)
        << -0.3, 0.1, 0.0, 0.0, 0.0);

    // alpha=0: 黒帯なし(有効画素のみ)、alpha=1: 全画素保持
    cv::Rect validROI;
    cv::Mat newCameraMatrix = cv::getOptimalNewCameraMatrix(
        cameraMatrix, distCoeffs, src.size(), /*alpha=*/0, src.size(), &validROI);

    cv::Mat dst;
    cv::undistort(src, dst, cameraMatrix, distCoeffs, newCameraMatrix);

    // 有効領域だけを切り出す
    cv::Mat cropped = dst(validROI);
    cv::imwrite("undistorted_cropped.jpg", cropped);
    std::cout << "有効ROI: " << validROI << "\n";

    return 0;
}

実行結果:

有効ROI: [639 x 479 from (0, 0)]

alpha=0 にすると黒帯が一切出ない代わりに画角が狭くなります。alpha=1 は全ピクセルを保持しますが周辺に黒帯が出ます。用途に応じて使い分けてください。


高速化: initUndistortRectifyMap + remap

cv::undistort は呼び出しのたびに内部でマップを再計算します。同じカメラで複数フレームを処理するリアルタイム用途では、マップを一度だけ生成しておき cv::remap で適用する方法が大幅に高速です。

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

int main()
{
    cv::Mat cameraMatrix = (cv::Mat_<double>(3, 3)
        << 800.0,   0.0, 320.0,
              0.0, 800.0, 240.0,
              0.0,   0.0,   1.0);

    cv::Mat distCoeffs = (cv::Mat_<double>(1, 5)
        << -0.3, 0.1, 0.0, 0.0, 0.0);

    cv::Size imageSize(640, 480);

    // マップを一度だけ計算する
    cv::Mat map1, map2;
    cv::initUndistortRectifyMap(
        cameraMatrix, distCoeffs,
        cv::Mat(),          // R: 単眼カメラは空
        cameraMatrix,       // newCameraMatrix
        imageSize,
        CV_32FC1,           // map の型
        map1, map2);

    // 以降はフレームごとに remap を呼ぶだけ
    cv::VideoCapture cap("video.mp4");
    if (!cap.isOpened()) {
        std::cerr << "動画を開けませんでした。\n";
        return 1;
    }

    cv::Mat frame, undistorted;
    while (cap.read(frame)) {
        cv::remap(frame, undistorted, map1, map2, cv::INTER_LINEAR);
        cv::imshow("undistorted", undistorted);
        if (cv::waitKey(1) == 'q') break;
    }

    return 0;
}

動画や連続フレーム処理では initUndistortRectifyMap + remap を使うのが実務上の定石です。


つまずきポイント

⚠️ src と dst に同じ Mat を渡すと assertion エラー

cv::undistort はインプレース処理に対応していません。src と dst に同じ cv::Mat を渡すと、実行時に assertion エラー(dst.data != src.data)が出ます。出力は別の変数で受け取ってください。

// NG: 同じ Mat を渡すと assertion 失敗
cv::undistort(img, img, cameraMatrix, distCoeffs);

// OK
cv::Mat dst;
cv::undistort(img, dst, cameraMatrix, distCoeffs);

⚠️ undistort を毎フレーム呼ぶとパフォーマンスが出ない

内部で毎回マップを計算するため、カメラパラメータが変わらないのに cv::undistort をループ内で呼び続けると CPU を無駄に消費します。リアルタイム処理では前述の initUndistortRectifyMap + remap パターンに切り替えてください。

⚠️ 歪み係数の要素数に注意

distCoeffs に渡せる要素数は 4・5・8・12・14 のいずれかです。誤ったサイズのベクトルを渡すと補正結果がおかしくなるか、実行時エラーになります。cv::calibrateCamera が出力した行列をそのまま使えば問題ありません。


関連する関数

  • cv::calibrateCamera — キャリブレーションボードの撮影結果からカメラ行列と歪み係数を算出する。cv::undistort に渡すパラメータはここで得る
  • cv::initUndistortRectifyMap — 歪み補正マップを事前計算する。高速化の必須セット
  • cv::remap — 計算済みマップで画像変換を適用する。initUndistortRectifyMap とセットで使う
  • cv::getOptimalNewCameraMatrix — 補正後の有効画素領域と黒帯のトレードオフを alpha パラメータで制御する

まとめ

  • cv::undistort は1関数でレンズ歪み補正を完結できる手軽なAPIです。
  • 連続フレーム処理では initUndistortRectifyMap + remap に切り替えることで大幅な高速化が見込めます。
  • カメラ行列・歪み係数は calibrateCamera の出力をそのまま利用するのが確実です。src と dst には別の変数を渡してください。

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

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

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

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