face_sdk_utils

face_sdk_utils is a part of Tech5 Face recognition SDK, it requires all SDK files on your machine and valid license. face_sdk_utils is a console program, which performs basic face recognition SDK functions without code writing.

To get HW IDs (--print-uuid)

The command displays the list of HW IDs used by face_sdk_utils.
Example:

> face_sdk_utils --print-uuid
MB: 64d06182-dba5-9b02-01ec-1831bf523fc3
GPU [0]: 720d3f1f-3dd1-4a9d-0ea2-5adafa70cae9

Linux-only: Correct work of this function requires the executable file, which have read access to the attribute product_uuid udev device dmi/id (usually it's /sys/devices/virtual/dmi/id/product_uuid file)

License request. (--request)

Via face_sdk_utils you can create license file-request. License file-request contains information about hardware ID, which is required for generating of license file-request. To create license file request run face_sdk_utils with parameter --request.
After the command face_sdk_utils creates file face_sdk.req in the current directory. To change the path and name of the output file-request use parameter --output.
All information required for CPU-only license generating will be included the file-request.
For GPU-mode using of extra parameter --compute-device is required. The value of this parameter should be the number of GPU-device, where the algorithms are to be executed.
It's allowed to use several comma-separated numbers of GPU-devices.

Example 1. Create a file-request for CPU-only mode:

> face_sdk_utils.exe --request

Example 2. Create a file-request for CPU-only mode with nin-standard name of output file:

> face_sdk_utils.exe --request --output="license_request.bin"

Example 3. Create a file-request for GPU mode:

> face_sdk_utils.exe --request --compute-device=0 --output="gpu_support_request.req"

License info. (--license)

Via face_sdk_utils you can check what Face SDK modules are included to your license with their versions, maximum batch size and expiration dates.
Also shows gpu support of your license.
Example 1. Show license info:

> face_sdk_utils.exe --license  
...
face_sdk:
  gpu_support: on
  face_detector:
    version: 200
    max_batch_size: 512
    expires: 2020.10.01
...
...
  image_compressor:
    version: 100
    allow_compress: yes
    expires: 2020.10.01

Fetch license. (--fetch-license)

This function fetch license from licensing server.
Parameters:

• --token - Obligatory parameter. License token.
• --compute-device - GPU identifiers to include in the request. Don't use this parameter for CPU only.
• --output - Output file name. Default value is face_sdk.lic.

Example 1. Fetch license for CPU only:

> face_sdk_utils.exe --fetch-license --token=insert-your-token-here

Example 2. Fetch license for GPU devices 1, 2, 3 with out file name "C:\Users\user\Desktop\custom_name.lic":

> face_sdk_utils.exe --fetch-license --token=insert-your-token-here --compute-device=[1, 2, 3] --output=C:\Users\user\Desktop\custom_name.lic

Performance test (--perf-test)

This function measures the performance of the algorithms with different parameters on your hardware.
The output of this command is performance values for specified algorithms and their parameters.
Probe images dataset and valid license are required for performance test.
Parameters:

• --input-dir - Obligatory parameter. A directory with input images, nested directories are allowed.
• --compute-device - Number of the device, where the performance test is run(-1 - CPU, 0..N - GPU).
• --batch-size - Batch size.
• --det-version - Version of face detection algorithm. Default value is 200.
• --det-skip - To skip the face detector's performance test.
• --alg-version - Version of alignment algorithm. Default value is 103.
• --alg-skip - To skip the alignment algorithm's performance test.
• --bld-version - Version of biometric template extraction algorithm. Default value is 105.
• --bld-skip - To skip the biometric template extraction algorithm's performance test.
• --ag-version - Version of age and gender classification algorithm. Default value is 100.
• --ag-skip - To skip the age and gender algorithm's performance test.
• --quality-version - Version of quality checker algorithm. Default value is 100.
• --quality-skip - To skip the quality checker algorithm's performance test.
• --blur-skip - To skip blur detection in Quality performance test.
• --glasses-smile-occlusion-skip - To skip glasses, smile, occlusion and closed eyes detections in Quality performance test.
• --hot-spots-skip - To skip hot spots detection in Quality checker performance test.
• --overexposure-skip - To skip overexposure detection in Quality checker performance test.
• --red-eyes-skip - To skip red eyes detection in Quality checker performance test.
• --rotation-skip - To skip rotation in Quality checker performance test.
• --background-skip - To skip background evenness detection in Quality checker performance test.
• --mask-skip - To skip mask detection in Quality checker performance test.
• --unnatural-skin-skip - To skip unnatural skin tone detection in Quality checker performance test.
• --image-compressor-version - Version of image compressor algorithm. Default value is 100.
• --image-compressor-skip - To skip the image compressor algorithm's performance test.
• --liveness-version - Version of liveness detection algorithm. Default value is 102.
• --liveness-skip - To skip liveness detection performance test.
• --matcher-fir-list-size - Size of the fir list. Default value is 500 000.
• --matcher-skip - To skip the matcher algorithm's performance test.

NOTE: Algorithms have dependencies on each other. See list of dependencies.
If dependencies are not met, you will see the error:

> face_sdk_utils.exe  --perf-test --input-dir=C:\Users\user\Desktop\imgs --det-skip --alg-ver=103 --bld-skip --ag-skip --quality-skip --image-compressor-skip  --matcher-skip
err:
 [struct std::_With_nested<class face_sdk::runtime_exception,class face_sdk::runtime_exception>]: Couldn't build testing pipeline
  [class face_sdk::runtime_exception]: You have to enable Face Detector for testing Alignment performance

Example 1. Performance test with default parameters

> face_sdk_utils --perf-test --input-dir="C:\Users\user\Desktop\imgs"
compute device = -1, batch size = 1
Face Detector (200) = 326ms, 3.06748 FPS
Alignment (103) = 26ms, 38.4615 FPS
Builder (105) = 735ms, 1.36054 FPS
Age&Gender (100) = 54ms, 18.5185 FPS
Quality checked (100) = 23ms, 43.4783 FPS
Image compression (100) = 17ms, 58.8235 FPS
Image decompression (100) = 26ms, 38.4615 FPS
Matcher (105) 1:500000 = 659ms

Example 2. Performance test on GPU with batch size 32

> face_sdk_utils --perf-test --input-dir="C:\Users\user\Desktop\imgs" --compute-device=0 --batch-size=32
... 
...
...
compute device = 0, batch size = 32
Face Detector (200) = 256ms, 125 FPS
Alignment (103) = 60ms, 533.333 FPS
Builder (105) = 477ms, 67.086 FPS
Age&Gender (100) = 38ms, 842.105 FPS
Quality checked (100) = 194ms, 164.948 FPS
Image compression (100) = 19ms, 52.6316 FPS
Image decompression (100) = 25ms, 40 FPS
Matcher (105) 1:500000 = 686ms

Example 3. Performance test of biometric template extraction algorithm version 104 on GPU

> face_sdk_utils --perf-test --input-dir="C:\Users\user\Desktop\imgs" --ag-skip --matcher-skip --quality-skip --image-compressor-skip --bld-version=104 --compute-device=0
...
...
...
compute device = 0, batch size = 1
Face Detector (200) = 21ms, 47.619 FPS
Alignment (103) = 3ms, 333.333 FPS
Builder (104) = 73ms, 13.6986 FPS
Age&Gender is skipped
Quality checked is skipped
Image compression is skipped
Image decompression is skipped
Matcher is skipped

The performance values given in the examples should not be considered as reference data

Biometric template extraction and matching

face_sdk_utils allows to do following without code writing:

• pre-processing the images (detection, alignment, biometric template extraction, etc) for the following import the data into the system.
• matching.

Face detection (--detect-faces)

The procedure runs the face detector algorithm for a given set of images in batch mode. Output results:

• serialized facial images found on input images (if --face-serialize specified).
• facial images found on input images (if --write-cropped-faces specified).
• detected_faces.csv report file, containing information about the processing result for every input images.

Parameters:

• --input-dir - Obligatory parameter. A directory with input images, nested directories are allowed.
• --output-dir - Obligatory parameter. A directory with output files. The structure of the output directory will correspond to the input directory.
• --det-version - To insert version of face detection algorithm. Default value is 200.
• --det-confidence - Face detector confidence. Default value is 0.9f.
• --face-selector - Face selector algoritm. 0 = widest face. 1 = best confidence, 2 = closest to center. All faces will be processed if parameter is not specified.
• --face-serialize - Detected faces will be serialized to output-dir if this parameter specified. Default value is true.
• --write-cropped-faces - Detected cropped faces will be saved to output-dir if this parameter specified. Default value is true.
• --compute-device - Number of the device, where the algorithms are run (-1 - CPU, 0..N - GPU).
• --batch-size - Batch size.
  Using of 2 last parameters speeds up the processing significantly provided that you have GPU device and the license.

Example 1. To run face detection algorithm on the set of images on GPU device 0 with batch size 32

> face_sdk_utils.exe --detect-faces --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\imgs_out" --compute-device=0 --batch-size=32
...
info: processed 128/1866 (6%)
...
info: processed 512/1866 (27%)
...
info: processed 1866/1866 (100%)

Example 2. To run face detection algorithm on the set of images on CPU without saving resulting faces on disk.

> face_sdk_utils.exe --detect-faces --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\imgs_out" --face-serialize=false --write-cropped-faces=false
...
info: processed 128/1866 (6%)
...
info: processed 512/1866 (27%)
...
info: processed 1866/1866 (100%)

The structure of detected_faces.csv file-report

Separator character ';' The first line in the file always describes the fields.

file_path;face_file_path;cropped_file_path;x;y;width;height;is_out_of_bounds_set;out_of_bounds;version;has_landmarks;landmarks

, where

• file_path - full path to the input image
• face_file_path - full path to the serialized facial image. n/a in case of –face-serialize=false
• cropped_file_path - full path to the cropped facial image. n/a in case of –write-cropped-faces=false
• confidence - face detector confidence
• x - x coordinate of top left face's point.
• y - y coordinate of top left face's point.
• width - width of the detected face.
• height - height of the detected face.
• is_out_of_bounds_set - true means face can be out of bounds of the source image.
• out_of_bounds - 1 - true means face is out of bounds of the source image.
• version - version of face detector's algorithm.
• has_landmarks - true means face has landmarks.
• landmarks - array of face's landmarks.

The field landmarks could be nor "[x1:y1][x2:y2][x3:y3]...[xN:yN]". Example of detected_faces.csv file:

C:\Users\user\images\PHOTO-1.jpg;n/a;n/a;11;93;57;57;true;false;200;true;[34:116][50:116][43:125][34:131][48:132]
C:\Users\user\images\PHOTO-2.jpg;n/a;n/a;156;42;46;46;true;false;200;true;[172:62][186:61][179:70][175:76][185:76]

Detection and alignment (--align)

The procedure runs the face detector and alignment algorithms for a given set of images in batch mode. Output results:

• aligned facial images found on input images.
• .alg-files. .alg-file - is a serialized to machine representation result of work of face detector and alignment algorithms.
• align.csv report file, containing information about the processing result for every input image.

Parameters:

• --input-dir - Obligatory parameter. A directory with input images, nested directories are allowed.
• --output-dir - Obligatory parameter. A directory with output images. The structure of the output directory will correspond to the input directory.
• --alg-serialize - The .alg files will be produced if this parameter is specified.
• --alg-version - To insert version of alignment algorithm. Default value is 103.
• --det-version - To insert version of face detection algorithm. Default value is 200.
• --det-skip - If the parameter is specified, the face detector is skipped and alignment runs directly on the input images. Pay attention: if the image has two or more faces, the alignment may give an unpredictable result.
• --det-confidence - Face detector confidence. Default value is 0.9f.
• --face-selector - Face selector algoritm. 0 = widest face. 1 = best confidence, 2 = closest to center. All faces will be processed if parameter is not specified.
• --compute-device - Number of the device, where the algorithms are run (-1 - CPU, 0..N - GPU).
• --batch-size - Batch size.
  Using of 2 last parameters speeds up the processing significantly provided that you have GPU device and the license.

Example 1. To run alignment algorithm on the set of images on GPU device 0 with batch size 32

> face_sdk_utils.exe --align --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\imgs_oout" --compute-device=0 --batch-size=32
...
info: processed 128/1866 (6%)
...
info: processed 512/1866 (27%)
...
info: processed 1866/1866 (100%)

Example 2. To run alignment algorithm on the set of images on CPU with skipped face detection.

> face_sdk_utils.exe --align --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\imgs_oout" --skip-det
...
info: processed 128/1866 (6%)
...
info: processed 512/1866 (27%)
...
info: processed 1866/1866 (100%)

The structure of align.csv file-report

Separator character ';' The first line in the file always describes the fields.

input;output;output_alg;threshold;bad_image;no_faces;multiply_faces;write_err

, where

• input - full path to the input image
• output - full path to the aligned image
• output_alg - full path to .alg file.
• threshold - quality assessement score.
• bad_image - 1 - can't read/decode the input image.
• no_faces - 1 - no face is found on the input image.
• multiply_faces - 1 - more than one face are found on the input image.
• write_err - 1 - one of the output files can't be written for some reasons.

Fields output, output_alg, threshold may have value "n/a" if the value of fields bad_image or no_faces = 1 Field threshold may have value "n/a" if the alignment algorithm's version doesn't support quality assessement

The field multiply_faces has value 1 means that more than one face are found on input image. In this case in the .csv-file new rows will be added for every detected face and to the output name will be added a postfix, for example

imgs\10004\101466_0.jpg;imgs_oout\10004\101466_0_0.jpg;imgs_oout\10004\101466_0_0.alg;17.558319;0;0;1;0
imgs\10004\101466_0.jpg;imgs_oout\10004\101466_0_1.jpg;imgs_oout\10004\101466_0_1.alg;-13.654776;0;0;1;0

Age and gender recognition (--age-n-gender)

The procedure runs the age and gender algorithm for a given set of .alg in batch mode. Output results:

• .csv report file with specified name, containing information about the processing result for every input file.

Parameters:

• --input-dir - Obligatory parameter. A directory with input .alg, nested directories are allowed.
• --output - Obligatory parameter. A directory with output file.
• --ag-version - Version of Age&Gender algorithm. Default is 100.
• --batch-size - Batch size.
• --compute-device - Number of the device, where the algorithms are run (-1 - CPU, 0..N - GPU).
  Using of 2 last parameters speeds up the processing significantly provided that you have GPU device and the license.

Example 1. To run age and gender algorithm on the set of .alg files on GPU device 0 with batch size 32

> face_sdk_utils.exe --detect-faces --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\out.csv" --compute-device=0 --batch-size=32
...
info: processed 128/1866 (6%)
...
info: processed 512/1866 (27%)
...
info: processed 1866/1866 (100%)

The structure of .csv file-report

Separator character ';' The first line in the file always describes the fields.

source;age;gender

, where

• source - full path to the input alg file.
• age - recognized age.
• gender - recognized gender.

The field age could be nor a float value specified age. The field gender could be nor a float value, < 0 means female, > 0 means male. Both fields could be nin case of wrong file in the input directory.

Example of .csv file:

C:\Users\user\algs\aligned1.alg;34.0423;0.8765
C:\Users\user\algs\aligned2.alg;28.9576;-2.7456
C:\Users\user\algs\aligned3.jpg;n/a;n/a

Biometric template extraction (--build)

The procedure runs the biometric template extraction algorithm for a given set of .alg files in batch mode. Output results:

• .fir-file for every input .alg-file. .fir file - is a serialized to machine representation result of work of biometric template extraction algorithm.
• build.csv report file, containing information about the processing result for every input .alg file.

Parameters:

• --input-dir - Obligatory parameter. A directory with input .alg files, nested directories are allowed.
• --output-dir - Obligatory parameter. A directory with output .fir-files. The structure of the output directory will correspond to the input directory.
• --bld-version - Version of biometric template extraction algorithm. Default value is 105.
• --compute-device - Number of the device, where the algorithms are run (-1 - CPU, 0..N - GPU).
• --batch-size - Batch size.
  Using of 2 last parameters speeds up the processing significantly provided that you have GPU device and the license.

Example 1. To run biometric template extraction algorithm on the set of images on GPU device 0 with batch size 32

> face_sdk_utils.exe --build --input-dir="C:\Users\user\Desktop\imgs_oout" --output-dir="C:\Users\user\Desktop\imgs_oout" --compute-device=0 --batch-size=32
...
info: processed 96/1812 (5%)
...
info: processed 928/1812 (51%)
...
info: processed 1812/1812 (100%)

Example 2. To run biometric template extraction algorithm version 100 on the set of images on GPU-device

> face_sdk_utils.exe --build --input-dir="C:\Users\user\Desktop\imgs_oout" --output-dir="C:\Users\user\Desktop\imgs_oout" --bld-version=100
...
info: processed 96/1812 (5%)
...
info: processed 928/1812 (51%)
...
info: processed 1812/1812 (100%)

Structure build.csv report file

Separator character ';' The first line in the file always describes the fields.

input;output;read_err;incompatible

, where

• input - full path to input .alg-file
• output - full path to output .fir-file
• read_error - 1 - input .alg file can't be written or it's corrupted.
• incompatible - 1 - used version of alignment algorithm is not compatible with the version of the biometric template extraction algorithm.

Field output may have a value "n/a" if values of the fields read_error or incompatible = 1

Detection, alignment and biometric template extraction (--align-n-build)

The all-in-one procedure (--aling + --build). Output results:

• .alg-files (serialized to machine representation result of work of face detector and alignment algorithms). Optional output.
• aligned facial images found on input images. Optional output.
• .fir-files (serialized to machine representation result of work of biometric template extraction algorithm).
• algn_n_build.csv report file, containing information about processing result for every input image file.

Parameters:

• --input-dir - Obligatory parameter. A directory with input images, nested directories are allowed.
• --output-dir - Obligatory parameter. A directory with output images, .alg files and .fir files. The structure of the output directory will correspond to the input directory.
• --det-version - To insert the version of face detection algorithm. Default value is 200.
• --det-skip - If a parameter other than zero is specified, the face detector is skipped and the alignment runs directly on the input images. Pay attention: if the image has two or more faces, the alignment may give an unpredictable result. Default value is 0.
• --det-confidence - Face detector confidence threshold. Default value for detector version 200 is 0.6.
• --face-selector - Face selector algoritm. 0 = widest face. 1 = best confidence, 2 = closest to center. All faces will be processed if parameter is not specified.
• --alg-version - To insert version of alignment algorithm. Default value is 103.
• --alg-serialize - To write .alg file to the disk - 1. Do not write .alg files - 0. Default value is 1.
• --alg-write-aligned - To write aligned images to the disk - 1. Do not write aligned images - 0. Default value is 0.
• --bld-version - Version of biometric template extraction algorithm (builder). Default value is 200.
• --compute-device - Number of the device, where the algorithms are run (-1 - CPU, 0..N - GPU). Default value is -1.
• --batch-size - Batch size (integer numbers from 1 and above). Default value is 1. Pay attention that batch size can be limited by your license. See more
  Using of 2 last parameters speeds up the processing significantly provided that you have GPU device and the license for batching.

Example 1. To run alignment and biometric template extraction algorithm on the set of images on GPU device 0 with batch size 32

> face_sdk_utils.exe --align-n-build --input-dir="/home/input_images" --output-dir="/home/result" --compute-device=0 --batch-size=32
...
info: processed 96/1812 (5%)
...
info: processed 928/1812 (51%)
...
info: processed 1812/1812 (100%)

Example 2. To run alignment version 100 and biometric template extraction algorithm version 100 without face detection on the set of images on GPU-device

> face_sdk_utils.exe --align-n-build  --input-dir="/home/input_images" --output-dir="/home/result" --det-skip=1 --alg-version=103 --bld-version=200
...
info: processed 96/1812 (5%)
...
info: processed 928/1812 (51%)
...
info: processed 1812/1812 (100%)

Structure algn_n_build.csv report file

Separator character ';' The first line in the file always describes the fields.

input;output_img;output_alg;output_fir;face_confidence;trashold;decode_error;no_faces;many_faces;write_img_err;write_alg_err;write_fir_err

, where

• input - full path to input input file
• output_img - full path to output aligned image (may have "n/a" if --alg-write-aliged=0 was passed or if value of fields decode_error or no_faces or write_img_err = 1)
• output_alg - full path to output .alg file (may have "n/a" if --alg-serialize=0 was passed or if value of fields decode_error or no_faces or write_alg_err = 1)
• output_fir - full path to output .fir file (may have "n/a" if value of fields decode_error or no_faces or write_fir_err = 1)
• face_confidence - Detected face confidence.
• trashold - quality assessement score.
• decode_error - 1 - input image can't be readed or decoded.
• no_faces - 1 - no face is found on the input image.
• many_faces - 1 - more than one face are found on the input image.
• write_img_err - 1 - output image can't be written
• write_alg_err - 1 - output .alg can't be written
• write_fir_err - 1 - output .fir can't be written

The field many_faces has value 1 means that more than one face are found on input image. In this case in the .csv-file new rows will be added for every detected face and to the output name will be added a postfix

Compact firs (--compact-firs)

The procedure takes logs firs from input directory, converts them to short and saves to the output directory. NOTE:
Since version 1.6 FaceSDK produces short firs by default, so the job helps to convert long first from previous version without re-extraction.

Parameters:

• --input-dir - Obligatory parameter. A directory with input files, nested directories are allowed.
• --output-dir - Obligatory parameter. Full path to output directory.

Example. To run algorithm:

> face_sdk_utils.exe --compact-firs --input-dir="C:\Users\user\Desktop\firs" --output-dir="C:\Users\user\Desktop\firs_output"

Results

If input directory contains correct firs files, then no logs will be shown and compressed firs files with the same names will be generated in output directory.
Otherwise error message will be shown.

Image's quality checker (--quality)

The procedure runs the quality checker algorithm for a given set of images in batch mode.
Output results:
- .csv report file with specified name, containing information about the processing result for every input file.

Parameters:

• --input-dir - Obligatory parameter. A directory with input images, nested directories are allowed.
• --output - Obligatory parameter. Output file.
• --version - Version of quality checker algorithm. Default is 100.
• --det-version - Version of face detection algorithm.
• --det-confidence - Face detector confidence. Default value is 0.9f.
• --face-selector - Face selector algoritm. 0 = widest face. 1 = best confidence, 2 = closest to center. All faces will be processed if parameter is not specified.
• --batch-size - Batch size.
• --compute-device - Number of the device, where the algorithms are run (-1 - CPU, 0..N - GPU).
• --blur-skip - To skip blur detection test.
• --glasses-smile-occlusion-skip - To skip glasses, smile, occlusion and closed eyes detections test.
• --hot-spots-skip - To skip hot spots detection test.
• --overexposure-skip - To skip overexposure detection test.
• --red-eyes-skip - To skip red eyes detection test.
• --rotation-skip - To skip rotation test.
• --background-skip - To skip background evenness detection test.
• --mask-skip - To skip mask detection test.
• --unnatural-skin-skip - To skip unnatural skin tone detection test.

Using of 2 last parameters speeds up the processing significantly provided that you have GPU device and the license.

Example 1. To run quality checker algorithm on the set of image files on GPU device 0 with batch size 32

> face_sdk_utils.exe --quality --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\out.csv" --compute-device=0 --batch-size=32
...
info: processed 128/1866 (6%)
...
info: processed 512/1866 (27%)
...
info: processed 1866/1866 (100%)

Example 2. To run quality checker algorithm on the set of image files on CPU device with face detector 210 version and confidence 0.7

> face_sdk_utils.exe --quality --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\out.csv" --det-version=210 --det-confidence=0.7
...
info: processed 128/1866 (6%)
...
info: processed 512/1866 (27%)
...
info: processed 1866/1866 (100%)

The structure of .csv file-report

Separator character ';' The first line in the file always describes the fields.

file_path;x;y;width;height;hot_spots;blur;overexposure;rotation;glasses;smile;occlusion;closed_eyes;red_left_eye;red_right_eye;unnatural_skin;even_background;mask

, where

• file_path - full path to the input image.
• x - x coordinate of top left face's point.
• y - y coordinate of top left face's point.
• width - width of the detected face.
• height - height of the detected face.
• hot_spots - value in range [0...1], where 0 means no hot spots and 1 means heavy hot spots.
• blur - value in range [0...1], where 0 means no blur and 1 means blurred image.
• overexposure - value in range [0...1], where 0 means normal exposure and 1 means under/overexposed image.
• rotation - value in range [0...1], where 0 means face on image is not rotated and 1 means it is rotated.
• glasses - value in range [0...1], where 0 means no glasses and 1 means glasses on.
• smile - value in range [0...1], where 0 means no smile and 1 means a smile.
• occlusion - value in range [0...1], where 0 means no occlusion and 1 means face is fully blocked.
• closed_eyes - value in range [0...1], where 0 means eyes are open and 1 means eyes are closed.
• red_left_eye - value in range [0...1], where 0 means normal eye color and 1 means red eye.
• red_right_eye - value in range [0...1], where 0 means normal eye color and 1 means red eye.
• unnatural_skin - value in range [0...1], where 0 means the skin color is normal and 1 means the color is unnatural.
• even_background - value in range [0...1], where 0 means the background is even and 1 means the background is uneven.
• mask - value in range [0...1], where 0 means no mask and 1 means there is a mask.

The field file_path will always be filled. Other fields can be n/a in case face detector doesn't detect faces on input image.

Example of .csv file:

C:\Users\user\Desktop\imgs\no_faces.jpg;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a;n/a
C:\Users\user\Desktop\imgs\1_face.jpg;8;83;464;464;0.084249;0.768069;207.000000;0.034059;0.000179;0.999723;0.000202;0.000189;0.001856;0.000034;0.662506;0.998105;0.000159

Biometric template matching (--match)

The procedure matches biometric templates against each other. Results are presented in .csv-file report.

Parameters:

• --input-dir - Obligatory parameter. A directory with input .alg files, nested directories are allowed.
• --output - Obligatory parameter. Full path to output .csv file.
• --threshold - Obligatory parameter. Similarity score (threshold) - matching results equal and above to the threshold are written to .csv-file report.
• --table-code - Used table code (reference to table code). Default value is "gn".
• --bld-version - Matching algorithm version. Default value is 105.

Example. To run matching algorithm version 200 with a threshold 8 from specified directory

> face_sdk_utils.exe --match --input-dir="C:\Users\user\Desktop\imgs_oout" --output="C:\Users\user\Desktop\imgs_oout\match.csv" --threshold=8 --bld-version=200

Structure .csv-file report

Separator character ';' The first line in the file always describes the fields.

source;target;score

, where

• source - full path to the first biometric template (.fir file)
• target - full path to the second biometric template (.fir file)
• score - matching result for source and target

Image compressor (--image-compressor)

The procedure compress or decompress images in the specified directory.

Parameters:

• --input-dir - Obligatory parameter. A directory with input files, nested directories are allowed.
• --output-dir - Obligatory parameter. Full path to output directory.
• --compr-version - Compressor algorithm version. Default value is 100.
• --direction - Obligatory parameter. Only 2 variants - compress and decompress.
• --compr-level - Compression level, possible values [1...5], where 1 means less size, lower quality and 5 means bigger size, but higher quality. Default value is 1.

Example 1. To run compress algorithm version 100 with compression level 3

> face_sdk_utils.exe --image-compressor --input-dir="C:\Users\user\Desktop\imgs" --output-dir="C:\Users\user\Desktop\out" --direction=compress --compr-level=3
...
info: processed 128/1866
...
info: processed 512/1866
...
info: processed 1866/1866

Example 2. To run decompress algorithm version 100

> face_sdk_utils.exe --image-compressor --input-dir="C:\Users\user\Desktop\out" --output-dir="C:\Users\user\Desktop\out" --direction=decompress
...
info: processed 128/1866
...
info: processed 512/1866
...
info: processed 1866/1866

Results

If --direction=compress, then .dat files will appear in the directory, specified with --output-dir parameter. The files you get will have the same names as input images.
If --direction=decompress, then .png files will appear in the directory, specified with --output-dir parameter. The files you get will have the same names as input dat files.

Liveness detection (--liveness)

The procedure performs liveness detection on images or .face files in the specified directory. NOTE! The job is not available on mobile platforms.

Parameters:

• --input-dir - Obligatory parameter. A directory with input files (images or .face), nested directories are allowed.
• --output - Obligatory parameter. Output file.
• --liv-version - Liveness detection algorithm version. Default value is 102.
• --liv-102-threshold1 - Threshold 1 value. Applicable to liveness 102 only. Default value is 0.001. Do not change the threshold without contacting Tech5 Support Team
• --liv-102-threshold2 - Threshold 2 value. Applicable to liveness 102 only. Default value is 0.9615. Do not change the threshold without contacting Tech5 Support Team
• --liv-102-threshold3 - Threshold 3 value. Applicable to liveness 102 only. Default value is 0.9896. Do not change the threshold without contacting Tech5 Support Team
• --det-version - Version of face detection algorithm. Default value is 200.
• --det-confidence - Face detector confidence. Default value is 0.9.
• --compute-device - Number of the device, where the algorithms are run (-1 - CPU, 0..N - GPU). Default value is -1.
• --batch-size - Batch size (integer numbers from 1 and above). Default value is 1. Pay attention that batch size can be limited by your license. See more
  

  input;bad_file;error_code;real;value1;value2;value3

  , where

input - full path to input file.

• bad_file - 1 means file is corrupted and was skipped
• error_code - liveness detection error code. 0 means no error. If you see non-zero value it means that liveness detection was skipped.
• real - liveness detection summary result. 0 means a spoof. 1 means a real person.
• value1, value2, value3 - liveness detection scores.

Example 1. To run liveness detection version 102 with default thresholds and default face detection algorithm

> face_sdk_utils.exe --liveness --input-dir="C:\Users\user\Desktop\imgs" --output="C:\Users\user\Desktop\imgs\liveness_results.csv" 
...
info: processed 128/1866
...
info: processed 512/1866
...
info: processed 1866/1866

Pure Fir extraction (–pure-fir-extraction)

The procedure extracts pure FIR data from .fir file and stores it in .bin file.
The procedure automatically detects type of FIR (long, short or binary) and calls corresponding face_sdk::pure_fir_extractor method.
The procedure writes file with extracted data in .bin as is. It writes an array of floats for long FIRs and array of bytes for short and binary FIRs

Parameters:

• --input-dir - Obligatory parameter. A directory with input .fir files, nested directories are allowed.
• --output - Obligatory parameter. Output directory to where the extracted data is written(.bin).

Translate distance to score (–dist-to-score)

The procedure translates L2 distance to -log(FAR) score which is used in FaceSDK.

Parameters:

• --distance - Obligatory parameter. Distance between FIRs.
• --firs-count - Number of FIRs for M:1 matching. Default is 1. Do not use any other values unless you work with M:1 matching, use Builder 104 and have a clear understanding of these features.
• --table-code - Obligatory parameter. Used table code (reference to table code).
• --bld-version - Obligatory parameter. Builder algorithm version.