変更点の概要

このドキュメントは、自分のコードをOpenCV 3.0に移行したいソフトウェア開発者を対象としている。

OpenCV 3.0では、バージョン2.4と比較して多くの新しいアルゴリズムと機能が導入された。一部のモジュールは書き直され、一部は再編成された。2.4のアルゴリズムのほとんどは引き続き存在するが、インターフェースが異なる場合がある。

このセクションでは、最も注目すべき変更点を全般的に説明する。移行作業のすべての詳細と例は、このドキュメントの次のパートにある。

Contribリポジトリ

https://github.com/opencv/opencv_contrib

ここはすべての新しい、実験的な、および非フリーのアルゴリズムのための場所である。メインリポジトリと比較してサポートチームからの注目はそれほど受けないが、コミュニティが良好な状態に保つよう努めている。

contrib リポジトリ付きでOpenCVをビルドするには、cmakeコマンドに次のオプションを追加する:

-DOPENCV_EXTRA_MODULES_PATH=<path-to-opencv_contrib>/modules

ヘッダーのレイアウト

2.4ではすべてのヘッダーが対応するモジュールのサブフォルダ（opencv2/<module>/<module>.hpp）に配置されていたが、3.0ではモジュール機能のほとんどを含むトップレベルのモジュールヘッダー（opencv2/<module>.hpp）があり、すべてのCスタイルAPI定義は別のヘッダー（例: opencv2/core/core_c.h）に移動された。

アルゴリズムインターフェース

アルゴリズムの一般的な使用パターンが変更された: 現在は、スマートポインタ cv::Ptr でラップしてヒープ上に作成する必要がある。バージョン2.4では、スタックとヒープの両方の割り当てが、直接またはスマートポインタ経由で許可されていた。

get および set メソッドは、CV_INIT_ALGORITHM マクロとともに cv::Algorithm クラスから削除された。3.0では、すべてのプロパティが getProperty/setProperty の純粋仮想メソッドのペアに変換された。その結果、名前を使って（汎用の Algorithm::create(String) メソッドを使って）cv::Algorithm インスタンスを作成して使用することは できなく なり、対応するファクトリメソッドを明示的に呼び出す必要がある。

変更されたモジュール

ml モジュールが書き直された
highgui モジュールが各パートに分割された: imgcodecs、videoio、および highgui 自体
features2d モジュールが再編成された（一部の特徴検出器が opencv_contrib/xfeatures2d モジュールに移動された）
legacy、nonfree モジュールが削除された。一部のアルゴリズムは別の場所に移動され、一部は完全に書き直されたか削除された
CUDA APIが更新された（gpu モジュール -> 複数の cuda モジュール、名前空間 gpu -> 名前空間 cuda）
OpenCL APIが変更された（ocl モジュールが削除され、個別の ocl:: 実装 -> Transparent API）
その他のいくつかのメソッドとクラスが移動された

移行のヒント

このセクションでは、具体的なアクションを例とともに説明する。

2.4の準備

最新の OpenCV 2.4.11 で加えられた変更により、現在のコードベースを移行に向けて準備できる:

cv::makePtr 関数が利用可能になった
opencv2/<module>.hpp ヘッダが作成された

新しいヘッダ構成

注意: 移行を容易にするための変更は OpenCV 3.0 で行われているため、以下の手順は必須ではないが推奨される。

古いモジュールヘッダのインクルードを置き換える:
// old header

#include "opencv2/<module>/<module>.hpp"

// new header

#include "opencv2/<module>.hpp"

アルゴリズムのモダンな使い方

アルゴリズムのインスタンスは cv::makePtr 関数、または利用可能であれば対応する静的ファクトリメソッドで生成しなければならない:
// good ways

Ptr<SomeAlgo> algo = makePtr<SomeAlgo>(...);

Ptr<SomeAlgo> algo = SomeAlgo::create(...);

それ以外の方法は非推奨である:
// bad ways

Ptr<SomeAlgo> algo = new SomeAlgo(...);

SomeAlgo * algo = new SomeAlgo(...);

SomeAlgo algo(...);

Ptr<SomeAlgo> algo = Algorithm::create<SomeAlgo>("name");
アルゴリズムのプロパティには対応する仮想メソッド getSomeProperty/setSomeProperty 経由でアクセスすべきである。汎用の get/set メソッドは削除された:
// good way

