General¶

Before you can call the SDK functions, you must first initialize the SDK with your desired configuration options. These configuration options will ultimately impact the behaviour of the SDK, so be sure to read through what each one does carefully.

Once you have initialized the SDK, then proceed to the the License section.

class SDK¶

Trueface::SDK::SDK()¶

Initialize the SDK using default ConfigurationOptions.

See: ConfigurationOptions

Trueface::SDK::SDK(const ConfigurationOptions &options)¶

Initialize the SDK using custom ConfigurationOptions.

Parameters: options – custom configuration options.

static std::string Trueface::SDK::getVersion()¶

Gets the version-build number of the SDK.

Returns: Version Number as a string.

enum Trueface::FacialRecognitionModel¶

Facial recognition models. To compare model performances, refer to our ROC curves. You can also find more information on our FAQ page. You can view the inference time for the various models on our benchmarks page. The current most accurate model is TFV5.

Values:

enumerator LITE¶: Our most lightweight model with fastest inference time but lowest accuracy, ideal for embedded systems or lightweight CPU only deployments, prototyping, and some 1 to 1 matching use cases.

enumerator LITE_V2¶: Lightweight model which has improved accuracy over the previous LITE model, though does have slightly greater inference time. Ideal for embedded systems or lightweight CPU only deployments, prototyping, and some 1 to 1 matching use cases.

enumerator FULL¶: Full TFV4 model which has better accuracy than the LITE model, but also has greater inference time. Ideal for GPU deployments and for 1 to N use cases. Note, TFV4 has now been deprecated and replaced by TFV5 which has better performance. Despite this, we will continue providing support for TFV4 for clients with existing collections.

enumerator TFV5¶: TFV5 is currently the highest accuracy model for unmasked face images. Ideal for GPU deployments and for 1 to N use cases.

enumerator TFV6¶: TFV6 is currently the highest accuracy model for masked face images. Use TFV6 in situations where it is anticipated that the probe image contains a masked face (for 1 to N search), or where one or both face images are masked (for 1 to 1 comparisons). TFV6 has comparable inference time to TFV5.

enum Trueface::ObjectDetectionModel¶

Object detection models.

Values:

enumerator ACCURATE¶

enumerator FAST¶

enum Trueface::FaceDetectionFilter¶

Filters the detected faces based on score thresholds obtained from ROC curve.

Values:

enumerator HIGH_RECALL¶: Filter the detected faces based on a low score threshold. Limits false negatives (does not detect a face), but may have more false positives (classifies a non-face as a face).

enumerator HIGH_PRECISION¶: Filter the detected faces based on a high score threshold. Limits false positives (classifies a non-face as a face), but may have more false negatives (does not detect a face).

enumerator BALANCED¶: Filter the detected faces based on a medium score threshold to balance false positives and false negatives. We advise using this option most of the time.

enumerator UNFILTERED¶: Do not filter the detected faces by score. Will have a large number of false positives (classifies a non-face as a face).

enum Trueface::DatabaseManagementSystem¶

Database Management System for storing Faceprints.

Values:

enumerator SQLITE¶: Use sqlite backend. Write Faceprints to local disk. Ideal for embedded systems or use cases where only one process connects to the database.

enumerator POSTGRESQL¶: Use a PostgreSQL backend. Ideal for distributed systems requiring synchronization.

enumerator NONE¶: Do not write Faceprints to disk, only store in ram. Warning, enrolled Faceprints will not be saved after the program terminates. Switching to a new collections will also delete all enrolled templates.

struct Trueface::GPUModuleOptions¶

GPU options for a specific module (ex. face detector).

Public Functions

inline GPUModuleOptions(bool val)¶: Enable or disable GPU inference.

Public Members

bool enableGPU = true¶: Use GPU for inference. If set to false, will use CPU for inference.

unsigned int deviceIndex = 0¶: GPU device index.

