# Premium SDK - Android ## Features * [x] Face Detection * [x] Face Liveness Detection * [x] Face Recognition * [x] Pose Estimation * [x] 68 points Face Landmark Detection * [x] Face Quality Calculation * [x] Face Occlusion Detection * [x] Eye Closure Detection * [x] Age, Gender Estimation * [x] Fully-Offline Works and On-Premise ## License We offer `lifetime license(perpetual license)` tied to each `application ID` for `Android` `SDK`s. The license is available with a `one-time payment`—meaning once you purchase it, you can use our `SDK` indefinitely without any recurring fees. To request a license, please contact us: > **Email:** > > **Telegram:** @kbyaisupport > > **WhatsApp:** +19092802609 ## System Requirements * **CPU:** 2 cores or more * **RAM:** 150MB or more * **OS:** Android 4.4 or later * **Architecture:** arm64-v8a, armeabi-v7a ## Setup 1. Copy the SDK (`libfacesdk` folder) to the `root` folder of your project. 2. Add SDK to the project in `settings.gradle` ```gradle include ':libfacesdk' ``` 3. Add dependency to your `build.gradle` ```gradle implementation project(path: ':libfacesdk') ``` ## Initializing SDK 1. Step one * To begin, you need to activate the SDK using the license that you have received. ```java FaceSDK.setActivation("..."); ``` * If activation is successful, the return value will be `SDK_SUCCESS`. Otherwise, an error value will be returned. 2. Step Two * After activation, call the SDK's initialization function. ```java FaceSDK.init(getAssets()); ``` * If initialization is successful, the return value will be `SDK_SUCCESS`. Otherwise, an error value will be returned. ## Enums and Classes ### 1. SDK\_ERROR This enumeration represents the return value of the `init` 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 | | Liveness score (0 \~ 1) | float | liveness | | Face quality (0 \~ 1) | float | face\_quality | | Face luminance (0 \~ 255) | float | face\_luminance | | Face occlusion (0 \~ 1) | float | face\_occlusion | | Eye closure (0 \~ 1) | float | left\_eye\_closed, right\_eye\_closed | | Mouth opening (0 \~ 1) | float | mouth\_opened | | Age, Gender | int | age, gender | | 68 points facial landmark | float\[] | landmarks\_68 |

### 3. FaceDetectionParam This class serves as the input parameter for face detection, enabling various processing functionalities such as `face liveness detection`, `eye closure checking`, `facial occlusion checking`, `mouth opening checking`, and `age and gender estimation`. | Feature | Type | Name | | -------------------- | ------- | ---------------------- | | Check liveness | boolean | check\_liveness | | Check eye closure | boolean | check\_eye\_closeness | | Check face occlusion | boolean | check\_face\_occlusion | | Check mouth opening | boolean | check\_mouth\_opened | | Estimate age, gender | boolean | estimate\_age\_gender | ## APIs ### 1. setActivation To begin, you need to activate the SDK using the license that you have received. ```kotlin var ret = FaceSDK.setActivation("...") ``` If activation is successful, the return value will be `SDK_SUCCESS`. Otherwise, an error value will be returned. ### 2. init After activation, call the SDK's initialization function. ```kotlin ret = FaceSDK.init(assets) ``` If initialization is successful, the return value will be `SDK_SUCCESS`. Otherwise, an error value will be returned. ### 3. faceDetection The Face SDK provides a unified function for detecting faces, enabling multiple functionalities such as `liveness detection`, `face orientation (yaw, roll, pitch)`, `face quality`, `facial occlusion`, `eye closure`, `mouth opening`, `age`, `gender`, and `facial landmarks`. The function can be used as follows: ```kotlin FaceSDK.faceDetection(bitmap, param) ``` This function requires two parameters: a `Bitmap` object and a `FaceDetectionParam` object that enables various processing functionalities. The function returns a list of `FaceBox` objects. ### 4. templateExtraction The SDK provides a function that can generate a `template` from a `bitmap` image. This `template` can then be used to verify the identity of the individual captured in the image. ```java byte[] templates = FaceSDK.templateExtraction(bitmap, faceBox); ``` The SDK's `template extraction` function takes two parameters: a `bitmap` object and an object of `FaceBox`. The function returns a byte array, which contains the template that can be used for person verification. ### 5. similarityCalucation The `similarityCalculation` function takes a byte array of two templates as a parameter. ```java float similarity = FaceSDK.similarityCalucation(templates1, templates1); ``` It returns the similarity value between the two templates, which can be used to determine the degree of similarity between the two individuals. ### 6. yuv2Bitmap The SDK provides a function called `yuv2Bitmap`, which converts a `yuv` frame to a `bitmap`. Since camera frames are typically in `yuv` format, this function is necessary to convert them to `bitmap`. The usage of this function is as follows: ```java Bitmap bitmap = FaceSDK.yuv2Bitmap(nv21, image.getWidth(), image.getHeight(), 7); ``` The first parameter is an `nv21` byte array containing the `yuv` data. The second parameter is the width of the `yuv` frame, and the third parameter is its height. The fourth parameter is the `conversion mode`, which is determined by the camera orientation. To determine the appropriate `conversion mode`, the following method can be used: ``` 1 2 3 4 5 6 7 8 888888 888888 88 88 8888888888 88 88 8888888888 88 88 88 88 88 88 88 88 88 88 88 88 8888 8888 8888 8888 88 8888888888 8888888888 88 88 88 88 88 88 88 888888 888888 ``` ## Default Thresholds ```kotlin val livenessThreshold = 0.7 val identifyThreshold = 0.8 val yawThreshold = 10.0 val rollThreshold = 10.0 val pitchThreshold = 10.0 val occlusionThreshold = 0.5 val eyeCloseThreshold = 0.8 val mouthOpeningThreshold = 0.5 ``` * If the liveness score exceeds `0.7`, the face is a `real face`. * If the similarity between two faces is higher than `0.8`, the face matching is successful. * 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.5`, the face is occluded. * If the eye close value is higher than `0.8`, it indicates that the eyes are closed. * If the mouth opening value is higher than `0.5`, it indicates that the mouth is open.