double clipLimit = clahe->getClipLimit();

clahe->setClipLimit(clipLimit);

// bad way

double clipLimit = clahe->getDouble("clipLimit");

clahe->set("clipLimit", clipLimit);

clahe->setDouble("clipLimit", clipLimit);
initModule_<moduleName>() の呼び出しを削除する

機械学習モジュール

このモジュールは書き直されたため、ソフトウェアを適応させるにはいくらかの作業が必要となる。すべてのアルゴリズムは、基底クラス StatModel とともに専用の ml 名前空間に配置されている。個別の SomeAlgoParams クラスは、対応する一連の getProperty/setProperty メソッドに置き換えられた。

次の表は 2.4 と 3.0 の機械学習クラスの対応を示す。

2.4	3.0
CvStatModel	cv::ml::StatModel
CvNormalBayesClassifier	cv::ml::NormalBayesClassifier
CvKNearest	cv::ml::KNearest
CvSVM	cv::ml::SVM
CvDTree	cv::ml::DTrees
CvBoost	cv::ml::Boost
CvGBTrees	未実装
CvRTrees	cv::ml::RTrees
CvERTrees	未実装
EM	cv::ml::EM
CvANN_MLP	cv::ml::ANN_MLP
未実装	cv::ml::LogisticRegression
CvMLData	cv::ml::TrainData

3.0 で書き直された ml アルゴリズムは xml/yml ファイルから古い学習済みモデルを読み込めるが、予測処理に差異が生じる可能性がある。

points_classifier.cpp サンプルからの次のコード断片は、モデル学習処理の違いを示している:

using namespace cv;
// ======== version 2.4 ========
Mat trainSamples, trainClasses;
prepare_train_data( trainSamples, trainClasses );
CvBoost  boost;
Mat var_types( 1, trainSamples.cols + 1, CV_8UC1, Scalar(CV_VAR_ORDERED) );
var_types.at<uchar>( trainSamples.cols ) = CV_VAR_CATEGORICAL;
CvBoostParams  params( CvBoost::DISCRETE, // boost_type
                       100, // weak_count
                       0.95, // weight_trim_rate
                       2, // max_depth
 false, //use_surrogates
                       0 // priors
                     );
boost.train( trainSamples, CV_ROW_SAMPLE, trainClasses, Mat(), Mat(), var_types, Mat(), params );
 
// ======== version 3.0 ========
Ptr<Boost> boost = Boost::create();
boost->setBoostType(Boost::DISCRETE);
boost->setWeakCount(100);
boost->setWeightTrimRate(0.95);
boost->setMaxDepth(2);
boost->setUseSurrogates(false);
boost->setPriors(Mat());
boost->train(prepare_train_data()); // 'prepare_train_data' returns an instance of ml::TrainData class

特徴検出

一部のアルゴリズム (FREAK, BRIEF, SIFT, SURF) は opencv_contrib リポジトリの xfeatures2d モジュール、xfeatures2d 名前空間へ移された。それらのインターフェースも変更された (基底クラス cv::Feature2D を継承するようになった)。

xfeatures2d モジュールのクラス一覧:

cv::xfeatures2d::BriefDescriptorExtractor - BRIEF 記述子を計算するクラス (2.4 での位置: features2d)
cv::xfeatures2d::FREAK - FREAK (Fast Retina Keypoint) キーポイント記述子を実装するクラス (2.4 での位置: features2d)
cv::xfeatures2d::StarDetector - CenSurE 検出器を実装するクラス (2.4 での位置: features2d)
cv::xfeatures2d::SIFT - Scale Invariant Feature Transform (SIFT) アルゴリズムを用いてキーポイントを抽出し記述子を計算するクラス (2.4 での位置: nonfree)
cv::xfeatures2d::SURF - 画像から Speeded Up Robust Features を抽出するクラス (2.4 での位置: nonfree)

次の手順が必要となる:

opencv_contrib をコンパイル処理に追加する
opencv2/xfeatures2d.h ヘッダをインクルードする
名前空間 xfeatures2d を使用する
必要に応じて operator() の呼び出しを detect, compute, detectAndCompute に置き換える

一部のクラスでは、独自の operator() の代わりに Feature2D 基底クラスが提供する汎用メソッド detect, compute, detectAndCompute を使用するようになった

次のコード断片はその違いを示す (video_homography.cpp サンプルより):

