はじめに

OpenCV (Open Source Computer Vision Library: http://opencv.org) は、数百種類のコンピュータビジョンアルゴリズムを含むオープンソースライブラリである。本ドキュメントでは、いわゆるOpenCV 2.x APIについて説明する。これは本質的にC++ APIであり、CベースのOpenCV 1.x API（C APIは非推奨であり、OpenCV 2.4リリース以降は「C」コンパイラでテストされていない）とは対照的なものである。

OpenCVはモジュール構造を持っており、パッケージにはいくつかの共有ライブラリまたは静的ライブラリが含まれている。次のモジュールが利用できる:

• コア機能 (core) - 密な多次元配列Matや、他のすべてのモジュールで使われる基本関数など、基本的なデータ構造を定義するコンパクトなモジュール。
• 画像処理 (imgproc) - 線形・非線形の画像フィルタリング、幾何学的な画像変換（リサイズ、アフィン・透視ワーピング、汎用的なテーブルベースのリマッピング）、色空間変換、ヒストグラムなどを含む画像処理モジュール。
• 画像ファイルの読み込みと書き込み (imgcodecs) - さまざまな形式の画像ファイルの読み書きを行う関数を含む。
• ビデオI/O (videoio) - ビデオキャプチャとビデオコーデックに対する使いやすいインターフェース。
• 高レベルGUI (highgui) - シンプルなUI機能に対する使いやすいインターフェース。
• 動画解析 (video) - 動き推定、背景差分、物体追跡アルゴリズムを含むビデオ解析モジュール。
• 3d (3d) - 基本的な多視点幾何アルゴリズム、物体の姿勢推定、および3D再構成の要素。
• 特徴フレームワーク (features) - 顕著な特徴の検出器、記述子、および記述子マッチャ。
• 物体検出 (objdetect) - あらかじめ定義されたクラス（例えば顔、目、マグカップ、人、車など）の物体やインスタンスの検出。
• カメラキャリブレーション (calib) - 単眼およびステレオカメラのキャリブレーション
• ステレオ対応付け (stereo) - ステレオ対応アルゴリズム
• 高レベルGUI (highgui) - シンプルなUI機能に対する使いやすいインターフェース。
• ビデオI/O (videoio) - ビデオキャプチャとビデオコーデックに対する使いやすいインターフェース。
• ディープニューラルネットワークモジュール (dnn) - ディープニューラルネットワークモジュール。
• コンピュテーショナルフォトグラフィ (photo) - ノイズ除去や修復（インペインティング）といった高度な写真処理技術。
• 画像のスティッチング (stitching) - 画像スティッチングとパノラマ作成のための関数。
• ... FLANNやGoogleテストのラッパー、Pythonバインディングなど、その他のヘルパーモジュール。

本ドキュメントの以降の章では、各モジュールの機能について説明する。ただしその前に、ライブラリ全体で広く使われている共通のAPIの概念に必ず慣れておくこと。

APIの概念

cv 名前空間

OpenCVのすべてのクラスと関数は cv 名前空間に配置されている。したがって、自分のコードからこの機能にアクセスするには、cv:: 指定子または using namespace cv; ディレクティブを使う:

#include "opencv2/core.hpp"
...
cv::Mat H = cv::findHomography(points1, points2, cv::RANSAC, 5);
...

または:

#include "opencv2/core.hpp"
using namespace cv;
...
Mat H = findHomography(points1, points2, RANSAC, 5 );
...

現在または将来のOpenCVの外部名の一部は、STLや他のライブラリと衝突する可能性がある。その場合は、明示的に名前空間指定子を使って名前の衝突を解決する:

Mat a(100, 100, CV_32F);
randu(a, Scalar::all(1), Scalar::all(std::rand()));
cv::log(a, a);
a /= std::log(2.);

自動メモリ管理

OpenCVはすべてのメモリを自動的に処理する。

まず、std::vector、cv::Mat、および関数やメソッドで使用されるその他のデータ構造は、必要なときに内部のメモリバッファを解放するデストラクタを持つ。これは、Matの場合のように、デストラクタが常にバッファを解放するとは限らないことを意味する。デストラクタはデータ共有の可能性を考慮する。デストラクタは、行列データバッファに関連付けられた参照カウンタをデクリメントする。バッファが解放されるのは参照カウンタがゼロに達したとき、つまり他のどの構造も同じバッファを参照していないときに限られる。同様に、Matインスタンスがコピーされるとき、実際のデータはコピーされない。代わりに、同じデータの別の所有者がいることを記憶するために参照カウンタがインクリメントされる。行列データの完全なコピーを作成する cv::Mat::clone メソッドもある。以下の例を参照のこと:

// create a big 8Mb matrix
Mat A(1000, 1000, CV_64F);
 
// create another header for the same matrix;
// this is an instant operation, regardless of the matrix size.
Mat B = A;
// create another header for the 3-rd row of A; no data is copied either
Mat C = B.row(3);
// now create a separate copy of the matrix
Mat D = B.clone();
// copy the 5-th row of B to C, that is, copy the 5-th row of A
// to the 3-rd row of A.
B.row(5).copyTo(C);
// now let A and D share the data; after that the modified version
// of A is still referenced by B and C.
A = D;
// now make B an empty matrix (which references no memory buffers),
// but the modified version of A will still be referenced by C,
// despite that C is just a single row of the original A
B.release();
 
// finally, make a full copy of C. As a result, the big modified
// matrix will be deallocated, since it is not referenced by anyone
C = C.clone();

Matやその他の基本構造の使用が簡単であることがわかる。しかし、自動メモリ管理を考慮せずに作成された高水準クラスやユーザー定義データ型についてはどうだろうか。それらのために、OpenCVはC++11のstd::shared_ptrに似た cv::Ptr テンプレートクラスを提供している。そのため、素のポインタを使う代わりに:

T* ptr = new T(...);

次のように書ける:

Ptr<T> ptr(new T(...));

または：

Ptr<T> ptr = makePtr<T>(...);

Ptr<T> は、T型インスタンスへのポインタと、そのポインタに関連付けられた参照カウンタをカプセル化する。詳細は cv::Ptr の説明を参照。

出力データの自動割り当て

OpenCVはメモリを自動的に解放し、また多くの場合、出力関数引数のメモリも自動的に割り当てる。したがって、関数が1つ以上の入力配列（cv::Mat インスタンス）といくつかの出力配列を持つ場合、出力配列は自動的に割り当てまたは再割り当てされる。出力配列のサイズと型は、入力配列のサイズと型から決定される。必要に応じて、関数は出力配列のプロパティを判断するのに役立つ追加の引数を取る。

例:

#include "opencv2/imgproc.hpp"
#include "opencv2/highgui.hpp"
 
using namespace cv;
 
int main(int, char**)
{
 VideoCapture cap(0);
 if(!cap.isOpened()) return -1;
 
 Mat frame, edges;
    namedWindow("edges", WINDOW_AUTOSIZE);
 for(;;)
    {
        cap >> frame;
        cvtColor(frame, edges, COLOR_BGR2GRAY);
        GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5);
        Canny(edges, edges, 0, 30, 3);
        imshow("edges", edges);
 if(waitKey(30) >= 0) break;
    }
 return 0;
}

