Cpp Quick Start

Installation

Please download the latest version and install it as follows. The procedure below is for the zip file.

unzip NGT-x.x.x.zip
cd NGT-x.x.x
mkdir build
cd build 
cmake ..
make 
make install

Since NGT libraries and executable files are installed in /usr/local/ by default, please add the directory to the search path as follows.

export PATH="$PATH:/opt/local/bin"
export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib 

Data insertion and index construction

Below is an example of data insertion and index construction

// construct.cpp                                                                                                                             
#include        "NGT/Index.h"
using namespace std;
int main(int argc, char **argv)
{
  NGT::Property property;
  property.dimension    = 128;
  property.objectType   = NGT::ObjectSpace::ObjectType::Float;
  property.distanceType = NGT::Index::Property::DistanceType::DistanceTypeL2;
  std::string   path("anng");
  NGT::Index::create(path, property);
  NGT::Index    index(path);
  ifstream      is("./data/sift-dataset-5k.tsv");
  string        line;
  while (getline(is, line)) {
    stringstream        linestream(line);
    vector<float>       object;
    while (!linestream.eof()) {
      float value;
      linestream >> value;
      object.push_back(value);
    }
    object.resize(property.dimension);  // cut off unnecessary data in the file.                                                             
    index.append(object);
  }
  index.createIndex(16);               // 16 is the number of threads to build indexes.                                                      
  index.save();
  return 0;
}

The ./data/sift-dataset-5k.tsv is an object file that includes registered objects. Each line represents each object. The file contains additional data after each object, which should be discarded before insertion, i.e., "obj.resize(property.dimension);". NGT::Index::append() appends the objects to the index repository. NGT::Index::createIndex() constructs an index for the appended objects. Its argument 16 is the number of threads to construct the index. NGT::Index::saveIndex() saves the constructed index into the specified directory anng.

Run the command below and execute construct in the top directory of NGT to refer the data files.

g++ -std=c++11 -o construct construct.cpp -lngt

Nearest neighbor search

Below is an example of a nearest neighbor search with NGT::Index::search().

// search.cpp                                                                                                                                
#include        "NGT/Index.h"
using namespace std;
int main(int argc, char **argv)
{
  NGT::Index    index("anng", true);    // "true" means read only.                                                                           
  NGT::Property property;
  index.getProperty(property);
  ifstream      is("./data/sift-query-3.tsv");
  string        line;
  int           queryNo = 1;
  while (getline(is, line)) {
    vector<float>       query;
    stringstream        linestream(line);
    while (!linestream.eof()) {
      float value;
      linestream >> value;
      query.push_back(value);
    }
    NGT::SearchQuery            searchQuery(query);
    NGT::ObjectDistances        results;
    searchQuery.setResults(&results);
    searchQuery.setSize(5);
    index.search(searchQuery);
    cout << "Query No." << queryNo++ << endl;
    cout << "Rank\tID\tDistance" << endl;
    for (size_t i = 0; i < results.size(); i++) {
      cout << i + 1 << "\t" << results[i].id << "\t" << results[i].distance << endl;
    }
    cout << endl;
  }
  return 0;
}

The ./data/sift-query-3.tsv consists of query objects in the same format as the registration object file. Since this file has three query objects, three sets of results are displayed. The search results are stored in results that is set to NGT::SearchQuery by NGT::SearchQuery::setResults(). The number of resultant objects is specified with NGT::SearchQuery::setSize().

Query No.1
Rank	ID	Distance
1	3031	239.332
2	4079	240.002
3	3164	244.504
4	3718	246.763
5	157	251.094
    ...