modules/legacy/doc/common_interfaces_of_generic_descriptor_matchers.rst

   1 Common Interfaces of Generic Descriptor Matchers
   2 ================================================
   3
   4 .. highlight:: cpp
   5
   6 OneWayDescriptorBase
   7 --------------------
   8 .. ocv:class:: OneWayDescriptorBase
   9
  10 Class encapsulates functionality for training/loading a set of one way descriptors
  11 and finding the nearest closest descriptor to an input feature. ::
  12
  13     class CV_EXPORTS OneWayDescriptorBase
  14     {
  15     public:
  16
  17         // creates an instance of OneWayDescriptor from a set of training files
  18         // - patch_size: size of the input (large) patch
  19         // - pose_count: the number of poses to generate for each descriptor
  20         // - train_path: path to training files
  21         // - pca_config: the name of the file that contains PCA for small patches (2 times smaller
  22         // than patch_size each dimension
  23         // - pca_hr_config: the name of the file that contains PCA for large patches (of patch_size size)
  24         // - pca_desc_config: the name of the file that contains descriptors of PCA components
  25         OneWayDescriptorBase(CvSize patch_size, int pose_count, const char* train_path = 0, const char* pca_config = 0,
  26                             const char* pca_hr_config = 0, const char* pca_desc_config = 0, int pyr_levels = 1,
  27                             int pca_dim_high = 100, int pca_dim_low = 100);
  28
  29         OneWayDescriptorBase(CvSize patch_size, int pose_count, const String &pca_filename, const String &train_path = String(), const String &images_list = String(),
  30                             float _scale_min = 0.7f, float _scale_max=1.5f, float _scale_step=1.2f, int pyr_levels = 1,
  31                             int pca_dim_high = 100, int pca_dim_low = 100);
  32
  33
  34         virtual ~OneWayDescriptorBase();
  35         void clear ();
  36
  37
  38         // Allocate: allocates memory for a given number of descriptors
  39         void Allocate(int train_feature_count);
  40
  41         // AllocatePCADescriptors: allocates memory for pca descriptors
  42         void AllocatePCADescriptors();
  43
  44         // returns patch size
  45         CvSize GetPatchSize() const {return m_patch_size;};
  46         // returns the number of poses for each descriptor
  47         int GetPoseCount() const {return m_pose_count;};
  48
  49         // returns the number of pyramid levels
  50         int GetPyrLevels() const {return m_pyr_levels;};
  51
  52         // returns the number of descriptors
  53         int GetDescriptorCount() const {return m_train_feature_count;};
  54
  55         // CreateDescriptorsFromImage: creates descriptors for each of the input features
  56         // - src: input image
  57         // - features: input features
  58         // - pyr_levels: the number of pyramid levels
  59         void CreateDescriptorsFromImage(IplImage* src, const vector<KeyPoint>& features);
  60
  61         // CreatePCADescriptors: generates descriptors for PCA components, needed for fast generation of feature descriptors
  62         void CreatePCADescriptors();
  63
  64         // returns a feature descriptor by feature index
  65         const OneWayDescriptor* GetDescriptor(int desc_idx) const {return &m_descriptors[desc_idx];};
  66
  67         // FindDescriptor: finds the closest descriptor
  68         // - patch: input image patch
  69         // - desc_idx: output index of the closest descriptor to the input patch
  70         // - pose_idx: output index of the closest pose of the closest descriptor to the input patch
  71         // - distance: distance from the input patch to the closest feature pose
  72         // - _scales: scales of the input patch for each descriptor
  73         // - scale_ranges: input scales variation (float[2])
  74         void FindDescriptor(IplImage* patch, int& desc_idx, int& pose_idx, float& distance, float* _scale = 0, float* scale_ranges = 0) const;
  75
  76         // - patch: input image patch
  77         // - n: number of the closest indexes
  78         // - desc_idxs: output indexes of the closest descriptor to the input patch (n)
  79         // - pose_idx: output indexes of the closest pose of the closest descriptor to the input patch (n)
  80         // - distances: distance from the input patch to the closest feature pose (n)
  81         // - _scales: scales of the input patch
  82         // - scale_ranges: input scales variation (float[2])
  83         void FindDescriptor(IplImage* patch, int n, vector<int>& desc_idxs, vector<int>& pose_idxs,
  84                             vector<float>& distances, vector<float>& _scales, float* scale_ranges = 0) const;
  85
  86         // FindDescriptor: finds the closest descriptor
  87         // - src: input image
  88         // - pt: center of the feature
  89         // - desc_idx: output index of the closest descriptor to the input patch
  90         // - pose_idx: output index of the closest pose of the closest descriptor to the input patch
  91         // - distance: distance from the input patch to the closest feature pose
  92         void FindDescriptor(IplImage* src, cv::Point2f pt, int& desc_idx, int& pose_idx, float& distance) const;
  93
  94         // InitializePoses: generates random poses
  95         void InitializePoses();
  96
  97         // InitializeTransformsFromPoses: generates 2x3 affine matrices from poses (initializes m_transforms)
  98         void InitializeTransformsFromPoses();
  99
 100         // InitializePoseTransforms: subsequently calls InitializePoses and InitializeTransformsFromPoses
 101         void InitializePoseTransforms();
 102
 103         // InitializeDescriptor: initializes a descriptor
 104         // - desc_idx: descriptor index
 105         // - train_image: image patch (ROI is supported)
 106         // - feature_label: feature textual label
 107         void InitializeDescriptor(int desc_idx, IplImage* train_image, const char* feature_label);
 108
 109         void InitializeDescriptor(int desc_idx, IplImage* train_image, const KeyPoint& keypoint, const char* feature_label);
 110
 111         // InitializeDescriptors: load features from an image and create descriptors for each of them
 112         void InitializeDescriptors(IplImage* train_image, const vector<KeyPoint>& features,
 113                                   const char* feature_label = "", int desc_start_idx = 0);
 114
 115         // Write: writes this object to a file storage
 116         // - fs: output filestorage
 117         void Write (FileStorage &fs) const;
 118
 119         // Read: reads OneWayDescriptorBase object from a file node
 120         // - fn: input file node
 121         void Read (const FileNode &fn);
 122
 123         // LoadPCADescriptors: loads PCA descriptors from a file
 124         // - filename: input filename
 125         int LoadPCADescriptors(const char* filename);
 126
 127         // LoadPCADescriptors: loads PCA descriptors from a file node
 128         // - fn: input file node
 129         int LoadPCADescriptors(const FileNode &fn);
 130
 131         // SavePCADescriptors: saves PCA descriptors to a file
 132         // - filename: output filename
 133         void SavePCADescriptors(const char* filename);
 134
 135         // SavePCADescriptors: saves PCA descriptors to a file storage
 136         // - fs: output file storage
 137         void SavePCADescriptors(CvFileStorage* fs) const;
 138
 139         // GeneratePCA: calculate and save PCA components and descriptors
 140         // - img_path: path to training PCA images directory
 141         // - images_list: filename with filenames of training PCA images
 142         void GeneratePCA(const char* img_path, const char* images_list, int pose_count=500);
 143
 144         // SetPCAHigh: sets the high resolution pca matrices (copied to internal structures)
 145         void SetPCAHigh(CvMat* avg, CvMat* eigenvectors);
 146
 147         // SetPCALow: sets the low resolution pca matrices (copied to internal structures)
 148         void SetPCALow(CvMat* avg, CvMat* eigenvectors);
 149
 150         int GetLowPCA(CvMat** avg, CvMat** eigenvectors)
 151         {
 152             *avg = m_pca_avg;
 153             *eigenvectors = m_pca_eigenvectors;
 154             return m_pca_dim_low;
 155         };
 156
 157         int GetPCADimLow() const {return m_pca_dim_low;};
 158         int GetPCADimHigh() const {return m_pca_dim_high;};
 159
 160         void ConvertDescriptorsArrayToTree(); // Converting pca_descriptors array to KD tree
 161
 162         // GetPCAFilename: get default PCA filename
 163         static String GetPCAFilename () { return "pca.yml"; }
 164
 165         virtual bool empty() const { return m_train_feature_count <= 0 ? true : false; }
 166
 167     protected:
 168         ...
 169     };
 170
 171 OneWayDescriptorMatcher
 172 -----------------------
 173 .. ocv:class:: OneWayDescriptorMatcher : public GenericDescriptorMatcher
 174
 175 Wrapping class for computing, matching, and classifying descriptors using the
 176 :ocv:class:`OneWayDescriptorBase` class. ::
 177
 178     class OneWayDescriptorMatcher : public GenericDescriptorMatcher
 179     {
 180     public:
 181         class Params
 182         {
 183         public:
 184             static const int POSE_COUNT = 500;
 185             static const int PATCH_WIDTH = 24;
 186             static const int PATCH_HEIGHT = 24;
 187             static float GET_MIN_SCALE() { return 0.7f; }
 188             static float GET_MAX_SCALE() { return 1.5f; }
 189             static float GET_STEP_SCALE() { return 1.2f; }
 190
 191             Params( int poseCount = POSE_COUNT,
 192                     Size patchSize = Size(PATCH_WIDTH, PATCH_HEIGHT),
 193                     String pcaFilename = String(),
 194                     String trainPath = String(), String trainImagesList = String(),
 195                     float minScale = GET_MIN_SCALE(), float maxScale = GET_MAX_SCALE(),
 196                     float stepScale = GET_STEP_SCALE() );
 197
 198             int poseCount;
 199             Size patchSize;
 200             String pcaFilename;
 201             String trainPath;
 202             String trainImagesList;
 203
 204             float minScale, maxScale, stepScale;
 205         };
 206
 207         OneWayDescriptorMatcher( const Params& params=Params() );
 208         virtual ~OneWayDescriptorMatcher();
 209
 210         void initialize( const Params& params, const Ptr<OneWayDescriptorBase>& base=Ptr<OneWayDescriptorBase>() );
 211
 212         // Clears keypoints stored in collection and OneWayDescriptorBase
 213         virtual void clear();
 214
 215         virtual void train();
 216
 217         virtual bool isMaskSupported();
 218
 219         virtual void read( const FileNode &fn );
 220         virtual void write( FileStorage& fs ) const;
 221
 222         virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
 223     protected:
 224         ...
 225     };
 226
 227 FernClassifier
 228 --------------
 229 .. ocv:class:: FernClassifier
 230
 231 ::
 232
 233     class CV_EXPORTS FernClassifier
 234     {
 235     public:
 236         FernClassifier();
 237         FernClassifier(const FileNode& node);
 238         FernClassifier(const vector<vector<Point2f> >& points,
 239                       const vector<Mat>& refimgs,
 240                       const vector<vector<int> >& labels=vector<vector<int> >(),
 241                       int _nclasses=0, int _patchSize=PATCH_SIZE,
 242                       int _signatureSize=DEFAULT_SIGNATURE_SIZE,
 243                       int _nstructs=DEFAULT_STRUCTS,
 244                       int _structSize=DEFAULT_STRUCT_SIZE,
 245                       int _nviews=DEFAULT_VIEWS,
 246                       int _compressionMethod=COMPRESSION_NONE,
 247                       const PatchGenerator& patchGenerator=PatchGenerator());
 248         virtual ~FernClassifier();
 249         virtual void read(const FileNode& n);
 250         virtual void write(FileStorage& fs, const String& name=String()) const;
 251         virtual void trainFromSingleView(const Mat& image,
 252                                         const vector<KeyPoint>& keypoints,
 253                                         int _patchSize=PATCH_SIZE,
 254                                         int _signatureSize=DEFAULT_SIGNATURE_SIZE,
 255                                         int _nstructs=DEFAULT_STRUCTS,
 256                                         int _structSize=DEFAULT_STRUCT_SIZE,
 257                                         int _nviews=DEFAULT_VIEWS,
 258                                         int _compressionMethod=COMPRESSION_NONE,
 259                                         const PatchGenerator& patchGenerator=PatchGenerator());
 260         virtual void train(const vector<vector<Point2f> >& points,
 261                           const vector<Mat>& refimgs,
 262                           const vector<vector<int> >& labels=vector<vector<int> >(),
 263                           int _nclasses=0, int _patchSize=PATCH_SIZE,
 264                           int _signatureSize=DEFAULT_SIGNATURE_SIZE,
 265                           int _nstructs=DEFAULT_STRUCTS,
 266                           int _structSize=DEFAULT_STRUCT_SIZE,
 267                           int _nviews=DEFAULT_VIEWS,
 268                           int _compressionMethod=COMPRESSION_NONE,
 269                           const PatchGenerator& patchGenerator=PatchGenerator());
 270         virtual int operator()(const Mat& img, Point2f kpt, vector<float>& signature) const;
 271         virtual int operator()(const Mat& patch, vector<float>& signature) const;
 272         virtual void clear();
 273         virtual bool empty() const;
 274         void setVerbose(bool verbose);
 275
 276         int getClassCount() const;
 277         int getStructCount() const;
 278         int getStructSize() const;
 279         int getSignatureSize() const;
 280         int getCompressionMethod() const;
 281         Size getPatchSize() const;
 282
 283         struct Feature
 284         {
 285             uchar x1, y1, x2, y2;
 286             Feature() : x1(0), y1(0), x2(0), y2(0) {}
 287             Feature(int _x1, int _y1, int _x2, int _y2)
 288             : x1((uchar)_x1), y1((uchar)_y1), x2((uchar)_x2), y2((uchar)_y2)
 289             {}
 290             template<typename _Tp> bool operator ()(const Mat_<_Tp>& patch) const
 291             { return patch(y1,x1) > patch(y2, x2); }
 292         };
 293
 294         enum
 295         {
 296             PATCH_SIZE = 31,
 297             DEFAULT_STRUCTS = 50,
 298             DEFAULT_STRUCT_SIZE = 9,
 299             DEFAULT_VIEWS = 5000,
 300             DEFAULT_SIGNATURE_SIZE = 176,
 301             COMPRESSION_NONE = 0,
 302             COMPRESSION_RANDOM_PROJ = 1,
 303             COMPRESSION_PCA = 2,
 304             DEFAULT_COMPRESSION_METHOD = COMPRESSION_NONE
 305         };
 306
 307     protected:
 308         ...
 309     };
 310
 311 FernDescriptorMatcher
 312 ---------------------
 313 .. ocv:class:: FernDescriptorMatcher : public GenericDescriptorMatcher
 314
 315 Wrapping class for computing, matching, and classifying descriptors using the
 316 :ocv:class:`FernClassifier` class. ::
 317
 318     class FernDescriptorMatcher : public GenericDescriptorMatcher
 319     {
 320     public:
 321         class Params
 322         {
 323         public:
 324             Params( int nclasses=0,
 325                     int patchSize=FernClassifier::PATCH_SIZE,
 326                     int signatureSize=FernClassifier::DEFAULT_SIGNATURE_SIZE,
 327                     int nstructs=FernClassifier::DEFAULT_STRUCTS,
 328                     int structSize=FernClassifier::DEFAULT_STRUCT_SIZE,
 329                     int nviews=FernClassifier::DEFAULT_VIEWS,
 330                     int compressionMethod=FernClassifier::COMPRESSION_NONE,
 331                     const PatchGenerator& patchGenerator=PatchGenerator() );
 332
 333             Params( const String& filename );
 334
 335             int nclasses;
 336             int patchSize;
 337             int signatureSize;
 338             int nstructs;
 339             int structSize;
 340             int nviews;
 341             int compressionMethod;
 342             PatchGenerator patchGenerator;
 343
 344             String filename;
 345         };
 346
 347         FernDescriptorMatcher( const Params& params=Params() );
 348         virtual ~FernDescriptorMatcher();
 349
 350         virtual void clear();
 351
 352         virtual void train();
 353
 354         virtual bool isMaskSupported();
 355
 356         virtual void read( const FileNode &fn );
 357         virtual void write( FileStorage& fs ) const;
 358
 359         virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
 360
 361     protected:
 362             ...
 363     };