7 Face Identification (1:N) Quickstart Guide
This page provides a comprehensive guide to how you can quickly build your face database and use the Face Identification function.
Last updated
This page provides a comprehensive guide to how you can quickly build your face database and use the Face Identification function.
Last updated
The Face Identification API searches a detected face among all registered face features in the feature databases and returns the closest results. Face identification is also called "one-to-many" or "1:N" matching. Candidate results are returned based on the similarity with the detected face. After creating a feature database and adding some registration photos to the database, you can perform the face identification with a newly uploaded image.
The following steps create a feature database, add a few features to the database, upload an image, detect the largest face in the image, then search similar faces within one feature database. When detected successfully, the system returns the search result and detected face information. Finally, the feature database is deleted.
During the APIs operating feature database, the db_id is a unique key to identify any single feature database. Please memorized the db_id in the response of the creating feature database API (POST/{app_id}/databases) or you can find it with the list feature databases API (GET/{app_id}/databases).
To start, make sure you have a Python environment installed.
Download and copy the following Python files to your Python path folder.
Open the api_parameters.py with a text editor and replace the following parameters will your info. Refer to Section 3.2 for more details.
Use the following command to send an API call to create a feature database with the name "foo" and the DB size 1000. Replace the path with your Python library path. The DB size restricts the maximum number of features which can be stored in a single feature database. Note that this number should be no more than the number of IDs you purchased in your subscription.
Create feature database API sends a request with the database name and the maximum size. After creating successfully, the response will contain a unique db_id. The result would be shown as follows.
Please memorize this db_id in the response_body. It will be used while calling other APIs in the next steps.
Use the following command to send an API call to confirm the existence of the feature database you have just created.
The result would be shown as follows.
You can find the feature database with the same db_id is returned.
The Quality Check API analyzes face size, angle, brightness, sharpness, occlusion, etc., and responses values for all factors. It's highly recommended to check image quality before adding faces to the feature database since higher image quality leads to higher recognition precision.
Use the following command to send an API call to perform a quality check.
The result would be shown as follows.
You should decide your acceptance level or threshold of each factor returned by the API. This logic should be built into your system. Different businesses have different use scenes and different demands on image quality.
We provide some reference values that are approximate to the image quality for passport photos. But, please adjust and configure the threshold based on your business requirements and test results.
| Name | Value range (only for reference) | Description |
|---|---|---|
angle.yaw | -10.0~10.0 | Yaw in angle. |
angle.pitch | -15.0~15.0 | Pitch in angle. |
angle.roll | -10.0~10.0 | Roll in angle. |
quality.distance2center | 0.2~1.0 | Indicate the distance between the center of the face and the center of the image, far to near. |
occlusion.occlusion_total | 0.0~0.02 | Face occlusion, low to high. |
occlusion.eye | 0.0 | Eye occlusion, low to high. |
occlusion.nose | 0.0 | Nose occlusion, low to high. |
occlusion.mouth | 0.0~0.4 | Mouth occlusion, low to high. |
occlusion.eyebrow | 0.0 | Eyebrow occlusion, low to high. |
occlusion.face_line | 0.0~0.1 | Face contour occlusion, low to high. |
quality.align_score | 1.0~ | Face landmarks score, low to high. |
quality.brightness | -0.5~0.5 | Face brightness, dark to bright. |
quality.sharpness | 0.8~1.0 | Face sharpness, bad to good. |
quality.mouth_open | 0.0~0.4 | Mouth opened size, closed to open. |
quality.missing | 0.9~1.0 | Effective face proportion, high to low. |
quality.size | 0~0.85 | The face proportion in the image, small to large. |
The Batch Add feature API sends some images in a single request to add multiple features to a feature database. Each feature added to a feature database will get a unique feature_id. You may also add identical images or several images belonging to the same person to a feature database multiple times and receive several differentfeature_id. That is to say, a feature_id does not have to be an equivalent to a single person, but rather a feature added at that time.
Use the following command to send an API call to add all images in the designated folder to the feature database we have created.
The result would be shown as follows. There are two images in the folder.
The features from the two images are added to the feature database.
The Face Searching API uploads an image and finds the top K similar faces within the feature database based on verification score results. The example code we provide here restricts the top two features with verification scores above 0.8.
Use the following command to send an API call to perform a search.
The result would be shown as follows.
The API response includes top K results if matches are found. Otherwise, no results will be returned. The two images added in the previous steps and the searching image belong to the same person, thus the feature_ids and their scores are returned.
Finally, if the feature database is no longer needed, you can simply delete the feature database. All features registered in the feature database will be deleted together simultaneously. Use the following command to send an API to perform the deletion.
The result would be shown as follows.
The feature database and all features added to it are now completely removed from your Mercury Cloud environment.