ディスクリプタMatcherの共通インタフェース ========================================================== .. highlight:: cpp OpenCV におけるキーポイントディスクリプタの Matcher は,同一の問題を解く異なるアルゴリズム間を容易にスイッチできる共通のインタフェースによってラップされています. このセクションでは,多次元空間の vector として表現できるディスクリプタ同士の,マッチング方法について述べます. "vector" ディスクリプタ Matcher を実装するすべてのオブジェクトは, :func:`DescriptorMatcher` インタフェースから派生します. .. index:: DMatch .. _DMatch: DMatch ------ `id=0.833135570216 Comments from the Wiki `__ .. ctype:: DMatch 2つのキーポイントディスクリプタ同士をマッチングします:クエリディスクリプタインデックス, 訓練ディスクリプタインデックス,訓練画像インデックス,ディスクリプタ同士の距離. .. code-block:: c struct DMatch { DMatch() : queryIdx(-1), trainIdx(-1), imgIdx(-1), distance(std::numeric_limits::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; }; .. .. index:: DescriptorMatcher .. _DescriptorMatcher: DescriptorMatcher ----------------- `id=0.152653741217 Comments from the Wiki `__ .. ctype:: DescriptorMatcher キーポイントディスクリプタ同士のマッチングのための抽象基底クラス. マッチング方法は,1つの画像のディスクリプタに対するマッチングと,画像集合のディスクリプタに対するマッチングの2種類に分けられます .. code-block:: c class DescriptorMatcher { public: virtual ~DescriptorMatcher(); virtual void add( const vector& descriptors ); const vector& 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& matches, const Mat& mask=Mat() ) const; void knnMatch( const Mat& queryDescriptors, const Mat& trainDescriptors, vector >& matches, int k, const Mat& mask=Mat(), bool compactResult=false ) const; void radiusMatch( const Mat& queryDescriptors, const Mat& trainDescriptors, vector >& matches, float maxDistance, const Mat& mask=Mat(), bool compactResult=false ) const; /* * 画像集合から得たディスクリプタ同士のマッチメソッド一覧. */ void match( const Mat& queryDescriptors, vector& matches, const vector& masks=vector() ); void knnMatch( const Mat& queryDescriptors, vector >& matches, int k, const vector& masks=vector(), bool compactResult=false ); void radiusMatch( const Mat& queryDescriptors, vector >& matches, float maxDistance, const vector& masks=vector(), bool compactResult=false ); virtual void read( const FileNode& ); virtual void write( FileStorage& ) const; virtual Ptr clone( bool emptyTrainData=false ) const = 0; static Ptr create( const string& descriptorMatcherType ); protected: vector trainDescCollection; ... }; .. .. index:: DescriptorMatcher::add cv::DescriptorMatcher::add -------------------------- `id=0.128112525401 Comments from the Wiki `__ ```` .. cfunction:: void add( const vector\& descriptors ) 訓練ディスクリプタコレクションにディスクリプタを追加します. コレクション trainDescCollectionが空ではない場合,新しいディスクリプタは,存在する訓練ディスクリプタに追加されます. :param descriptors: 追加されるディスクリプタ.各 ``decriptors[i]`` は, 同一の(1 つの)訓練画像から得られたディスクリプタの集合です. .. index:: DescriptorMatcher::getTrainDescriptors cv::DescriptorMatcher::getTrainDescriptors ------------------------------------------ `id=0.567847085882 Comments from the Wiki `__ ```` .. cfunction:: const vector\& getTrainDescriptors() const 訓練ディスクリプタコレクション(つまり, trainDescCollection)へのリンクを返します. .. index:: DescriptorMatcher::clear cv::DescriptorMatcher::clear ---------------------------- `id=0.537317200959 Comments from the Wiki `__ .. cfunction:: void DescriptorMatcher::clear() 訓練ディスクリプタコレクションをクリアします. .. index:: DescriptorMatcher::empty cv::DescriptorMatcher::empty ---------------------------- `id=0.449707496008 Comments from the Wiki `__ .. cfunction:: bool DescriptorMatcher::empty() const コレクション内に訓練ディスクリプタが存在しない場合に true を返します. .. index:: DescriptorMatcher::isMaskSupported cv::DescriptorMatcher::isMaskSupported -------------------------------------- `id=0.682119605656 Comments from the Wiki `__ .. cfunction:: bool DescriptorMatcher::isMaskSupported() ディスクリプタ Matcher がマスキング可能なマッチングをサポートする場合に true を返します. .. index:: DescriptorMatcher::train cv::DescriptorMatcher::train ---------------------------- `id=0.930114781576 Comments from the Wiki `__ .. cfunction:: void DescriptorMatcher::train() 訓練ディスクリプタ Matcher(例えば,訓練 flann インデックス). すべてのマッチングメソッドにおいて,マッチングの前に train() メソッドが毎回実行されます. このメソッドが存在しないディスクリプタ Matcher(例えば BruteForceMatcher)もありますが, その他の Matcher では内部構造を実際に学習します(例えば FlannBasedMatcher は flann::Index を学習します). .. index:: DescriptorMatcher::match cv::DescriptorMatcher::match ---------------------------- `id=0.751450252797 Comments from the Wiki `__ ```` ```` ```` ```` .. cfunction:: void DescriptorMatcher::match( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector\& matches, const Mat\& mask=Mat() ) const クエリ集合の各ディスクリプタに最もマッチするものを,訓練ディスクリプタから見つけます. クエリディスクリプタはすべて,同じクエリ画像から検出されたキーポイントに対するディスクリプタです. このメソッドの第1のバージョンでは,引数で訓練ディスクリプタを与えます.これらは同じ訓練画像から検出されたキーポイントに対してのディスクリプタになります. 第2のバージョンでは,addメソッドによってセットされた訓練ディスクリプタコレクションが利用されます. オプションとして,どのディスクリプタをマッチさせるかを記述するマスク(または,マスクの集合)が利用できます.mask.at(i,j)が0ではない場合にのみ, queryDescriptors[i]は trainDescriptors[j]とマッチされます. .. cfunction:: void DescriptorMatcher::match( const Mat\& queryDescriptors, vector\& matches, const vector\& masks=vector() ) :param queryDescriptors: ディスクリプタのクエリ集合. :param trainDescriptors: ディスクリプタの訓練集合.これは,クラスオブジェクト内に保存される訓練ディスクリプタ集合には追加されません. :param matches: マッチ.クエリディスクリプタが ``mask`` によって除外される場合は,このディスクリプタに対するマッチは追加されません. その場合, ``matches`` のサイズは,クエリディスクリプタ数よりも小さくなります. :param mask: 入力されたクエリと訓練ディスクリプタの行列との,可能なマッチング指定するマスク. :param masks: マスクの集合.各 ``masks[i]`` が,入力されたクエリと i-番目の画像の訓練ディスクリプタ (つまり, ``trainDescCollection[i]`` )との,可能なマッチングを指定します. .. index:: DescriptorMatcher::knnMatch cv::DescriptorMatcher::knnMatch ------------------------------- `id=0.811296618107 Comments from the Wiki `__ :func:`DescriptorMatcher::match` .. cfunction:: void DescriptorMatcher::knnMatch( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector >\& matches, int k, const Mat\& mask=Mat(), bool compactResult=false ) const クエリ集合の各ディスクリプタに対して,最も良い上位 k 個のマッチを訓練ディスクリプタから見つけます. 見つかった k 個(無理な場合は,それより少ない個数)のマッチは,その距離の昇順で返されます. クエリおよび訓練ディスクリプタに関する詳細は, を参照してください. .. cfunction:: void DescriptorMatcher::knnMatch( const Mat\& queryDescriptors, vector >\& matches, int k, const vector\& masks=vector(), bool compactResult=false ) :param queryDescriptors, trainDescriptors, mask, masks: :func:`DescriptorMatcher::match` を参照してください. :param matches: マッチ.それぞれの ``matches[i]`` は,同一のクエリディスクリプタに対する,K個,またはそれ未満のマッチを表します. :param k: 各クエリディスクリプタに対して求められるベストマッチの個数(無理な場合は,これより少なくなります). :param compactResult: マスク(またはマスクの集合)が空ではない場合に利用されます. ``compactResult`` が false の場合, ``matches`` vector は, ``queryDescriptors`` の行数と同じサイズになります. ``compactResult`` が true の場合, ``matches`` vector は,マスクによって完全に除外されたクエリディスクリプタに対するマッチを含まなくなります. .. index:: DescriptorMatcher::radiusMatch cv::DescriptorMatcher::radiusMatch ---------------------------------- `id=0.270059023328 Comments from the Wiki `__ :func:`DescriptorMatcher::match` .. cfunction:: void DescriptorMatcher::radiusMatch( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector >\& matches, float maxDistance, const Mat\& mask=Mat(), bool compactResult=false ) const 各クエリディスクリプタに対して,与えられた閾値よりも小さい距離にあるベストマッチを見つけます. 見つかったマッチは,その距離の昇順で返されます.クエリおよび訓練ディスクリプタに関する詳細は,を参照してください. .. cfunction:: void DescriptorMatcher::radiusMatch( const Mat\& queryDescriptors, vector >\& matches, float maxDistance, const vector\& masks=vector(), bool compactResult=false ) :param queryDescriptors, trainDescriptors, mask, masks: :func:`DescriptorMatcher::match` を参照してください. :param matches, compactResult: :func:`DescriptorMatcher::knnMatch` を参照してください. :param maxDistance: マッチの距離の閾値. .. index:: DescriptorMatcher::clone cv::DescriptorMatcher::clone ---------------------------- `id=0.316055020508 Comments from the Wiki `__ .. cfunction:: Ptr \\DescriptorMatcher::clone( bool emptyTrainData ) const Matcher を複製します. :param emptyTrainData: emptyTrainData が false の場合,このメソッドはオブジェクトの深いコピーを作成します. つまり,パラメータと訓練データの両方がコピーされます.emptyTrainData が true の場合,現在のパラメータのみをコピーした オブジェクトが作成され,訓練データは空になります. .. index:: DescriptorMatcher::create cv::DescriptorMatcher::create ----------------------------- `id=0.514409307286 Comments from the Wiki `__ :func:`DescriptorMatcher` .. code-block:: c .. :param : ```` ```` ```` ```` ```` ```` .. index:: BruteForceMatcher .. _BruteForceMatcher: BruteForceMatcher ----------------- `id=0.801551158169 Comments from the Wiki `__ .. ctype:: BruteForceMatcher ブルートフォースディスクリプタ Matcher.この Matcher は, 1番目の集合の各ディスクリプタに対して,それに最も近いディスクリプタを見つけるために2番目の集合を全探索します. このディスクリプタ Matcher は,ディスクリプタ集合同士のマスキング可能なマッチングをサポートします. .. code-block:: c template class BruteForceMatcher : public DescriptorMatcher { public: BruteForceMatcher( Distance d = Distance() ); virtual ~BruteForceMatcher(); virtual bool isMaskSupported() const; virtual Ptr clone( bool emptyTrainData=false ) const; protected: ... } .. 効率化のため,BruteForceMatcher は,距離基準によってテンプレート化されています. 浮動小数点型ディスクリプタに対しては, ``L2`` が選択されます. サポートされる距離のクラスは,次のようになります: .. code-block:: c template struct Accumulator { typedef T Type; }; template<> struct Accumulator { typedef unsigned int Type; }; template<> struct Accumulator { typedef unsigned int Type; }; template<> struct Accumulator { typedef int Type; }; template<> struct Accumulator { typedef int Type; }; /* * ユークリッド2乗距離ファンクタ */ template struct L2 { typedef T ValueType; typedef typename Accumulator::Type ResultType; ResultType operator()( const T* a, const T* b, int size ) const; }; /* * マンハッタン距離(city block distance)ファンクタ */ template struct CV_EXPORTS L1 { typedef T ValueType; typedef typename Accumulator::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; ... }; .. .. index:: FlannBasedMatcher .. _FlannBasedMatcher: FlannBasedMatcher ----------------- `id=0.0928831182906 Comments from the Wiki `__ .. ctype:: FlannBasedMatcher Flann ベースのディスクリプタ Matcher.この Matcher は,訓練ディスクリプタコレクションの :func:`flann::Index` を学習して, ベストマッチを見つけるために,その最近傍探索メソッドを呼び出します. したがって,巨大な訓練コレクションとマッチングする場合は,この Matcher は,ブルートフォース Matcher よりも高速になります. :func:`flann::Index` が,マスキング可能なディスクリプタ集合同士のマッチングをサポートしないので, ``FlannBasedMatcher`` も,それをサポートしません. .. code-block:: c class FlannBasedMatcher : public DescriptorMatcher { public: FlannBasedMatcher( const Ptr& indexParams=new flann::KDTreeIndexParams(), const Ptr& searchParams=new flann::SearchParams() ); virtual void add( const vector& descriptors ); virtual void clear(); virtual void train(); virtual bool isMaskSupported() const; virtual Ptr clone( bool emptyTrainData=false ) const; protected: ... }; ..