Skip to content

Core Facility#

Common Interfaces#

Face Engine Object#

The Face Engine object is a root object of the entire FaceEngine. Everything begins with it, so it is essential to create at least one instance of it. Although it is possible to have multiple instances of the Face Engine, it is impractical to do so (as explained in section "Automatic reference counting" in chapter "Core concepts"). To create a Face Engine instance call createFaceEngine function. Also, you may specify default dataPath and configPath in createFaceEngine parameters.

If you plan to use GPU acceleration, you should keep in mind CUDA runtime initialization and shutdown. Specifically, CUDA creates global runtime object with implicit lifetime; see
http://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#initialization.

To prevent FaceEngine runtime and lifetime mismatch, it is recommended to avoid creating static global instances of FaceEngine objects, as their destruction order is undetermined.

Settings Provider#

Settings provider is a special entity that loads settings from various locations. Since settings might be shared among several objects, it is useful to cache them to minimize disk reads and provide a dictionary-like interface for named value lookup.

This is what the provider does. The provider object stands somewhat aside FaceEngine facility structure and is created by a separate factory function createSettingsProvider. This function accepts configuration file path as a parameter (see section "Configuration data" for details). By default, the engine holds a single provider instance for all facilities. Think of it as a reference counted config file. This provider is passed by the Face Engine object to each factory it creates. The factory, in turn, can read its configuration data from the object and pass it further to its child objects. In typical scenarios, you should not bother with providers as the engine does everything for you. However, when relying on custom factory creation parameters (see the description in section "Face engine object"), you have to create and supply a provider wherever it is required manually.

Helper Interfaces#

Archive Interface#

Archive interface is used to provide serialization functions with a data source. It contains methods primarily for data reading and writing. Note, that IArchive is not derived from IRefCounted, thus does not imply any special memory management strategies.

A few points to keep in mind when implementing your archive:

  • FaceEngine objects that use IArchive for serialization purposes do call only write() (during saving) or only read() (during loading) but never both during the same process unless otherwise is explicitly stated;
  • During saving or loading FaceEngine objects are free to write or read their data in chunks; e.g., there may be several sequential calls to write() in the scope of a single serialization request. The same is true for read(). Basically, read() and write() should behave pretty much like C fread() and fwrite() standard library functions.

Any IArchive implementation should be aware of these notes.

Since these interface methods are pretty obvious and mostly self-explanatory, we advise you to check out FaceEngine Reference Manual for the details.

Sensor type#

SensorType determines which type of camera sensor is used to perform estimation. Currently two types of SensorType are available: Visible, NIR. The user can indicate the required type of sensor when creating an object by passing the appropriate parameter.

Data Paths#

Model Data#

Various FaceEngine modules may require data files to operate. The files contain various algorithm models and constants used at runtime. All the files are gathered together into a single data directory. The data directory location is assumed to reside in:

  • /opt/visionlabs/data on Linux
  • ./data on Windows

One may override the data directory location by means of setDataDirectory() method which is available in IFaceEngine. Current data location may be retrieved via getDataDirectory() method.

Configuration Data#

The configuration file is called faceengine.conf and stored in /data directory by default. ConfigurationGuide.pdf with parameter description and default values is located at /doc package folder.

At runtime, the configuration file data is managed by a special object that implements ISettingsProvider interface (see section "Settings provider"). The provider is instantiated by means of createSettingsProvider() function that accepts configuration file location as a parameter or uses aforementioned defaults if not specified.

One may supply a different configuration to any factory object by means of setSettingsProvider() method, which is available in each factory object interface, including IFaceEngine. Currently, bound settings provider may be retrieved via getSettingsProvider() method.