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仕様書・サンプルコード

