cv::fastNlMeansDenoising は Non-Local Means アルゴリズムを使ったノイズ除去関数です。ガウシアンブラーや中央値フィルタと比べて、エッジを保持しながらノイズを除去できるのが最大の特徴です。グレースケール画像に対応しており、カラー画像には cv::fastNlMeansDenoisingColored を使います。
最小の呼び出しは次のとおりです。
cv::fastNlMeansDenoising(src, dst, 10.0f, 7, 21);
動作環境
- OpenCV 4.x
- コンパイル例:
g++ -std=c++17 main.cpp `pkg-config --cflags --libs opencv4` -o main
環境構築がまだの方は環境構築ガイドを先にどうぞ。
基本の使い方
#include <opencv2/opencv.hpp>
#include <opencv2/photo.hpp>
#include <iostream>
int main() {
// グレースケールで読み込む
cv::Mat src = cv::imread("input.png", cv::IMREAD_GRAYSCALE);
if (src.empty()) {
std::cerr << "画像を読み込めませんでした" << std::endl;
return 1;
}
cv::Mat dst;
// h=10: フィルタ強度、templateWindowSize=7、searchWindowSize=21
cv::fastNlMeansDenoising(src, dst, 10.0f, 7, 21);
cv::imwrite("output.png", dst);
std::cout << "ノイズ除去完了: output.png に保存しました" << std::endl;
return 0;
}
実行結果
ノイズ除去完了: output.png に保存しました
output.png を確認すると、元画像に比べてランダムなざらつき(ノイズ)が抑えられ、輪郭部分は比較的シャープなまま残っていることが確認できます。
行ごとの解説
| 行 | 内容 |
|---|---|
cv::imread(..., IMREAD_GRAYSCALE) |
グレースケールで読み込む。fastNlMeansDenoising はグレースケール画像向け |
src.empty() チェック |
読み込み失敗を必ず検出する |
fastNlMeansDenoising(src, dst, 10.0f, 7, 21) |
フィルタ強度10・テンプレートウィンドウ7・探索ウィンドウ21で除去 |
cv::imwrite |
結果をファイルに保存 |
引数と戻り値
cv::fastNlMeansDenoising(グレースケール用)
| 引数 | 型 | 説明 |
|---|---|---|
src |
cv::InputArray |
入力画像(8ビットの1〜4チャンネル。想定はグレースケール) |
dst |
cv::OutputArray |
出力画像(srcと同サイズ・同型) |
h |
float |
フィルタ強度。値が大きいほどノイズ除去が強い反面、ぼけも増す。典型値: 3〜10 |
templateWindowSize |
int |
テンプレートパッチのサイズ(奇数)。デフォルト 7 |
searchWindowSize |
int |
類似パッチを探す範囲(奇数)。デフォルト 21 |
戻り値はなし(void)。結果は dst に格納されます。
cv::fastNlMeansDenoisingColored(カラー用)
| 引数 | 型 | 説明 |
|---|---|---|
src |
cv::InputArray |
入力画像(CV_8UC3 のBGR画像。CV_8UC4 も可) |
dst |
cv::OutputArray |
出力画像 |
h |
float |
輝度成分のフィルタ強度 |
hColor |
float |
色成分のフィルタ強度。通常 h と同値か小さめに設定 |
templateWindowSize |
int |
テンプレートパッチのサイズ(奇数) |
searchWindowSize |
int |
探索ウィンドウサイズ(奇数) |
実践例
カラー画像のノイズ除去
実務でよく扱うBGRカラー画像には fastNlMeansDenoisingColored を使います。
#include <opencv2/opencv.hpp>
#include <opencv2/photo.hpp>
#include <iostream>
int main() {
// BGRカラーで読み込む
cv::Mat src = cv::imread("color_input.png");
if (src.empty()) {
std::cerr << "画像を読み込めませんでした" << std::endl;
return 1;
}
cv::Mat dst;
// h=10: 輝度強度、hColor=10: 色強度、テンプレート7、探索21
cv::fastNlMeansDenoisingColored(src, dst, 10.0f, 10.0f, 7, 21);
cv::imwrite("color_output.png", dst);
std::cout << "カラーノイズ除去完了: color_output.png に保存しました" << std::endl;
return 0;
}
実行結果
カラーノイズ除去完了: color_output.png に保存しました
hColor を h より小さくする(例: h=10, hColor=7)と色のにじみを抑えやすくなります。撮影条件や画像によって調整してください。
フィルタ強度の比較ループ
パラメータ選定が難しいため、複数の h の値で出力を比較するスクリプトが実務では便利です。
#include <opencv2/opencv.hpp>
#include <opencv2/photo.hpp>
#include <iostream>
#include <string>
int main() {
cv::Mat src = cv::imread("input.png", cv::IMREAD_GRAYSCALE);
if (src.empty()) {
std::cerr << "画像を読み込めませんでした" << std::endl;
return 1;
}
// h を 5〜20 まで5刻みで試す
for (int h : {5, 10, 15, 20}) {
cv::Mat dst;
cv::fastNlMeansDenoising(src, dst, static_cast<float>(h), 7, 21);
std::string filename = "output_h" + std::to_string(h) + ".png";
cv::imwrite(filename, dst);
std::cout << "保存: " << filename << std::endl;
}
return 0;
}
実行結果
保存: output_h5.png
保存: output_h10.png
保存: output_h15.png
保存: output_h20.png
各ファイルを並べて見比べることで、エッジのつぶれと残留ノイズのトレードオフを目視確認できます。
つまずきポイント
⚠️ opencv2/photo.hpp のインクルード忘れ
fastNlMeansDenoising は photo モジュールに属しています。opencv2/opencv.hpp だけでコンパイルできる環境もありますが、個別ヘッダを使う構成では opencv2/photo.hpp を明示的にインクルードしないとコンパイルエラーになります。リンク時も opencv_photo ライブラリが必要です。
// CMakeLists.txt でモジュールを明示する場合
find_package(OpenCV REQUIRED photo)
target_link_libraries(your_target ${OpenCV_LIBS})
⚠️ カラー画像を fastNlMeansDenoising に渡してもエラーにならない
cv::fastNlMeansDenoising は8ビットの1〜4チャンネル画像を受け付けるため、BGRの3チャンネル画像(CV_8UC3)を渡しても例外は出ず、そのまま BGR の値で処理されてしまいます。cv::fastNlMeansDenoisingColored は画像を CIELAB に変換し、輝度(h)と色(hColor)を別の強さで処理するので、カラー画像にはこちらを使ってください。
// エラーにはならないが、カラー向けの処理ではない
cv::fastNlMeansDenoising(color_src, dst, 10.0f, 7, 21);
// カラー画像はこちら
cv::fastNlMeansDenoisingColored(color_src, dst, 10.0f, 10.0f, 7, 21);
なお、この形(float h を1つ渡す形)は8ビット画像専用です。CV_16U の画像を渡すと Unsupported depth! Only CV_8U is supported for NORM_L2 の例外になります。16ビット画像は std::vector<float> で h を渡し、normType に cv::NORM_L1 を指定する形を使います。
⚠️ 処理が遅い・タイムアウトする
Non-Local Means は探索ウィンドウ全体を走査するため、searchWindowSize が大きいほど処理時間が増大します。フルHD画像に searchWindowSize=21 を使うと、Apple M シリーズの Mac(OpenCV 4.14)で、グレースケールでも1枚あたり約0.3秒(シングルスレッドでは約1.4秒)、fastNlMeansDenoisingColored では約0.8秒かかりました。リアルタイム処理には不向きです。速度優先ならば cv::GaussianBlur や cv::medianBlur を検討してください。
関連する関数
cv::GaussianBlur— 高速なノイズ低減。エッジ保持は弱いがリアルタイム向きcv::medianBlur— ごま塩ノイズに強い中央値フィルタcv::fastNlMeansDenoisingColored— 本記事で紹介したカラー画像向け姉妹関数cv::bilateralFilter— エッジ保持型平滑化。Non-Local Means より高速
まとめ
cv::fastNlMeansDenoising はエッジを保ちながらノイズを除去できる強力な関数ですが、処理速度は遅めです。グレースケールには fastNlMeansDenoising、カラーには fastNlMeansDenoisingColored を使い分けてください。パラメータ h の調整は複数値を出力して目視比較するのが実務的な最短ルートです。
🛠 画像処理のプロが開発するSDK/API
本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。
→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

