https://github.com/kby-ai/faceattribute-android
This is a demo project that incorporates 3D passive face liveness detection, face recognition, face capture, and analysis of face attributes including age, gender, face quality, face occlusion, eye closure, and mouth opening.
https://github.com/kby-ai/faceattribute-android
age-gender age-gender-estimation anti-spoofing ekyc eye-closeness eye-closure face-attributes face-capture face-liveness-detection face-occlusion face-quality face-recognition kyc liveness liveness-detection mask-detection mouth-openness verification
Last synced: 5 days ago
JSON representation
This is a demo project that incorporates 3D passive face liveness detection, face recognition, face capture, and analysis of face attributes including age, gender, face quality, face occlusion, eye closure, and mouth opening.
- Host: GitHub
- URL: https://github.com/kby-ai/faceattribute-android
- Owner: kby-ai
- Created: 2023-05-01T19:25:52.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-31T02:22:12.000Z (2 months ago)
- Last Synced: 2025-07-31T05:28:36.089Z (2 months ago)
- Topics: age-gender, age-gender-estimation, anti-spoofing, ekyc, eye-closeness, eye-closure, face-attributes, face-capture, face-liveness-detection, face-occlusion, face-quality, face-recognition, kyc, liveness, liveness-detection, mask-detection, mouth-openness, verification
- Language: Java
- Homepage: https://kby-ai.com/face-recognition-sdk/
- Size: 100 MB
- Stars: 20
- Watchers: 7
- Forks: 14
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
### Our facial recognition algorithm is globally top-ranked by NIST in the FRVT 1:1 leaderboards. 
[Latest NIST FRVT evaluation report 2024-12-20](https://pages.nist.gov/frvt/html/frvt11.html)
#### 🆔 ID Document Liveness Detection - Linux - [Here](https://web.kby-ai.com)
#### 📚 Product & Resources - [Here](https://github.com/kby-ai/Product)
#### 🛟 Help Center - [Here](https://docs.kby-ai.com)
#### 💼 KYC Verification Demo - [Here](https://github.com/kby-ai/KYC-Verification-Demo-Android)
#### 🙋♀️ Docker Hub - [Here](https://hub.docker.com/u/kbyai)
# FaceAttribute-Android
## Overview
This repository integrates several `facial recognition` technologies, including `3D passive face liveness detection`, `face recognition`, `automatic face capture`, and analysis of various `face attributes` such as `age`, `gender`, `face quality`, `facial occlusion`, `eye closure`, and `mouth opening`.
The system utilizes `face liveness detection` technology to generate a real-time liveness score based on a single image captured by the camera.
Additionally, the demo offers `Face Recognition` capabilities, enabling enrollment from a gallery and real-time identification of faces captured by the camera.
The repository also features an automatic face capture function that verifies various `facial attributes`, such as `face quality`, `facial orientation` (`yaw`, `roll`, `pitch`), `facial occlusion` (e.g., mask, sunglass, hand over face), `eye closure`, `mouth opening`, and the position of the face within the `region of interest` (`ROI`).
Moreover, the repository can compute scores for different face attributes from a gallery image, including `liveness`, `face orientation` (`yaw`, `roll`, `pitch`), `face quality`, `luminance of the face`, `facial occlusion`, `eye closure`, `mouth opening`, `age`, and `gender`.
> In this repository, we integrated `KBY-AI`'s `Premium Face Mobile SDK` into `Android` native platform.
### ◾FaceSDK(Mobile) Details
| Basic | Standard | 🔽 Premium |
|------------------|------------------|------------------|
| Face Detection | Face Detection | Face Detection |
| Face Liveness Detection | Face Liveness Detection | Face Liveness Detection |
| Pose Estimation | Pose Estimation | Pose Estimation |
| | Face Recognition | Face Recognition |
| | | 68 points Face Landmark Detection |
| | | Face Quality Calculation |
| | | Face Occlusion Detection |
| | | Eye Closure Detection |
| | | Age, Gender Estimation |
### ◾FaceSDK(Mobile) Product List
| No. | Repository | SDK Details |
|------------------|-----------------------------------------------------------------------------------------------------------|------------------|
| 1 | [Face Liveness Detection - Android](https://github.com/kby-ai/FaceLivenessDetection-Android) | Basic SDK |
| 2 | [Face Liveness Detection - iOS](https://github.com/kby-ai/FaceLivenessDetection-iOS) | Basic SDK |
| 3 | [Face Recognition + Face Liveness Detection - Android](https://github.com/kby-ai/FaceRecognition-Android) | Standard SDK |
| 4 | [Face Recognition + Face Liveness Detection - iOS](https://github.com/kby-ai/FaceRecognition-iOS) | Standard SDK |
| 5 | [Face Recognition + Face Liveness Detection - Flutter](https://github.com/kby-ai/FaceRecognition-Flutter) | Standard SDK |
| 6 | [Face Recognition + Face Liveness Detection - Ionic-Cordova](https://github.com/kby-ai/FaceRececogniion-Ionic-Cordova) | Standard SDK |
| 7 | [Face Recognition + Face Liveness Detection - React-Native](https://github.com/kby-ai/FaceRecognition-React-Native) | Standard SDK |
| ➡️ | [Face Attribute - Android](https://github.com/kby-ai/FaceAttribute-Android) | Premium SDK |
| 9 | [Face Attribute - iOS](https://github.com/kby-ai/FaceAttribute-iOS) | Premium SDK |
| 10 | [Face Attribute - Flutter](https://github.com/kby-ai/FaceAttribute-Flutter) | Premium SDK |
> To get `Face SDK(server)`, please visit products [here](https://github.com/kby-ai/Product).
## Try the APK
### Google Play
## Performance Video
You can visit our YouTube video [here](https://www.youtube.com/watch?v=-WiAethTacc) to see how well our demo app works.
[](https://www.youtube.com/watch?v=-WiAethTacc)
## Screenshots
## SDK License
The face recognition project relies on `KBY-AI`'s SDK, which requires a license for each `application ID`.
- The code below shows how to use the license: https://github.com/kby-ai/FaceAttribute-Android/blob/db2f1134af4ce947c318d5213f1b1e703c400dbf/app/src/main/java/com/kbyai/faceattribute/MainActivity.kt#L33-L43
- To request a license, please contact us:
🧙`Email:` contact@kby-ai.com
🧙`Telegram:` [@kbyaisupport](https://t.me/kbyaisupport)
🧙`WhatsApp:` [+19092802609](https://wa.me/+19092802609)
🧙`Discord:` [KBY-AI](https://discord.gg/CgHtWQ3k9T)
🧙`Teams:` [KBY-AI](https://teams.live.com/l/invite/FBAYGB1-IlXkuQM3AY)
## About SDK
### 1. Set up
- Copy the SDK (`libfacesdk` folder) to the `root` folder in your project.
- Add SDK to the project in `settings.gradle`.
```bash
include ':libfacesdk'
```
- Add dependency to your `build.gradle`.
```bash
implementation project(path: ':libfacesdk')
```
### 2. Initializing an SDK
- Step One
To begin, you need to activate the `SDK` using the license that you have received.
```kotlin
FaceSDK.setActivation("...")
```
If activation is successful, the return value will be `SDK_SUCCESS`. Otherwise, an error value will be returned.
- Step Two
After activation, call the `SDK`'s initialization function.
```kotlin
FaceSDK.init(getAssets());
```
If initialization is successful, the return value will be `SDK_SUCCESS`. Otherwise, an error value will be returned.
### 3. SDK Classes
- FaceBox
This class represents the output of the face detection function and can be utilized in template creation functions.
| 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 |
> 68 points facial landmark
- 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 |
### 4. SDK APIs
#### - Face Detection
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.
#### - Create Templates
The `FaceSDK` 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 image captured.
```kotlin
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.
#### - Calculation similiarity
The `similarityCalculation` function takes a byte array of two `template`s as a parameter.
```kotlin
float similarity = FaceSDK.similarityCalucation(templates1, templates1);
```
It returns the similarity value between the two `template`s, which can be used to determine the level of likeness between the two individuals.
#### - Yuv to Bitmap
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:
```kotlin
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:
```kotlin
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
```