C++ Demo Programs

The bin directory contains the following executable files of the demo programs:

• demo – an example of face tracking and face estimation
• video_recognition_demo – an example of using the pbio::VideoWorker object
• test_calibration – an example of camera calibration
• test_filecap – an example of face capturing, saving and sample loading
• test_facecut – an example of face capturing and cropping, as well as estimation of the face image quality, gender and age
• test_identify – an example of creating, saving, loading and matching of templates
• test_videocap – an example of face tracking and liveness estimation

demo

The program demonstrates tracking, detection and cropping of faces, detection of anthropometric points and angles, as well as estimation of face quality, age and gender, emotions, and liveness (by processing an RGB image from your camera).

To make a quick run of the demo with default parameters on Windows, go to the bin folder and double-left-click demo.exe.

Location of C++ demo

In the upper left corner of the demo you can see the Face SDK components, which can be turned on and off with the left mouse click:

• rectangles – face rectangle
• angles – angles
• quality – image quality
• liveness – liveness
• age and gender – age and gender
• base cut, full cut, token cut – type of face cropping (basic, full frontal, token frontal)
• points – anthropometric points
• face quality – face quality
• angles vectors – vector angles
• emotions – emotions
• masked face - checking the presence of a mask on the face
• eyes openness - checking whether the eyes are closed or open

Running demo.exe

Error messages (if any) are printed in the console.

You can also run demo.exe specifying some parameters (for example, if you have an online license).
Startup parameters:

• capturer_conf – path to the capturer config file (learn more about types of config files in Capturer Class Reference)
• config_dir – path to the conf/facerec directory
• dll_path – path to the libfacerec.so or facerec.dll library file
• license_dir – path to the directory with a license; provide this parameter if you need to change a default directory license

Source code: demo.cpp

The OpenCV library is required for build.

video_recognition_demo

The program is an example of using pbio::VideoWorker and demonstrates face tracking and identification/verification on several video streams from the camera. This program also allows you to check the active liveness of a face.

To make a quick run of the demo with default parameters and check face recognition on Windows:

1. Create a database, which will be used for face recognition. To create a database, go to the bin/base folder and create a new folder, for example, person0. Copy a picture of a person to be used for recognition and create a file name.txt, which should contain a person's name.

Content of bin/base/person0

2. Go to the bin folder and run the script demo_web_m_last_v30.bat, demo_web_m_last_v300.bat, demo_web_m_last_v1000.bat or demo_web_m6v7.bat by double-left-click. You can use any above script to run this demo, the only difference is a recognition method (9.30, 9.300, 9.1000, and 6.7, see the detailed information in Face Identification).

Location of C++ video_recognition_demo

3. Tracking and identification results are displayed in a window (one window per one source). Tracked faces are highlighted with a green circle. In the upper right corner of the window you can see the recognition results: a tracked face on the left and a face from the database and the name on the right.

Running C++ video_recognition_demo

You can also run video_recognition_demo.exe specifying some parameters (for example, if you have an online license).
Startup parameters:

• at least one source, each source is a number (webcam number), or a text (the URL of a video stream or the path to a video file);
• and then, in any order, the following parameters:
  • config_dir – path to the conf/facerec directory
  • dll_path – path to the libfacerec.so or facerec.dll library file
  • database_dir – path to the directory with a database, in which a directory was created for each person containing his/her photos and a text file name.txt containing his/her name. An example of the database is stored in bin/base
  • frame_fps_limit – FPS limit
  • fullscreen – fullscreen mode
  • license_dir – path to the directory with a license; provide this parameter if you need to change a default directory license;
  • vw_config_file – name of the VideoWorker config file
  • method_config – name of the Recognizer config file
  • recognition_far_threshold – recognition far threshold (float number)
  • enable_active_liveness – enable active liveness check

Examples of startup scripts:

• Linux:

  • demo_web_m_last_v30.sh – with method 9.30 and webcam 0
  • demo_web_m_last_v300.sh – with method 9.300 and webcam 0
  • demo_web_m_last_v1000.sh – with method 9.1000 and webcam 0
  • demo_web_m6v7.sh – with method 6.7 and webcam 0
  • demo_web_active_liveness_v30.sh – launch with enabled active liveness check, with method 9.30 and webcam 0

• Windows:

  • demo_web_m_last_v30.bat – with method 9.30 and webcam 0
  • demo_web_m_last_v300.bat – with method 9.300 and webcam 0
  • demo_web_m_last_v1000.bat – with method 9.1000 and webcam 0
  • demo_web_m6v7.bat – with method 6.7 and webcam 0
  • demo_web_active_liveness_v30.bat – launch with enabled active liveness check, with method 9.30 and webcam 0

Error messages (if any) are printed in the console.

Source code: examples/cpp/video_recognition_demo

The OpenCV and boost libraries are required for build.

test_calibration

A program for camera calibration, an example of using the pbio::CameraCalibrator object.

The program runs in two modes:

• calibrate – to perform a camera calibration
• view – to see the result of distortion correction on the basis of calibration results

Startup parameters in the calibration mode:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory
• webcam id or stream url
• desired image frame width
• desired image frame height
• calibrate
• pattern type (acircles, circles or chessboard)
• pattern width
• pattern height
• path to the file, in which you want to save the calibrated parameters

Example of launch from the bin directory in the calibrate mode:

Linux: ./test_calibration ../lib/libfacerec.so ../conf/facerec/ 0 640 480 calibrate acircles 4 11 ./camparam.bin
Windows: test_calibration facerec.dll ../conf/facerec/ 0 640 480 calibrate acircles 4 11 ./camparam.bin

To perform the calibration, you need to print a calibration template (see Camera Calibration and Correction of Distortion) and fix it on a flat surface, preferably black. We recommend you to use the asymmetrical circle pattern. Then move either the pattern or the camera to capture the pattern in different poses. The program will show the approximate coverage of the pattern pose space and draw tips about the required pattern poses. Then press the c key to perform calibration. This may take about a minute, during this time the program freezes.

If the calibration is successful, the program shows a reprojection error and performs correction of frame distortion. Use the q and w keys to change the distortion correction parameter alpha. Press the s key to save the calibrated parameters or capture more pattern poses and perform the calibration again.

Startup parameters in the view mode:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory
• webcam id or stream url
• desired image frame width
• desired image frame height
• view
• path to the file, in which the camera parameters were saved

Example of launch from the bin directory in the view mode:

Linux: ./test_calibration ../lib/libfacerec.so ../conf/facerec/ 0 640 480 view ./camparam.bin
Windows: test_calibration facerec.dll ../conf/facerec/ 0 640 480 view ./camparam.bin

Use the q and w keys to change the distortion correction parameter alpha.

Source code: cpp/test_calibration/test_calibration.cpp

The OpenCV library is required for build.

test_filecap

The program demonstrates face detection and saving and loading of pbio::RawSample.

Startup parameters:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory
• capturer config file name
• paths to the input image files

Example of launch from the bin directory:

Linux: ./test_filecap ../lib/libfacerec.so ../conf/facerec common_capturer4.xml set1/01100.jpg
Windows: test_filecap facerec.dll ../conf/facerec common_capturer4.xml set1/01100.jpg

Face detection result is displayed in a window. The console displays the coordinates and orientations of the detected faces, as well as the paths, which are used to store the samples. Error messages, if any, are also printed in the console.

Source code: cpp/test_filecap/test_filecap.cpp

The OpenCV library is required for build.

test_facecut

The program demonstrates the detection and cropping of faces, as well as estimation of the face image quality, sex and age.

Startup parameters:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory
• paths to the input image files

Example of launch from the bin directory:

Linux: ./test_facecut ../lib/libfacerec.so ../conf/facerec set1/01100.jpg
Windows: test_facecut facerec.dll ../conf/facerec set1/01100.jpg

The results of face detection, coordinates of the detected faces, estimated quality, emotions, gender and age, as well as the paths used to save the cropped images are displayed in the console. Error messages, if any, are also printed in the console.

Source code: cpp/test_facecut/test_facecut.cpp

No additional libraries are required for build.

test_identify

The program demonstrates creation, saving, loading and matching of templates.

The program operates in three modes:

• enrollment – face detection in a group of images, creation of a template for each face, and saving the templates to a file.
• identification – face detection in one image, template creation, and matching of the template with every template created in the enrollment mode and loaded from the file.
• verification – detection of faces in two images, creation of two templates and their matching.

Launch parameters in the enrollment mode:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory
• name of the Recognizer config file
• enroll
• path to the directory with images (e.g. bin/set1)
• path to a text file containing a list of image file names (e.g. bin/set1/list.txt)
• path for saving templates to a file

Launch parameters in the identification mode:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory
• name of the Recognizer config file
• identify
• path to the image file
• path to the file with templates that was created in the enrollment mode

Launch parameters in the verification mode:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory
• name of the Recognizer config file
• verify
• path to the first image file
• path to the second image file

Example of launch from the bin directory in the identification mode:

• Linux: ./test_identify ../lib/libfacerec.so ../conf/facerec method7v7_recognizer.xml enroll set1 set1/list.txt templates.bin
• Windows: test_identify facerec.dll ../conf/facerec method7v7_recognizer.xml enroll set1 set1/list.txt templates.bin

Example of launch from the bin directory in the enrollment mode:

• Linux: ./test_identify ../lib/libfacerec.so ../conf/facerec method7v7_recognizer.xml identify set2/01100.jpg templates.bin
• Windows: test_identify facerec.dll ../conf/facerec method7v7_recognizer.xml identify set2/01100.jpg templates.bin

Example of launch from the bin directory in the verification mode:

• Linux: ./test_identify ../lib/libfacerec.so ../conf/facerec method7v7_recognizer.xml verify set1/01100.jpg set2/01100.jpg
• Windows: test_identify facerec.dll ../conf/facerec method7v7_recognizer.xml verify set1/01100.jpg set2/01100.jpg

Work progress and matching results are displayed in the console. Error messages, if any, are also displayed in the console.

Source code: test_identify.cpp

No additional libraries are required for build.

test_videocap

The program demonstrates face tracking and liveness estimation.

Startup parameters:

• path to the libfacerec.so or facerec.dll library file
• path to the conf/facerec directory

Example of launch from the bin directory:

Linux: ./test_videocap ../lib/libfacerec.so ../conf/facerec
Windows: test_videocap facerec.dll ../conf/facerec

The result of face tracking, as well as the results of liveness estimation, are displayed in the console. Error messages, if any, are also displayed in the console.

Source code: cpp/test_videocap/test_videocap.cpp

The OpenCV library is required for build.