ディスクリプタMatcherの共通インタフェース

OpenCV におけるキーポイントディスクリプタの Matcher は,同一の問題を解く異なるアルゴリズム間を容易にスイッチできる共通のインタフェースによってラップされています. このセクションでは,多次元空間の vector として表現できるディスクリプタ同士の,マッチング方法について述べます. “vector” ディスクリプタ Matcher を実装するすべてのオブジェクトは, DescriptorMatcher() インタフェースから派生します.

DMatch

Comments from the Wiki

DMatch

2つのキーポイントディスクリプタ同士をマッチングします:クエリディスクリプタインデックス, 訓練ディスクリプタインデックス,訓練画像インデックス,ディスクリプタ同士の距離.

struct DMatch
{
    DMatch() : queryIdx(-1), trainIdx(-1), imgIdx(-1),
               distance(std::numeric_limits<float>::max()) {}
    DMatch( int _queryIdx, int _trainIdx, float _distance ) :
            queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(-1),
            distance(_distance) {}
    DMatch( int _queryIdx, int _trainIdx, int _imgIdx, float _distance ) :
            queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(_imgIdx),
            distance(_distance) {}

    int queryIdx; // クエリディスクリプタインデックス
    int trainIdx; // 訓練ディスクリプタインデックス
    int imgIdx;   // 訓練画像インデックス

    float distance;

    // 小さいほど良い
    bool operator<( const DMatch &m ) const;
};

DescriptorMatcher

Comments from the Wiki

DescriptorMatcher

キーポイントディスクリプタ同士のマッチングのための抽象基底クラス. マッチング方法は,1つの画像のディスクリプタに対するマッチングと,画像集合のディスクリプタに対するマッチングの2種類に分けられます

class DescriptorMatcher
{
public:
    virtual ~DescriptorMatcher();

    virtual void add( const vector<Mat>& descriptors );

    const vector<Mat>& getTrainDescriptors() const;
    virtual void clear();
    bool empty() const;
    virtual bool isMaskSupported() const = 0;

    virtual void train();

    /*
     * 画像ペアから得たディスクリプタ同士のマッチメソッド一覧.
     */
    void match( const Mat& queryDescriptors, const Mat& trainDescriptors,
                vector<DMatch>& matches, const Mat& mask=Mat() ) const;
    void knnMatch( const Mat& queryDescriptors, const Mat& trainDescriptors,
                   vector<vector<DMatch> >& matches, int k,
                   const Mat& mask=Mat(), bool compactResult=false ) const;
    void radiusMatch( const Mat& queryDescriptors, const Mat& trainDescriptors,
                      vector<vector<DMatch> >& matches, float maxDistance,
                      const Mat& mask=Mat(), bool compactResult=false ) const;
    /*
     * 画像集合から得たディスクリプタ同士のマッチメソッド一覧.
     */
    void match( const Mat& queryDescriptors, vector<DMatch>& matches,
                const vector<Mat>& masks=vector<Mat>() );
    void knnMatch( const Mat& queryDescriptors, vector<vector<DMatch> >& matches,
                   int k, const vector<Mat>& masks=vector<Mat>(),
                   bool compactResult=false );
    void radiusMatch( const Mat& queryDescriptors, vector<vector<DMatch> >& matches,
                      float maxDistance, const vector<Mat>& masks=vector<Mat>(),
                      bool compactResult=false );

    virtual void read( const FileNode& );
    virtual void write( FileStorage& ) const;

    virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;

    static Ptr<DescriptorMatcher> create( const string& descriptorMatcherType );

protected:
    vector<Mat> trainDescCollection;
    ...
};

cv::DescriptorMatcher::add

Comments from the Wiki


void add(const vector<Mat>& descriptors)

訓練ディスクリプタコレクションにディスクリプタを追加します.

コレクション trainDescCollectionが空ではない場合,新しいディスクリプタは,存在する訓練ディスクリプタに追加されます.

param descriptors:
 追加されるディスクリプタ.各 decriptors[i] は, 同一の(1 つの)訓練画像から得られたディスクリプタの集合です.

cv::DescriptorMatcher::getTrainDescriptors

Comments from the Wiki


const vector<Mat>& getTrainDescriptors() const

訓練ディスクリプタコレクション(つまり, trainDescCollection)へのリンクを返します.

cv::DescriptorMatcher::clear

Comments from the Wiki

void DescriptorMatcher::clear()

訓練ディスクリプタコレクションをクリアします.

cv::DescriptorMatcher::empty

Comments from the Wiki

bool DescriptorMatcher::empty() const

コレクション内に訓練ディスクリプタが存在しない場合に true を返します.

cv::DescriptorMatcher::isMaskSupported

Comments from the Wiki