ビデオフレームの解像度とビット深度はビデオキャプチャモジュールが把握しているため、配列frameは >> 演算子によって自動的に割り当てられる。配列edgesはcvtColor関数によって自動的に割り当てられる。これは入力配列と同じサイズおよびビット深度を持つ。色変換コード cv::COLOR_BGR2GRAY が渡されており、これはカラーからグレースケールへの変換を意味するため、チャンネル数は1である。frameとedgesは、それ以降のすべてのビデオフレームが同じ解像度を持つため、ループ本体の最初の実行時に一度だけ割り当てられることに注意。もし何らかの方法でビデオ解像度を変更すると、配列は自動的に再割り当てされる。

この技術の鍵となる構成要素は cv::Mat::create メソッドである。このメソッドは、希望する配列のサイズと型を受け取る。配列がすでに指定されたサイズと型を持っている場合、メソッドは何もしない。そうでない場合は、以前に割り当てられたデータがあればそれを解放し（この処理には参照カウンタのデクリメントとゼロとの比較が含まれる）、その後、必要なサイズの新しいバッファを割り当てる。ほとんどの関数は各出力配列に対して cv::Mat::create メソッドを呼び出すため、出力データの自動割り当てが実現される。

このスキームの注目すべき例外として、cv::mixChannels、cv::RNG::fill、およびその他いくつかの関数やメソッドがある。これらは出力配列を割り当てられないため、事前に自分で割り当てておく必要がある。

飽和演算

コンピュータビジョンライブラリとして、OpenCVはしばしばチャンネルあたり8ビットまたは16ビットというコンパクトな形式でエンコードされ、そのため値の範囲が限られた画像ピクセルを多く扱う。さらに、色空間変換、明るさ・コントラスト調整、シャープニング、複雑な補間（バイキュービック、Lanczos）といった画像に対する特定の演算は、利用可能な範囲を超える値を生成しうる。結果の下位8（16）ビットだけを保存すると、視覚的なアーティファクトが生じ、その後の画像解析に影響を及ぼす可能性がある。この問題を解決するために、いわゆる飽和 (saturation) 演算が用いられる。例えば、演算結果 r を8ビット画像に保存するには、0..255の範囲内で最も近い値を求める:

