Face Search

Face Search (On-Premises) allows you to quickly find and identify faces within large internal databases. The entire search process is performed locally, providing a safe, fast, and scalable solution for facial recognition while maintaining full data security.

Prerequisites

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

Requirement	Specification
OS	Ubuntu 22.04
CPU	8 Core 16 Threads
RAM	64GB
Disk	500GB*
Server	Freshly installed and upgraded
Docker	Ensure that the latest version of Docker is installed
Images	Client can enroll up to 1000 images with a maximum size of 640x320 pixels per image

note

Based on your number of enrollments disk space might need to increase. This space can store around 10million face maps.

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

Install AWS CLI

sudo apt update 
sudo apt install awscli 
aws --version

Configure AWS Credentials

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

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 Registry

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_search:hash_id
docker pull 084864413923.dkr.ecr.eu-north-1.amazonaws.com/cache2:latest

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:
Copy each command mentioned in below cells one by one and execute them respectively.

Create a Docker network and volume:

docker network create facia-network
docker volume create facia-cache

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

Run the Cache2 container:

docker run -d --name cache2 --network=facia-network -v facia-cache:/usr/share/elasticsearch/data 084864413923.dkr.ecr.eu-north-1.amazonaws.com/cache2:latest

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 --link cache2:cache2 084864413923.dkr.ecr.eu-north-1.amazonaws.com/face_search:hash_id

Wait for Initialization

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

curl localhost:5001/status_check

if the response is returned as "Service 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 Endpoints

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.

1. Face Search/Enrollment

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

{
    "hash_id": "your_hash_id",
    "service": "face_search",  // or "face_enrollment"
    "enroll_face": false,
    "selfie_image": "base64_encoded_selfie_image"
}

Server Response in face_enrollment

{
    "image_id": "DA84BB4260E641D1A640DBB1500C65FD",
    "message": "Success",
    "is_enroll": true
}

Interpretation of Response:

image_id : Id assigned to enrolled persons image.
message: Success indicated that the pipeline processed successfully.

Server Response in face_search

{
    "image_id": "216B742C37AC4805B9C2D99D116CA198",
    "is_enroll": false,
    "matching_records": [
        {
            "image_id": "DA84BB4260E641D1A640DBB1500C65FD",
            "score": 0.98
        }
    ],
    "message": "Success"
}

image_id : ID of the image being searched.
is_enroll: If false then image is not enrolled. If true then the image has enrolled successfully.
matching_records : returns the matching images id and similarity score in the dictionary object.
message: Success indicated that the pipeline processed successfully.

Use Cases

Wrong hash_id

{
    "message": "Invalid credentials"
}

Corrupted Image

{
    "error": "Invalid or corrupt selfie image. Images must be in PNG, JPG, or JPEG format."
}

Face Search when enroll_face key is True

{
    "image_id": "83CF084F7B8844098DD41891FA5A951C",
    "is_enroll": true,  //means that face has enrolled in Tree
    "matching_records": [],
    "message": "Success"
}

Face Search when enroll_face key is False

{
    "image_id": "83CF084F7B8844098DD41891FA5A951C",
    "is_enroll": false,  //means that face has not enrolled in Tree
    "matching_records": [],
    "message": "Success"
}

Missing image

{
    "error": "Selfie image is required and must be JPEG, JPG or PNG."
}

Demo Limit Reach

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

Database connection issue

{
    "error": "Database connection issue."
}

2. Bulk Enrollment

Method: POST
URL: /bulk_enroll
Content-Type: multipart/form-data
Request Body:

{
    "email": "your_email",
    "password": "your_password",
    "files": "zip_file_in_bytes"
}

Server Response in bulk enrollment

{
  "enrolled_images": [
   {"img1.jpg": "A5722BA1677F44CD8C9E10EF00A587EB"},
   {"img2.jpg": "AAHSDG1232V3V21V3V123V123V123V12"},
   {"img3.jpg": "FF2F2F2F132F1VEG21VWGEV12EVG1GV1"},
   {"img4.jpg": "ASD23232D2C2C2C2C12WB12BW21WB2W1"},
   {"img5.jpg": "IOWPEFELKFEFKNERFJENFENFEJFNEJME"},
   {"img6.jpg": "A5722BA1677F44CD8C9E10EF00A587EB"},
   {"img7.jpg": "A5722BA1677F44CD8C9E10EF00A587EB"},
   {"img8.jpg": "A5722BA1677F44CD8C9E10EF00A587EB"},
   {"img9.jpg": "A5722BA1677F44CD8C9E10EF00A587EB"},
   {"img10.jpg": "A5722BA1677F44CD8C9E10EF00A587EB"},
   {"img11.jpg": "A5722BA1677F44CD8C9E10EF00A587EB"}

  ],
  "failed_images": [],
  "message": "Success"
}

enrolled_images : returns a list of image names along with their corresponding unique IDs. These IDs represent the unique identity of each enrolled person's image and can be used to search or reference the successfully enrolled images for future identification or verification purposes.
failed_images: return the images and their ids that failed to enroll.
message: Success indicated that the pipeline processed successfully.

