Face Recognition Offline SDK Package

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:

ModuleFeatures
Face DetectionDetect the position where the face appears in the picture, and mark the five key points of the face
Face recognitionMatch the current face with the face in the database to determine the current face identity information
Person-to-card comparisonCollect photos on the ID card and determine whether the current face matches the face on the ID card
Face attribute predictionPredict the person’s gender and age according to the face which appears in the picture
Liveness detectionJudge 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 nameDescription
sunmi_facelib.aaraar of SDK lib library related code
modelsConfiguration 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 environmentplatformCompiler Environment
Android7 and abovearm32, arm64NDK

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:

  1. 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.
  2. 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.
  3. 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:

  1. 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.
  2. 3D liveness body detection needs to ensure that the BGR image and the depth image are corresponding in time.
  3. 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.
  4. 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 model3D camera modelDepth map resolutionX-direction offset of depth mapY-direction offset of depth mapWhether to rotate
K1Pro A640*48028-20no
K2D2plus400*64075-15yes
T2nonenonenonenoneno

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

AliasTypeDescription
SunmiFaceStatusintTypedef, defined in the face_type.h file
SunmiFaceHandlevoid*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:

MemberValueDescription
SUNMI_FACE_FEATURE_LEN256Face feature vector length
SUNMI_FACE_ID_LEN64id character length limit
SUNMI_FACE_NAME_LEN64Face username length
SUNMI_FACE_IMG_ID_LEN64ID length of face collection image
SUNMI_FACE_LANDMARK_LEN5Number 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 memberStatus codeDescription
FACE_CODE_OK0correct
FACE_CODE_UNINIT1SDK is not initialized
FACE_CODE_EMPTY_IMAGE2Picture is empty
FACE_CODE_NO_MODEL3No model file loaded
FACE_CODE_CONFIG_ERROR4Configuration error
FACE_CODE_BAD_ILLUMINATION5Poor light conditions
FACE_CODE_POSE_ERROR6The face position does not meet the requirements
FACE_CODE_SMALL_FACE_SIZE7Face size is too small
FACE_CODE_LOW_IMAGE_QUALITY8Facial image is blurred
FACE_CODE_NOT_LIVENESS9Non-living face image
FACE_CODE_LICENSE_ERROR10Invalid authorization file
FACE_CODE_LICENSE_EXPIRED11License expired
FACE_CODE_IMAGE_ID_ERROR101Image id does not exist when deleting

4.3.2. SunmiFaceGenderType

Explanation: gender type

Enumeration memberValueDescription
FACE_ATTR_FEMALE0Gender: Female
FACE_ATTR_MALE1Sex: Male

4.3.3 SunmiFaceMode

Explanation: executive function selection

Enumeration memberValueDescription
PredictMode_None0No functions are executed
PredictMode_Detect1Execute face detection function.
PredictMode_Feature3Execute face feature extraction function.
PredictMode_Age5Execute age prediction function.
PredictMode_Gender5Execute gender prediction function.

4.4. Structure type

4.4.1. SunmiFaceRect

Explanation: face frame position

MemberTypeDescription
x1_floatThe abscissa of the upper left corner of the face frame
y1_floatThe ordinate of the upper left corner of the face frame
x2_floatThe abscissa of the lower right corner of the face frame
y2_floatThe ordinate of the small right corner of the face frame
score_floatConfidence

4.4.2. SunmiFaceLmk

Explanation: face key point coordinates

MemberTypeDescription
x_floatKey point abscissa
y_floatKey point ordinate

4.4.3. SunmiFaceImage

Explanation: face recognition input image

MemberTypeDescription
buf_unsigned char *Picture pixel byte address
buf_len_intByte buffer length
img_w_intImage width
img_h_intImage height
max_face_count_intMaximum number of faces in a single image
depth_buf_unsigned char *Depth map data byte address
depth_buf_len_intDepth map data length
depth_img_w_intDepth map width
depth_img_h_intDepth map height
predict_mode_intThe selection of functions which needs to execute

4.4.4. SunmiFacePose

Explanation: pose

MemberTypeDescription
pitch_floatPitch angle
yaw_floatYaw angle
roll_floatRoll angle

4.4.5. SunmiFaceAge

Explanation: age

MemberTypeDescription
classification_intAge range (0-74 years old)
score_floatConfidence

4.4.6. SunmiFaceGender

Explanation: gender

MemberTypeDescription
classification_intGender classification (0: female; 1: male)
score_floatConfidence

4.4.7. SunmiFaceFeature

Explanation: single feature extraction output information structure

MemberTypeDescription
face_rect_SunmiFaceRectPosition of face rectangle
liveness_score_floatVital fraction
feature_[SUNMI_FACE_FEATURE_LEN]floatFace feature array
landmark_[SUNMI_FACE_LANDMARK_LEN]SunmiFaceLmkkey point
pose_SunmiFacePoseFace pose
age_SunmiFaceAge age
gender_SunmiFaceGender gender

4.4.8. SunmiFaceImageFeatures

Explanation: multiple feature extraction output information structure

MemberTypeDescription
features_SunmiFaceFeature *Feature array
features_count_intFeature array length

4.4.9. SunmiFaceConfigParam

Explanation: face configuration parameters

MemberTypeDescription
thread_num_intThe number of threads (cpu cores) used in the SDK face detection and face recognition calculations, 0 means all cpu cores are used
distance_threshold_floatFace distance threshold
yaw_threshold_floatYaw angle threshold
pitch_threshold_floatPitch angle threshold
roll_threshold_floatRoll angle threshold
min_face_sizeintMinimum face size
image_quality_threshold_floatImage quality threshold
min_luminance_intMinimum brightness
max_luminance_intHighest brightness
rgb_liveness_threshold_floatRGB live detection threshold
depth_liveness_threshold_float3D live detection threshold
liveness_on_boolLiving body detection switch

