C++ Samples

The bin directory contains the following executable files of the samples:

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

The upper left corner of the demo shows Face SDK components, which can be turned on and off by 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 - Checks the presence of a mask on the face
• eyes openness - Checks 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 Capturer config files.
• 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 sample is an example of using pbio::VideoWorker. It demonstrates face tracking and identification/verification on several video streams from the camera. This sample also lets you check the active face liveness.

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

1. Create a database to 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 must contain a person's name written in Latin on one line.

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 Facial Recognition).

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. The recognition results are displayed in the upper right corner of the window: a tracked face is displayed on the left, and a face from the database and the name are displayed 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. This database has a directory for each person, which contains a person's photos and a text file name.txt with a person's 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 sample for camera calibration, an example of using the pbio::CameraCalibrator object.

The sample 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, where 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, 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 sample 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 might take about a minute, during this time the sample freezes.

If the calibration is successful, the sample 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, where 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 sample 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, 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 sample 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 sample demonstrates creation, saving, loading and matching of templates.

The sample 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 that contains 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 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 identify set1 set1/list.txt templates.bin
• Windows: test_identify facerec.dll ../conf/facerec method7v7_recognizer.xml identify 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 enroll set2/01100.jpg templates.bin
• Windows: test_identify facerec.dll ../conf/facerec method7v7_recognizer.xml enroll 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 sample 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.