Face Match

Face Match (On-Premises) enables secure comparison of two facial images to verify whether they belong to the same person. All matching operations are conducted entirely within your servers, ensuring complete control over sensitive biometric data with no external transmission.

Prerequisites

Below are the essential prerequisites to ensure the seamless operation of the Facia services:

Requirement	Specification
OS	Ubuntu 22.04
CPU	16 Core 32 Threads
RAM	32GB
Disk	500GB
Server	Freshly installed and upgraded
Docker	Ensure that the latest version of Docker is installed

Please Login/Signup to your Facia account in order to get the AWS credentials, so you can pull the docker image. Once logged in, you can retrieve the credentials from this URL in settings.

Install and Configure AWS Account

The installation of awscli can be done using the following command, please run the commands in the following order as it is:

note

If you are not using the internet in your environment then you might need to enable it temporarily to fetch the registories.

sudo apt update
sudo apt install awscli
aws --version

In order to configure the aws cli we need to run the below commands, this will show the prompt which requires the secret token:

aws configure

Once the above command is run then, we need to enter the id and the secret key during the aws cli configuration.

You will be prompted to enter the Client ID, Secret Token, and AWS Region.

Please copy and paste these credentials from the On-Prem Keys section available on the Merchant Portal. After login/signup, input the required values as follows:

• Client ID
• Secret Token
• AWS Region

When prompted with: Default output format [None]: Simply press the Enter key to continue without selecting any output format. Make sure to enter the credentials accurately to ensure a successful configuration.

Sample Response:

root@root:~# aws configure
Access Key ID [None]: your_access_id
AWS Secret Access Key [None]: your_secret_key
Default region name [None]: your_region_name
Default output format [None]:

Now you will have the aws cli configured in your server and good to start builds pulling from the Elastic Container Registry (ECR)

aws configure list

Docker Login to AWS ECR Registry

To access Docker images stored in AWS Elastic Container Registry (ECR), run the following command:

aws ecr get-login-password --region eu-north-1 | docker login --username AWS --password-stdin 084864413923.dkr.ecr.eu-north-1.amazonaws.com

Setting up the Updated Docker Images from AWS ECR Registry

Pull the Updated Images from AWS ECR

There are a total of four images that you need to pull from the AWS ECR registry. Following are the commands to pull the docker images:

docker pull 084864413923.dkr.ecr.eu-north-1.amazonaws.com/cache:latest

docker pull 084864413923.dkr.ecr.eu-north-1.amazonaws.com/face_match_onp:hash_id

Run the Containers

• To run the FACIA application on a different IP address and port, modify the -p flag in the docker run command for ml_services_container. (Optional)
• Create a Docker network named facia-network and run the containers with the following commands:

1. Create a Docker network:

docker network create facia-network

2. Run the MongoDB container:

docker run -d --name mongodb_local_container -e USER=mongoAdmin -e PASS=TBbuaxROrspF8K6ugQJ29s8ZMqc --network=facia-network 084864413923.dkr.ecr.eu-north-1.amazonaws.com/cache:latest

3. Run the ML services container:

docker run -d --name ml_services_container --network=facia-network -p 127.0.0.1:5001:5001 --link mongodb_local_container:mongodb_local 084864413923.dkr.ecr.eu-north-1.amazonaws.com/face_match_onp:hash_id

Wait for Initialization

Allow 5-10 minutes for the services to initialize before proceeding. Check the status of the ml container using:

curl localhost:5001/status_check

If the response is returned as {"message": "Services is live"} then we are good to go with start putting the requests OR else you need to wait till its ready.

Note

Images must be in PNG, JPG, or JPEG format.

API Integration

Please Login/Signup to your Facia account in order to get the Hash_id, so you can use docker. Once logged in, you can retrieve the Hash ID from this URL in settings.

Endpoint Details

• Method: POST
• URL: /process_similarity
• Content-Type: application/json
• Request Body:

{
    "hash_id": "hash_id",
    "selfie_image": "selfie_image_base64_encoded_string",
    "document_image": "document_image_base64_encoded_string"
}

• Server Response:

{
    "face_similarity_result": {
        "is_match": 0/1,
        "similarity_score": 0.0-1.0
    },
    "message": "Success"
}

Interpretation of Response

• is_match: 1 if the faces match, 0 if they do not match
• similarity_score: A score representing the similarity between the two faces
• message: Indicates the success of the process

Use Cases

1. Wrong Hash ID

{
    "message": "Invalid credentials"
}

2. Corrupted Selfie or Document Image

{
    "error": "hash_id is required"
}

3. Corrupted Image

{
    "error": "The document or selfie image is invalid or corrupted. Please upload an image in PNG, JPG, or JPEG format."
}

4. Face Match

{
    "face_similarity_result": {
        "is_match": 1,
        "similarity_score": 0.932992
    },
    "message": "Success"
}

5. Face Not Match

{
    "face_similarity_result": {
        "is_match": 0,
        "similarity_score": 0.2345545
    },
    "message": "Success"
}

6. Missing Images

{
    "error": "Both selfie_image and document_image are required"
}

7. Demo Limit Reached

{
    "message": "Your request limit has been reached."
}

Testing Script in Python

Note

You need to add the value of the variable within the key "image_path" as per your business needs.

import requests
import os
import json
import base64
import mimetypes

image1_path = "image1"
image2_path = "image2"
hash_id = "hash_id"

def encode_image(image_path):
    file_extension = os.path.splitext(image_path)[1].lower()
    mime_type, _ = mimetypes.guess_type(image_path)
    
    with open(image_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')

    base64_image = f"data:{mime_type};base64,{encoded_string}"
    return base64_image

selfie_image_base64 = encode_image(image1_path)
document_image_base64 = encode_image(image2_path)

json_data = {
    'hash_id': hash_id,
    'selfie_image': selfie_image_base64,
    'document_image': document_image_base64,
}

r = requests.post("http://127.0.0.1:5001/process_similarity", json=json_data)
print(f"Response Code: {r.status_code}")

try:
    response_data = r.json()  
    print("Response JSON:", response_data)
except json.JSONDecodeError:
    print("Failed to decode JSON. Response text:")
    print(r.text)