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.

Important

By default, the SDK is initialized with the Trueface::FacialRecognitionModel::LITE face recognition model. This is our fastest and most lightweight face recognition model; however, it is not the most accurate face recognition model we offer. To use a more accurate model, refer to the Trueface::FacialRecognitionModel section below then be sure to initialize the SDK with the desired Trueface::ConfigurationOptions.

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.

Return

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. The current most accurate model is TFV5.

Values:

enumerator LITE

Lightweight model with faster inference time but reduced accuracy, ideal for embedded systems or lightweight CPU only deployments, and for 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. Ideal for GPU deployments and for 1 to N use cases.

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. Not available in Windows SDK.

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::EnableGPU

Enable GPU support (default is false). Note, GPU support requires a different version of the SDK. You are able to enable GPU for all modules or only specific modules.

Public Functions

inline EnableGPU(bool val)

Enable or disable GPU inference for all modules

Public Members

bool faceDetector = false

Enable GPU inference for face detection

bool faceRecognizer = false

Enable GPU inference for face recognition template generation

Trueface::EnableGPU::EnableGPU() = default
inline Trueface::EnableGPU::EnableGPU(bool val)

Enable or disable GPU inference for all modules

struct Trueface::ConfigurationOptions

SDK configuration options

Public Members

FacialRecognitionModel frModel = FacialRecognitionModel::LITE

The model to be used for facial recognition (default is LITE model)

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.

FaceDetectionMode fdMode = FaceDetectionMode::VERSATILE

The face detection mode (default is VERSATILE). This configuration option is now deprecated and may be removed in future releases.

FaceDetectionFilter fdFilter = FaceDetectionFilter::BALANCED

The threshold level to use when filtering detected faces (default is BALANCED)

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.

EnableGPU enableGPU = {}

Enable GPU support (default is false). Note, GPU support requires a different version of the SDK. You are able to enable GPU for all modules or only specific modules.

unsigned int deviceIndex = 0

GPU device index

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

Deprecated

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

Deprecated since version 0.19.

enum Trueface::FaceDetectionMode

Face detection modes

Values:

enumerator ROBUST

The ROBUST mode is optimized for face recognition, smallestFaceHeight less than 80 pixels will be overridden.

enumerator VERSATILE

The VERSATILE mode can detect small faces (as small as 16x16 pixel) and is faster than the ROBUST mode for the same Trueface::ConfigurationOptions.smallestFaceHeight.