bool DescriptorMatcher::isMaskSupported()

ディスクリプタ Matcher がマスキング可能なマッチングをサポートする場合に true を返します.

cv::DescriptorMatcher::train

Comments from the Wiki

void DescriptorMatcher::train()

訓練ディスクリプタ Matcher(例えば,訓練 flann インデックス).

すべてのマッチングメソッドにおいて,マッチングの前に train() メソッドが毎回実行されます. このメソッドが存在しないディスクリプタ Matcher(例えば BruteForceMatcher)もありますが, その他の Matcher では内部構造を実際に学習します(例えば FlannBasedMatcher は flann::Index を学習します).

cv::DescriptorMatcher::match

Comments from the Wiki

void DescriptorMatcher::match(const Mat& queryDescriptors, const Mat& trainDescriptors, vector<DMatch>& matches, const Mat& mask=Mat()) const

クエリ集合の各ディスクリプタに最もマッチするものを,訓練ディスクリプタから見つけます.

クエリディスクリプタはすべて,同じクエリ画像から検出されたキーポイントに対するディスクリプタです. このメソッドの第1のバージョンでは,引数で訓練ディスクリプタを与えます.これらは同じ訓練画像から検出されたキーポイントに対してのディスクリプタになります. 第2のバージョンでは,addメソッドによってセットされた訓練ディスクリプタコレクションが利用されます. オプションとして,どのディスクリプタをマッチさせるかを記述するマスク(または,マスクの集合)が利用できます.mask.at<uchar>(i,j)が0ではない場合にのみ, queryDescriptors[i]は trainDescriptors[j]とマッチされます.

void DescriptorMatcher::match(const Mat& queryDescriptors, vector<DMatch>& matches, const vector<Mat>& masks=vector<Mat>())
パラメタ:
  • queryDescriptors – ディスクリプタのクエリ集合.
  • trainDescriptors – ディスクリプタの訓練集合.これは,クラスオブジェクト内に保存される訓練ディスクリプタ集合には追加されません.
  • matches – マッチ.クエリディスクリプタが mask によって除外される場合は,このディスクリプタに対するマッチは追加されません. その場合, matches のサイズは,クエリディスクリプタ数よりも小さくなります.
  • mask – 入力されたクエリと訓練ディスクリプタの行列との,可能なマッチング指定するマスク.
  • masks – マスクの集合.各 masks[i] が,入力されたクエリと i-番目の画像の訓練ディスクリプタ (つまり, trainDescCollection[i] )との,可能なマッチングを指定します.

cv::DescriptorMatcher::knnMatch

Comments from the Wiki

DescriptorMatcher::match()

void DescriptorMatcher::knnMatch(const Mat& queryDescriptors, const Mat& trainDescriptors, vector<vector<DMatch> >& matches, int k, const Mat& mask=Mat(), bool compactResult=false) const

クエリ集合の各ディスクリプタに対して,最も良い上位 k 個のマッチを訓練ディスクリプタから見つけます.

見つかった k 個(無理な場合は,それより少ない個数)のマッチは,その距離の昇順で返されます. クエリおよび訓練ディスクリプタに関する詳細は, を参照してください.

void DescriptorMatcher::knnMatch(const Mat& queryDescriptors, vector<vector<DMatch> >& matches, int k, const vector<Mat>& masks=vector<Mat>(), bool compactResult=false)
パラメタ:
  • trainDescriptors, mask, masks (queryDescriptors,) – DescriptorMatcher::match() を参照してください.
  • matches – マッチ.それぞれの matches[i] は,同一のクエリディスクリプタに対する,K個,またはそれ未満のマッチを表します.
  • k – 各クエリディスクリプタに対して求められるベストマッチの個数(無理な場合は,これより少なくなります).
  • compactResult – マスク(またはマスクの集合)が空ではない場合に利用されます. compactResult が false の場合, matches vector は, queryDescriptors の行数と同じサイズになります. compactResult が true の場合, matches vector は,マスクによって完全に除外されたクエリディスクリプタに対するマッチを含まなくなります.

cv::DescriptorMatcher::radiusMatch

Comments from the Wiki

DescriptorMatcher::match()

void DescriptorMatcher::radiusMatch(const Mat& queryDescriptors, const Mat& trainDescriptors, vector<vector<DMatch> >& matches, float maxDistance, const Mat& mask=Mat(), bool compactResult=false) const

各クエリディスクリプタに対して,与えられた閾値よりも小さい距離にあるベストマッチを見つけます.

見つかったマッチは,その距離の昇順で返されます.クエリおよび訓練ディスクリプタに関する詳細は,を参照してください.

