Implements a Bag of Words based (BoW) image search. More...

#include <bag_of_words.hpp>

Inheritance diagram for BagOfWords:

Collaboration diagram for BagOfWords:

Data Structures
struct	MatchResults
	Subclass of match results base which also returns scores. More...

struct	SearchParams
	Subclass of train params base which specifies inverted index training parameters. More...

struct	TrainParams
	Subclass of train params base which specifies inverted index training parameters. More...

Public Member Functions
	BagOfWords ()

	BagOfWords (const std::string &file_path)

bool	train (Dataset &dataset, const std::shared_ptr< const TrainParamsBase > &params, const std::vector< std::shared_ptr< const Image > > &examples)
	Given a set of training parameters, list of images, trains. More...

bool	load (const std::string &file_path)
	Loads a trained search structure from the input filepath. More...

bool	save (const std::string &file_path) const
	Saves a trained search structure to the input filepath. More...

std::shared_ptr< MatchResultsBase >	search (Dataset &dataset, const std::shared_ptr< const SearchParamsBase > &params, const std::shared_ptr< const Image > &example)
	Given a set of search parameters, a query image, searches for matching images and returns the match. More...

cv::Mat	vocabulary () const
	Returns the vocabulary matrix. More...

uint32_t	num_clusters () const
	Returns the number of clusters in the vocabulary. More...

Public Member Functions inherited from SearchBase
	SearchBase ()

	SearchBase (const std::string &file_path)

virtual	~SearchBase ()

std::vector< std::shared_ptr < MatchResultsBase > >	search (Dataset &dataset, const std::shared_ptr< SearchParamsBase > &params, const std::vector< std::shared_ptr< const Image > > &examples)
	Given a set of search parameters, list of query images, searches for matching images and returns the result matches. More...

Protected Attributes
cv::Mat	vocabulary_matrix

Detailed Description

Implements a Bag of Words based (BoW) image search.

Note that search here is not implemented and would throw an error should you try to call it. A naive implementation would have to compute tf-idf with all possible image. Instead, you should train a BoW model and use this model in conjuction with a InvertedIndex search model to perform a query.

Definition at line 9 of file bag_of_words.hpp.

Constructor & Destructor Documentation

BagOfWords::BagOfWords ( )

Definition at line 18 of file bag_of_words.cxx.

                        : SearchBase() {
 
 }

BagOfWords::BagOfWords ( const std::string & file_path )

Definition at line 23 of file bag_of_words.cxx.

References filesystem::file_exists(), and load().

                                                  : SearchBase(file_path) {
         if(!filesystem::file_exists(file_path)) {
                 std::cerr << "Error reading bag of words from " << file_path << std::endl;
                 return;
         }
         if(!this->load(file_path)) {
                 std::cerr << "Error reading bag of words from " << file_path << std::endl;
         }
 }

Member Function Documentation

bool BagOfWords::load ( const std::string & file_path )

virtual

Loads a trained search structure from the input filepath.

Implements SearchBase.

Definition at line 33 of file bag_of_words.cxx.

References filesystem::load_cvmat(), and vocabulary_matrix.

Referenced by BagOfWords(), and compute_bow().

                                                  {
         std::cout << "Reading bag of words from " << file_path << "..." << std::endl;
 
         if (!filesystem::load_cvmat(file_path, vocabulary_matrix)) {
                 std::cerr << "Failed to read vocabulary from " << file_path << std::endl;
                 return false;
         }
 
         std::cout << "Done reading bag of words." << std::endl;
         
         return true;
 }

uint32_t BagOfWords::num_clusters ( ) const

Returns the number of clusters in the vocabulary.

Definition at line 156 of file bag_of_words.cxx.

References vocabulary_matrix.

                                         {
         return vocabulary_matrix.rows;
 }

bool BagOfWords::save ( const std::string & file_path ) const

virtual

Saves a trained search structure to the input filepath.

Implements SearchBase.

Definition at line 47 of file bag_of_words.cxx.

References filesystem::create_file_directory(), vocabulary_matrix, and filesystem::write_cvmat().

Referenced by compute_bow(), main(), and train_bow().

                                                        {
         std::cout << "Writing bag of words to " << file_path << "..." << std::endl;
 
         filesystem::create_file_directory(file_path);
         if (!filesystem::write_cvmat(file_path, vocabulary_matrix)) {
                 std::cerr << "Failed to write vocabulary to " << file_path << std::endl;
                 return false;
         }
 
         std::cout << "Done writing bag of words." << std::endl;
         return true;
 }

std::shared_ptr< MatchResultsBase > BagOfWords::search	(	Dataset &	dataset,
		const std::shared_ptr< const SearchParamsBase > &	params,
		const std::shared_ptr< const Image > &	example
	)

virtual

Given a set of search parameters, a query image, searches for matching images and returns the match.

