cv::calcOpticalFlowFarneback の使い方【OpenCV/C++】〜密なオプティカルフローで動き検出〜
cv::calcOpticalFlowFarneback は、フレーム間のすべての画素について移動ベクトルを計算する「密なオプティカルフロー」を Gunnar Farneback のアルゴリズムで実現する関数です。物体追跡・動き検出・映像安定化など、フレーム全体の動きを把握したいシーンで使います。
最小の呼び出し例:
cv::calcOpticalFlowFarneback(prevGray, nextGray, flow, 0.5, 3, 15, 3, 5, 1.2, 0);
動作環境
- OpenCV 4.x
- C++17
- ビルド:
g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4) -o main
環境構築がまだの方は環境構築ガイドを先にどうぞ。
基本の使い方
連続する2フレームを読み込み、フロー結果を HSV 色相で可視化する完全プログラムです。
#include <iostream>
#include <opencv2/opencv.hpp>
int main()
{
// 動画ファイルを開く(カメラなら 0 を指定)
cv::VideoCapture cap("input.mp4");
if (!cap.isOpened()) {
std::cerr << "動画を開けませんでした" << std::endl;
return 1;
}
cv::Mat frame, prevGray, nextGray;
// 最初のフレームを取得してグレースケール変換
cap >> frame;
if (frame.empty()) {
std::cerr << "フレームの読み込みに失敗しました" << std::endl;
return 1;
}
cv::cvtColor(frame, prevGray, cv::COLOR_BGR2GRAY);
// HSV 可視化用のベースを作成
cv::Mat hsv(frame.size(), CV_8UC3, cv::Scalar(0, 255, 0));
while (true) {
cap >> frame;
if (frame.empty()) break;
// 現フレームをグレースケールに変換
cv::cvtColor(frame, nextGray, cv::COLOR_BGR2GRAY);
// 密なオプティカルフローを計算(結果は CV_32FC2 の Mat)
cv::Mat flow;
cv::calcOpticalFlowFarneback(
prevGray, nextGray, flow,
0.5, // pyrScale: ピラミッドスケール
3, // levels: ピラミッド階層数
15, // winsize: 平均化ウィンドウサイズ
3, // iterations: 各スケールでの反復回数
5, // polyN: 多項式展開の近傍サイズ
1.2, // polySigma: ガウスの標準偏差
0 // flags
);
// flow を極座標(大きさ・角度)に変換して HSV で可視化
cv::Mat flowChannels[2];
cv::split(flow, flowChannels); // flowChannels[0]=x成分, [1]=y成分
cv::Mat magnitude, angle;
cv::cartToPolar(flowChannels[0], flowChannels[1], magnitude, angle, true);
// 色相 = 移動方向、明度 = 移動量
cv::Mat hsvChannels[3];
cv::split(hsv, hsvChannels);
angle.convertTo(hsvChannels[0], CV_8U, 0.5); // 角度 → 色相 [0,180]
cv::normalize(magnitude, hsvChannels[2], 0, 255, cv::NORM_MINMAX, CV_8U);
cv::merge(hsvChannels, 3, hsv);
// BGR に変換して表示
cv::Mat bgr;
cv::cvtColor(hsv, bgr, cv::COLOR_HSV2BGR);
cv::imshow("Farneback Optical Flow", bgr);
if (cv::waitKey(30) == 'q') break;
// 現フレームを次のループの前フレームに
std::swap(prevGray, nextGray);
}
return 0;
}
実行結果:
ウィンドウ "Farneback Optical Flow" が表示されます。
動いている物体がある領域には色がつき、
その色相(色)が移動方向を、明るさが移動速度を表します。
静止している領域は黒く表示されます。
'q' キーで終了します。
コード解説:
cv::cvtColorでグレースケール変換: オプティカルフローの入力はCV_8UC1のグレースケール画像が必要です。flowの型はCV_32FC2: 各画素に(dx, dy)の2チャンネル浮動小数点値が格納されます。cv::splitで x/y 成分を分離後、cv::cartToPolarで大きさと角度を求めます。- HSV の H チャンネルに角度、V チャンネルに正規化した大きさをマッピングすることで方向と速度を直感的に可視化できます。
引数と戻り値
| 引数 | 型 | 説明 |
|---|---|---|
prev |
InputArray |
前フレームのグレースケール画像(CV_8UC1) |
next |
InputArray |
現フレームのグレースケール画像(CV_8UC1) |
flow |
InputOutputArray |
出力フロー。CV_32FC2 の Mat(dx, dy 成分) |
pyrScale |
double |
ピラミッドスケール。0.5 が標準(次の階層が半分のサイズ) |
levels |
int |
ピラミッドの階層数。多いほど大きな動きを捉えられる |
winsize |
int |
平均化ウィンドウサイズ。大きいほどロバストだが精度は低下 |
iterations |
int |
各ピラミッド階層での反復回数 |
polyN |
int |
多項式展開の近傍サイズ。5 または 7 が一般的 |
polySigma |
double |
多項式展開で使うガウスの標準偏差。polyN=5→1.1〜1.2、polyN=7→1.5 程度 |
flags |
int |
cv::OPTFLOW_USE_INITIAL_FLOW(前回 flow を初期値に使う)/ cv::OPTFLOW_FARNEBACK_GAUSSIAN(ガウス窓使用) |
戻り値はなし(void)。結果は flow に書き込まれます。
実践例
動き領域をマスクとして抽出する
フロー magnitude のしきい値処理で動き領域だけを抽出します。
#include <iostream>
#include <opencv2/opencv.hpp>
int main()
{
cv::VideoCapture cap("input.mp4");
if (!cap.isOpened()) {
std::cerr << "動画を開けませんでした" << std::endl;
return 1;
}
cv::Mat frame, prevGray, nextGray;
cap >> frame;
if (frame.empty()) return 1;
cv::cvtColor(frame, prevGray, cv::COLOR_BGR2GRAY);
while (true) {
cap >> frame;
if (frame.empty()) break;
cv::cvtColor(frame, nextGray, cv::COLOR_BGR2GRAY);
cv::Mat flow;
cv::calcOpticalFlowFarneback(prevGray, nextGray, flow,
0.5, 3, 15, 3, 5, 1.2, 0);
// magnitude を計算
cv::Mat flowChannels[2];
cv::split(flow, flowChannels);
cv::Mat magnitude, angle;
cv::cartToPolar(flowChannels[0], flowChannels[1], magnitude, angle);
// しきい値処理で動き領域のマスクを生成
cv::Mat motionMask;
double threshold = 2.0; // 2 ピクセル以上の移動を「動き」と判定
cv::threshold(magnitude, motionMask, threshold, 255, cv::THRESH_BINARY);
motionMask.convertTo(motionMask, CV_8U);
// 動き領域を元フレームに重畳
cv::Mat result = frame.clone();
result.setTo(cv::Scalar(0, 0, 255), motionMask); // 動き領域を赤で塗る
cv::imshow("Motion Mask", result);
if (cv::waitKey(30) == 'q') break;
std::swap(prevGray, nextGray);
}
return 0;
}
実行結果:
動きのある領域が赤くハイライトされた映像が表示されます。
threshold の値を大きくすると細かい揺れを無視でき、
小さくすると微小な動きも検出します。
フロー結果をファイルに保存する
処理結果を動画ファイルに書き出したい場合は、cv::VideoWriter の使い方【OpenCV/C++】〜動画ファイルを書き出す〜 を参照してください。
つまずきポイント
⚠️ 入力画像が CV_8UC1 でないと assertion 失敗する
cv::calcOpticalFlowFarneback の prev・next は グレースケール(CV_8UC1) でなければなりません。BGR カラー画像を直接渡すと実行時に assertion が発生します。必ず cv::cvtColor でグレースケール変換してから渡してください。
// NG: BGR のまま渡す
cv::calcOpticalFlowFarneback(prevBGR, nextBGR, flow, ...);
// OK: グレースケール変換してから渡す
cv::cvtColor(prevBGR, prevGray, cv::COLOR_BGR2GRAY);
cv::calcOpticalFlowFarneback(prevGray, nextGray, flow, ...);
⚠️ OPTFLOW_USE_INITIAL_FLOW では flow を CV_32FC2 で渡す
出力の flow は CV_32FC2 の浮動小数点2チャンネルで返されます(通常の呼び出しでは、別の型で確保した Mat を渡しても CV_32FC2 に作り直されます)。前回の flow を初期値として使う OPTFLOW_USE_INITIAL_FLOW フラグを立てる場合は、入力画像と同じサイズの CV_32FC2 を渡す必要があり、型やサイズが違うと assertion(_flow0.channels() == 2 && _flow0.depth() == CV_32F など)で例外になります。
⚠️ winsize を大きくするとフローがぼやける
winsize は平均化ウィンドウサイズで、大きくするとノイズに強くなり速い動きも捉えやすくなる一方、動きの境界がぼやけたフローになります。既定(ボックスフィルタ)では winsize を大きくしても計算時間はほとんど変わりませんが、OPTFLOW_FARNEBACK_GAUSSIAN を指定すると winsize に応じて計算時間が増えます。処理速度が足りない場合は levels と iterations を調整するか、入力画像をリサイズしてからフローを計算し、ベクトルを元スケールに戻す方法が有効です。
関連する関数
- cv::VideoCapture — 動画・カメラ入力の取得。cv::VideoCapture の使い方【OpenCV/C++】〜カメラ映像を取り込む〜
- cv::VideoWriter — フロー可視化結果を動画保存する。cv::VideoWriter の使い方【OpenCV/C++】〜動画ファイルを書き出す〜
- cv::calcOpticalFlowPyrLK — 特定の特徴点のみ追跡するスパースなオプティカルフロー。密なフローが重すぎる場合の代替
- cv::cartToPolar — フロー (dx, dy) を大きさ・角度に変換する際に使用
まとめ
cv::calcOpticalFlowFarneback は全画素の移動ベクトルを一度に得られる密なオプティカルフロー実装です。入力は必ず CV_8UC1 のグレースケール画像を用意し、出力 flow(CV_32FC2)を cv::cartToPolar で可視化するパターンが基本形です。リアルタイム用途では levels・iterations と入力解像度の調整が処理速度のカギになります。
🛠 画像処理のプロが開発するSDK/API
本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。
→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