void DescriptorMatcher::radiusMatch(const Mat& queryDescriptors, vector<vector<DMatch> >& matches, float maxDistance, const vector<Mat>& masks=vector<Mat>(), bool compactResult=false)
パラメタ:
  • trainDescriptors, mask, masks (queryDescriptors,) – DescriptorMatcher::match() を参照してください.
  • compactResult (matches,) – DescriptorMatcher::knnMatch() を参照してください.
  • maxDistance – マッチの距離の閾値.

cv::DescriptorMatcher::clone

Comments from the Wiki

Ptr<DescriptorMatcher> \DescriptorMatcher::clone(bool emptyTrainData) const

Matcher を複製します.

パラメタ:
  • emptyTrainData – emptyTrainData が false の場合,このメソッドはオブジェクトの深いコピーを作成します. つまり,パラメータと訓練データの両方がコピーされます.emptyTrainData が true の場合,現在のパラメータのみをコピーした オブジェクトが作成され,訓練データは空になります.

cv::DescriptorMatcher::create

Comments from the Wiki

DescriptorMatcher()

Ptr<DescriptorMatcher> DescriptorMatcher::create(const string& descriptorMatcherType)

デフォルトパラメータで,指定された種類の を作成するディスクリプタ Matcher ファクトリ

(デフォルトコンストラクタを使う方が好まれます).

param descriptorMatcherType:
 ディスクリプタ Matcher の種類.

以下の種類の Matcher がサポートされます: "BruteForce" (it uses L2 ), "BruteForce-L1" , "BruteForce-Hamming" , "BruteForce-HammingLUT" , "FlannBased"

BruteForceMatcher

Comments from the Wiki

BruteForceMatcher

ブルートフォースディスクリプタ Matcher.この Matcher は, 1番目の集合の各ディスクリプタに対して,それに最も近いディスクリプタを見つけるために2番目の集合を全探索します. このディスクリプタ Matcher は,ディスクリプタ集合同士のマスキング可能なマッチングをサポートします.

template<class Distance>
class BruteForceMatcher : public DescriptorMatcher
{
public:
    BruteForceMatcher( Distance d = Distance() );
    virtual ~BruteForceMatcher();

    virtual bool isMaskSupported() const;
    virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected:
    ...
}

効率化のため,BruteForceMatcher は,距離基準によってテンプレート化されています. 浮動小数点型ディスクリプタに対しては, L2<float> が選択されます. サポートされる距離のクラスは,次のようになります:

template<typename T>
struct Accumulator
{
    typedef T Type;
};

template<> struct Accumulator<unsigned char>  { typedef unsigned int Type; };
template<> struct Accumulator<unsigned short> { typedef unsigned int Type; };
template<> struct Accumulator<char>   { typedef int Type; };
template<> struct Accumulator<short>  { typedef int Type; };

/*
 * ユークリッド2乗距離ファンクタ
 */
template<class T>
struct L2
{
    typedef T ValueType;
    typedef typename Accumulator<T>::Type ResultType;

    ResultType operator()( const T* a, const T* b, int size ) const;
};

/*
 * マンハッタン距離(city block distance)ファンクタ
 */
template<class T>
struct CV_EXPORTS L1
{
    typedef T ValueType;
    typedef typename Accumulator<T>::Type ResultType;

    ResultType operator()( const T* a, const T* b, int size ) const;
    ...
};

/*
 * ハミング距離(city block distance)ファンクタ
 */
struct HammingLUT
{
    typedef unsigned char ValueType;
    typedef int ResultType;

    ResultType operator()( const unsigned char* a, const unsigned char* b,
                           int size ) const;
    ...
};

struct Hamming
{
    typedef unsigned char ValueType;
    typedef int ResultType;

    ResultType operator()( const unsigned char* a, const unsigned char* b,
                           int size ) const;
    ...
};

FlannBasedMatcher

Comments from the Wiki

FlannBasedMatcher

Flann ベースのディスクリプタ Matcher.この Matcher は,訓練ディスクリプタコレクションの flann::Index() を学習して, ベストマッチを見つけるために,その最近傍探索メソッドを呼び出します. したがって,巨大な訓練コレクションとマッチングする場合は,この Matcher は,ブルートフォース Matcher よりも高速になります. flann::Index() が,マスキング可能なディスクリプタ集合同士のマッチングをサポートしないので, FlannBasedMatcher も,それをサポートしません.

class FlannBasedMatcher : public DescriptorMatcher
{
public:
    FlannBasedMatcher(
      const Ptr<flann::IndexParams>& indexParams=new flann::KDTreeIndexParams(),
      const Ptr<flann::SearchParams>& searchParams=new flann::SearchParams() );

    virtual void add( const vector<Mat>& descriptors );
    virtual void clear();

    virtual void train();
    virtual bool isMaskSupported() const;

    virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected:
    ...
};