Sunmi Developer Docs

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:

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