using namespace cv;
// ====== 2.4 =======
#include "opencv2/features2d/features2d.hpp"
BriefDescriptorExtractor brief(32);
GridAdaptedFeatureDetector detector(new FastFeatureDetector(10, true), DESIRED_FTRS, 4, 4);
// ...
detector.detect(gray, query_kpts); //Find interest points
brief.compute(gray, query_kpts, query_desc); //Compute brief descriptors at each keypoint location
// ====== 3.0 =======
#include "opencv2/features2d.hpp"
#include "opencv2/xfeatures2d.hpp"
using namespace cv::xfeatures2d;
Ptr<BriefDescriptorExtractor> brief = BriefDescriptorExtractor::create(32);
Ptr<FastFeatureDetector> detector = FastFeatureDetector::create(10, true);
// ...
detector->detect(gray, query_kpts); //Find interest points
brief->compute(gray, query_kpts, query_desc); //Compute brief descriptors at each keypoint location

OpenCL

すべての特化された ocl 実装は、汎用の C++ アルゴリズムインターフェースの背後に隠蔽された。これにより、関数の実行経路を実行時に動的に選択できるようになった: CPU か OpenCL か。この仕組みは「Transparent API」とも呼ばれる。

新しいクラス cv::UMat は、OpenCL デバイスとのデータ交換を便利な形で隠蔽することを目的としている。

次の例は API の変更を示す (OpenCV サイトより):

OpenCL 対応コード OpenCV-2.x
// initialization

VideoCapture vcap(...);

ocl::OclCascadeClassifier fd("haar_ff.xml");

ocl::oclMat frame, frameGray;

Mat frameCpu;

vector<Rect> faces;

for(;;){

// processing loop

vcap >> frameCpu;

frame = frameCpu;

ocl::cvtColor(frame, frameGray, BGR2GRAY);

ocl::equalizeHist(frameGray, frameGray);

fd.detectMultiScale(frameGray, faces, ...);

// draw rectangles …

// show image …

}

cv::VideoCapture
Class for video capturing from video files, image sequences or cameras.
Definition videoio.hpp:786
OpenCL 対応コード OpenCV-3.x
// initialization

VideoCapture vcap(...);

CascadeClassifier fd("haar_ff.xml");

UMat frame, frameGray; // the only change from plain CPU version

vector<Rect> faces;

for(;;){

// processing loop

vcap >> frame;

cvtColor(frame, frameGray, BGR2GRAY);

equalizeHist(frameGray, frameGray);

fd.detectMultiScale(frameGray, faces, ...);

// draw rectangles …

// show image …

}

cv::CascadeClassifier
Cascade classifier class for object detection.
Definition objdetect.hpp:258

cv::UMat
Definition mat.hpp:2499

CUDA

CUDA モジュールは opencv_contrib リポジトリへ移された。

ドキュメント形式

ドキュメントは Doxygen 形式に変換された。更新されたドキュメント執筆ガイドは、OpenCV リファレンスドキュメントの Tutorials セクションにある (OpenCV のドキュメント執筆)。

両バージョンへの対応

場合によっては、両方のバージョンの OpenCV に対応することが可能である。

ソースコード

アプリケーションのソースコードでライブラリのメジャーバージョンを確認するには、次の方法を用いるべきである:

#include "opencv2/core/version.hpp"
#if CV_MAJOR_VERSION == 2
// do opencv 2 code
#elif CV_MAJOR_VERSION == 3
// do opencv 3 code
#endif

覚え書き: CV_VERSION_MAJOR は使用しないこと。2.4 と 3.x のブランチで意味が異なる!

ビルドシステム

ビルドシステムでライブラリのバージョンを確認することで、アプリケーション内で異なるモジュールをリンクしたり、一部の機能を有効化/無効化したりできる。これには標準的な cmake や pkg-config の変数を使用できる:

cmake 用の OpenCV_VERSION には完全なバージョンが含まれる。例えば "2.4.11" や "3.0.0" など
cmake 用の OpenCV_VERSION_MAJOR にはメジャーバージョン番号のみが含まれる。2 または 3
pkg-config ファイルには標準フィールド Version がある

例:

if(OpenCV_VERSION VERSION_LESS "3.0")
# use 2.4 modules
else()
# use 3.x modules
endif()


原著者	Maksim Shabunin
互換性	OpenCV >= 3.0

目次