Precision precision = Precision::FP16¶: Precision level used for inference.

int32_t maxBatchSize = 4¶: The maximum batch size which will be used.

int32_t optBatchSize = 1¶: The batch size which should be optimized for. Must be less than or equal to Trueface::GPUModuleOptions.maxBatchSize.

size_t maxWorkspaceSizeMb = 2000¶: The maximum allowable GPU memory to be used for model conversion, in Mb. Applications should allow the engine builder as much workspace as they can afford. At runtime, the SDK allocated no more than this and typically less.

Trueface::GPUModuleOptions::GPUModuleOptions() = default¶

inline Trueface::GPUModuleOptions::GPUModuleOptions(bool val): Enable or disable GPU inference.

struct Trueface::GPUOptions¶

GPU options for the SDK. Note, GPU support requires a different version of the SDK. You can enable GPU inference for all supported modules by setting this option to true. Default uses CPU for inference.

Public Functions

inline GPUOptions(bool val)¶: Enable or disable GPU inference for all modules.

Public Members

GPUModuleOptions faceDetectorGPUOptions = {}¶: Options for face detector GPU inference.

GPUModuleOptions faceRecognizerGPUOptions = {}¶: Options for face recognizer GPU inference.

Trueface::GPUOptions::GPUOptions() = default¶

inline Trueface::GPUOptions::GPUOptions(bool val): Enable or disable GPU inference for all modules.

struct Trueface::InitializeModule¶

Initialize module in SDK constructor. By default, the SDK uses lazy initialization, meaning modules are only initialized when they are first used (on first inference). This is done so that modules which are not used do not load their models into memory, and hence do not utilize memory. The downside to this is that the first inference will be much slower as the model file is being decrypted and loaded into memory. Therefore, if you know you will use a module, choose to pre-initialize the module, which reads the model file into memory in the SDK constructor.

Public Members

bool faceDetector = false¶: Face detector.

bool faceRecognizer = false¶: Face recognizer.

bool objectDetector = false¶: Object detector.

bool bodyposeEstimator = false¶: Bodypose estimator.

bool liveness = false¶: Liveness.

bool activeSpoof = false¶: Active spoof.

bool passiveSpoof = false¶: Passive spoof.

bool landmarkDetector = false¶: 106 face point landmark detector.

struct Trueface::EncryptDatabase¶

Encrypt the biometric templates and identity strings when storing in the database using AES encryption. Note, enabling this option does add overhead to Faceprint enrollment as well as loading a collection from a database into memory. Enabling encryption does not increase the 1 to N identification time.

Public Members

bool enableEncryption = false¶: Enable database encryption. Must provide encryption key if encryption is enabled. If enabling encryption with PostgreSQL backend, it is strongly advised to require SSL for PostgreSQL connection.

std::string key¶: Encryption key. The key is hashed to a fixed length before being used for encryption.

struct Trueface::ConfigurationOptions¶

SDK configuration options.

Public Members

int mobilePowerSave = 0¶: Android Only Power saving mode. 0 = all cores enabled (default). 1 = only little clusters enabled. 2 = only big clusters enabled.

int mobileThreads = 4¶: Mobile Only Set the number of threads used for inference. For non-mobile platforms, should use the OMP_NUM_THREADS environment variable.

size_t mobileAvailableMemory = 0¶: iOS Only SDK user must define how much memory is available for iOS application. Should be set using the following code: #include <os/proc.h> options.mobileAvailableMemory = os_proc_available_memory();

FacialRecognitionModel frModel = FacialRecognitionModel::TFV5 ¶: The model to be used for facial recognition (default is TFV5).

ObjectDetectionModel objModel = ObjectDetectionModel::ACCURATE ¶: The model to be used for object detection (default is ACCURATE model).

