Face Search SDK(1:N Face Recognition) - Server

This stands for 1:N face recognition docker, face search, face lookup, 1:N face matching docker, face comparison docker, face search engine docker, face identification docker, on server

We implemented face search SDK to perform 1:N face recognition`and 1:N face matching ondocker container.

This SDK demonstrates 1:N face recognition, face search SDK derived from KBY-AI's face recognition server SDK by implementing the functionalities to register face and search face from database(PostgreSQL). This SDK offers APIs to enroll face, to search face, to see database, to clear database. And every API can be customized by updating app.py file accordingly.

We provide the 1:N Face Recognition SDK and face search SDK for both Windows and Linux.

Features

License

We offer lifetime licenses(perpetual) based on machine ID for Servers (Windows, Linux).

To request a license, please contact us:

Email: [email protected]

LogoShare on WhatsAppWhatsApp.com
LogoTelegram: Contact @kbyaiTelegram
LogoJoin the KBY-AI Discord Server!Discord

System Requirements

1. Windows

  • CPU: 2 cores or more (Recommended: 2 cores)

  • RAM: 4 GB or more (Recommended: 8 GB)

  • HDD: 4 GB or more (Recommended: 8 GB)

  • OS: Windows 7 or later

  • Architecture: x64

  • Dependency: OpenVINO™ Runtime (Version: 2022.3), ncnn Runtime(20220721), Vulkan SDK Runtime(1.3.250)

2. Linux

  • CPU: 2 cores or more (Recommended: 2 cores)

  • RAM: 4 GB or more (Recommended: 8 GB)

  • HDD: 4 GB or more (Recommended: 8 GB)

  • OS: Ubuntu 20.04 or later

  • Architecture: x64

  • Dependency: OpenVINO™ Runtime (Version: 2022.3)

Postman Endpoints

To test the API, you can use Postman. Here are the endpoints for testing:

  1. http://<your-base-url>/register This API enrolls face data from image base64 format and save it to database(PostgreSQL)

  2. http://<your-base-url>/search This API seeks face similar to input face among database and returns enrolled image ID and similarity score.

  3. http://<your-base-url>/user_list This API shows all data enrolled on database(PostgreSQL).

  4. http://<your-base-url>/remove_all This API removes all data from database.

Example of face search API

Initializing SDK

  1. Step one

  • First, obtain the machine code for activation and request a license based on the machine code.

machineCode = getMachineCode()
print("machineCode: ", machineCode.decode('utf-8'))

  1. Step Two

  • Next, activate the SDK using the received license.

setActivation(license.encode('utf-8'))

  • If activation is successful, the return value will be SDK_SUCCESS. Otherwise, an error value will be returned.

  1. Step Three

  • After activation, call the initialization function of the SDK.

initSDK("data".encode('utf-8'))

  • The first parameter is the path to the model.

  • If initialization is successful, the return value will be SDK_SUCCESS. Otherwise, an error value will be returned.

Enums and Structure

1. SDK_ERROR

This enumeration represents the return value of the initSDK and setActivation functions.

Feature
Value
Name

Successful activation or initialization

0

SDK_SUCCESS

License key error

-1

SDK_LICENSE_KEY_ERROR

AppID error (Not used in Server SDK)

-2

SDK_LICENSE_APPID_ERROR

License expiration

-3

SDK_LICENSE_EXPIRED

Not activated

-4

SDK_NO_ACTIVATED

Failed to initialize SDK

-5

SDK_INIT_ERROR

2. FaceBox

This class represents the output of the face detection function that contains the detected face rectangle, liveness score, and facial angles such as yaw, roll, and pitch.

Feature
Type
Name

Face rectangle

int

x1, y1, x2, y2

Face angles (-45 ~ 45)

float

yaw, roll, pitch

Face quality (0 ~ 1)

float

face_quality

Face luminance (0 ~ 255)

float

face_luminance

Eye distance (pixels)

float

eye_dist

Eye closure (0 ~ 1)

float

left_eye_closed, right_eye_closed

Face occlusion (0 ~ 1)

float

face_occlusion

Mouth opening (0 ~ 1)

float

mouth_opened

68 points facial landmark

float[68 * 2]

landmarks_68

Face templates

unsigned char [2048]

templates

Face angles
68 points facial landmark

Main Functions

1. getMachineCode

First, obtain the machine code for activation and request a license based on the machine code.

machineCode = getMachineCode()
print("machineCode: ", machineCode.decode('utf-8'))

2. setActivation

Next, activate the SDK using the received license.

setActivation(license.encode('utf-8'))

If activation is successful, the return value will beSDK_SUCCESS. Otherwise, an error value will be returned.

3. initSDK

After activation, call the initialization function of the SDK.

initSDK("data".encode('utf-8'))

The first parameter is the path to the model.

When using Windows, it is necessary to provide the complete file path for the model.

Example:

model_path = "C:\path\to\model"

If initialization is successful, the return value will be SDK_SUCCESS. Otherwise, an error value will be returned.

4. faceDetection

The Face SDK provides a single API for detecting faces, determining face orientation (yaw, roll, pitch), assessing face quality, detecting facial occlusion, eye closure, mouth opening, and identifying facial landmarks.

The function can be used as follows:

# Python code example
faceBoxes = (FaceBox * maxFaceCount)()
faceCount = faceDetection(image_np, image_np.shape[1], image_np.shape[0], faceBoxes, maxFaceCount)
// C++ code example
FaceBox* faceBoxes = (FaceBox*)malloc(sizeof(FaceBox) * maxFaceCount);
memset(faceBoxes, 0, sizeof(FaceBox) * maxFaceCount);

ret = faceDetection(image.data, image.cols, image.rows, faceBoxes, maxFaceCount);

This function requires 5 parameters.

  • The first parameter: the byte array of the RGB image buffer.

  • The second parameter: the width of the image.

  • The third parameter: the height of the image.

  • The fourth parameter: the FaceBox array allocated with maxFaceCount for storing the detected faces.

  • The fifth parameter: the count allocated for the maximum FaceBox objects.

The function returns the count of the detected face.

5. templateExtraction

The SDK provides a function that enables the generation of templates from RGB data. These templates can be used for face verification between two faces.

The function can be used as follows:

# Python code example
faceBoxes = (FaceBox * maxFaceCount)()

...

templateExtraction(image_np1, image_np1.shape[1], image_np1.shape[0], faceBoxes[0])
// C++ code example

FaceBox* faceBoxes = (FaceBox*)malloc(sizeof(FaceBox) * maxFaceCount);
memset(faceBoxes, 0, sizeof(FaceBox) * maxFaceCount);

...

templateExtraction(image.data, image.cols, image.rows, faceBoxes[0]);

This function requires 4 parameters.

  • The first parameter: the byte array of the RGB image buffer.

  • The second parameter: the width of the image.

  • The third parameter: the height of the image.

  • The fourth parameter: the FaceBox object obtained from the faceDetection function.

If the template extraction is successful, the function will return 0. Otherwise, it will return -1.

6. similarityCalculation

The similarityCalculation function takes a byte array of two templates as a parameter.

# Python code example

similarity = similarityCalculation(faceBoxes1[0].templates, faceBoxes2[0].templates)
// C++ code example

FaceBox* faceBoxes = (FaceBox*)malloc(sizeof(FaceBox) * maxFaceCount);
memset(faceBoxes, 0, sizeof(FaceBox) * maxFaceCount);

...

float similarity = similarityCalculation(faceBoxes[0].templates, faceBoxes[1].templates);

It returns the similarity value between the two templates, which can be used to determine the level of likeness between the two individuals.

Default Thresholds

verifyThreshold = 0.67

  • If the similarity value between the two templates is high, it indicates that the faces are the same.

PreviousFace Recognition SDK - ServerNextID Card Recognition SDK

Last updated