4 Feature & Image

This page describes how images, including faces, are processed in Mercury Cloud.

4.1 Feature

When we compare faces, add faces to the database, or search a face from the database, the algorithm does not directly use the uploaded raw images. Instead, features are extracted from faces within the Mercury Cloud platform when using these APIs. A feature is a multi-dimension vector that is extracted from the face in the image. Each face from the image will generate a unique feature. What a similarity score indicates is the distance between the feature vectors of two faces.

Therefore, in all Mercury Cloud OpenAPI documents, it refers to comparison or searching for features when mentioning face comparison or face searching. Mercury Cloud OpenAPI DO NOT store any image binary or files within the service.

4.2 Image encoding

Mercury Cloud OpenAPIs use base64 encoded image binaries in HTTP requests to allow image data transmissions. It is much easier to convert the image to the base64 string in Linux via bash command. Refer to the following script and command to convert your images.

Python

def base64_encode_file(file_path):
    handle = open(file_path, "rb")
    raw_bytes = handle.read()
    handle.close()
    return base64.b64encode(raw_bytes).decode("utf-8")

Bash

$ base64 file_path

4.3 Image standards

There are five essential APIs in the service that require base64 encoded image data as input, namely, the Face Detect API (/{app_id}/detect), the Face Compare API (/{app_id}/compare), the Quality Check API (/{app_id}/quality), the Add Feature API (/{app_id}/databases/{db_id}/features), and the Face Search API (/{app_id}/databases/search). The requirements of input images are common among those APIs and are as follows.

• The image format should be JPG, PNG, BMP, TIFF, or GIF (Only the first frame is accepted).

• The file size should be smaller than 8MB.

• The minimum detectable face area should be more than 32x32 pixels.

• In the Face Detect API (/{app_id}/detect) and the Add Feature API (/{app_id}/databases/{db_id}/features), where batch upload is supported, the number of images in a single API call should be no more than 16.

Higher face image quality means better precision, while larger image file size means more response time in the API call. As the best practice, we highly recommend using high-quality, frontal, clear images, with the face area over 200x200 pixels, while the file is trimmed and compressed to less than 200KB before calling APIs.