\[I(x,y)= \min ( \max (\textrm{round}(r), 0), 255)\]

同様の規則が8ビット符号付き、16ビット符号付きおよび符号なしの型にも適用される。このセマンティクスはライブラリ全体で使われている。C++コードでは、標準的なC++のキャスト演算に似た cv::saturate_cast<> 関数を使って行われる。上で示した式の実装を以下に示す:

I.at<uchar>(y, x) = saturate_cast<uchar>(r);

ここで cv::uchar はOpenCVの8ビット符号なし整数型である。最適化されたSIMDコードでは、paddusb、packuswbなどのSSE2命令が使われる。これらはC++コードとまったく同じ動作を実現するのに役立つ。

覚え書き

結果が32ビット整数の場合、飽和は適用されない。

固定されたピクセル型。テンプレートの限定的な使用

テンプレートは、非常に強力で効率的かつ安全なデータ構造やアルゴリズムの実装を可能にするC++の優れた機能である。しかし、テンプレートを多用すると、コンパイル時間とコードサイズが劇的に増大する可能性がある。さらに、テンプレートだけを使う場合、インターフェースと実装を分離することが難しくなる。これは基本的なアルゴリズムには問題ないが、1つのアルゴリズムが数千行のコードに及ぶこともあるコンピュータビジョンライブラリには適していない。このため、また、テンプレートをまったく持たないか、限られたテンプレート機能しか持たないPython、Java、Matlabといった他言語向けのバインディング開発を簡素化するためにも、現在のOpenCVの実装は、テンプレートよりも多態性と実行時ディスパッチに基づいている。実行時ディスパッチが遅すぎる箇所（ピクセルアクセス演算子など）、不可能な箇所（汎用の cv::Ptr<> の実装）、あるいは単に非常に不便な箇所（cv::saturate_cast<>()）では、現在の実装は小さなテンプレートクラス、メソッド、関数を導入している。現在のOpenCVバージョンのそれ以外の場所では、テンプレートの使用は限定的である。

その結果、ライブラリが扱える基本データ型は限られた固定の集合である。すなわち、配列の要素は次の型のいずれかでなければならない:

• 8ビット符号なし整数 (uint8_t, uchar)
• 8ビット符号付き整数 (int8_t, schar)
• 16ビット符号なし整数 (uint16_t, ushort)
• 16ビット符号付き整数 (int16_t, short)
• 32ビット符号なし整数 (uint32_t, unsigned) *1
• 32ビット符号付き整数 (int32_t, int)
• 64ビット符号なし整数 (uint64_t, unsigned long) *1
• 64ビット符号付き整数 (int64_t, long) *1
• 16ビット brain浮動小数点数 / bfloat16 (bfloat) *1
• 16ビット半精度浮動小数点数 / hfloat16 (hfloat)
• 32ビット単精度浮動小数点数 (float)
• 64ビット倍精度浮動小数点数 (double)
• ブール値 (boolean) *1
• すべての要素が同じ型（上記のいずれか）を持つ、複数の要素のタプル。要素がこのようなタプルである配列はマルチチャンネル配列と呼ばれ、要素がスカラー値であるシングルチャンネル配列とは対照的である。チャンネルの最大数は CV_CN_MAX 定数で定義されており、現在は128に設定されている。

覚え書き

*1) OpenCV5からサポートされている。

これらの基本型に対して、以下の定義が適用される:

#define CV_8U   0
#define CV_8S   1
#define CV_16U  2
#define CV_16S  3
#define CV_32S  4
#define CV_32F  5
#define CV_64F  6
#define CV_16F  7
#define CV_16BF 8
#define CV_Bool 9
#define CV_64U  10
#define CV_64S  11
#define CV_32U  12

マルチチャンネル（nチャンネル）型は、次のオプションを使って指定できる:

• CV_8UC1 ... CV_32UC4 定数（チャンネル数が1から4までの場合）
• チャンネル数が4を超える場合やコンパイル時に不明な場合の CV_8UC(n) ... CV_32UC(n) または CV_MAKETYPE(CV_8U, n) ... CV_MAKETYPE(CV_32U, n) マクロ。

覚え書き

