Face SDK  1.7 Mozart rc
Face Recognition Software Development Kit
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"

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.
  • --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.
  • --matcher-fir-list-size - Size of the enrolled list. Default value is 500 000.
  • --matcher-skip - To skip the matcher algorithm's performance test.
  • --compute-device - Number of device, where the performance test is run(-1 - CPU, 0..N - GPU).
  • --batch-size - Batch size.

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) = 275ms, frame rate 3.63636 FPS
alignment (103) = 18ms, frame rate 55.5556 FPS
builder (105) = 608ms, frame rate 1.64474 FPS
age gender (100) = 45ms, frame rate 22.2222 FPS
matcher (105) 1:500000 = 41ms

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) = 165ms, frame rate 98.57235 FPS
alignment (103) = 14ms, frame rate 85.9254 FPS
builder (105) = 404ms, frame rate 87.1544 FPS
age gender (100) = 36ms, frame rate 438.4257 FPS
matcher (105) 1:500000 = 41ms

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" --skip-det --skip-alg --skip-ag --skip-matcher --bld-version=104 --compute-device=0
...
...
...
compute device = 0, batch size = 1
face_detector skipped
alignment skipped
builder (104) = 533ms, frame rate 10.5083 FPS
age gender skipped
matcher 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 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
  • 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 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 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 device, where the algorithms is 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 device, where the algorithms is 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 writed
  • write_alg_err - 1 - output .alg can't be writed
  • write_fir_err - 1 - output .fir can't be writed

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 [shorts firs by default] (@produces_short_firs), 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 .alg, nested directories are allowed.
  • --output - Obligatory parameter. A directory with output file.
  • --version - Version of quality checker algorithm. Default is 100.
  • --det-version - Version of face detection algorithm. Face detection step will be skipped if not specified.
  • --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 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 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;blur;overexposure;rotation;glass;smile;occlusion;closed_eyes

, 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.
  • blur - value can be [0...1], where 0 means no blur and 1 means all blured.
  • overexposure - value can be [0...1], where 0 means no overexposure and 1 means all overexposured.
  • rotation - value can be [0...1], where 0 means face on image is not rotated and 1 means it is rotated.
  • glass - value can be [0...1], where 0 means no glasses and 1 means glasses on.
  • smile - value can be [0...1], where 0 means no smile and 1 means smile.
  • occlusion - value can be [0...1], where 0 means no occlusion and 1 means face is fully blocked.
  • closed_eyes - value can be [0...1], where 0 means eyes open and 1 means eyes closed.

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\images\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;
C:\Users\user\images\1_face.jpg;458;666;275;275;0.0731814;0.0943888;0.198709;0.000961387;0.00396354;0.996309;0.9924;

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.

Generated by   doxygen 1.8.17