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

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

This `SDK` demonstrates `1:N face recognition`, `face search SDK` derived from `KBY-AI`'s [face recognition server SDK](https://hub.docker.com/r/kbyai/face-recognition) by implementing the functionalities to register face and search face from database(`PostgreSQL`).\
This `SDK` offers `API`s to enroll face, to search face, to see database, to clear database. And every `API` can be customized by updating [app.py](https://github.com/kby-ai/FaceSearch-Docker/blob/main/app.py) file accordingly.

{% hint style="info" %}
We provide the 1:N Face Recognition SDK and face search SDK for both Windows and Linux.
{% endhint %}

## Features

* [x] Face Detection
* [x] 1:N Face Recognition
* [x] Face Enrollment(Face Register)
* [x] Face Search
* [x] Pose Estimation
* [x] 68 points Face Landmark Detection
* [x] Face Quality Calculation
* [x] Face Occlusion Detection
* [x] Eye Closure Detection
* [x] Mouth Opening Check

## License

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

To request a license, please contact us:

> **Email:** <contact@kby-ai.com> &#x20;

{% embed url="<https://wa.me/+19092802609>" %}

{% embed url="<https://t.me/kbyaisupport>" %}

{% embed url="<https://discord.gg/6wm383re2s>" %}

## 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](https://github.com/kby-ai/FaceSearch-Docker/blob/main/kby-ai-facesearch.postman_collection.json) for testing:

1. `http://<your-base-url>/register`\
   This `API` enrolls face data from image base64 format and save it to database(`PostgreSQL`)<br>
2. `http://<your-base-url>/search`\
   This `API` seeks face similar to input face among database and returns enrolled image ID and similarity score.<br>
3. `http://<your-base-url>/user_list`\
   This `API` shows all data enrolled on database(`PostgreSQL`).<br>
4. `http://<your-base-url>/remove_all`\
   This `API` removes all data from database.

<figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2FxgJr8ZyDZ0L6wVIHvm5k%2F448062778-ca670eb8-3f86-468b-a7ba-d6ab6dedffaf.jpg?alt=media&#x26;token=0212bf55-ae8c-4a0b-8264-694b33fdc1e6" alt=""><figcaption><p>Example of face search API</p></figcaption></figure>

## Initializing SDK

1. Step one

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

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

2. Step Two

* Next, activate the `SDK` using the received license.

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

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

3. Step Three

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

```python
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.

<table><thead><tr><th width="349.3333333333333">Feature</th><th width="99">Value</th><th>Name</th></tr></thead><tbody><tr><td>Successful activation or initialization</td><td>0</td><td>SDK_SUCCESS</td></tr><tr><td>License key error</td><td>-1</td><td>SDK_LICENSE_KEY_ERROR</td></tr><tr><td>AppID error (Not used in Server SDK)</td><td>-2</td><td>SDK_LICENSE_APPID_ERROR</td></tr><tr><td>License expiration</td><td>-3</td><td>SDK_LICENSE_EXPIRED</td></tr><tr><td>Not activated</td><td>-4</td><td>SDK_NO_ACTIVATED</td></tr><tr><td>Failed to initialize SDK</td><td>-5</td><td>SDK_INIT_ERROR</td></tr></tbody></table>

### 2. FaceBox

This class represents the output of the `face detection` function that contains the detected `face rectangle`, `liveness score`, and `facial angle`s 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                             |

<div align="center"><figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2Fj4XxekdSV6Q6cW9KZhPr%2Fimage.png?alt=media&#x26;token=5ace558a-3793-48f0-9324-e1ec8fe80561" alt="" width="524"><figcaption><p>Face angles</p></figcaption></figure></div>

<figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2FUIRrOk6XwkLE9EFC5G4k%2Fimage.png?alt=media&#x26;token=564744e4-1b2f-4f00-9ace-afc84bb9f17e" alt="" width="563"><figcaption><p>68 points facial landmark</p></figcaption></figure>

## Main Functions

### 1. getMachineCode

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

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

### 2. setActivation

Next, activate the `SDK` using the received license.

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

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

### 3. initSDK

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

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

The first parameter is the path to the model.

{% hint style="warning" %}
When using Windows, it is necessary to provide the complete file path for the model.

Example:&#x20;

model\_path = "C:\path\to\model"
{% endhint %}

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
# Python code example
faceBoxes = (FaceBox * maxFaceCount)()
faceCount = faceDetection(image_np, image_np.shape[1], image_np.shape[0], faceBoxes, maxFaceCount)
```

```cpp
// 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 `template`s from `RGB data`. These `templates` can be used for face verification between two faces.

The function can be used as follows:

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

...

templateExtraction(image_np1, image_np1.shape[1], image_np1.shape[0], faceBoxes[0])
```

```cpp
// 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
# Python code example

similarity = similarityCalculation(faceBoxes1[0].templates, faceBoxes2[0].templates)
```

```cpp
// 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

```python
verifyThreshold = 0.67 
```

* If the similarity value between the two templates is high, it indicates that the faces are the same.<br>