Use Cases

Wrong hash_id

{
    "message": "Invalid credentials"
}

Invalid Zip file

{
    "error": "Invalid file",
    "message": "The uploaded file is not a valid ZIP file."
}

Missing Zip file

{
    "error": "Missing file",
    "message": "Please upload a ZIP file."
}

Demo Limit Reach

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

Database connection issue

{
    "error": "Database connection issue."
}

Note on Image Size and Upload Limitations

For a single request, users can enroll up to 1000 images with a maximum size of 640x320 pixels per image. For images exceeding this size, there is no restriction on the dimensions, and users can enroll images of any size. Please ensure that the number of images does not exceed 1000 for optimal processing in a single request.

3. Delete Record

Method: DELETE
URL: /delete_record
Content-Type: application/json
Request Body:

{
    "email": "your_email",
    "password": "your_password",
    "Image_id": "image_id"
}

Server Response in delete_record

{
    "message": "Record deleted successfully from ElasticSearch",
}

Use Cases

Wrong hash_id

{
    "message": "Invalid credentials"
}

Missing or Empty Image_id

{
    "error": "image_id is required."
}

Record not found

{
    "error": "Record not found"
}

Demo Limit Reach

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

Database connection issue

{
    "error": "Database connection issue."
}

4. Delete Tree

Method: DELETE
URL: /delete_tree
Content-Type: application/json
Request Body:

{
    "email": "your_email",
    "password": "your_password"
}

Server Response in delete_tree

{
    "success": "Tree cleared successfully!",
}

Use Cases

Wrong hash_id

{
    "message": "Invalid credentials"
}

Demo Limit Reach

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

Database connection issue

{
    "error": "Database connection issue."
}

Testing Scripts

note

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

Face Search/Enrollment Testing Script

import base64
import uuid
import requests
import os
import mimetypes

def generate_reference_id():
    return str(uuid.uuid4()).replace('-', '').upper()

def encode_image_to_base64(image_path):
    if not os.path.exists(image_path):
        raise FileNotFoundError(f"{image_path} not found")
    mime_type, _ = mimetypes.guess_type(image_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Invalid image file")
    with open(image_path, "rb") as img:
        return f"data:{mime_type};base64,{base64.b64encode(img.read()).decode()}"

image1_path = "image.png"
json_data = {
    'hash_id': "your_hash_id",
    'service': "face_search",  # or "face_enrollment"
    'enroll_face': False,
    'selfie_image': encode_image_to_base64(image1_path)
}
response = requests.post("http://127.0.0.1:5001/search_face", json=json_data)
print(f"Response Code: {response.status_code}")
print(f"Response Text: {response.json()}")

Bulk Enrollment Testing Script

import requests
import json

zip_file_path = "zip_file_path"
email = "email"
password = "password"

with open(zip_file_path, "rb") as zip_file:
    zip_file_data = zip_file.read()

files = {
    'zip_file': ('zipfile.zip', zip_file_data, 'application/zip')
}
data = {
    'email': email,
    'password': password,
}

r = requests.post(
    "http://127.0.0.1:5001/bulk_enroll",
    files=files, 
    data=data,
    timeout=600
)

if r.status_code == 200:
    try:
        response_json = r.json()
        print(f"Response Code: {r.status_code}")
        print(f"Response Text: {response_json}")
    except json.JSONDecodeError:
        print("Error: Unable to decode response as JSON.")
else:
    print(f"Error: {r.status_code} - {r.text}")

Face Search

Prerequisites​

Install and Configure AWS Account​

Install AWS CLI​

Configure AWS Credentials​

Docker Login to AWS ECR Registry​

Setting up the Updated Docker Images from AWS ECR Registry​

Pull the Updated Images from AWS ECR Registry​

Run the Containers​

Wait for Initialization​

API Endpoints​

1. Face Search/Enrollment​

Server Response in face_enrollment​

Interpretation of Response:​

Server Response in face_search​

Use Cases​

2. Bulk Enrollment​

Server Response in bulk enrollment​

Use Cases​

Note on Image Size and Upload Limitations​

3. Delete Record​

Server Response in delete_record​

Use Cases​

4. Delete Tree​

Server Response in delete_tree​

Use Cases​

Testing Scripts​

Face Search/Enrollment Testing Script​

Bulk Enrollment Testing Script​

Prerequisites

Install and Configure AWS Account

Install AWS CLI

Configure AWS Credentials

Docker Login to AWS ECR Registry

Setting up the Updated Docker Images from AWS ECR Registry

Pull the Updated Images from AWS ECR Registry

Run the Containers

Wait for Initialization

API Endpoints

1. Face Search/Enrollment

Server Response in face_enrollment

Interpretation of Response:

Server Response in face_search

Use Cases

2. Bulk Enrollment

Server Response in bulk enrollment

Use Cases

Note on Image Size and Upload Limitations

3. Delete Record

Server Response in delete_record

Use Cases

4. Delete Tree

Server Response in delete_tree

Use Cases

Testing Scripts

Face Search/Enrollment Testing Script

Bulk Enrollment Testing Script