Search is not valid for bag of words - this would require computing tf-idf on all possible images in the dataset, and this function will assert(0) should you try to run it. Instead, you should train a Bag of Words (BoW) model and use it with one of the other search mechanisms, such as the inverted index.

Implements SearchBase.

Definition at line 147 of file bag_of_words.cxx.

                                                                                                                                                                     {
         assert(0);
         return nullptr;
 }

bool BagOfWords::train	(	Dataset &	dataset,
		const std::shared_ptr< const TrainParamsBase > &	params,
		const std::vector< std::shared_ptr< const Image > > &	examples
	)

virtual

Given a set of training parameters, list of images, trains.

Returns true if successful, false if not successful.

Implements SearchBase.

Definition at line 77 of file bag_of_words.cxx.

References filesystem::file_exists(), Dataset::image(), filesystem::load_cvmat(), Dataset::location(), vision::merge_descriptors(), BagOfWords::TrainParams::numClusters, and vocabulary_matrix.

Referenced by compute_bow(), main(), and train_bow().

                                                                                                                                                      {
 
         const std::shared_ptr<const TrainParams> &ii_params = std::static_pointer_cast<const TrainParams>(params);
         
         uint32_t k = ii_params->numClusters;
         uint32_t n = ii_params->numFeatures;
 
         std::vector<uint64_t> all_ids(examples.size());
         for (uint64_t i = 0; i < examples.size(); i++) {
                 all_ids[i] = examples[i]->id;
         }
         std::random_shuffle(all_ids.begin(), all_ids.end());
 
         std::vector<cv::Mat> all_descriptors;
         uint64_t num_features = 0;
         for (size_t i = 0; i < all_ids.size(); i++) {
                 std::shared_ptr<Image> image = std::static_pointer_cast<Image>(dataset.image(all_ids[i]));
                 if (image == nullptr) continue;
 
                 const std::string &descriptors_location = dataset.location(image->feature_path("descriptors"));
                 if (!filesystem::file_exists(descriptors_location)) continue;
 
                 cv::Mat descriptors, descriptorsf;
                 if (filesystem::load_cvmat(descriptors_location, descriptors)) {
                         num_features += descriptors.rows;
                         if (n > 0 && num_features > n) break;
                         descriptors.convertTo(descriptorsf, CV_32FC1);
                         all_descriptors.push_back(descriptorsf);
                 }
         }
         const cv::Mat merged_descriptor = vision::merge_descriptors(all_descriptors, true);
         
 #if ENABLE_FASTCLUSTER && ENABLE_MPI
         
         int rank = MPI::COMM_WORLD.Get_rank();
 
         uint32_t D = merged_descriptor.cols;
         float *dataf = (float *)merged_descriptor.data;
         vocabulary_matrix = cv::Mat(k, D, CV_32FC1);
         float *clusters = (float *)vocabulary_matrix.data;
 
         // initialize the clusters (random at the moment)
         if(rank == 0) { // initial clusters get broadcast
                 std::vector<uint64_t> indices(num_features);
                 for(size_t i=0; i<indices.size(); i++) {
                         indices[i] = i;
                 }
                 std::random_shuffle(indices.begin(), indices.end());
                 for(size_t i=0; i<k; i++) {
                         memcpy(&clusters[D * i], &dataf[D * indices[i]], sizeof(float) * D);
                 }
         }
 
     fastcluster::kmeans<float>(load_rows_in_mem, (void *)merged_descriptor.data, 
                                     build_nnobj, (void *)merged_descriptor.data,
                                     (float *)clusters, num_features, D, k, 16, 0, (char *)0);
         return true;
 #else
         cv::Mat labels;
         uint32_t attempts = 1;
         cv::TermCriteria tc(cv::TermCriteria::COUNT | cv::TermCriteria::EPS, 16, 0.0001);
         if (k > merged_descriptor.rows) { // k > n 
                 std::cerr << "Warning: # clusters > # features, automatically setting #clusters = #features." << std::endl;
                 k = merged_descriptor.rows;
         }
         cv::kmeans(merged_descriptor, k, labels, tc, attempts, cv::KMEANS_PP_CENTERS, vocabulary_matrix);
 #endif
         return true;
 }

cv::Mat BagOfWords::vocabulary ( ) const

Returns the vocabulary matrix.

Definition at line 152 of file bag_of_words.cxx.

References vocabulary_matrix.

Referenced by compute_bow(), and main().

                                    {
         return vocabulary_matrix;
 }

Field Documentation

cv::Mat BagOfWords::vocabulary_matrix

protected

Definition at line 56 of file bag_of_words.hpp.

Referenced by load(), num_clusters(), save(), train(), and vocabulary().

The documentation for this class was generated from the following files:

/home/psastras/vocabtree/modules/search/bag_of_words/bag_of_words.hpp
/home/psastras/vocabtree/modules/search/bag_of_words/bag_of_words.cxx

Data Structures

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation