# Face Liveness Detection SDK - Server We implemented face liveness detection SDK via docker container in Python language {% hint style="info" %} We provide the Face Liveness Detection SDK for both Windows and Linux. {% endhint %} ## Features * [x] Face Detection * [x] Face Liveness Detection * [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 license` based on `machine ID` from 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: 8 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: 8 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) ## Import SDK 1. Python ```python from facesdk import getMachineCode from facesdk import setActivation from facesdk import faceDetection from facesdk import initSDK from facebox import FaceBox ``` 2. C++ ```cpp #include "facesdk.h" ``` ```cmake # CMake for Windows target_link_libraries(your_app_name /path/to/library/facesdk1.lib ) # CMake for Linux target_link_libraries(your_app_name /path/to/library/libfacesdk1.so ) ``` ## Initializing SDK 1. Step one * First, obtain the `machine code` for activation and request a license based on the `machine code`. ```python # Python code example machineCode = getMachineCode() print("machineCode: ", machineCode.decode('utf-8')) ``` ```cpp // C++ code example printf("machine code: %s\n", getMachineCode()); ``` 2. Step Two * Next, activate the SDK using the received license. ```python # Python code example setActivation(license.encode('utf-8')) ``` ```cpp // C++ code example int ret = setActivation("..."); ``` * 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 # Python code example initSDK("data".encode('utf-8')) ``` ```cpp // C++ code example ret = initSDK("data"); ``` * 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 | | Liveness score (0 \~ 1) | float | liveness | | 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 angles

68 points facial landmark

## APIs ### 1. getMachineCode First, obtain the `machine code` for activation and request a license based on the `machine code`. ```python # Python code example machineCode = getMachineCode() print("machineCode: ", machineCode.decode('utf-8')) ``` ```cpp // C++ code example printf("machine code: %s\n", getMachineCode()); ``` ### 2. setActivation Next, activate the SDK using the received license. ```python # Python code example setActivation(license.encode('utf-8')) ``` ```cpp // C++ code example int ret = setActivation("..."); ``` 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 # Python code example initSDK("data".encode('utf-8')) ``` ```cpp // C++ code example ret = initSDK("data"); ``` The first parameter is the path to the model. {% hint style="danger" %} When using Windows, it is necessary to provide the complete file path for the model. For 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`, performing `liveness detection`, determining `face orientation (yaw, roll, pitch)`, assessing `face quality`, detecting `facial occlusion`, `eye closure`, `mouth opening`, and identifying `facial landmark`s. 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. ## Default Thresholds ```python livenessThreshold = 0.7 yawThreshold = 10 pitchThreshold = 10 rollThreshold = 10 occlusionThreshold = 0.9 eyeClosureThreshold = 0.8 smallFaceThreshold = 100 ``` * If the liveness score exceeds `0.7`, the face is a `real face`. * If the absolute values of the face angles are less than `10.0`, the face is identified as a fronted face. * If the occlusion value is higher than `0.9`, the face is occluded. * If the eye close value is higher than `0.8`, it indicates that the eyes are closed. * If the eye's distance is less than `100`, it indicates that the face is too small.
--- # 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-liveness-detection-sdk-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.