int smallestFaceHeight = 40¶: The smallest face height that the face detector can detect. (default is 40 pixels, min value is 16 pixels). The face detector has a detection scale range of about 5 octaves. Ex. 40 pixels yields the detection scale range of ~40 pixels to 1280 (=40x2^5) pixels. If set to -1, will dynamically adjusts the face detection scale range from image-height/32 to image-height to ensure that large faces are detected in high resolution images. Increasing the Trueface::ConfigurationOptions.smallestFaceHeight will result in faster face detection.

FaceDetectionFilter fdFilter = FaceDetectionFilter::BALANCED ¶: The face detection filter (default is BALANCED). Filters the detected faces based on score thresholds obtained from ROC curve.

DatabaseManagementSystem dbms = DatabaseManagementSystem::SQLITE ¶: Database management system for storing Faceprints (default is SQLITE).

std::string modelsPath = "./"¶: The directory path containing the model files.

bool frVectorCompression = false¶: Improves the computation speed for 1 to 1 comparisons and 1 to N searches by compressing the feature vector and enabling additional optimizations.

GPUOptions gpuOptions = GPUOptions{false}¶: Options for enabling and configuring GPU inference. Default uses CPU inference. Note, GPU support requires a different version of the SDK. You can easily enable GPU inference for all supported modules by setting this option to true.

std::vector<unsigned int> batchSizes = {}¶: Though this option is deprecated, it should continue to be used for older models such as the FULL and TFV5 models. For newer models such as TFV6 and newer, use Trueface::GPUModuleOptions.optBatchSize instead. Specify the batch sizes which will be used, resulting in improved performance when switching between batch sizes. If the batch sizes are specified, then using a non-specified batch size will result in an exception being thrown. Note, GPU memory will be allocated for each of the specified batch sizes, so specifying too many batch sizes may result in an out-of-memory crash. Leave vector empty to support dynamic batch sizes. Dynamic batch sizes will result in a slowdown when switching between batch sizes. Ex. If processing 36 images in the following batches: 10, 10, 10, 6 there will be a slight slowdown when switching from the batch size of 10 to 6.

InitializeModule initializeModule = {}¶: Initialize specified modules in the SDK constructor (default uses lazy initialization).

EncryptDatabase encryptDatabase = {}¶: Encrypt the biometric templates and identity strings when storing in the database using AES encryption (default is disabled).

enum Trueface::ErrorCode¶

Error codes returned by methods.

Values:

enumerator NO_ERROR¶

enumerator INVALID_LICENSE¶

enumerator FILE_READ_FAIL¶

enumerator UNSUPPORTED_IMAGE_FORMAT¶

enumerator UNSUPPORTED_MODEL¶

enumerator NO_FACE_IN_FRAME¶

enumerator FAILED¶

enumerator COLLECTION_CREATION_ERROR¶

enumerator DATABASE_CONNECTION_ERROR¶

enumerator ENROLLMENT_ERROR¶

enumerator MAX_COLLECTION_SIZE_EXCEEDED¶

enumerator NO_RECORD_FOUND¶

enumerator NO_COLLECTION_FOUND¶

enumerator COLLECTION_DELETION_ERROR¶

enumerator EXTREME_FACE_ANGLE¶

enumerator FACE_TOO_CLOSE¶

enumerator FACE_TOO_FAR¶

enumerator FACE_TOO_SMALL¶

Deprecated¶

The following have been deprecated and may be removed in future releases of the SDK.

Warning

doxygenstruct: Cannot find class “Trueface::EnableGPU” in doxygen xml output for project “TruefaceSDK” from directory: /root/project/build/docs/doxygen/xml

Warning

doxygenfunction: Cannot find function “Trueface::EnableGPU::EnableGPU” in doxygen xml output for project “TruefaceSDK” from directory: /root/project/build/docs/doxygen/xml

Warning

doxygenfunction: Cannot find function “Trueface::EnableGPU::EnableGPU” in doxygen xml output for project “TruefaceSDK” from directory: /root/project/build/docs/doxygen/xml