6 Face Verification (1:1) Quickstart Guide

This page provides a comprehensive guide to how you can quickly use the face verification function in Mercury Cloud.

The Face Verification API detects the largest face in two images and verifies whether these two faces are from the same person. Face verification is also called "one-to-one" or "1:1" matching. Verification can be used in identity verification that matches a snapshot with a previously registered image, like a photo on the driver's license.

The following steps upload two images, detect the largest face within each image, and compare the likelihood that the two faces are the same person. When detected successfully, the system returns the comparison result and detected face information.

6.1 Preparation

To start, make sure you have a Python environment installed.

Download and copy the following Python files to your Python path folder.

1KB

auth_headers.py

API Auth Headers Generator

611B

base64_encode.py

Image File to Base64 Converter

1KB

compare_images.py

Comapre Faces

605B

api_parameters.py

API Parameters

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.

Python

# 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'

6.2 Send a face comparison request

Try the following command to send an API call of Face Comparison to compare the largest face in 2 images. Replace the path with your Python library path and target image file path, respectively.

Bash

python {python_path}\compare_images.py "{image_path}\image1.jpg" "{image_path}\image2.jpg"

The result would be shown as follows. It includes the comparison score field that shows the similarity of two faces detected and one_face, another_face fields that include detection results.

Compare image: {image_path}\image1.jpg {image_path}\image2.jpg
https://mercury.japancv.co.jp/openapi/face/v1/aabbccdd-eeff-0011-2233-445566778899/detect
Http status code: 200
Similarity: 0.9915448
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
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 Similarity stands for the confidence level of the two faces belong to the same person. In this example, we can say we are 99.15% confident that they are verified to be the same person.

6.3 Threshold and accuracy

You should decide your acceptance level, which is usually called "threshold," to compare with the similarity score and judge the final result of this face verification. This logic should be built into your system. Mercury Cloud service could not decide it for you.

Depending on the threshold, the result of face verification might be different. For example, suppose the threshold is set to a strict value of 0.995. The hypothesis of the two faces being the same person is rejected since 0.9915448 < 0.995, even though the comparison score is considered to be a relatively high one. On the contrary, if the threshold is set to a more reasonable value of 0.95, we can accept the same hypothesis since 0.9915448>0.95.

The threshold setting is a trade-off between the false acceptance rate (FAR) and the false rejection rate (FRR). The higher the threshold, the more likely a false rejection would happen and less likely that a false acceptance would happen.

Different businesses have different use scenes and different demands on face recognition accuracy. Some common threshold values are set from 0.6 to 0.7 to avoid FAR as much as possible. But, please adjust and configure the threshold based on your business requirements and test results.