#CV_32FC1 == #CV_32F, #CV_32FC2 == #CV_32FC(2) == #CV_MAKETYPE(CV_32F, 2)、および #CV_MAKETYPE(depth, n) == (CV_MAT_DEPTH(depth) + (((cn)-1) << CV_CN_SHIFT))。これは、型定数がビット深度（最下位のCV_CN_SHIFTビット、現在は5に設定されている）とチャンネル数から1を引いた値（次の log2(CV_CN_MAX) ビット）から構成されることを意味する。

例:

Mat mtx(3, 3, CV_32F); // make a 3x3 floating-point matrix
Mat cmtx(10, 1, CV_64FC2); // make a 10x1 2-channel floating-point
 // matrix (10-element complex vector)
Mat img(Size(1920, 1080), CV_8UC3); // make a 3-channel (color) image
 // of 1920 columns and 1080 rows.
Mat grayscale(img.size(), CV_MAKETYPE(img.depth(), 1)); // make a 1-channel image of
 // the same size and same
 // channel type as img

より複雑な要素を持つ配列は、OpenCVを使って構築したり処理したりすることはできない。さらに、各関数やメソッドは、可能なすべての配列型の一部しか扱えない。通常、アルゴリズムが複雑になるほど、サポートされる形式の部分集合は小さくなる。このような制限の典型的な例を以下に示す:

• 顔検出アルゴリズムは、8ビットのグレースケール画像またはカラー画像でのみ動作する。
• 線形代数の関数やほとんどの機械学習アルゴリズムは、浮動小数点配列でのみ動作する。
• cv::add のような基本関数は、すべての型をサポートする。
• 色空間変換関数は、8ビット符号なし、16ビット符号なし、32ビット浮動小数点の型をサポートする。

各関数がサポートする型の部分集合は実用上の必要性から定められており、将来的にユーザーの要望に応じて拡張される可能性がある。

InputArrayとOutputArray

多くのOpenCV関数は、密な2次元または多次元の数値配列を処理する。通常、このような関数は cv::Mat を引数として取るが、場合によっては std::vector<>（たとえば点集合の場合）や cv::Matx<>（3x3のホモグラフィ行列など）を使う方が便利なこともある。APIに多くの重複が生じるのを避けるため、特別な「プロキシ」クラスが導入されている。基本となる「プロキシ」クラスは cv::InputArray である。これは、関数の入力として読み取り専用の配列を渡すために使用される。InputArrayから派生した cv::OutputArray クラスは、関数の出力配列を指定するために使用される。通常、これらの中間型を気にする必要はない（また、これらの型の変数を明示的に宣言すべきではない）。すべて自動的に動作する。InputArray/OutputArrayの代わりに、常に cv::Mat、std::vector<>、cv::Matx<>、cv::Vec<>、または cv::Scalar を使用できると考えてよい。関数が省略可能な入力配列または出力配列を持ち、それを持っていない、または渡したくない場合は、cv::noArray() を渡す。

エラー処理

OpenCVは致命的なエラーを通知するために例外を使う。入力データが正しい形式で指定された値の範囲に属しているにもかかわらず、何らかの理由でアルゴリズムが成功できない場合（例えば最適化アルゴリズムが収束しなかった場合）は、特別なエラーコード（通常は単なるブール変数）を返す。

例外は cv::Exception クラスまたはその派生クラスのインスタンスとなりうる。さらに、cv::Exception は std::exception の派生クラスである。そのため、他の標準C++ライブラリのコンポーネントを使ってコード内で適切に処理できる。

例外は通常、#CV_Error(errcode, description) マクロ、またはそのprintf風の #CV_Error_(errcode, (printf-spec, printf-args)) 亜種を使うか、あるいは条件をチェックしてそれが満たされない場合に例外をスローする CV_Assert(condition) マクロを使ってスローされる。性能が重要なコードのためには、Debug構成でのみ保持される CV_DbgAssert(condition) がある。自動メモリ管理のおかげで、突然のエラーが発生した場合でも、すべての中間バッファは自動的に解放される。必要に応じて例外をキャッチするために、try文を追加するだけでよい:

try
{
    ... // call OpenCV
}
catch (const cv::Exception& e)
{
 const char* err_msg = e.what();
    std::cout << "exception caught: " << err_msg << std::endl;
}

マルチスレッドと再入可能性

現在のOpenCV実装は完全にリエントラント（再入可能）である。すなわち、同じ関数や異なるクラスインスタンスの同じメソッドを異なるスレッドから呼び出せる。また、参照カウント操作にはアーキテクチャ固有のアトミック命令を使用するため、同じMatを異なるスレッドで使用できる。