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.

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).

7.1 Preparation

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.

# Common parameters. Used for all API calls.
# Base URL for Mercury Open API.
api_url = "https://mercury.japancv.co.jp/openapi/face/v1"
# Provision App Id for API calls.
app_id = "aabbccdd-eeff-0011-2233-445566778899"
# Provision access key to authentication.
access_key = '00112233-4455-6677-8899-aabbccddeeff'
# Provision secret key to authentication.
secret_key = '13579acegijmoqsuwyACEGIJMOPSUWY'

7.2 Create a feature database

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.

python {python_path}\create_feature_db.py foo 1000

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.

Compare feature database: name: foo max size: 1000
Http status code: 200
response: {
 "trace_id": "de2557f6b435c836dd12447413bc9966",
 "name": "foo",
 "db_id": "4caf27d2-f621-4cbf-acec-a7553f226000",
 "object_type": "OBJECT_FACE",
 "feature_version": 24902,
 "description": "Description for database foo",
 "created_at": "2021-07-15T04:11:04.744807758Z",
 "max_size": 1000,
 "size": 0
}

Please memorize this db_id in the response_body. It will be used while calling other APIs in the next steps.

7.3 List feature databases

Use the following command to send an API call to confirm the existence of the feature database you have just created.

python {python_path}\list_feature_db.py

The result would be shown as follows.

List feature databases:
Http status code: 200
db_ids: [
 "4caf27d2-f621-4cbf-acec-a7553f226000"
]

You can find the feature database with the same db_id is returned.

7.4 Check Image Quality

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.

python {python_path}\check_quality.py "{image_path}\image.jpg"

The result would be shown as follows.

Check quality: {image_path}\image.jpg
Http status code: 200
Quality results: {
 "angle": {
  "yaw": 0.0027652662,
  "pitch": 7.864833,
  "roll": 0.049663484
 },
 "quality": {
  "distance2center": 0.08779055,
  "size": 0.36317098,
  "brightness": 0.17242007,
  "sharpness": 1,
  "mouth_open": 0.018774271,
  "missing": 1,
  "align_score": 9.999992
 },
 "occlusion": {
  "eye": 0,
  "nose": 0,
  "mouth": 0,
  "eyebrow": 0,
  "face_line": 0,
  "occlusion_total": 0
 },
 "rectangle": {
  "top": 610,
  "left": 332,
  "width": 777,
  "height": 774
 }
}

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.

Passport level image quality

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.

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.

7.5 Add some images to the feature database

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.

python {python_path}\add_faces.py "4caf27d2-f621-4cbf-acec-a7553f226000" {image_path}

The result would be shown as follows. There are two images in the folder.

Add to database: 4caf27d2-f621-4cbf-acec-a7553f226000 image: {image_path}\image1.jpg
Http status code: 200
Face feature_id: 4caf27d2f6214cbfaceca7553f226001000000000000008e
Detect face. rectangle: {'top': 625, 'left': 350, 'width': 793, 'height': 818} angle: {'yaw': -0.42474133, 'pitch': 9.596367, 'roll': 0.07245465}
Predicted attributes:
        Age: 29 ~ 39
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE
Add to database: 4caf27d2-f621-4cbf-acec-a7553f226000 image: {image_path}\image2.jpg
Http status code: 200
Face feature_id: 4caf27d2f6214cbfaceca7553f226001000000000000008f
Detect face. rectangle: {'top': 637, 'left': 276, 'width': 844, 'height': 834} angle: {'yaw': 4.691873, 'pitch': 10.485169, 'roll': 1.0859865}
Predicted attributes:
        Age: 28 ~ 38
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE

The features from the two images are added to the feature database.

7.6 Search in 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.

python {python_path}\search_faces.py "4caf27d2-f621-4cbf-acec-a7553f226000" "{image_path}\image.jpg"

The result would be shown as follows.

Search face: {image_path}\image.jpg in:  4caf27d2-f621-4cbf-acec-a7553f226000
Http status code: 200
Detect face. rectangle: {'top': 342, 'left': 171, 'width': 384, 'height': 392} angle: {'yaw': -1.557804, 'pitch': 10.313386, 'roll': 1.3425148}
Predicted attributes:
        Age: 28 ~ 38
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE
        db_id: 4caf27d2-f621-4cbf-acec-a7553f226000
top 1 score: 0.9813498
        feature: {'feature_id': '4caf27d2f6214cbfaceca7553f226001000000000000008e', 'key': '', 'extra_info': 'image1.jpg'}
top 2 score: 0.9803276
        feature: {'feature_id': '4caf27d2f6214cbfaceca7553f226001000000000000008f', 'key': '', 'extra_info': 'image2.jpg'}

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.

7.7 Delete the feature database

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.

python {python_path}\delete_feature_db.py "4caf27d2-f621-4cbf-acec-a7553f226000"

The result would be shown as follows.

Delete feature database: db_id: 4caf27d2-f621-4cbf-acec-a7553f226000
Http status code: 200
response: {
 "trace_id": "81c28dcd71c48befdcd2d92afb34c278"
}

The feature database and all features added to it are now completely removed from your Mercury Cloud environment.

Previous6 Face Verification (1:1) Quickstart Guide Next8 Guidance to Advanced Users

Last updated 2 years ago