diff --git a/README.md b/README.md index 613f2eb..5cc4bc3 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ It includes features that allow for testing face liveness detection using both i | Eye Closure Detection | Eye Closure Detection | | Mouth Opening Check | Mouth Opening Check | - +> Reference > - [Face Liveness Detection - Android(Basic SDK)](https://github.com/kby-ai/FaceLivenessDetection-Android) > - [Face Liveness Detection - iOS(Basic SDK)](https://github.com/kby-ai/FaceLivenessDetection-iOS) > - [Face Recognition - Android(Stdndard SDK)](https://github.com/kby-ai/FaceRecognition-Android) @@ -70,7 +70,7 @@ This project uses KBY-AI's Face Liveness Detection Server SDK, which requires a - OS: Ubuntu 20.04 or later - Dependency: OpenVINO™ Runtime (Version: 2022.3) -### 2. Setup and test +### 2. Setup and Test - Clone the project: ``` git clone https://github.com/kby-ai/FaceLivenessDetection-Docker.git @@ -104,11 +104,94 @@ This project uses KBY-AI's Face Liveness Detection Server SDK, which requires a Test with a base64-encoded image: Send a POST request to http://{xx.xx.xx.xx}:8080/check_liveness_base64. - You can download the Postman collection to easily access and use these endpoints. [click here](https://github.com/kby-ai/FaceLivenessDetection-Docker/blob/main/postman/kby-ai-live.postman_collection.json) + You can download the Postman collection to easily access and use these endpoints. [click here](https://github.com/kby-ai/FaceLivenessDetection-Docker/blob/main/postman/kby-ai-live.postman_collection.json) +## About SDK - - +### 1. Initializing an SDK +- 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')) + ``` + +- 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. + +- 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. + +### 2. Enum and Structure + - 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 | + +- FaceBox + + This structure represents the output of the face detection function. + + | 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[] | landmarks_68 | + + > 68 points facial landmark + + + +### 3. APIs + - Face Detection + + 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 landmarks. + + The function can be used as follows: + + ``` + faceBoxes = (FaceBox * maxFaceCount)() + faceCount = faceDetection(image_np, image_np.shape[1], image_np.shape[0], 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. + +### 4. Thresholds + The default thresholds are as the following below: + https://github.com/kby-ai/FaceLivenessDetection-Docker/blob/6aafd08dba5093600008ec66df39f362e53f9bb8/app.py#L17-L29