4.4.10. SunmiFaceCompareResult

Explanation: face matching result

MemberTypeDescription
is_matched_boolIf the distance is less than the face spacing threshold, it is true, otherwise it is false
distance_floatFace distance

4.4.11. SunmiFaceDBRecord

Explanation: face database record

MemberTypeDescription
id_[SUNMI_FACE_ID_LEN]charFace unique id
name_[SUNMI_FACE_NAME_LEN]charusername
img_id_[SUNMI_FACE_IMG_ID_LEN]charThe unique id of the face collection image
feature_[SUNMI_FACE_FEATURE_LEN]floatFacial features

4.4.12. SunmiFaceDBIdInfo

Explanation: face database information

MemberTypeDescription
id_[SUNMI_FACE_ID_LEN]charFace unique id
name_[SUNMI_FACE_NAME_LEN]charusername
is_matched_boolIf the distance is less than the face spacing threshold, it is true, otherwise it is false
distance_floatFace 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

VariableTypeDescription
handleSunmiFaceHandle*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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
config_fileconst 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

VariableTypeDescription
codeSunmiFaceStatusSunmiFaceStatus 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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
fingerprintconst std::string&Device fingerprint string
licenseconst 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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
configconst SunmiFaceConfigParam&Configuration parameter

Return value: SunmiFaceStatus

5.1.7. SunmiFaceGetConfig

Function definition: SunmiFaceStatus SunmiFaceGetConfig(SunmiFaceHandle handle, SunmiFaceConfigParam& config);

Function: Get the current SDK parameters

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
configSunmiFaceConfigParam&Configuration parameter

Return value: SunmiFaceStatus

5.1.8. SunmiFaceRelease

Function definition: SunmiFaceStatus SunmiFaceRelease(SunmiFaceHandle handle);

Function function: release handle

VariableTypeDescription
handleSunmiFaceHandleOutput 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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
imageSunmiFaceImageInput picture structure
featuresSunmiFaceImageFeatures *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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
feature1SunmiFaceFeature *Comparison feature 1
feature2SunmiFaceFeature *Comparison feature 2
compare_resultSunmiFaceCompareResult *Comparison result

Return value: SunmiFaceStatus

5.1.11. SunmiFaceReleaseImageFeatures

Function definition: SunmiFaceStatus SunmiFaceReleaseImageFeatures(SunmiFaceImageFeatures *features);

Function: release facial features

VariableTypeDescription
featuresSunmiFaceImageFeatures *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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
db_nameconst 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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
recordSunmiFaceDBRecord *recordFace record

Return value: SunmiFaceStatus

5.1.14. SunmiFaceSearchDB

Function definition: SunmiFaceStatus SunmiFaceSearchDB(SunmiFaceHandle handle, SunmiFaceDBRecord *record, SunmiFaceDBIdInfo *idInfo);

Function: 1:N face search

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
recordSunmiFaceDBRecord *Face database record structure
idInfoSunmiFaceDBIdInfo *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

VariableTypeDescription
handleSunmiFaceHandleOutput parameters, create face SDK handle
img_idchar *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 nameDescription
SunmiFaceSDKFace 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

VariableTypeDescription
configPathStringConfiguration file path

Return value: SunmiFaceStatusCode

6.2.3. verifyLicense

Function definition: public static int verifyLicense(Context context, String license)

Function function: verify license

VariableTypeDescription
contextContextAndroid context
licenseStringLicense string

Return value: SunmiFaceStatusCode

6.2.4. getDeviceFingerprint

Function definition: public static String getDeviceFingerprint(Context context)

Function: Get fingerprint of Android device

VariableTypeDescription
contextContextandroid context

Return value: device fingerprint string

6.2.5. getErrorString

Function definition: public static String getErrorString(int code)

Function function: get error string

VariableTypeDescription
codeinterror code

Return value: error description string

6.2.6. setConfig

Function definition: public static int setConfig(SunmiFaceConfigParam config)

Function function: set configuration

VariableTypeDescription
configSunmiFaceConfigParamSDK configuration parameters

Return value: SunmiFaceStatusCode

6.2.7. getConfig

Function definition: public static int getConfig(SunmiFaceConfigParam config)

Function: Get the current SDK configuration

VariableTypeDescription
configSunmiFaceConfigParamSDK 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

VariableTypeDescription
imageSunmiFaceImageInput image
featuresSunmiFaceImageFeaturesReturn 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

VariableTypeDescription
features1SunmiFaceFeatureFace feature 1
features2SunmiFaceFeatureFace feature 2
compare_resultSunmiFaceCompareResultComparison result

Return value: SunmiFaceStatusCode

6.2.10. releaseImageFeatures

Function definition: public static int releaseImageFeatures(SunmiFaceImageFeatures features)

Function: release facial features

VariableTypeDescription
featuresSunmiFaceImageFeaturesFacial features

Return value: SunmiFaceStatusCode

6.2.11. initDB

Function definition: public static int initDB(String db_name)

Function: Initialize the new face database

VariableTypeDescription
db_nameStringFace 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

VariableTypeDescription
featureSunmiFaceFeatureFacial 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

VariableTypeDescription
recordSunmiFaceDBRecordFace 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

VariableTypeDescription
recordSunmiFaceDBRecordFace record to search
idInfoSunmiFaceDBIdInfosearch 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

VariableTypeDescription
img_idStringID of the collected face image

Return value: SunmiFaceStatusCode