Skip to main content
Version: 3.26.0 (latest)

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​

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:

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 to FacerecService.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 the library, you need to add a reference to FacerecCSharpWrapper.dll to your project.

After building the project, add FacerecCSharpWrapper.dll, and depending on the operating system, add facerec.dll (for Windows) or create a reference facerec.dll to libfacerec.so (for Linux) in the directory with the 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].

NodeJS​

Note. Node v18.20.8 or higher is supported.

The package face_sdk_3divi allows you to use the libfacerec library in a NodeJS project. To install the package, call npm install /path/to/FaceSDK/node_js from your project.

Go​

Supported platform: Linux only.

To build and run executables using the Go API, you need to set the following environment variables:

  • CGO_LDFLAGS="-L<path_to_face_sdk_lib_directory> -lfacerec"
  • LD_LIBRARY_PATH=<path_to_face_sdk_lib_directory>

The package facesdk allows you to use the libfacerec library in a Go project. To use the package, add the following line in your code:

import (facesdk github.com/3DiVi/Go-API)

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 the face_sdk/conf/facerec/ directory.
note

In NodeJS, you need to call the Init function from the face_sdk_3divi package with the same parameters.

Example​

This example shows initialization of the libfacerec library using FacerecService.createService method.

#include <iostream>
#include <exception>
#include <facerec/import.h>
#include <facerec/libfacerec.h>
int main (int argc, char** argv)
{
    try
    {
        std::string faceSDKRootDir = "/path/to/face_sdk";
        
#ifdef _WIN32
        std::string dll_path = faceSDKRootDir + "/bin/facerec.dll";
#else
        std::string dll_path = faceSDKRootDir + "/lib/libfacerec.so";
#endif
        std::string conf_dir = faceSDKRootDir + "/conf/facerec/";
        std::string license_dir = faceSDKRootDir + "/license/";
        
        pbio::FacerecService::Ptr service;
        service = pbio::FacerecService::createService(dll_path, conf_dir, license_dir);

        pbio::Context detectorConfig = service->createContext();
        pbio::Context fitterConfig = service->createContext();
        pbio::Context faceExtractorConfig = service->createContext();
        
        detectorConfig["unit_type"] = "FACE_DETECTOR";
        fitterConfig["unit_type"] = "FACE_FITTER";
        faceExtractorConfig["unit_type"] = "FACE_TEMPLATE_EXTRACTOR";
    
        pbio::ProcessingBlock faceDetector = service->createProcessingBlock(detectorConfig);
        pbio::ProcessingBlock faceFitter = service->createProcessingBlock(fitterConfig);
        pbio::ProcessingBlock faceExtractor = service->createProcessingBlock(faceExtractorConfig);
        // ...
    }
    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;
    }
}