Face recognition Demo APP and SDK packages are available as below. You can enable your software with face recognition by the SDK.
As a start, you can first install the demo app, watch how face recognition works, and, decide your app design. ( Please note the face recognition will only be functioning with SUNMI license, you can have a 3-months free license from SUNMI sales). Also, you can request APP source code to ease your application development.
Face Recognition DemoAPP v1.2.0 (61.6M): Download
Face Recognition SDK package v1.2.0 (35.5M): Download
Note:
1) SUNMI face recognition offline SDK supports Android7 and above system environments, and is compatible with SUNMI devices such as K1, K2, D2, D2mini, and T2. For new device adaptability, please consult sales and related technical personnel.
2) liveness body detection function: including RGB liveness body and 3D liveness body functions, among which 3D liveness body function needs to be equipped with a 3D binocular camera.
1. Overview
SUNMI face recognition SDK is a face technology development kit for Android devices. This SDK development package contains functions such as face detection, face recognition, person-to-card comparison and face attribute prediction, and is released in the form of aar package and models. This document introduces the SDK usage instructions, data structure and interface definition, which is convenient for developers to refer to when calling the SDK interface.
1.1. Scope of document usage
This face recognition interface document is mainly suitable for reference reading by relevant personnel of face recognition developmen
1.2. Function list
The SUNMI face recognition SDK mainly provides the following functions:
Module | Features |
Face Detection | Detect the position where the face appears in the picture, and mark the five key points of the face |
Face recognition | Match the current face with the face in the database to determine the current face identity information |
Person-to-card comparison | Collect photos on the ID card and determine whether the current face matches the face on the ID card |
Face attribute prediction | Predict the person’s gender and age according to the face which appears in the picture |
Liveness detection | Judge whether the face which appears in the picture comes from a real person or not, and the result will be more accurate when 3D camera is used. |
1.3. Description of the development kit SDK
The SUNMI face recognition SDK includes the sunmi_facelib.aar file and the models folder. The models folder contains a configuration file and six model files:
File/folder name | Description |
sunmi_facelib.aar | aar of SDK lib library related code |
models | Configuration file: config.json Model file: face_graph.json, face_param.params, detect_graph.json, detect_param.params, liveness_graph.json, liveness_param.params, depth_detector.yml, attribute_graph.json and attribute_param.params |
Note: There is only one instance of the SUNMI face recognition SDK, and the thread is not reentrant. It can only be called by one thread at the same time, and cannot be called by multiple threads at the same time.
2. Environmental Information
System environment | platform | Compiler Environment |
Android7 and above | arm32, arm64 | NDK |
3. Java SDK instructions
3.1. Get device hardware fingerprint
The authorization of SUNMI face recognition SDK needs to bind hardware fingerprint information and Android system information. Before the first use, the developer can obtain the hardware fingerprint information through the following code and provide it to SUNMI. SUNMI will verify and provide the license authorization file of the face recognition SDK. This file is generally stored in the same level directory as the model file for verification authorization in 3.6. It can be stored in a path on the SD card or in the APP file path. Make sure to upload normally and be replaced.
Note:
1)The face recognition demo provided by SUNMI reads the license authorization file from the sdcard root directory by default.
2)Make sure that the wifi switch is turned on.
String fingerprint = SunmiFaceSDK.getDeviceFingerprint(context);
3.2. Import SDK package
Just import the SDK aar package in the Android Studio project.
3.3. Store model files
The model files (.json and .params files) can be stored in a certain path of the SD card or in the APP file path. Make sure that the path where the model is located can be accessed.
3.4. Configure the config.json file
Use the config.json file in the model package as a template, or create a config.json file by yourself and copy the following code. Modify according to the actual path stored in the 9 files face_graph.json, face_param.params, detect_graph.json, detect_param.params, liveness_graph.json, liveness_param.params depth_detector.yml, attribute_graph.json and attribute_param.params in 3.3. The SDK needs to be initialized by reading this config.json configuration file
{
// Face recognition library file, this file is in SDK JNILibs, generally do not need to be modified
"face_lib_path": "libface_lib.so",
// Face recognition library network description file, an absolute path is required
"face_graph_path": "/storage/emulated/0/faceTest/face_graph.json",
// Face recognition library network parameter file, an absolute path is required
"face_param_path": "/storage/emulated/0/faceTest/face_param.params",
// Face detection library file, this file is in SDK JNILibs, generally do not need to be modified
"detect_lib_path": "libdetect_lib.so",
// Face detection library network description file, an absolute path is required
"detect_graph_path": "/storage/emulated/0/faceTest/detect_graph.json",
// Face detection library network parameter file, an absolute path is required
"detect_param_path": "/storage/emulated/0/faceTest/detect_param.params",
// 2D Liveness detection library file, this file is in SDK JNILibs, generally do not need to be modified
"liveness_lib_path": "libliveness_lib.so",
// The network description file of the 2D liveness detection library, an absolute path is required
"liveness_graph_path": "/storage/emulated/0/faceTest/liveness_graph.json",
// The network parameter file of the 2D liveness detection library, an absolute path is required
"liveness_param_path": "/storage/emulated/0/faceTest/liveness_param.params",
// The path of the face database, an absolute path is required
"face_db_file": "/storage/emulated/0/faceTest/sunmi_face.db",
// 3D liveness detection model, an absolute path is required
"depth_detector": "/storage/emulated/0/faceTest/depth_detector.yml"
// Face attribute prediction library file, this file is in SDK JNILibs, generally do not need to be modified
"attr_lib_path": "libattribute_lib.so",
// The network description file of the face attribute prediction library, an absolute path is required
"attr_graph_path": "/storage/emulated/0/faceTest/attribute_graph.json",
// The network parameter file of the face attribute prediction library, an absolute path is required
"attr_param_path": "/storage/emulated/0/faceTest/attribute_param.params",
}
3.5. Initialize SDK
The following is an example of SDK calling the init interface to perform initialization. The init interface parameter is the path of the config.json file in 3.4.
String confPath = Environment.getExternalStorageDirectory() +
"/faceTest/config.json";
int code = SunmiFaceSDK.init(confPath);
3.6. Verify authorization file
Use code similar to the following to read the content of the authorization file into the Java String, and then verify it through the verifyLicense interface. If the verification is passed, other SDK interfaces can be called normally. If the verification fails, calling other SDK interfaces will return an authorization error code. The error code is “10”, it means the authorization file is invalid; the error code is “11”, it means the authorization file is out of date. If there is any authorization problem, please contact SUNMI to solve it.
Note: Make sure that the wifi switch is turned on
String license = readToString(Environment.getExternalStorageDirectory() +
"/faceTest/license_valid.txt");
int code = SunmiFaceSDK.verifyLicense(context, license); // context is Android Contex
3.7. Configure SDK
SUNMI face recognition SDK parameters can be dynamically configured. It is recommended to get the current parameters through getConfig first, and then use the setConfig interface to set the parameters after modifying the parameters as needed. The sample code is as follows:
SunmiFaceConfigParam param = new SunmiFaceConfigParam();
SunmiFaceSDK.getConfig(param);
param.setDistanceThreshold(0.9f); //When SDK is used for payment scenario, the //recommended value is 0.9, and when it is used for person-to-card comparison, 1.1 may //be the best threshold. The smaller the range, the stricter the face recognition
param.setYawThreshold(50.0f);//Face pose threshold, set a smaller face pose threshold. //If the threshold is smaller, the face pose requirements will be stricter to ensure that the //face pose is relatively positive for recognition
param.setPitchThreshold(50.0f);
param.setRollThreshold(50.0f);
param.setMinFaceSize(60);//Minimum face detection size. Larger and clearer face //recognition is more accurate
param.setImageQualityThreshold(10);//If the threshold is higher, the sharpness of the //face will be better, so the more accurate the face recognition
param.setMinLuminance(10);//Minimum light
param.setMaxLuminance(180);//Maximum light
param.setLivenessOn(true);//Enable face liveness detection
param.setThreadNum(1); //Use a cpu core to perform face detection and face //recognition
int code = SunmiFaceSDK.setConfig(param);
3.8. Extract facial features
Extraction steps:
1.Bitmap image obtained: The user obtains the bitmap from the camera and sends it to the SDK according to requirements.
2. The size of the incoming image: The aspect ratio of the best input image for face SDK detection is 1:1. If the aspect ratio is too large, the detection performance may decrease slightly.
3. Image format processing: Convert the acquired Bitmap image to BGR byte buffer format. (Please refer to the following sample code)
4. Interface call: Pass in BGR byte buffer, and create SunmiFaceImage through the SunmiFaceImage constructor. Then pass the SunmiFaceImage image data through the getImageFeatures interface to get the SunmiFaceImageFeatures face result.
5. Multi-face recognition logic: If there are multiple faces, SunmiFaceFeature is arranged in SunmiFaceImageFeatures according to the confidence score from high to low.
6. Face database record: faceFeature2FaceDBRecord converts the obtained face features into face database records, and sets the relevant ID and name.
7. Resource release: SunmiFaceImageFeatures dynamically allocates memory space in the SDK, and the interface needs to be called to release resources after use.
The sample code is as follows:
public static byte[] getPixelsBGR(Bitmap image) {
// Calculate how many bytes the picture has
int bytes = image.getByteCount();
ByteBuffer buffer = ByteBuffer.allocate(bytes); // Create a new buffer
image.copyPixelsToBuffer(buffer); // Move byte data to buffer
byte[] temp = buffer.array(); // Get the underlying array containing data
byte[] pixels = new byte[(temp.length / 4) * 3]; // allocate space to BGR
// Reorganize the pixels
for (int i = 0; i ‹temp.length / 4; i++) {
pixels[i * 3] = temp[i * 4 + 2]; //B
pixels[i * 3 + 1] = temp[i * 4 + 1]; //G
pixels[i * 3 + 2] = temp[i * 4]; //R
}
return pixels;
}
private void addFeature(String name) {
if (bitmap == null) {
Toast.makeText(context, "Please take a picture first", Toast.LENGTH_SHORT).show();
return;
}
byte[] srcData = FileUtils.getPixelsBGR(bitmap);
SunmiFaceImage image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 1);
SunmiFaceImageFeatures features = new SunmiFaceImageFeatures();
SunmiFaceSDK.getImageFeatures(image, features);
SunmiFaceFeature feature_ary = features.getFeatures();
Log.e("ma", "face info: "+ features.getFeaturesCount());
if (features.getFeaturesCount() == 0) {
showId("No face detected, please take a photo again!");
return;
}
SunmiFaceFeature feature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(feature_ary, 0);
SunmiFaceDBRecord record = SunmiFaceSDK.faceFeature2FaceDBRecord(feature);
record.setId(name);
record.setName(name);
SunmiFaceSDK.addDBRecord(record);
SunmiFaceSDK.releaseImageFeatures(features);
Log.e("face", "Successfully collected" + etName.getText().toString());
}
3.9. Add facial features to the face database
SunmiFaceDBRecord contains three parameters: img_id_, id and name, img_id_ does not need to be set, id and name need to be set by the caller:
- img_id_ does not need to be set. After calling addDBRecord to successfully add the record to the face database, img_id_ in SunmiFaceDBRecord will be automatically set as the unique id representing this picture in the face database. img_id_ can be understood as the unique name of the input image, and the SDK guarantees that the returned img_id is not repeated. The user can use img_id as the file name to save the captured face photos. According to this img_id, deleteDBRecord can be called to delete this record.
- id is the unique id of the person whose face is entered. The SDK considers the flexibility of the developer’s call and does not restrict its uniqueness. Under normal circumstances, it is recommended that the caller must ensure the uniqueness of the id. The id can be understood as the ID card number, the cafeteria card number, and the membership number, etc. that are generally not renumbered.
- The name can be non-unique. Two people with the same name are allowed, and each person can enter multiple faces.
Example:
Records in the database:
User A, id is 0001, name is Zhang San, picture 1, picture 2;
User B, id is 0002, name is also Zhang San, picture 3, picture 4, picture 5.
Users A and B have the same name and have multiple pictures, and the facial features extracted from each picture are stored.
Note: It is recommended to store the recognized face pictures during the face recognition process. It is recommended to use the getImgId() in the SunmiFaceDBRecord returned by the addDBRecord interface to name the picture, so that the picture and the facial features in the face database can be bound to facilitate related operations and comparisons on the face database in the future.
3.10. Get key points of face
Get the face key point array through getLandmark_, and get the information of each key point in the array. The sample code is as follows:
SunmiFaceFeature feature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(feature_ary, 0);
SunmiFaceLmk lmk_ary = feature.getLandmark();
for(int i = 0; i ‹SunmiFaceLibConstants.SUNMI_FACE_LANDMARK_LEN; i++) {
SunmiFaceLmk lmk = SunmiFaceLib.SunmiFaceLmkArrayGetItem(lmk_ary, i);
}
3.11. Search face database
Call searchDB to execute the face database search function to find the most similar face. If the SDK judges that the face distance is less than the threshold, matched is set to true, otherwise it is false. The sample code is as follows:
SunmiFaceDBRecord record = SunmiFaceSDK.faceFeature2FaceDBRecord(feature);
SunmiFaceDBIdInfo info = new SunmiFaceDBIdInfo();
SunmiFaceSDK.searchDB(record, info);
if (info.getIsMatched()) {
Log.e("ma", "Found");
}
else {
Log.e("ma", "Not Found");
}
3.12. Face 1:1 comparison
Extract the facial features of the two pictures to be compared, and obtain two facial features feature1 and feature2 of the type SunmiFaceFeature. Get the comparison result after calling compare1v1 interface. getIsMatched() gets the comparison result, getDistance() gets the distance measurement between two faces.
SunmiFaceCompareResult result;
int code = SunmiFaceSDK.compare1v1(feature1, feature2, result)
boolean isMatched = result.getIsMatched()
float distance = result.getDistance();
3.13. Liveness detection
2D liveness body detection uses UVC camera to realize 2D liveness body detection function, which is suitable for situations without 3D camera.
3D liveness body detection uses ORBBEC 3D structured light camera to realize 3D liveness body detection function, and its prediction effect is greatly improved compared with 2D liveness body detection. The depth map depth is 16bit data, which represents the distance between the object and the camera in millimeters. Need to pay attention to the following points:
- To use liveness detection, the BGR image resolution is required to be 480×640, and the resolution of the 3D liveness detection depth map is shown in the table below.
- 3D liveness body detection needs to ensure that the BGR image and the depth image are corresponding in time.
- There is a certain position deviation between the color map and the depth map. Taking the face position detected by the color map as a reference, the deviation of the depth map in the x direction and the y direction is shown in the following table.
- In liveness detection, there is a certain probability that a real person is judged to be non-living. Therefore, it is recommended that the judgment of non-living body needs to be performed about 3 times to confirm. The probability of a non-living body being judged as a real person is less than 1%.
Device model | 3D camera model | Depth map resolution | X-direction offset of depth map | Y-direction offset of depth map | Whether to rotate |
K1 | Pro A | 640*480 | 28 | -20 | no |
K2 | D2plus | 400*640 | 75 | -15 | yes |
T2 | none | none | none | none | no |
The steps for using liveness detection are as follows:
1. Turn on liveness detection and configure the threshold.
SunmiFaceConfigParam param = new SunmiFaceConfigParam();
SunmiFaceSDK.getConfig(param);
param.setLivenessOn(true);
param.setDepthLivenessThreshold(0.5f); // The recommended threshold for both 2D and 3D is around 0.5
param.setDepthXOffset(75); // 3D sets the offset of the depth map in the x direction according to the device model
param.setDepthYOffset(-15); // 3D sets the offset of the depth map in the y direction according to the device model
ret = SunmiFaceSDK.setConfig(param);
2. Construct SunmiFaceImage and pass in BGR image and depth image at the same time.
SunmiFaceImage image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), depth, depth_height, depth_width, 1); // 3D liveness detection
SunmiFaceImage image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 1); // 2D liveness detection
Note: When the camera needs to be rotated, the two images need to be rotated by 90 degrees before the BGR and depth images are imported. The code for BGR image rotation is as follows:
public static Bitmap rotateBitmap(Bitmap origin, float alpha) {
if (origin == null) {
return null;
}
int width = origin.getWidth();
int height = origin.getHeight();
Matrix matrix = new Matrix();
matrix.setRotate(alpha);
// Rotate around the place
Bitmap newBM = Bitmap.createBitmap(origin, 0, 0, width, height, matrix, false);
if (newBM.equals(origin)) {
return newBM;
}
return newBM;
}
The depth map rotation code is as follows:
public static byte [] rotateDepthImage(byte[] depthByte, int height, int width){
if(depthByte == null){return null;}
int depthLen = height * width * 2;
byte [] newDepth = new byte [depthLen];
for (int i = 0; i‹=width-1; i++){
for(int j = 0; j‹=height-1; j++){
newDepth[2*(i*height+j)] = depthByte[2*((height-1-j)*width+i)];
newDepth[2*(i*height+j)+1] = depthByte[2*((height-1-j)*width+i)+1];
}
}
return newDepth;
}
3. View the result of liveness body judgment, if the code is FACE_CODE_OK, it is judged as liveness body. If the code is FACE_CODE_NOT_LIVENESS, it is judged as non-living.
int code = SunmiFaceSDK.getImageFeatures(image, features);
3.14. Get face attributes
The face attribute first needs to obtain the face feature faceFeature, and then obtain the age and gender attributes according to the face feature. The main sample code is as follows:
SunmiFaceFeature faceFeature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(features.getFeatures(), 0);
SunmiFaceAge ageInfo = faceFeature.getAge();
int age = ageInfo.getClassification();
float ageScore = ageInfo.getScore();
SunmiFaceGender genderInfo = faceFeature.getGender();
int gender = genderInfo.getClassification();
float genderScore = genderInfo.getScore();
3.15. Executive function selection
The function selection is to facilitate developers to select only the required SDK functions in actual development, reducing the waste of computing resources and time. This function can be controlled by the predict_mode_ member defined in SunmiFaceImage.
For example, in 3.8 and 3.14, the functions of SUNMI Face Recognition SDK for extracting facial features and acquiring facial attributes are introduced respectively. In fact, the SDK completes face detection, face feature extraction, and face attribute recognition at the same time in the code provided in these two sections. If the developer only needs to use one of them, performing the three functions at the same time will greatly waste computing resources and time. Therefore, you can use the function selection to control.The main sample code is as follows:
image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 1); // Create SunmiFaceImage object based on bitmap
SunmiFaceImageFeatures features = new SunmiFaceImageFeatures(); //Create an empty SunmiFaceImageFeatures object
image.setPredictMode(SunmiFaceMode.PredictMode_Age); // Only make age predictions
image.setPredictMode(SunmiFaceMode.PredictMode_Feature); // Only make feature extraction
image.setPredictMode(SunmiFaceMode.PredictMode_Detect); // Only make face detection
image.setPredictMode(SunmiFaceMode.PredictMode_Age|SunmiFaceMode.PredictMode_Feature); // Perform facial feature extraction and age prediction
image.setPredictMode(SunmiFaceMode.PredictMode_Age|SunmiFaceMode.PredictMode_Feature|PredictMode_Gender); // Perform facial feature extraction, age and gender prediction, that is, perform all functions of the SDK, this line of code does not need to be written, the SDK default mode is to perform all functions
ret = SunmiFaceSDK.getImageFeatures(image, features); // Extract corresponding features according to the selected mode
4. Data Type Definition
4.1. Type aliases
Alias | Type | Description |
SunmiFaceStatus | int | Typedef, defined in the face_type.h file |
SunmiFaceHandle | void* | Typedef, defined in the face.h file |
4.2. Macro
The data type used by the interface is defined in the face_type.h header file. The main data are as follows:
Member | Value | Description |
SUNMI_FACE_FEATURE_LEN | 256 | Face feature vector length |
SUNMI_FACE_ID_LEN | 64 | id character length limit |
SUNMI_FACE_NAME_LEN | 64 | Face username length |
SUNMI_FACE_IMG_ID_LEN | 64 | ID length of face collection image |
SUNMI_FACE_LANDMARK_LEN | 5 | Number of face key points |
4.3. Enumerated Types
The data structure used by the interface is defined in the face_type.h header file.
4.3.1. SunmiFaceStatusCode
Explanation: SUNMI face recognition status code
Enumeration member | Status code | Description |
FACE_CODE_OK | 0 | correct |
FACE_CODE_UNINIT | 1 | SDK is not initialized |
FACE_CODE_EMPTY_IMAGE | 2 | Picture is empty |
FACE_CODE_NO_MODEL | 3 | No model file loaded |
FACE_CODE_CONFIG_ERROR | 4 | Configuration error |
FACE_CODE_BAD_ILLUMINATION | 5 | Poor light conditions |
FACE_CODE_POSE_ERROR | 6 | The face position does not meet the requirements |
FACE_CODE_SMALL_FACE_SIZE | 7 | Face size is too small |
FACE_CODE_LOW_IMAGE_QUALITY | 8 | Facial image is blurred |
FACE_CODE_NOT_LIVENESS | 9 | Non-living face image |
FACE_CODE_LICENSE_ERROR | 10 | Invalid authorization file |
FACE_CODE_LICENSE_EXPIRED | 11 | License expired |
FACE_CODE_IMAGE_ID_ERROR | 101 | Image id does not exist when deleting |
4.3.2. SunmiFaceGenderType
Explanation: gender type
Enumeration member | Value | Description |
FACE_ATTR_FEMALE | 0 | Gender: Female |
FACE_ATTR_MALE | 1 | Sex: Male |
4.3.3 SunmiFaceMode
Explanation: executive function selection
Enumeration member | Value | Description |
PredictMode_None | 0 | No functions are executed |
PredictMode_Detect | 1 | Execute face detection function. |
PredictMode_Feature | 3 | Execute face feature extraction function. |
PredictMode_Age | 5 | Execute age prediction function. |
PredictMode_Gender | 5 | Execute gender prediction function. |
4.4. Structure type
4.4.1. SunmiFaceRect
Explanation: face frame position
Member | Type | Description |
x1_ | float | The abscissa of the upper left corner of the face frame |
y1_ | float | The ordinate of the upper left corner of the face frame |
x2_ | float | The abscissa of the lower right corner of the face frame |
y2_ | float | The ordinate of the small right corner of the face frame |
score_ | float | Confidence |
4.4.2. SunmiFaceLmk
Explanation: face key point coordinates
Member | Type | Description |
x_ | float | Key point abscissa |
y_ | float | Key point ordinate |
4.4.3. SunmiFaceImage
Explanation: face recognition input image
Member | Type | Description |
buf_ | unsigned char * | Picture pixel byte address |
buf_len_ | int | Byte buffer length |
img_w_ | int | Image width |
img_h_ | int | Image height |
max_face_count_ | int | Maximum number of faces in a single image |
depth_buf_ | unsigned char * | Depth map data byte address |
depth_buf_len_ | int | Depth map data length |
depth_img_w_ | int | Depth map width |
depth_img_h_ | int | Depth map height |
predict_mode_ | int | The selection of functions which needs to execute |
4.4.4. SunmiFacePose
Explanation: pose
Member | Type | Description |
pitch_ | float | Pitch angle |
yaw_ | float | Yaw angle |
roll_ | float | Roll angle |
4.4.5. SunmiFaceAge
Explanation: age
Member | Type | Description |
classification_ | int | Age range (0-74 years old) |
score_ | float | Confidence |
4.4.6. SunmiFaceGender
Explanation: gender
Member | Type | Description |
classification_ | int | Gender classification (0: female; 1: male) |
score_ | float | Confidence |
4.4.7. SunmiFaceFeature
Explanation: single feature extraction output information structure
Member | Type | Description |
face_rect_ | SunmiFaceRect | Position of face rectangle |
liveness_score_ | float | Vital fraction |
feature_[SUNMI_FACE_FEATURE_LEN] | float | Face feature array |
landmark_[SUNMI_FACE_LANDMARK_LEN] | SunmiFaceLmk | key point |
pose_ | SunmiFacePose | Face pose |
age_ | SunmiFaceAge | age |
gender_ | SunmiFaceGender | gender |
4.4.8. SunmiFaceImageFeatures
Explanation: multiple feature extraction output information structure
Member | Type | Description |
features_ | SunmiFaceFeature * | Feature array |
features_count_ | int | Feature array length |
4.4.9. SunmiFaceConfigParam
Explanation: face configuration parameters
Member | Type | Description |
thread_num_ | int | The number of threads (cpu cores) used in the SDK face detection and face recognition calculations, 0 means all cpu cores are used |
distance_threshold_ | float | Face distance threshold |
yaw_threshold_ | float | Yaw angle threshold |
pitch_threshold_ | float | Pitch angle threshold |
roll_threshold_ | float | Roll angle threshold |
min_face_size | int | Minimum face size |
image_quality_threshold_ | float | Image quality threshold |
min_luminance_ | int | Minimum brightness |
max_luminance_ | int | Highest brightness |
rgb_liveness_threshold_ | float | RGB live detection threshold |
depth_liveness_threshold_ | float | 3D live detection threshold |
liveness_on_ | bool | Living body detection switch |
4.4.10. SunmiFaceCompareResult
Explanation: face matching result
Member | Type | Description |
is_matched_ | bool | If the distance is less than the face spacing threshold, it is true, otherwise it is false |
distance_ | float | Face distance |
4.4.11. SunmiFaceDBRecord
Explanation: face database record
Member | Type | Description |
id_[SUNMI_FACE_ID_LEN] | char | Face unique id |
name_[SUNMI_FACE_NAME_LEN] | char | username |
img_id_[SUNMI_FACE_IMG_ID_LEN] | char | The unique id of the face collection image |
feature_[SUNMI_FACE_FEATURE_LEN] | float | Facial features |
4.4.12. SunmiFaceDBIdInfo
Explanation: face database information
Member | Type | Description |
id_[SUNMI_FACE_ID_LEN] | char | Face unique id |
name_[SUNMI_FACE_NAME_LEN] | char | username |
is_matched_ | bool | If the distance is less than the face spacing threshold, it is true, otherwise it is false |
distance_ | float | Face distance |
5. C++ function interface definition
The definition of the external interface is in the face.h header file.
5.1. Function interface definition
5.1.1. SunmiFaceGetVersion
Function definition: SUNMI_FACE_API const char* SunmiFaceGetVersion();
Function: Get the Sunmi face recognition SDK version
Return value: SDK version string
5.1.2. SunmiFaceCreate
Function definition: SunmiFaceStatus SunmiFaceCreate(SunmiFaceHandle* handle);
Function: create a handle, the user needs to keep this handle until released
Variable | Type | Description |
handle | SunmiFaceHandle* | Output parameters, create face SDK handle |
Return value: SunmiFaceStatus
5.1.3. SunmiFaceInit
Function definition: SunmiFaceStatus SunmiFaceInit(SunmiFaceHandle handle, const std::string& config_file);
Function: Use the configuration file to initialize the SDK
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
config_file | const std::string& | Configuration file path |
Return value: SunmiFaceStatus
5.1.4. SunmiFaceGetErrorString
Function definition: const char* SunmiFaceGetErrorString(SunmiFaceStatus code);
Function: Get the error description string through SunmiFaceStatus
Variable | Type | Description |
code | SunmiFaceStatus | SunmiFaceStatus code |
Return value: error description string
5.1.5. SunmiFaceVerifyLicense
Function definition: SunmiFaceStatus SunmiFaceVerifyLicense(SunmiFaceHandle handle, const std::string& fingerprint, const std::string& license);
Function function: verify whether the device fingerprint and authorization file are legal
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
fingerprint | const std::string& | Device fingerprint string |
license | const std::string& | Authorization file string |
Return value: SunmiFaceStatus
5.1.6. SunmiFaceSetConfig
Function definition: SunmiFaceStatus SunmiFaceSetConfig(SunmiFaceHandle handle, const SunmiFaceConfigParam& config);
Function function: set configuration information
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
config | const SunmiFaceConfigParam& | Configuration parameter |
Return value: SunmiFaceStatus
5.1.7. SunmiFaceGetConfig
Function definition: SunmiFaceStatus SunmiFaceGetConfig(SunmiFaceHandle handle, SunmiFaceConfigParam& config);
Function: Get the current SDK parameters
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
config | SunmiFaceConfigParam& | Configuration parameter |
Return value: SunmiFaceStatus
5.1.8. SunmiFaceRelease
Function definition: SunmiFaceStatus SunmiFaceRelease(SunmiFaceHandle handle);
Function function: release handle
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
Return value: SunmiFaceStatus
5.1.9. SunmiFaceGetImageFeatures
Function definition: SunmiFaceStatus SunmiFaceGetImageFeatures(SunmiFaceHandle handle, SunmiFaceImage image, SunmiFaceImageFeatures *features);
Function function: get facial features from the image
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
image | SunmiFaceImage | Input picture structure |
features | SunmiFaceImageFeatures * | Return facial features |
Return value: SunmiFaceStatus
5.1.10. SunmiFaceCompare1v1
Function definition: SunmiFaceStatus SunmiFaceCompare1v1(SunmiFaceHandle handle, SunmiFaceFeature *feature1, SunmiFaceFeature *feature2, SunmiFaceCompareResult *compare_result);
Function: 1:1 face comparison
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
feature1 | SunmiFaceFeature * | Comparison feature 1 |
feature2 | SunmiFaceFeature * | Comparison feature 2 |
compare_result | SunmiFaceCompareResult * | Comparison result |
Return value: SunmiFaceStatus
5.1.11. SunmiFaceReleaseImageFeatures
Function definition: SunmiFaceStatus SunmiFaceReleaseImageFeatures(SunmiFaceImageFeatures *features);
Function: release facial features
Variable | Type | Description |
features | SunmiFaceImageFeatures * | Facial features |
Return value: SunmiFaceStatus
5.1.12. SunmiFaceInitDB
Function definition: SunmiFaceStatus SunmiFaceInitDB(SunmiFaceHandle handle, const char* db_name);
Function: Open the face database file, if it does not exist, create an empty face database. When the SDK is initialized, the face_db_file specified in config.json will be opened by default
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
db_name | const char* | Database file name |
Return value: SunmiFaceStatus
5.1.13. SunmiFaceAddDBRecord
Function definition: SunmiFaceStatus SunmiFaceAddDBRecord(SunmiFaceHandle handle, SunmiFaceDBRecord *record);
Function function: add a face record to the face database
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
record | SunmiFaceDBRecord *record | Face record |
Return value: SunmiFaceStatus
5.1.14. SunmiFaceSearchDB
Function definition: SunmiFaceStatus SunmiFaceSearchDB(SunmiFaceHandle handle, SunmiFaceDBRecord *record, SunmiFaceDBIdInfo *idInfo);
Function: 1:N face search
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
record | SunmiFaceDBRecord * | Face database record structure |
idInfo | SunmiFaceDBIdInfo * | search results |
Return value: SunmiFaceStatus
5.1.15. SunmiFaceDeleteDBRecord
Function definition: SunmiFaceStatus SunmiFaceDeleteDBRecord(SunmiFaceHandle handle, char *img_id);
Function: delete a face record in the face database according to the image id
Variable | Type | Description |
handle | SunmiFaceHandle | Output parameters, create face SDK handle |
img_id | char * | The unique ID of the face collection image in the face database |
Return value: SunmiFaceStatus
6. Java function interface definition
The definition of the external interface is in the SunmiFaceSDK.java file.
6.1. Interface class definition
Class name | Description |
SunmiFaceSDK | Face recognition interface class name definition |
6.2. Function interface definition
6.2.1. getVersion
Function definition: public static String getVersion()
Function: Get SUNMI face recognition SDK version number
Return value: SDK version string
6.2.2. Init
Function definition: public static int init(String configPath)
Function: Initialize SDK
Variable | Type | Description |
configPath | String | Configuration file path |
Return value: SunmiFaceStatusCode
6.2.3. verifyLicense
Function definition: public static int verifyLicense(Context context, String license)
Function function: verify license
Variable | Type | Description |
context | Context | Android context |
license | String | License string |
Return value: SunmiFaceStatusCode
6.2.4. getDeviceFingerprint
Function definition: public static String getDeviceFingerprint(Context context)
Function: Get fingerprint of Android device
Variable | Type | Description |
context | Context | android context |
Return value: device fingerprint string
6.2.5. getErrorString
Function definition: public static String getErrorString(int code)
Function function: get error string
Variable | Type | Description |
code | int | error code |
Return value: error description string
6.2.6. setConfig
Function definition: public static int setConfig(SunmiFaceConfigParam config)
Function function: set configuration
Variable | Type | Description |
config | SunmiFaceConfigParam | SDK configuration parameters |
Return value: SunmiFaceStatusCode
6.2.7. getConfig
Function definition: public static int getConfig(SunmiFaceConfigParam config)
Function: Get the current SDK configuration
Variable | Type | Description |
config | SunmiFaceConfigParam | SDK configuration parameters |
Return value: SunmiFaceStatusCode
6.2.8. getImageFeatures
Function definition: public static int getImageFeatures(SunmiFaceImage image, SunmiFaceImageFeatures features)
Function function: face detection and face feature extraction from images
Variable | Type | Description |
image | SunmiFaceImage | Input image |
features | SunmiFaceImageFeatures | Return facial features |
Return value: SunmiFaceStatusCode
6.2.9. compare1v1
Function definition: public int compare1v1(SunmiFaceFeature feature1, SunmiFaceFeature feature2, SunmiFaceCompareResult compare_result)
Function: 1:1 comparison of faces
Variable | Type | Description |
features1 | SunmiFaceFeature | Face feature 1 |
features2 | SunmiFaceFeature | Face feature 2 |
compare_result | SunmiFaceCompareResult | Comparison result |
Return value: SunmiFaceStatusCode
6.2.10. releaseImageFeatures
Function definition: public static int releaseImageFeatures(SunmiFaceImageFeatures features)
Function: release facial features
Variable | Type | Description |
features | SunmiFaceImageFeatures | Facial features |
Return value: SunmiFaceStatusCode
6.2.11. initDB
Function definition: public static int initDB(String db_name)
Function: Initialize the new face database
Variable | Type | Description |
db_name | String | Face database file name |
Return value: SunmiFaceStatusCode
6.2.12. faceFeature2FaceDBRecord
Function definition: public static SunmiFaceDBRecord faceFeature2FaceDBRecord(SunmiFaceFeature feature)
Function: Convert facial feature structure to adult face database record structure
Variable | Type | Description |
feature | SunmiFaceFeature | Facial features |
Return value: SunmiFaceDBRecord
6.2.13. addDBRecord
Function definition: public static int addDBRecord(SunmiFaceDBRecord record)
Function function: add a record to the face database, after the addition is successful, the ID of the picture in the face database can be obtained through img_id_, and it can be used for subsequent deletion
Variable | Type | Description |
record | SunmiFaceDBRecord | Face database record structure |
Return value: SunmiFaceStatusCode
6.2.14. searchDB
Function definition: public static int searchDB(SunmiFaceDBRecord record, SunmiFaceDBIdInfo idInfo)
Function: 1:N face comparison in the database
Variable | Type | Description |
record | SunmiFaceDBRecord | Face record to search |
idInfo | SunmiFaceDBIdInfo | search results |
Return value: SunmiFaceStatusCode
6.2.15. deleteDBRecord
Function definition: public static int deleteDBRecord(String img_id)
Function: delete a record in the face database according to the image id
Variable | Type | Description |
img_id | String | ID of the collected face image |
Return value: SunmiFaceStatusCode