Pastec more specifically uses the patent-free ORB descriptor and not the well-known proprietary SIFT and SURF descriptors.

 

Source Code: https://github.com/Visu4link/Pastec

 

How to Compile?  

 

Dependencies

Pastec requires OpenCV 3.X, and libmicrohttpd and libcurl to be compiled. These packages can be activated with the following command on Ubuntu 18.04:

 

sudo apt-get install libopencv-dev libmicrohttpd-dev

 

If you're using a different distribution or operating system, you may need to compile it yourself.

 

Design

 

Pastec uses cmake as framework for construction. You need Git to obtain the source code, too. They can be activated on Ubuntu by using the following command:

sudo apt-get install cmake git

 

To compile Pastec, use the following command first to get the sources:

git clone https://github.com/Visu4link/pastec.git
cd pastec

Build a folder for compilation then:

mkdir build

Go to the following subdirectory and run cmake:

cd build
cmake ../

Finally, to compile Pastec, run make:

make

Update

To start Pastec simply run the executable pastec. It takes the path to a file which contains a list of visual ORB words as a mandatory statement. For now, please use the visualWordsORB.dat format. Next Pastec releases will include resources to create your own visual word list.

 

./pastec visualWordsORB.dat

 

The default passtec port listens to the REST API is 4212. The -p argument helps you to set another port. You may also send the -i argument a path to an index file to load.

 

HTTP API

Using a simple HTTP API, Pastec can be managed. It listens to the 4212 port by default but you can modify this with the -p argument.

 

Pastec answers are always in JSON format. They contain a compulsory form field defining the obtained result or an error. Every picture has a corresponding I d that is a 32 bit unsigned integer. This Id sets out the relation between the images and their signatures in the index.

 

All the images submitted must have dimensions greater than 150 pixels. When one image size reaches 1000 pixels, the image is resized such that the maximum size is set to 1000 pixels and the original aspect ratio is retained.

 

A full list of calls to the API here is:

 

Add a picture to its index

This call allows adding an image 's signature to the index to make it available for search. To define it you must have the image's compressed binary data and an id.

 

Path: /index / images/

HTTP process: PUT

Data: binary image data to be inserted compressed in JPEG or a JSON that includes the image URL in the field "url"

Type of answer:"IMAGE ADDED" 

Possible error types: ""IMAGE_NOT_DECODED", "IMAGE_SIZE_TOO_BIG", "IMAGE_SIZE_TOO_SMALL", "IMAGE_DOWNLOADER_HTTP_ERROR" with the HTTP status code in the "image_downloader_http_response_code" field.

 

To give an example:

Command line with data from the image:

Example:

• Command line with image data:

  curl -X PUT --data-binary @/home/test/img/1.jpg http://localhost:4212/index/images/23
  

• Answer:

  {
     "image_id" : 23,
     "type" : "IMAGE_ADDED"
  }
  

• Command line with an image URL:

  curl -X PUT -d '{"url":"http://www.mydomain.com/path/to/my/image.jpg"}' http://localhost:4212/index/images/26
  

• Answer:

  {
     "image_id" : 26,
     "type" : "IMAGE_ADDED"
  }

Removing an image from the index

This call removes the signature of an image in the index thanks to its id. Be careful to not call often this method if your index is big because it is currently very slow.

• Path: /index/images/
• HTTP method: DELETE
• Answer type: "IMAGE_REMOVED"
• Possible error type: "IMAGE_NOT_FOUND"
• Example:
  • Command line:

    curl -X DELETE http://localhost:4212/index/images/23
    

  • Answer:

    {
       "image_id" : 23,
       "type" : "IMAGE_REMOVED"
    }
    

Search request

This call performs a search in the index thanks to a request image. It returns the id of the matched images from the most to the least relevant ones.

Request JPEG images with a size approximately equal to 450x340 pixels and a 75% quality are usally enough to achieve a good matching. Their small size allows to quickly send them over a mobile network.

• Path: /index/searcher
• HTTP method: POST
• Data: the binary data of the request image compressed in JPEG or a JSON containing the URL of the image in the "url" field.
• Answer: "SEARCH_RESULTS" as type field and a list of the the matched image ids from the most to the least relevant one in the "image_ids" field
• Possible error types: "IMAGE_NOT_DECODED", "IMAGE_SIZE_TOO_BIG", "IMAGE_SIZE_TOO_SMALL"
• Example:
  • Command line with image data:

    curl -X POST --data-binary @/home/test/img/request.jpg http://localhost:4212/index/searcher
    

  • Answer:

    {
       "image_ids" : [ 2, 5, 43 ],
       "type" : "SEARCH_RESULTS"
    }
    

  • Command line with an image URL:

    curl -X POST -d '{"url":"http://www.mydomain.com/path/to/my/image.jpg"}' http://localhost:4212/index/searcher
    

  • Answer:

    {
       "image_ids" : [ 8, 12, 73 ],
       "type" : "SEARCH_RESULTS"
    }
    

Clear an index

This call erases all the data currently contained in the index.

• Path: /index/io
• HTTP method: POST
• Answer type: "INDEX_CLEARED"
• Possible error types: -
• Example:
  • Command line:

    curl -X POST -d '{"type":"CLEAR"}' http://127.0.0.1:4212/index/io
    

  • Answer:

    {
       "type" : "INDEX_CLEARED"
    }
    

Load an index

This call loads the index data in a provided path.

• Path: /index/io
• HTTP method: POST
• Data: a json with a type field of value "LOAD" and a "index_path" field that set the path where to read the index.
• Answer type: "INDEX_LOADED"
• Possible error types: "INDEX_NOT_FOUND"
• Example:
  • Command line:

    curl -X POST -d '{"type":"LOAD", "index_path":"test.dat"}' http://127.0.0.1:4212/index/io
    

  • Answer:

    {
       "type" : "INDEX_LOADED"
    }
    

Save an index

This call saves the index data in a specified path.

• Path: /index/io
• HTTP method: POST
• Data: a json with a type field of value "WRITE" and a "index_path" field that set the path where to write the index
• Answer type: "INDEX_WRITTEN"
• Possible error types: "INDEX_NOT_WRITTEN"
• Example:
  • Command line:

    curl -X POST -d '{"type":"WRITE", "index_path":"test.dat"}' http://127.0.0.1:4212/index/io
    

  • Answer:

    {
       "type" : "INDEX_WRITTEN"
    }
    

Ping Pastec

This call sends a simple PING command to pastec that answers with a PONG.

• Path: /
• HTTP method: POST
• Data: a json with a "type" field of value "PONG"
• Answer type: "PONG"
• Possible error types: -
• Example:
  • Command line:

    curl -X POST -d '{"type":"PING"}' http://localhost:4212/
    

  • Answer:

    {
       "type" : "PONG"
    }