Skip to content

Search

Our search API allows you to search for registered persons by using an image.

Given an image of a person, search answers the following two questions:

  1. Are they a registered person?
  2. Which registered person are they?

This facilitates a wide variety of use-cases ranging from Attendance Tracking, Building Security, etc.

Sending a search request

The following snippet shows the process of creating a search request:

std::vector<std::string> verify_images{ “C:\\images\\varun.jpg”};
SearchRequest search_request(verify_images,0.7,SearchMode::FAST);

In addition to supplying up to 3 images in a list, you can optionally specify a collection_id, min_score, and SearchMode as follows.

search_request.collection_id=”123454”;
search_request.min_score=0.7;
search_request.search_mode=SearchMode::FAST;

The collectionid if not None, will restrict the search to only persons who belong to the specified collection.

The min_score is a similarity threshold ranging between 0 and 1. When specified (as in this example), the API will return only persons with a similarity score above 0.7.

The search_mode when using SearchMode::ACCURATE performs double the computation (and hence is slower) but can give a better score.

If you want to recognize persons with masks, you can try a min_score of 0.66

Usually omitting these parameters and letting the system use the defaults is good enough for most purposes.

Now that we have created a search_request, let's send it to the server:

std::vector<PersonSearchResult> result_persons = sdk.search.search(search_request);

The result is simply a list of PersonSearchResult with each object containing a person attribute and a score attribute.

As an example, we can access the person and score attributes from the first item in the result:

result_persons[0].score;
result_persons[0].name;
result_persons[0].id;

A search can return more than one matched person, thus we use the first item from the result in the example above.

Sending a multi-face detection and search request

The search API we used before assumes that there is only one prominent face in an image. But what if we wanted to recognize all the people in an image?

This would mean we first need to detect all faces, and then search for each detected face, and each detected face could match with more than one person.

To make this easy for you, we combined the search and detect functionalities in one API call.

As a user, you can choose to only detect faces, or to detect faces, and also search for them:

std::string input_image = "C:\\detection\\one_face.jpg";
std::vector<DetectionResponseItem> result = sdk.search.detect(input_image);

Since we did not search any person and simply detected the face in image, the list of person items will always be empty.

Now we can try our request where we did specify SearchOptions

std::vector<string> images{ “C:\\detection\\one_face.jpg”};
SearchRequest search_request{ images ,0.7,SearchMode::FAST ,"" };
std::vector<PersonSearchResult> result;
result = sdk.search.search(search_request);

It is to be noted that more than one person can be associated with each detection.

Structure of the detection response

The detection response is a list of DetectionResponseItem objects. Each DetectionResponseItem contains:

  1. box - a box object of type Box, with object attributes left, top, right, left of type int

  2. landmarks - a landmarks object of type Landmarks, with attributes left_eye, right_eye, etc. each of type Coordinate. A Coordinate object has attributes x and y.

  3. thumbnail - a thumbnail of the detected face encoded in base64 string

  4. detection_score - a detection score of type float

  5. persons - a list of persons matching the detection thumbnail of type PersonSearchResult

Verifying a specific Person

If you know the id of a specific person, and you would just like to know if a given image matches the person with the specified id, then this API is best suited to your needs.

As usual, we first create a VerificationRequest

std::vector<string> images{“C:\\images\\varun.jpg”};
VerificationRequest verification_request{“bb106660-85cd-44d0-8b80-2dc288503890
”,images,0.7,SearchMode::FAST };

Then we call the API:

PersonSearchResult verified_person = sdk.search.verify(verification_request);

The response is an object of type PersonSearchResult and contains a person attribute of type Person and a score attribute of type float.

If the image doesn't match the id, then person object will be None, and the score shall be 0.