Connection to the project
To start using Face SDK, you need to add and use the libfacerec library in your project. libfacerec is the key Face SDK's library that implements the main Face SDK's functionality, including detection, attribute estimation and identification/verification.
Add the libfacerec library to the project
Required dependencies
First of all, install the dependencies below:
For Windows:
- sense4.dll. This library is located in the bin folder of Face SDK distribution package. If you change the default location, the library must be placed next to
facerec.dll
. - (64-bit): tensorflow.dll when GPU/AVX2 acceleration is used. This library is located in the bin folder of Face SDK distribution package. It must be located in the directory, which your application is launched from. Otherwise, add the path to the directory with this library to the
PATH
system variable. - (64-bit): Microsoft Visual C++ Redistributable for Visual Studio 2019
For Linux:
- libusb-0.1.so.4
- (64-bit): libtensorflow.so.2 when GPU/AVX2 acceleration is used. This library is located in the lib folder of Face SDK distribution package.
C++
The libfacerec library is loaded dynamically in runtime mode when the static method pbio::FacerecService::createService
is called. Therefore, you don't need to link your program with libfacerec.so (Linux) or facerec.dll (Windows). Only add the include directory to header file directories.
All libfacerec declarations are divided in two headers:
- facerec/import.h : must be included only in one project file (for example, in main.cpp).
- facerec/libfacerec.h : must be included in each file that uses a library.
The libfacerec library doesn't have any actual third-party dependencies*, since all used third-party libraries (see Open source licenses) are linked statically. Therefore, any version of these libraries must work for examples, in which OpenCV or boost is used.
* – except for the linux x86_64 and windows_x86_64 distribution packages when GPU/AVX2 acceleration is used. In this case, a dependency on libtensorflow.so.2, libonnxruntime.so or tensorflow.dll, onnxruntime.dll is used respectively.
Library version
You can get the current library version by calling the get_version
method from the created FacerecService
object. This method will return a string in the format of x.yy.zz
, where x
is the major version, yy
is the minor version, and zz
is the patch version.
In C++ the version can be additionally obtained from the preprocessor constants:
LIBFACEREC_VERSION
: string representation, similar toFacerecService.get_version()
LIBFACEREC_VERSION_HEX
: 3-byte HEX representation that is useful in numeric comparisons, e.g.0x010234
For more information on how Face SDK works in C++ projects, see a set of C++ samples.
Java
To use facerec.jar in a project, specify the path to this file in classpath
. The facerec.jar Java library is a wrapper for the C++ library, so libfacerec_jni.so and libfacerec.so for Linux and Android or facerec_jni.dll and facerec.dll for Windows are required in runtime. Path to the directory, which contains lifacerec_jni.so or facerec_jni.dll, must be specified in java.library.path
.
For more information on how Face SDK works in Java projects, see a set of Java samples.
C#
To use facerec in a project, add a reference to FacerecCSharpWrapper.dll in a project. Add facerec.so (for Linux) or facerec.dll (for Windows) and FacerecCSharpWrapper.dll to the folder with executable file.
For more information on how Face SDK works in C# projects, see a set of C# samples.
Python
Note: Python 3.6 or higher is supported. setuptools
package must be installed before starting the installation.
face_sdk_3divi
package allows you to use the libfacerec library in a Python project. To install the package, go to the python_api directory and run pip3 install .
For more information on how Face SDK works in Python projects, see a set of Python samples.
Use the libfacerec library
To use the libfacerec library, call the FacerecService.createService
method, which dynamically loads the library. The result of method operation is FacerecService
interface object,which is required to create other interface objects, including Capturers, Estimators and Recognizers.
Warning: You can call FacerecService.createService
only once, otherwise, you may encounter a crash.
To initialize the libfacerec library, call FacerecService.createService
method with the following arguments:
- dll_path: Absolute or relative path to the library file libfacerec.so (Linux) or facerec.dll (Windows).
- facerec_conf_dir: Absolute or relative path to the directory with config files (directory
face_sdk/conf/facerec/
in the distribution package). - license_dir: Absolute or relative path to the directory with the license, otherwise, an empty string. If the string is empty, the license file is searched first in the
face_sdk/license/
directory, then in theface_sdk/conf/facerec/
directory.
To initialize the libfacerec library with preloaded (stored in a string variable) license, call FacerecService.createService
method with the following arguments:
- dll_path: Absolute or relative path to the library file libfacerec.so (Linux) or facerec.dll (Windows).
- facerec_conf_dir: Absolute or relative path to the directory with config files (directory
face_sdk/conf/facerec/
in the distribution package). - license: License in the form of a special structure:
FacerecService.License
Example 1
This example shows initialization of the libfacerec library using FacerecService.createService
method.
- C++
- C#
- Java
- Python
#include <iostream>
#include <exception>
#include <facerec/import.h>
#include <facerec/libfacerec.h>
int main (int argc, char** argv)
{
try
{
pbio::FacerecService::Ptr service;
#ifdef _WIN32
service = pbio::FacerecService::createService("../bin/facerec.dll", "../conf/facerec/");
#else
service = pbio::FacerecService::createService("../lib/libfacerec.so", "../conf/facerec/");
#endif
const pbio::Recognizer::Ptr recognizer = service->createRecognizer("method7v7_recognizer.xml");
pbio::FacerecService::Config capturer_config("common_capturer4_fda.xml");
capturer_config.overrideParameter("min_size", 200);
pbio::Capturer::Ptr capturer = service->createCapturer(capturer_config);
// ...
}
catch(const pbio::Error &e)
{
std::cerr << "facerec exception catched: '" << e.what() << "' code: " << std::hex << e.code() << std::endl;
}
catch(const std::exception &e)
{
std::cerr << "exception catched: '" << e.what() << "'" << std::endl;
}
}
using System;
using VDT.FaceRecognition.SDK;
namespace Example
{
public class Example
{
public static void Main(string []args)
{
try
{
String faceSDKRootDir = "/path/to/face_sdk";
FacerecService service = FacerecService.createService(faceSDKRootDir + "/conf/facerec", "");
Recognizer recognizer = service.createRecognizer("method7v7_recognizer.xml", true, true, false);
FacerecService.Config capturerConfig = new FacerecService.Config("common_capturer4_fda.xml");
capturerConfig.overrideParameter("min_size", 200);
Capturer capturer = service.createCapturer(capturerConfig);
// ...
}
catch (Error e)
{
Console.WriteLine(e.Message);
}
catch (Exception e)
{
Console.WriteLine(e.Message);
}
}
}
}
package example;
import java.lang.String;
import java.lang.Exception;
import com.vdt.face_recognition.sdk.FacerecService;
import com.vdt.face_recognition.sdk.Recognizer;
import com.vdt.face_recognition.sdk.Capturer;
import com.vdt.face_recognition.sdk.SDKException;
public class Example
{
public static void main(String []args)
{
try
{
final String faceSDKRootDir = "/path/to/face_sdk";
final FacerecService service = FacerecService.createService(faceSDKRootDir + "/lib/libfacerec.so", faceSDKRootDir + "/conf/facerec", "");
final Recognizer recognizer = service.createRecognizer("method7v7_recognizer.xml", true, true, false);
FacerecService.Config capturerConfig = service.new Config("common_capturer4_fda.xml");
capturerConfig.overrideParameter("min_size", 200);
final Capturer capturer = service.createCapturer(capturerConfig);
// ...
}
catch (SDKException e)
{
System.out.println(e.getMessage());
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
from face_sdk import Config, FacerecService, Error
if __name__ == '__main__':
try:
face_sdk_root_dir = "path/to/face_sdk"
service = FacerecService.create_service(face_sdk_root_dir + "/lib/libfacerec.so", face_sdk_root_dir + "/conf/facerec")
recognizer = service.create_recognizer("method7v7_recognizer.xml", True, True, False)
capturer_config = Config("common_capturer4_fda.xml")
capturer = service.create_capturer(capturer_config)
# ...
except Error as e:
print(e)
Example 2
This example shows calling of the createService
method with a preloaded license.
- C++
- C#
- Java
std::string license_body = "<?xml version="1.0" encoding="utf-8"?><License>........"; // contents of your license
auto license = pbio::FacerecService::License(license_body);
const pbio::FacerecService::Ptr service = pbio::FacerecService::createService("../bin/facerec.dll", "../conf/facerec/", license);
string license_body = "<?xml version="1.0" encoding="utf-8"?><License>........"; // contents of your license
FacerecService service = FacerecService.createService(faceSDKRootDir + "/conf/facerec", new FacerecService.License(license_body));
String license_body = "<?xml version="1.0" encoding="utf-8"?><License>........"; // contents of your license
final FacerecService service = FacerecService.createService(faceSDKRootDir + "/lib/libfacerec.so", faceSDKRootDir + "/conf/facerec", new FacerecService.License(license_body));