Common Interfaces of Generic Descriptor Matchers ================================================ .. highlight:: cpp OneWayDescriptorBase -------------------- .. ocv:class:: OneWayDescriptorBase Class encapsulates functionality for training/loading a set of one way descriptors and finding the nearest closest descriptor to an input feature. :: class CV_EXPORTS OneWayDescriptorBase { public: // creates an instance of OneWayDescriptor from a set of training files // - patch_size: size of the input (large) patch // - pose_count: the number of poses to generate for each descriptor // - train_path: path to training files // - pca_config: the name of the file that contains PCA for small patches (2 times smaller // than patch_size each dimension // - pca_hr_config: the name of the file that contains PCA for large patches (of patch_size size) // - pca_desc_config: the name of the file that contains descriptors of PCA components OneWayDescriptorBase(CvSize patch_size, int pose_count, const char* train_path = 0, const char* pca_config = 0, const char* pca_hr_config = 0, const char* pca_desc_config = 0, int pyr_levels = 1, int pca_dim_high = 100, int pca_dim_low = 100); OneWayDescriptorBase(CvSize patch_size, int pose_count, const string &pca_filename, const string &train_path = string(), const string &images_list = string(), float _scale_min = 0.7f, float _scale_max=1.5f, float _scale_step=1.2f, int pyr_levels = 1, int pca_dim_high = 100, int pca_dim_low = 100); virtual ~OneWayDescriptorBase(); void clear (); // Allocate: allocates memory for a given number of descriptors void Allocate(int train_feature_count); // AllocatePCADescriptors: allocates memory for pca descriptors void AllocatePCADescriptors(); // returns patch size CvSize GetPatchSize() const {return m_patch_size;}; // returns the number of poses for each descriptor int GetPoseCount() const {return m_pose_count;}; // returns the number of pyramid levels int GetPyrLevels() const {return m_pyr_levels;}; // returns the number of descriptors int GetDescriptorCount() const {return m_train_feature_count;}; // CreateDescriptorsFromImage: creates descriptors for each of the input features // - src: input image // - features: input features // - pyr_levels: the number of pyramid levels void CreateDescriptorsFromImage(IplImage* src, const vector& features); // CreatePCADescriptors: generates descriptors for PCA components, needed for fast generation of feature descriptors void CreatePCADescriptors(); // returns a feature descriptor by feature index const OneWayDescriptor* GetDescriptor(int desc_idx) const {return &m_descriptors[desc_idx];}; // FindDescriptor: finds the closest descriptor // - patch: input image patch // - desc_idx: output index of the closest descriptor to the input patch // - pose_idx: output index of the closest pose of the closest descriptor to the input patch // - distance: distance from the input patch to the closest feature pose // - _scales: scales of the input patch for each descriptor // - scale_ranges: input scales variation (float[2]) void FindDescriptor(IplImage* patch, int& desc_idx, int& pose_idx, float& distance, float* _scale = 0, float* scale_ranges = 0) const; // - patch: input image patch // - n: number of the closest indexes // - desc_idxs: output indexes of the closest descriptor to the input patch (n) // - pose_idx: output indexes of the closest pose of the closest descriptor to the input patch (n) // - distances: distance from the input patch to the closest feature pose (n) // - _scales: scales of the input patch // - scale_ranges: input scales variation (float[2]) void FindDescriptor(IplImage* patch, int n, vector& desc_idxs, vector& pose_idxs, vector& distances, vector& _scales, float* scale_ranges = 0) const; // FindDescriptor: finds the closest descriptor // - src: input image // - pt: center of the feature // - desc_idx: output index of the closest descriptor to the input patch // - pose_idx: output index of the closest pose of the closest descriptor to the input patch // - distance: distance from the input patch to the closest feature pose void FindDescriptor(IplImage* src, cv::Point2f pt, int& desc_idx, int& pose_idx, float& distance) const; // InitializePoses: generates random poses void InitializePoses(); // InitializeTransformsFromPoses: generates 2x3 affine matrices from poses (initializes m_transforms) void InitializeTransformsFromPoses(); // InitializePoseTransforms: subsequently calls InitializePoses and InitializeTransformsFromPoses void InitializePoseTransforms(); // InitializeDescriptor: initializes a descriptor // - desc_idx: descriptor index // - train_image: image patch (ROI is supported) // - feature_label: feature textual label void InitializeDescriptor(int desc_idx, IplImage* train_image, const char* feature_label); void InitializeDescriptor(int desc_idx, IplImage* train_image, const KeyPoint& keypoint, const char* feature_label); // InitializeDescriptors: load features from an image and create descriptors for each of them void InitializeDescriptors(IplImage* train_image, const vector& features, const char* feature_label = "", int desc_start_idx = 0); // Write: writes this object to a file storage // - fs: output filestorage void Write (FileStorage &fs) const; // Read: reads OneWayDescriptorBase object from a file node // - fn: input file node void Read (const FileNode &fn); // LoadPCADescriptors: loads PCA descriptors from a file // - filename: input filename int LoadPCADescriptors(const char* filename); // LoadPCADescriptors: loads PCA descriptors from a file node // - fn: input file node int LoadPCADescriptors(const FileNode &fn); // SavePCADescriptors: saves PCA descriptors to a file // - filename: output filename void SavePCADescriptors(const char* filename); // SavePCADescriptors: saves PCA descriptors to a file storage // - fs: output file storage void SavePCADescriptors(CvFileStorage* fs) const; // GeneratePCA: calculate and save PCA components and descriptors // - img_path: path to training PCA images directory // - images_list: filename with filenames of training PCA images void GeneratePCA(const char* img_path, const char* images_list, int pose_count=500); // SetPCAHigh: sets the high resolution pca matrices (copied to internal structures) void SetPCAHigh(CvMat* avg, CvMat* eigenvectors); // SetPCALow: sets the low resolution pca matrices (copied to internal structures) void SetPCALow(CvMat* avg, CvMat* eigenvectors); int GetLowPCA(CvMat** avg, CvMat** eigenvectors) { *avg = m_pca_avg; *eigenvectors = m_pca_eigenvectors; return m_pca_dim_low; }; int GetPCADimLow() const {return m_pca_dim_low;}; int GetPCADimHigh() const {return m_pca_dim_high;}; void ConvertDescriptorsArrayToTree(); // Converting pca_descriptors array to KD tree // GetPCAFilename: get default PCA filename static string GetPCAFilename () { return "pca.yml"; } virtual bool empty() const { return m_train_feature_count <= 0 ? true : false; } protected: ... }; OneWayDescriptorMatcher ----------------------- .. ocv:class:: OneWayDescriptorMatcher : public GenericDescriptorMatcher Wrapping class for computing, matching, and classifying descriptors using the :ocv:class:`OneWayDescriptorBase` class. :: class OneWayDescriptorMatcher : public GenericDescriptorMatcher { public: class Params { public: static const int POSE_COUNT = 500; static const int PATCH_WIDTH = 24; static const int PATCH_HEIGHT = 24; static float GET_MIN_SCALE() { return 0.7f; } static float GET_MAX_SCALE() { return 1.5f; } static float GET_STEP_SCALE() { return 1.2f; } Params( int poseCount = POSE_COUNT, Size patchSize = Size(PATCH_WIDTH, PATCH_HEIGHT), string pcaFilename = string(), string trainPath = string(), string trainImagesList = string(), float minScale = GET_MIN_SCALE(), float maxScale = GET_MAX_SCALE(), float stepScale = GET_STEP_SCALE() ); int poseCount; Size patchSize; string pcaFilename; string trainPath; string trainImagesList; float minScale, maxScale, stepScale; }; OneWayDescriptorMatcher( const Params& params=Params() ); virtual ~OneWayDescriptorMatcher(); void initialize( const Params& params, const Ptr& base=Ptr() ); // Clears keypoints stored in collection and OneWayDescriptorBase virtual void clear(); virtual void train(); virtual bool isMaskSupported(); virtual void read( const FileNode &fn ); virtual void write( FileStorage& fs ) const; virtual Ptr clone( bool emptyTrainData=false ) const; protected: ... }; FernClassifier -------------- .. ocv:class:: FernClassifier :: class CV_EXPORTS FernClassifier { public: FernClassifier(); FernClassifier(const FileNode& node); FernClassifier(const vector >& points, const vector& refimgs, const vector >& labels=vector >(), int _nclasses=0, int _patchSize=PATCH_SIZE, int _signatureSize=DEFAULT_SIGNATURE_SIZE, int _nstructs=DEFAULT_STRUCTS, int _structSize=DEFAULT_STRUCT_SIZE, int _nviews=DEFAULT_VIEWS, int _compressionMethod=COMPRESSION_NONE, const PatchGenerator& patchGenerator=PatchGenerator()); virtual ~FernClassifier(); virtual void read(const FileNode& n); virtual void write(FileStorage& fs, const String& name=String()) const; virtual void trainFromSingleView(const Mat& image, const vector& keypoints, int _patchSize=PATCH_SIZE, int _signatureSize=DEFAULT_SIGNATURE_SIZE, int _nstructs=DEFAULT_STRUCTS, int _structSize=DEFAULT_STRUCT_SIZE, int _nviews=DEFAULT_VIEWS, int _compressionMethod=COMPRESSION_NONE, const PatchGenerator& patchGenerator=PatchGenerator()); virtual void train(const vector >& points, const vector& refimgs, const vector >& labels=vector >(), int _nclasses=0, int _patchSize=PATCH_SIZE, int _signatureSize=DEFAULT_SIGNATURE_SIZE, int _nstructs=DEFAULT_STRUCTS, int _structSize=DEFAULT_STRUCT_SIZE, int _nviews=DEFAULT_VIEWS, int _compressionMethod=COMPRESSION_NONE, const PatchGenerator& patchGenerator=PatchGenerator()); virtual int operator()(const Mat& img, Point2f kpt, vector& signature) const; virtual int operator()(const Mat& patch, vector& signature) const; virtual void clear(); virtual bool empty() const; void setVerbose(bool verbose); int getClassCount() const; int getStructCount() const; int getStructSize() const; int getSignatureSize() const; int getCompressionMethod() const; Size getPatchSize() const; struct Feature { uchar x1, y1, x2, y2; Feature() : x1(0), y1(0), x2(0), y2(0) {} Feature(int _x1, int _y1, int _x2, int _y2) : x1((uchar)_x1), y1((uchar)_y1), x2((uchar)_x2), y2((uchar)_y2) {} template bool operator ()(const Mat_<_Tp>& patch) const { return patch(y1,x1) > patch(y2, x2); } }; enum { PATCH_SIZE = 31, DEFAULT_STRUCTS = 50, DEFAULT_STRUCT_SIZE = 9, DEFAULT_VIEWS = 5000, DEFAULT_SIGNATURE_SIZE = 176, COMPRESSION_NONE = 0, COMPRESSION_RANDOM_PROJ = 1, COMPRESSION_PCA = 2, DEFAULT_COMPRESSION_METHOD = COMPRESSION_NONE }; protected: ... }; FernDescriptorMatcher --------------------- .. ocv:class:: FernDescriptorMatcher : public GenericDescriptorMatcher Wrapping class for computing, matching, and classifying descriptors using the :ocv:class:`FernClassifier` class. :: class FernDescriptorMatcher : public GenericDescriptorMatcher { public: class Params { public: Params( int nclasses=0, int patchSize=FernClassifier::PATCH_SIZE, int signatureSize=FernClassifier::DEFAULT_SIGNATURE_SIZE, int nstructs=FernClassifier::DEFAULT_STRUCTS, int structSize=FernClassifier::DEFAULT_STRUCT_SIZE, int nviews=FernClassifier::DEFAULT_VIEWS, int compressionMethod=FernClassifier::COMPRESSION_NONE, const PatchGenerator& patchGenerator=PatchGenerator() ); Params( const string& filename ); int nclasses; int patchSize; int signatureSize; int nstructs; int structSize; int nviews; int compressionMethod; PatchGenerator patchGenerator; string filename; }; FernDescriptorMatcher( const Params& params=Params() ); virtual ~FernDescriptorMatcher(); virtual void clear(); virtual void train(); virtual bool isMaskSupported(); virtual void read( const FileNode &fn ); virtual void write( FileStorage& fs ) const; virtual Ptr clone( bool emptyTrainData=false ) const; protected: ... };