Linux QuickStart
Note：Sample is only used to assist customers in understanding how to use the SDK interface, test basic functions and provide sample code. During actual development, customers can reference the code, change the sample code or rewrite the entire code.
Linux platform provides sample demos in C++ and Java. The example below illustrates the configuration process using OpenCV 3.2.0 on Ubuntu operating system.
Note：SDK itself does not rely on OpenCV library. OpenCV library is only used for sample demonstrations, based on OpenCV 3.2.0.
1 Install dependency packages
Install Java JDK (Only for Java programming use. C++ developers do not need to install this package.)
1. Download Java JDK:
Download the JDK at this link. We recommend installing JDK 1.8 and select Linux x64 version.
2. Execute the following command in Terminal:
3. Configure environment variables:
Include the following information at the end and save the file：
4. Update the settings:
In Terminal enter the following: source /etc/profile
5. Test if the installation is successful:
In Terminal enter "java -version" to check if the standard version info can be displayed.
Compile and install OpenCV library (including C++ library, Java library and jar file)
1.Install dependency packages
Execute the following command to install dependency packages: sudo apt-get install build-essential pkg-config python-dev cmake ant
2. Download OpenCV 3.2.0
Download the OpenCV 3.2.0 source code at this link.
3. Unzip opencv-3.2.0.zip and extract into destination path
4. In the destination path, create a new folder named 'build'. Click into the new folder and execute the following command:
Check if cmake command was successfully executed (refer to the photo below).
Check if the output contains java：
If expected content is not contained in the output, then please configure the environment variables and execute the above command again: export JAVA_HOME=/usr/lib/jvm/jdk1.8.0_65
5.Make install
Execute the following commands in order:
6. Copy the installed libraries.
If the make install is successful, you can see the opencv-320.jar file under the build/bin directory. Copy opencv/build/lib/libopencv_java320.so to /usr/lib.
Copy all files in sdk/libs/linux-x86_64 and libjni_facepro.so file in sdk/samples/java/jni_libs/x86_64 to /usr/lib.
2. C++ sample test configuration
1. Navigate to the file path where samples are saved：sdk\samples\c++
2. Execute make command
3. Configure SDK authorization
In this sample, we need to save the XXXXXX.lic authorization file into the license_filepath set in the sample configuration file (XXXXX.ini). When running the sample, the SDK authorization interface will load the authorization file XXX.lic in this file path. The authorization interface must be executed successfully first before any other interfaces can be used.
Special Note: When running the sample, if the license file has been changed, please delete the senseid_facepro_sn folder (this folder corresponds to the activation_code_dir directory in the configuration file XXX.ini and can be customized) as well as all the activation code files in the folder. This is because the lic files and activation code files corresponds to each other.
Please reference the Authorization Interface for authorization interface definitions. The sample below shows typical workflows for online activated license:
stid_face_professional_online_activate_license to load provided license content.
stid_face_professional_online_activate_license to connect to the web-activated license.
stid_face_professional_online_activate_license to output the newly-activated license content.
stid_face_professional_load_license_content to load new license content.
stid_face_professional_load_license_content to return to STID_OK and confirm successful authentication.
stid_license_release_content to release the license content and end the workflow.
4.Execute sample
There are two ways to execute the sample:
1). Directly run the .sh script corresponding to the sample - run_sample_face_XXX.sh (sh does not require execution access rights. chmod +x will add the execution access rights).
2). Configure LD_LIBRARY_PATH to point to library file path sdk\libs\linux-x86_64. Run test_sample_face_XXX (eg. LD_LIBRARY_PATH=../../libs/linux-x86_64 test_sample_face_XXX [parameter]).
To execute parameters, please reference the fourth section in this sample documentation - 'Introduction to Sample Functions and Parameters'.
3. Java sample test configuration
These steps are basically similar to running Java sample test configuration on Windows platform. Please refer to the steps to run Java sample on Windows platform in the Windows QuickStart.
To execute parameters, please reference the fourth section in this sample documentation - 'Introduction to Sample Functions and Parameters'.
4. Introduction to Sample Functions and Parameters
Functions and parameter explanation
Note：
Parameters can be classified into command type parameters and parameters in configuration files. Command type parameters provide the required parameters for specially-defined functions in sample; parameters in configuration files provide the basic configurations in various samples such as authorization file paths and model file paths.
When executing a sample, if the license files have been changed, please delete the senseid_facepro_sn folder (this folder corresponds to the activation_code_dir file path in the XXX.ini configuration file, and can be self-configured) as well as all the activation files within the folder.
a).sample_face_detect_1vs1(corresponds to java sample and named Detect_OneVSOne)
1). Functions
Verify configuration instruction set, face test, facial feature extraction and face comparison functions.
2). Executing parameters
i).Command Line:
[ini file path] [image A path] [image B path] ([image face orientation])
-ini file path: Configure file path
-image A path: File path of image A
-image B path: File path of image A
-image face orientation: Enable selection of parameters and input of face orientation in photos (by default it detects two photos with the same orientation). 0 represents up, 1 represents left, 2 represents right, 3 represents down; if no parameters exists, then it represents up orientation.
ii). Configuration files:
license_filepath: Authorization files
activation_code_dir: File path where the activation code is saved
alignment_model_filepath: Face test model file path
verify_model_filepath: Facial features extraction model file path
compare_model_filepath: Facial feature comparison model file path
detector_config: Face test model detector configuration: large face mode, small face mode or combination of large and small face mode
alignment_count: (can be selected) Key facial alignment iteration count. Increasing this count can raise the alignment accuracy but will decrease efficiency. Value range (0x1 ~ 0xff)
compare_threshold: Face comparison threshold. If the comparison score exceeds the threshold then evaluate the image as the same person. Value range (0,1)
3). Input and Output:
Input: two sets of photos and photo orientation
Output: Face comparison score and evaluate if the photos show the same person
b).sample_face_extract_image_feature_to_file(corresponding java sample name is ExtractFeature)
1). Functions
Verify face comparison. Facial feature extraction function. Save all the photo features in a particular folder as a json file. Provide face library for use by other face recognition sample.
2). Executing parameters
i). Command line:
[ini file path] [search image dir] [output feature file name] ([image face orientation])
-ini file path: configuration file path
-search image dir: photo folder where facial features for extraction are saved
-output feature file name: json file name for photo features
-image face orientation: Enable selection of parameters and input of face orientation in photos (by default it detects two photos with the same orientation) 0 represents up, 1 represents left, 2 represents right, 3 represents down; if no parameters exists, then it represents up orientation
ii). Configuration files：
license_filepath: Authorization files
activation_code_dir: File path where the activation code is saved
alignment_model_filepath: Face test model file path
verify_model_filepath: Facial features extraction model file path
detector_config: Face test model detector configuration: large face mode, small face mode or combination of large and small face mode
alignment_count: (can be selected) Key facial alignment iteration count. Increasing this count can raise the alignment accuracy but will decrease efficiency. Value range (0x1 ~ 0xff)
3). Input and Output:
Input: Photo folder file name Output: Folder where photo feature json format files are saved
c).sample_face_singleliveness_1vsN(corresponding java sample name is SinglelivenessOneVSN)
1). Functions
Verify monocular tracking. Frame selection based on facial quality assessment. Monocular face assessment. Facial feature extraction. Facial feature 1vsN search function. Monocular camera liveness check. Comparison with facial feature library. Facial identity recognition simulation.
2). Executing parameters
i). Command line:
[ini file path] [feature file name]
-ini file path: Configuration file path
-feature file name: Facial feature json file name
ii).Configuration files
license_filepath: Authorization files
activation_code_dir: File path where the activation code is saved
singleliveness_model_filepath: Monocular facial liveness model file path
calcpose_model_filepath: Model for calculation of face orientation
verify_model_filepath: Facial features extraction model file path
compare_model_filepath: Comparison model file path
singleliveness_track_config: Monocular tracking configuration. Only supports large face mode or small face mode.
rgb_camera_index: RGB camera index
camera_face_orientation: Camera and face orientation
hack_threshold: Liveness check threshold. If liveness score exceeds the threshold then evaluate the image as fake. Value range (0,1)
frame_selector_threshold: Face quality assessment configuration settings. Includes face quality and face orientation parameter range. For details of configuration info, please refer to header file and configuration file test.ini
3). Input and Output:
Input: Photo feature json file that provides N-comparison library. Output: Returns monocular liveness check score to evaluate if person is real. Based on the comparison score, print out the names of photos with the highest scores compared to the photo being evaluated.
4). Function module designation:
In the sample, you can designate function modules: 1. Frame selection: Face quality assessment and face orientation calculation. 2. Frame selection + liveness check function. 3. Frame selection + liveness check + 1vsN search function.
i).C++ sample:
Use macro definition to open different function modules. Frame selection: open macro TRACK_FRAMESELECTOR.
Frame selection + liveness check: open macro TRACK_FRAMESELECTOR and macro TRACK_FRAMESELECTOR_LIVENESS.
Frame selection + liveness check + 1vsN search: open macro TRACK_FRAMESELECTOR, macro TRACK_FRAMESELECTOR_LIVENESS, macro TRACK_FRAMESELECTOR_LIVENESS_1VSN.
ii).Java sample:
Use static variable definition to open different function modules. Frame selection: TRACK_FRAMESELECTOR set as 1.
Frame selection+liveness check: TRACK_FRAMESELECTOR set as 1. TRACK_FRAMESELECTOR_SINGLELIVENESS set as TRACK_FRAMESELECTOR & 1.
Frame selection + liveness check + 1vsN search: TRACK_FRAMESELECTOR set as 1， TRACK_FRAMESELECTOR_SINGLELIVENESS set as TRACK_FRAMESELECTOR & 1;TRACK_FRAMESELECTOR_SINGLELIVENESS_1VSN set as TRACK_FRAMESELECTOR_SINGLELIVENESS & 1;
d).sample_face_binocularliveness_1vsN(corresponding java sample name is BinocularlivenessOneVSN)
1).Functions
Verify binocular tracking. Frame selection based on facial quality assessment. Binocular face assessment.Facial feature extraction. Facial feature 1vsN search function. Binocular camera liveness check. Comparison with facial feature library. Facial identity recognition simulation.
2). Executing parameters
i).Command line:
[ini file path] [feature file name]
-ini file path: Configuration file path
-feature file name: Facial feature json file name
ii).Configuration files:
license_filepath: Authorization files
activation_code_dir: File path where the activation code is saved
binocularliveness_model_filepath: Binocular liveness check model file path
calcpose_model_filepath: Model for calculation of face orientation
verify_model_filepath: Facial features extraction model file path
compare_model_filepath: Comparison model file path
binocularliveness_track_config: Binocular tracking configuration. Only support large face model or small face model.
rgb_camera_index: RGB camera index
infrared_camera_index: Infrared camera index
camera_face_orientation: Camera and face orientation
hack_threshold: Liveness check threshold. If liveness score exceeds the threshold then evaluate the image as fake. Value range (0,1)
frame_selector_threshold: Face quality assessment configuration settings. Includes face quality and face orientation parameter range. For details of configuration info, please refer to header file and configuration file test.ini
3). Input and Output:
Input: Photo feature json file that provides N-comparison library Output: Returns binocular liveness check score to evaluate if person is real. Based on the comparison score, print out the names of photos with the highest scores compared to the photo being evaluated.
4). Function module designation:
In the sample, you can designate function modules: 1. Frame selection: Face quality assessment and face orientation calculation. 2. Frame selection + liveness check function. 3. Frame selection + liveness check + 1vsN search function.
i).C++ sample:
Use macro definition to open different function modules. Frame selection: open macro TRACK_FRAMESELECTOR.
Frame selection + liveness check: open macro TRACK_FRAMESELECTOR and macro TRACK_FRAMESELECTOR_LIVENESS.
Frame selection + liveness check + 1vsN search: open macro TRACK_FRAMESELECTOR, macro TRACK_FRAMESELECTOR_LIVENESS, macro TRACK_FRAMESELECTOR_LIVENESS_1VSN.
ii).Java sample:
Use static variable definition to open different function modules. Frame selection: TRACK_FRAMESELECTOR set as 1.
Frame selection + liveness check: TRACK_FRAMESELECTOR set as 1， TRACK_FRAMESELECTOR_BINOCULARLIVENESS set as TRACK_FRAMESELECTOR & 1.
Frame selection + liveness check + 1vsN search: TRACK_FRAMESELECTOR set as 1， TRACK_FRAMESELECTOR_BINOCULARLIVENESS set as TRACK_FRAMESELECTOR & 1;TRACK_FRAMESELECTOR_BINOCULARLIVENESS_1VSN set as TRACK_FRAMESELECTOR_BINOCULARLIVENESS & 1;
Note：It is recommended to use notepad++ to edit ini configuration files and save as utf-8 code format.
Last updated
