# 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:** {% embed url="" %} {% embed url="" %} {% embed url="" %} ## 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:///register`\ This `API` enrolls face data from image base64 format and save it to database(`PostgreSQL`)
2. `http:///search`\ This `API` seeks face similar to input face among database and returns enrolled image ID and similarity score.
3. `http:///user_list`\ This `API` shows all data enrolled on database(`PostgreSQL`).
4. `http:///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`. ```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.
FeatureValueName
Successful activation or initialization0SDK_SUCCESS
License key error-1SDK_LICENSE_KEY_ERROR
AppID error (Not used in Server SDK)-2SDK_LICENSE_APPID_ERROR
License expiration-3SDK_LICENSE_EXPIRED
Not activated-4SDK_NO_ACTIVATED
Failed to initialize SDK-5SDK_INIT_ERROR
### 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 |

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`. ```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: 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.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.kby-ai.com/help/product/face-liveness-detection-sdk-face-recognition-sdk/face-search-sdk-1-n-face-recognition-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.